diff --git a/onramp/blueprints.rst b/onramp/blueprints.rst index 3cef47c..4fc2f6c 100644 --- a/onramp/blueprints.rst +++ b/onramp/blueprints.rst @@ -480,12 +480,12 @@ required extensions. It has been written to do nothing unless variable target. -OAI gNB -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +OAI 5G RAN +~~~~~~~~~~~~~~~~~~~~ Aether can be configured to work with the open source gNB from OAI. The blueprint runs in either simulation mode or with physical UEs -connecting to a software-defined radio. The following assumes +connecting to a USRP software-defined radio. The following assumes familiarity with the OAI 5G RAN stack. .. _reading_oai: @@ -518,10 +518,10 @@ The blueprint includes the following: gNB. * An Integration test running in simulation mode is still pending. The - blueprint has been tested with USRP X310, but other models should + blueprint has been validated with USRP X310, but other models should also work. -To use the OAI gNB first copy the vars file to ``main.yml``: +To use an OAI gNB, first copy the vars file to ``main.yml``: .. code-block:: @@ -585,6 +585,15 @@ parameters`` section need to be modified to work with the Aether Core: GNB_IPV4_ADDRESS_FOR_NG_AMF = "{{oai.gnb.ip}}/24"; +One other variable of note is ``ran_subnet: "172.20.0.0/16"`` in the +``core`` block of ``vars/main.yml``. As a general rule, +``core.ran_subnet`` is set to the empty string (``""``) whenever a +physical gNB is on the same L2 network as the Core, but in the case of +an OAI-based gNB, the RAN stack runs in a Macvlan-connected Docker +container, and so the variable is set to ``"172.20.0.0/16"``. (This +is similar to how OnRamp configures the Core for an emulated gNB using +gNBsim.) + To deploy the OAI blueprint in simulation mode, run the following: .. code-block:: diff --git a/onramp/directory.rst b/onramp/directory.rst index 0396e21..59d645b 100644 --- a/onramp/directory.rst +++ b/onramp/directory.rst @@ -12,16 +12,7 @@ up to speed on the rest of the system. .. admonition:: Troubleshooting Hint - This guide includes *Troubleshooting Hints* like this one. Our first - hint is to recommend that the guide be followed sequentially. This - is because each section establishes a milestone that may prove - useful when you find yourself trying to troubleshoot a problem in a - later section. For example, isolating a problem with a physical gNB - is easier if you know that connectivity to the AMF and UPF works - correctly, which the :doc:`Emulated RAN ` section - helps to establish. - - Our second hint is to join the ``#aether-onramp`` channel of the + Users are encouraged to join the ``#aether-onramp`` channel of the `ONF Workspace `__ on Slack, where questions about using OnRamp to bring up Aether are asked and answered. The ``Troubleshooting`` bookmark for that channel includes @@ -59,7 +50,6 @@ Helm Charts | https://charts.aetherproject.org | https://charts.onosproject.org - | https://charts.opencord.org | https://charts.atomix.io | https://sdrancharts.onosproject.org | https://charts.rancher.io/ diff --git a/onramp/network.rst b/onramp/network.rst index 0c1c843..fd4569c 100644 --- a/onramp/network.rst +++ b/onramp/network.rst @@ -253,35 +253,35 @@ example ``ens18`` interface for illustrative purposes: .. code-block:: $ sudo tcpdump -i any sctp -w sctp-test.pcap - $ sudo tcpdump -i ens18 port 2152 -w gtp-outside.pcap - $ sudo tcpdump -i access port 2152 -w gtp-inside.pcap + $ sudo tcpdump -i ens18 port 2152 -w n3-outside.pcap + $ sudo tcpdump -i access port 2152 -w n3-inside.pcap $ sudo tcpdump -i core net 172.250.0.0/16 -w n6-inside.pcap $ sudo tcpdump -i ens18 net 172.250.0.0/16 -w n6-outside.pcap The first trace, saved in file ``sctp.pcap``, captures SCTP packets sent to establish the control path between the base station and the -Mobile Core (i.e., N2 messages). Toggling "Mobile Data" on a physical -UE, for example by turning Airplane Mode off and on, will generate the -relevant control plane traffic; gNBsim automatically triggers this -activity. +Mobile Core (over the **N2** interface). Toggling "Mobile Data" on a +physical UE, for example by turning Airplane Mode off and on, will +generate the relevant control plane traffic; gNBsim automatically +triggers this activity. -The second and third traces, saved in files ``gtp-outside.pcap`` and -``gtp-inside.pcap``, respectively, capture GTP packets (tunneled +The second and third traces, saved in files ``n3-outside.pcap`` and +``n3-inside.pcap``, respectively, capture GTP packets (tunneled through port ``2152`` ) on the RAN side of the UPF. Setting the interface to ``ens18`` corresponds to "outside" the UPF and setting the interface to ``access`` corresponds to "inside" the UPF. Running -``ping`` from a physical UE will generate the relevant user plane (N3) -traffic; gNBsim automatically triggers this activity. +``ping`` from a physical UE will generate the relevant user plane traffic +(over the **N3** interface); gNBsim automatically triggers this activity. Similarly, the fourth and fifth traces, saved in files ``n6-inside.pcap`` and ``n6-outside.pcap``, respectively, capture IP -packets on the Internet side of the UPF (which is known as the **N6** -interface in 3GPP). In these two tests, ``net 172.250.0.0/16`` -corresponds to the IP addresses assigned to UEs by the SMF. Running -``ping`` from a physical UE will generate the relevant user plane -traffic; gNBsim automatically triggers this activity. +packets on the Internet side of the UPF (over the **N6** interface). +In these two tests, ``net 172.250.0.0/16`` corresponds to the IP +addresses assigned to UEs by the SMF. Running ``ping`` from a physical +UE will generate the relevant user plane traffic; gNBsim automatically +triggers this activity. -If the ``gtp-outside.pcap`` has packets and the ``gtp-inside.pcap`` +If the ``n3-outside.pcap`` has packets and the ``n3-inside.pcap`` is empty (no packets captured), you may run the following commands to make sure packets are forwarded from the ``ens18`` interface to the ``access`` interface and vice versa: diff --git a/onramp/overview.rst b/onramp/overview.rst index 2f75b1f..b9fe3d4 100644 --- a/onramp/overview.rst +++ b/onramp/overview.rst @@ -35,3 +35,26 @@ discussion on Slack in the `ONF Community Workspace needs to be done can be found in the `Aether OnRamp Wiki `__. +How to Read This Guide +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This guide is written to be followed sequentially, with each section +establishing a capability that later sections build upon. This is also +helpful when troubleshooting a setup—for example, isolating a problem +with a physical gNB is easier if you know that connectivity to the AMF +and UPF works correctly, which the :doc:`Emulated RAN +` section helps to establish. + +Once you reach the last section (:doc:`Other Blueprints +`), you will have seen examples of all the +degrees-of-freedom OnRamp supports, with the goal of preparing you to +take ownership of your own deployment. You can do this by defining +your own customized blueprint, and/or directly interacting with Helm +and Kubernetes (rather than depending entirely on OnRamp's playbooks). + +That final :doc:`Other Blueprints ` section then +gives a brief synopsis of several additional OnRamp blueprints. Each +blueprint enables a particular combination of Ansible features, +demonstrating how those features are enabled, configured, and +deployed. This section presumes familiarity with all of OnRamp's +capabilities introduced in the earlier sections.