added ran_subnet explanation

Signed-off-by: Larry Peterson <[email protected]>

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::

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 </onramp/gnbsim>` 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 <https://onf-community.slack.com/>`__ 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/

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:

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
 <https://wiki.aetherproject.org/display/HOME/Aether+OnRamp>`__.
 
+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
+</onramp/gnbsim>` section helps to establish.
+
+Once you reach the last section (:doc:`Other Blueprints
+</onramp/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 </onramp/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.