llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 1 | Quick Start |
| 2 | ----------------------- |
| 3 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 4 | This section describes a low-overhead way to get started with OnRamp. |
| 5 | It brings up a one-node Kubernetes cluster, deploys a 5G version of |
| 6 | SD-Core on that cluster, and runs an emulated 5G workload against the |
| 7 | 5G Core. It assumes a low-end server that meets the following |
| 8 | requirements: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 9 | |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 10 | * Haswell CPU (or newer), with at least 4 CPUs and 16GB RAM. |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 11 | * Clean install of Ubuntu 20.04 or 22.04, with 5.15 (or later) kernel. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 12 | |
| 13 | For example, something like an Intel NUC is more than enough to get |
| 14 | started. |
| 15 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 16 | While it's possible to use OnRamp to deploy Aether on a laptop (e.g., |
| 17 | in a VirtualBox VM), because the goal is to eventually scale a |
| 18 | deployment and/or run Aether 24/7, OnRamp has been developed and |
| 19 | tested on physical servers and server-based VMs. The latter includes |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 20 | Proxmox (see the example configuration shown in :numref:`Figure %s |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 21 | <fig-proxmox>`); AWS (specify a ``t2.xlarge`` instance); and CloudLab |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 22 | (specify either a ``small-lan`` or ``single-pc-ubuntu`` instance). |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 23 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 24 | .. _fig-proxmox: |
| 25 | .. figure:: figures/proxmox.png |
| 26 | :width: 500px |
| 27 | :align: center |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 28 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 29 | Example configuration of Proxmox VM. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 30 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 31 | |
| 32 | Prep Environment |
| 33 | ~~~~~~~~~~~~~~~~~~~~~ |
| 34 | |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 35 | To install Aether OnRamp, you must be able able to run ``sudo`` without |
| 36 | a password, and there should be no firewall running on the server. You can |
| 37 | verify this is the case by executing the following, which should |
| 38 | report ``Status: inactive``: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 39 | |
| 40 | .. code-block:: |
| 41 | |
| 42 | $ sudo ufw status |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 43 | Status: inactive |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 44 | |
Larry Peterson | a30a75e | 2023-09-01 15:44:37 -0700 | [diff] [blame^] | 45 | Your server should use *systemd-networkd* to configure the |
| 46 | network. This is the default for Ubuntu, but you can verify it by |
| 47 | typing: |
| 48 | |
| 49 | .. code-block:: |
| 50 | |
| 51 | $ systemctl status systemd-networkd.service |
| 52 | |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 53 | OnRamp depends on Ansible, which you can install on your server as |
| 54 | follows: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 55 | |
| 56 | .. code-block:: |
| 57 | |
| 58 | $ sudo apt install pipx |
| 59 | $ sudo apt install python3.8-venv |
| 60 | $ pipx install --include-deps ansible |
| 61 | $ pipx ensurepath |
| 62 | $ sudo apt-get install sshpass |
| 63 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 64 | Once installed, displaying the Ansible version number should result in |
| 65 | output similar to the following: |
| 66 | |
| 67 | .. code-block:: |
| 68 | |
| 69 | $ ansible --version |
| 70 | ansible [core 2.11.12] |
| 71 | config file = None |
| 72 | configured module search path = ['/home/foo/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] |
| 73 | ansible python module location = /home/foo/.local/lib/python3.6/site-packages/ansible |
| 74 | ansible collection location = /home/foo/.ansible/collections:/usr/share/ansible/collections |
| 75 | executable location = /home/foo/.local/bin/ansible |
| 76 | python version = 3.6.9 (default, Mar 10 2023, 16:46:00) [GCC 8.4.0] |
| 77 | jinja version = 3.0.3 |
| 78 | libyaml = True |
| 79 | |
Larry Peterson | aa89b8e | 2023-08-17 15:28:59 -0700 | [diff] [blame] | 80 | Note that a fresh install of Ubuntu may be missing other packages that |
| 81 | you need (e.g., ``git``, ``curl``, ``make``), but you will be prompted |
| 82 | to install them as you step through the Quick Start sequence. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 83 | |
| 84 | Download Aether OnRamp |
| 85 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 86 | |
| 87 | Once ready, clone the Aether OnRamp repo on this target deployment |
| 88 | server: |
| 89 | |
| 90 | .. code-block:: |
| 91 | |
| 92 | $ git clone --recursive https://github.com/opennetworkinglab/aether-onramp.git |
| 93 | $ cd aether-onramp |
| 94 | |
| 95 | Taking a quick look at your ``aether-onramp`` directory, there are |
| 96 | four things to note: |
| 97 | |
| 98 | 1. The ``deps`` directory contains the Ansible deployment |
| 99 | specifications for all the Aether subsystems. Each of these |
| 100 | subdirectories (e.g., ``deps/5gc``) is self-contained, meaning you |
| 101 | can execute the Make targets in each individual directory. Doing so |
| 102 | causes Ansible to run the corresponding playbook. For example, the |
| 103 | installation playbook for the 5G Core can be found in |
| 104 | ``deps/5gc/roles/core/tasks/install.yml``. |
| 105 | |
| 106 | 2. The Makefile in the main OnRamp directory imports (``#include``) |
| 107 | the per-subsystem Makefiles, meaning all the individual steps |
| 108 | required to install Aether can be managed from this main directory. |
| 109 | The Makefile includes comments listing the key Make targets defined |
| 110 | by the included Makefiles. *Importantly, the rest of this guide |
| 111 | assumes you are working in the main OnRamp directory, and not in |
| 112 | the individual subsystems.* |
| 113 | |
| 114 | 3. File ``vars/main.yml`` defines all the Ansible variables you will |
| 115 | potentially need to modify to specify your deployment scenario. |
| 116 | This file is the union of all the per-component ``var/main.yml`` |
| 117 | files you find in the corresponding ``deps`` directory. This |
| 118 | top-level variable file overrides the per-component var files, so |
| 119 | you will not need to modify the latter. Note that the ``vars`` |
| 120 | directory contains several variants of ``main.yml``, each tailored |
| 121 | for a different deployment scenario. The default ``main.yml`` |
| 122 | (which is the same as ``main-quickstart.yml``) supports the Quick |
| 123 | Start deployment described in this section; we'll substitute the |
| 124 | other variants in later sections. |
| 125 | |
| 126 | 4. File ``hosts.ini`` (host inventory) is Ansible's way of specifying |
| 127 | the set of servers (physical or virtual) that Ansible targets with |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 128 | various installation playbooks. The default version of ``hosts.ini`` |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 129 | included with OnRamp is simplified to run everything on a single |
| 130 | server (the one you've cloned the repo onto), with additional lines |
| 131 | you may eventually need for a multi-node cluster commented out. |
| 132 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 133 | Set Target Parameters |
| 134 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 135 | |
| 136 | The Quick Start deployment described in this section requires that you |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 137 | modify two sets of parameters to reflect the specifics of your target |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 138 | deployment. |
| 139 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 140 | The first set is in file ``hosts.ini``, where you will need to give the IP |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 141 | address and login credentials for the server you are working on. At |
| 142 | this stage, we assume the server you downloaded OnRamp onto is the |
| 143 | same server you will be installing Aether on. |
| 144 | |
| 145 | .. code-block:: |
| 146 | |
Larry Peterson | 925ac6b | 2023-08-23 13:38:35 -0700 | [diff] [blame] | 147 | node1 ansible_host=10.76.28.113 ansible_user=aether ansible_password=aether ansible_sudo_pass=aether |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 148 | |
Larry Peterson | 925ac6b | 2023-08-23 13:38:35 -0700 | [diff] [blame] | 149 | In this example, address ``10.76.28.113`` and the three occurrences |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 150 | of the string ``aether`` need to be replaced with the appropriate |
| 151 | values. Note that if you set up your server to use SSH keys instead |
| 152 | of passwords, then ``ansible_password=aether`` needs to be replaced |
| 153 | with ``ansible_ssh_private_key_file=~/.ssh/id_rsa`` (or wherever |
| 154 | your private key can be found). |
| 155 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 156 | The second set of parameters is in ``vars/main.yml``, where the **two** lines |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 157 | currently reading |
| 158 | |
| 159 | .. code-block:: |
| 160 | |
| 161 | data_iface: ens18 |
| 162 | |
| 163 | need to be edited to replace ``ens18`` with the device interface for |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 164 | you server, and the line specifying the IP address of the Core's AMF |
| 165 | needs to be edited to reflect your server's IP address: |
| 166 | |
| 167 | .. code-block:: |
| 168 | |
| 169 | amf: |
Larry Peterson | 925ac6b | 2023-08-23 13:38:35 -0700 | [diff] [blame] | 170 | ip: "10.76.28.113" |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 171 | |
| 172 | You can learn your server's IP address and interface using the Linux ``ip`` |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 173 | command: |
| 174 | |
| 175 | .. code-block:: |
| 176 | |
| 177 | $ ip a |
| 178 | 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 |
| 179 | link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 |
| 180 | inet 127.0.0.1/8 scope host lo |
| 181 | valid_lft forever preferred_lft forever |
| 182 | inet6 ::1/128 scope host |
| 183 | valid_lft forever preferred_lft forever |
| 184 | 2: ens18: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000 |
| 185 | link/ether 2c:f0:5d:f2:d8:21 brd ff:ff:ff:ff:ff:ff |
| 186 | inet 10.76.28.113/24 metric 100 brd 10.76.28.255 scope global ens3 |
| 187 | valid_lft forever preferred_lft forever |
| 188 | inet6 fe80::2ef0:5dff:fef2:d821/64 scope link |
| 189 | valid_lft forever preferred_lft forever |
| 190 | |
| 191 | In this example, the reported interface is ``ens18`` and the IP |
| 192 | address is ``10.76.28.113`` on subnet ``10.76.28.0/24``. We will use |
| 193 | these three values as a running example throughout the guide, as a |
| 194 | placeholder for your local details. |
| 195 | |
Larry Peterson | 505d4b3 | 2023-08-21 14:39:45 -0700 | [diff] [blame] | 196 | .. admonition:: Troubleshooting Hint |
| 197 | |
| 198 | Due to a limitation in gNBsim (the RAN emulator introduced later in |
| 199 | this section), it is necessary for your server to be configured with |
| 200 | IPv6 enabled (as the ``inet6`` line in the example output indicates |
| 201 | is the case for interface ``ens18``). If IPv6 is not enabled, the |
| 202 | emulated RAN will not successfully connect to the AMF. |
| 203 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 204 | Note that ``vars/main.yml`` and ``hosts.ini`` are the only two files |
| 205 | you need to modify for now, but there are additional config files that |
| 206 | you may want to modify as we move beyond the Quick Start deployment. |
| 207 | We'll identify those files throughout this section, for informational |
| 208 | purposes, and revisit them in later sections. |
| 209 | |
| 210 | Many of the tasks specified in the various Ansible playbooks result in |
| 211 | calls to Kubernetes, either directly via ``kubectl``, or indirectly |
| 212 | via ``helm``. This means that after executing the sequence of |
| 213 | Makefile targets described in the rest of this guide, you'll want to |
| 214 | run some combination of the following commands to verify that the |
| 215 | right things happened: |
| 216 | |
| 217 | .. code-block:: |
| 218 | |
| 219 | $ kubectl get pods --all-namespaces |
| 220 | $ helm repo list |
| 221 | $ helm list --namespace kube-system |
| 222 | |
| 223 | The first reports the set of Kubernetes namespaces currently running; |
| 224 | the second shows the known set of repos you are pulling charts from; |
| 225 | and the third shows the version numbers of the charts currently |
| 226 | deployed in the ``kube-system`` namespace. |
| 227 | |
| 228 | If you are not familiar with ``kubectl`` (the CLI for Kubernetes), we |
| 229 | recommend that you start with `Kubernetes Tutorial |
| 230 | <https://kubernetes.io/docs/tutorials/kubernetes-basics/>`__. And |
| 231 | although not required, you may also want to install |
| 232 | `k9s <https://k9scli.io/>`__\ , a terminal-based UI that provides a |
| 233 | convenient alternative to ``kubectl`` for interacting with Kubernetes. |
| 234 | |
| 235 | Note that we have not yet installed Kubernetes or Helm, so these |
| 236 | commands are not yet available. At this point, the only verification |
| 237 | step you can take is to type the following: |
| 238 | |
| 239 | .. code-block:: |
| 240 | |
| 241 | $ make aether-pingall |
| 242 | |
| 243 | The output should show that Ansible is able to securely connect to all |
| 244 | the nodes in your deployment, which is currently just the one that |
| 245 | Ansible knows as ``node1``. |
| 246 | |
| 247 | Install Kubernetes |
| 248 | ~~~~~~~~~~~~~~~~~~~ |
| 249 | |
| 250 | The next step is to bring up an RKE2.0 Kubernetes cluster on your |
| 251 | target server. Do this by typing: |
| 252 | |
| 253 | .. code-block:: |
| 254 | |
| 255 | $ make aether-k8s-install |
| 256 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 257 | Note that the Ansible playbooks triggered by this (and other) make |
| 258 | targets will output red results from time-to-time (indicating an |
| 259 | exception or failure), but as long as Ansible keeps progressing |
| 260 | through the playbook, such output can be safely ignored. |
| 261 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 262 | Once the playbook completes, executing ``kubectl`` will show the |
| 263 | ``kube-system`` namespace running, with output looking something like |
| 264 | the following: |
| 265 | |
| 266 | .. code-block:: |
| 267 | |
| 268 | $ kubectl get pods --all-namespaces |
| 269 | NAMESPACE NAME READY STATUS RESTARTS AGE |
| 270 | kube-system cloud-controller-manager-node1 1/1 Running 0 2m4s |
| 271 | kube-system etcd-node1 1/1 Running 0 104s |
| 272 | kube-system helm-install-rke2-canal-8s67r 0/1 Completed 0 113s |
| 273 | kube-system helm-install-rke2-coredns-bk5rh 0/1 Completed 0 113s |
| 274 | kube-system helm-install-rke2-ingress-nginx-lsjz2 0/1 Completed 0 113s |
| 275 | kube-system helm-install-rke2-metrics-server-t8kxf 0/1 Completed 0 113s |
| 276 | kube-system helm-install-rke2-multus-tbbhc 0/1 Completed 0 113s |
| 277 | kube-system kube-apiserver-node1 1/1 Running 0 97s |
| 278 | kube-system kube-controller-manager-node1 1/1 Running 0 2m7s |
| 279 | kube-system kube-multus-ds-96cnl 1/1 Running 0 95s |
| 280 | kube-system kube-proxy-node1 1/1 Running 0 2m1s |
| 281 | kube-system kube-scheduler-node1 1/1 Running 0 2m7s |
| 282 | kube-system rke2-canal-h79qq 2/2 Running 0 95s |
| 283 | kube-system rke2-coredns-rke2-coredns-869b5d56d4-tffjh 1/1 Running 0 95s |
| 284 | kube-system rke2-coredns-rke2-coredns-autoscaler-5b947fbb77-pj5vk 1/1 Running 0 95s |
| 285 | kube-system rke2-ingress-nginx-controller-s68rx 1/1 Running 0 48s |
| 286 | kube-system rke2-metrics-server-6564db4569-snnv4 1/1 Running 0 56s |
| 287 | |
| 288 | If you are interested in seeing the details about how Kubernetes is |
| 289 | customized for Aether, look at |
| 290 | ``deps/k8s/roles/rke2/templates/master-config.yaml``. Of particular |
| 291 | note, we have instructed Kubernetes to allow service for ports ranging |
| 292 | from ``2000`` to ``36767`` and we are using the ``multus`` and |
| 293 | ``canal`` CNI plugins. |
| 294 | |
| 295 | Install SD-Core |
| 296 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 297 | |
| 298 | We are now ready to bring up the 5G version of the SD-Core. To do |
| 299 | that, type: |
| 300 | |
| 301 | .. code-block:: |
| 302 | |
| 303 | $ make aether-5gc-install |
| 304 | |
| 305 | ``kubectl`` will now show the ``omec`` namespace running (in addition |
| 306 | to ``kube-system``), with output similar to the following: |
| 307 | |
| 308 | .. code-block:: |
| 309 | |
| 310 | $ kubectl get pods -n omec |
| 311 | NAME READY STATUS RESTARTS AGE |
| 312 | amf-5887bbf6c5-pc9g2 1/1 Running 0 6m13s |
| 313 | ausf-6dbb7655c7-42z7m 1/1 Running 0 6m13s |
| 314 | kafka-0 1/1 Running 0 6m13s |
| 315 | metricfunc-b9f8c667b-r2x9g 1/1 Running 0 6m13s |
| 316 | mongodb-0 1/1 Running 0 6m13s |
| 317 | mongodb-1 1/1 Running 0 4m12s |
| 318 | mongodb-arbiter-0 1/1 Running 0 6m13s |
| 319 | nrf-54bf88c78c-kcm7t 1/1 Running 0 6m13s |
| 320 | nssf-5b85b8978d-d29jm 1/1 Running 0 6m13s |
| 321 | pcf-758d7cfb48-dwz9x 1/1 Running 0 6m13s |
| 322 | sd-core-zookeeper-0 1/1 Running 0 6m13s |
| 323 | simapp-6cccd6f787-jnxc7 1/1 Running 0 6m13s |
| 324 | smf-7f89c6d849-wzqvx 1/1 Running 0 6m13s |
| 325 | udm-768b9987b4-9qz4p 1/1 Running 0 6m13s |
| 326 | udr-8566897d45-kv6zd 1/1 Running 0 6m13s |
| 327 | upf-0 5/5 Running 0 6m13s |
| 328 | webui-5894ffd49d-gg2jh 1/1 Running 0 6m13s |
| 329 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 330 | If you see problematic pods that are not getting into the ``Running`` |
| 331 | state, a re-install usually corrects the problem. Type: |
| 332 | |
| 333 | .. code-block:: |
| 334 | |
| 335 | make aether-resetcore |
| 336 | |
| 337 | Once running, you will recognize pods that correspond to many of the |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 338 | microservices discussed is `Chapter 5 |
| 339 | <https://5g.systemsapproach.org/core.html>`__. For example, |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 340 | ``amf-5887bbf6c5-pc9g2`` implements the AMF. Note that for historical |
| 341 | reasons, the Aether Core is called ``omec`` instead of ``sd-core``. |
| 342 | |
| 343 | If you are interested in seeing the details about how SD-Core is |
| 344 | configured, look at |
| 345 | ``deps/5gc/roles/core/templates/radio-5g-values.yaml``. This is an |
Larry Peterson | 505d4b3 | 2023-08-21 14:39:45 -0700 | [diff] [blame] | 346 | example of a *values override* file that Helm passes along to |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 347 | Kubernetes when launching the service. Most of the default settings |
| 348 | will remain unchanged, with the main exception being the |
| 349 | ``subscribers`` block of the ``omec-sub-provision`` section. This |
| 350 | block will eventually need to be edited to reflect the SIM cards you |
| 351 | actually deploy. We return to this topic in the section describing how |
| 352 | to bring up a physical gNB. |
| 353 | |
| 354 | |
| 355 | Run Emulated RAN Test |
| 356 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 357 | |
| 358 | We can now test SD-Core with emulated traffic by typing: |
| 359 | |
| 360 | .. code-block:: |
| 361 | |
| 362 | $ make aether-gnbsim-install |
| 363 | $ make aether-gnbsim-run |
| 364 | |
| 365 | Note that you can re-execute the ``aether-gnbsim-run`` target multiple |
| 366 | times, where the results of each run are saved in a file within the |
| 367 | Docker container running the test. You can access that file by typing: |
| 368 | |
| 369 | .. code-block:: |
| 370 | |
| 371 | $ docker exec -it gnbsim-1 cat summary.log |
| 372 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 373 | If successful, the output should look like the following: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 374 | |
| 375 | .. code-block:: |
| 376 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 377 | 2023-08-09T19:57:09Z [INFO][GNBSIM][Summary] Profile Name: profile2 , Profile Type: pdusessest |
Larry Peterson | af9ea36 | 2023-08-11 16:40:19 -0700 | [diff] [blame] | 378 | 2023-08-09T19:57:09Z [INFO][GNBSIM][Summary] UEs Passed: 5 , UEs Failed: 0 |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 379 | 2023-08-09T19:57:09Z [INFO][GNBSIM][Summary] Profile Status: PASS |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 380 | |
| 381 | This particular test, which runs the cryptically named ``pdusessest`` |
Larry Peterson | af9ea36 | 2023-08-11 16:40:19 -0700 | [diff] [blame] | 382 | profile, emulates five UEs, each of which: (1) registers with the |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 383 | Core, (2) initiates a user plane session, and (3) sends a minimal data |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 384 | packet over that session. In addition to displaying the summary |
| 385 | results, you can also open a shell in the ``gnbsim-1`` container, |
| 386 | where you can view the full trace of every run of the emulation, each |
| 387 | of which has been saved in a timestamped file: |
| 388 | |
| 389 | .. code-block:: |
| 390 | |
| 391 | $ docker exec -it gnbsim-1 bash |
| 392 | bash-5.1# ls |
| 393 | gnbsim gnbsim1-20230809T125702.config summary.log |
| 394 | gnbsim.log gnbsim1-20230809T125702.log |
| 395 | bash-5.1# more gnbsim1-20230809T125702.log |
| 396 | 2023-08-09T19:57:05Z [INFO][GNBSIM][App] App Name: GNBSIM |
| 397 | 2023-08-09T19:57:05Z [INFO][GNBSIM][App] Setting log level to: info |
| 398 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB][gnb1] GNodeB IP: GNodeB Port: 9487 |
| 399 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB][UserPlaneTransport] User Plane transport listening on: 172.20.0.2:2152 |
| 400 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB] Current range selector value: 63 |
| 401 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB] Current ID range start: 1056964608 end: 1073741823 |
| 402 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB][ControlPlaneTransport] Connected to AMF, AMF IP: 10.76.28.113 AMF Port: 38412 |
| 403 | ... |
| 404 | |
Larry Peterson | 505d4b3 | 2023-08-21 14:39:45 -0700 | [diff] [blame] | 405 | .. admonition:: Troubleshooting Hint |
| 406 | |
| 407 | If ``summary.log`` is empty, it means the emulation did not run due |
| 408 | to a configuration error. To debug the problem, open a bash shell on |
| 409 | the gNBsim container (as shown in the preceding example), and look |
| 410 | at ``gnbsim.log``. Output that includes ``failed to connect amf`` |
| 411 | and ``err: address family not supported by protocol`` indicates that |
| 412 | your server does not have IPv6 enabled. |
| 413 | |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 414 | .. admonition:: Troubleshooting Hint |
| 415 | |
| 416 | If ``summary.log`` reports ``UEs Passed: 0 , UEs Failed: 5`` then it |
| 417 | is likely the case that SD-Core did not come up cleanly. Type |
| 418 | ``make aether-resetcore``, and after verifying all pods are running |
| 419 | with ``kubectl``, run gNBsim again. |
| 420 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 421 | If you are interested in the config file that controls the test, |
| 422 | including the option of enabling other profiles, take a look at |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 423 | ``deps/gnbsim/config/gnbsim-default.yaml``. We return to the issue of |
Larry Peterson | af9ea36 | 2023-08-11 16:40:19 -0700 | [diff] [blame] | 424 | customizing gNBsim in a later section, but for now there are some |
| 425 | simple modifications you can try. For example, the following code |
| 426 | block defines a set of parameters for ``pdusessest`` (also known as |
| 427 | ``profile2``): |
| 428 | |
| 429 | .. code-block:: |
| 430 | |
| 431 | - profileType: pdusessest # UE Initiated Session |
| 432 | profileName: profile2 |
| 433 | enable: true |
| 434 | gnbName: gnb1 |
| 435 | execInParallel: false |
| 436 | startImsi: 208930100007487 |
| 437 | ueCount: 5 |
| 438 | defaultAs: "192.168.250.1" |
| 439 | perUserTimeout: 100 |
| 440 | plmnId: |
| 441 | mcc: 208 |
| 442 | mnc: 93 |
| 443 | dataPktCount: 5 |
| 444 | opc: "981d464c7c52eb6e5036234984ad0bcf" |
| 445 | key: "5122250214c33e723a5dd523fc145fc0" |
| 446 | sequenceNumber: "16f3b3f70fc2" |
| 447 | |
| 448 | You can edit ``ueCount`` to change the number of UEs included in the |
| 449 | emulation (currently limited to 100) and you can set |
| 450 | ``execInParallel`` to ``true`` to emulate those UEs connecting to the |
| 451 | Core in parallel (rather than serially). You can also change the |
| 452 | amount of information gNBsim outputs by modifying ``logLevel`` in the |
| 453 | ``logger`` block at the end of the file. For any changes you make, |
| 454 | just rerun ``make aether-gnbsim-run`` to see the effects; you do not |
| 455 | need to reinstall gNBsim. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 456 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 457 | Clean Up |
| 458 | ~~~~~~~~~~~~~~~~~ |
| 459 | |
| 460 | We recommend continuing on to the next section before wrapping up, but |
| 461 | when you are ready to tear down your Quick Start deployment of Aether, |
| 462 | simply execute the following commands: |
| 463 | |
| 464 | .. code-block:: |
| 465 | |
| 466 | $ make aether-gnbsim-uninstall |
| 467 | $ make aether-5gc-uninstall |
| 468 | $ make aether-k8s-uninstall |
| 469 | |
| 470 | Note that while we stepped through the system one component at a time, |
| 471 | OnRamp includes compound Make targets. For example, you can uninstall |
| 472 | everything covered in this section by typing: |
| 473 | |
| 474 | .. code-block:: |
| 475 | |
| 476 | $ make aether-uninstall |
| 477 | |
| 478 | Look at the ``Makefile`` to see the available set of Make targets. |