llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 1 | Emulated RAN |
| 2 | ---------------- |
| 3 | |
| 4 | gNBsim emulates a 5G RAN, generating (mostly) Control Plane traffic |
| 5 | that can be directed at SD-Core. This section describes how to |
| 6 | configure gNBsim, so as to both customize and scale the workload it |
| 7 | generates. We assume gNBsim runs in one or more servers, independent |
| 8 | of the server(s) that host SD-Core. These servers are specified in the |
Larry Peterson | 782fec3 | 2023-10-09 12:30:57 -0700 | [diff] [blame^] | 9 | ``hosts.ini`` file, as described in the section on Scaling Aether. This |
| 10 | blueprint assumes you start with a variant of ``vars/main.yml`` |
| 11 | customized for running gNBsim. This is easy to do: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 12 | |
| 13 | .. code-block:: |
| 14 | |
| 15 | $ cd vars |
| 16 | $ cp main-gnbsim.yml main.yml |
| 17 | |
| 18 | Configure gNBsim |
| 19 | ~~~~~~~~~~~~~~~~~~ |
| 20 | |
| 21 | Two sets of parameters control gNBsim. The first set, found in the |
| 22 | ``gnbsim`` section of ``vars/main.yml``, controls how gNBsim is |
| 23 | deployed: (1) the number of servers it runs on; (2) the number of |
| 24 | Docker containers running within each server; (3) what configuration |
| 25 | to run in each of those containers; and |
| 26 | (4) how those containers connect to SD-Core. For example, consider the |
| 27 | following variable definitions: |
| 28 | |
| 29 | .. code-block:: |
| 30 | |
| 31 | gnbsim: |
| 32 | docker: |
| 33 | container: |
| 34 | image: omecproject/5gc-gnbsim:main-PR_88-cc0d21b |
| 35 | prefix: gnbsim |
| 36 | count: 2 |
| 37 | network: |
| 38 | macvlan: |
| 39 | name: gnbnet |
| 40 | |
| 41 | router: |
| 42 | data_iface: ens18 |
| 43 | macvlan: |
| 44 | iface: gnbaccess |
| 45 | subnet_prefix: "172.20" |
| 46 | |
| 47 | servers: |
| 48 | 0: |
| 49 | - "config/gnbsim-s1-p1.yaml" |
| 50 | - "config/gnbsim-s1-p2.yaml" |
| 51 | 1: |
| 52 | - "config/gnbsim-s2-p1.yaml" |
| 53 | - "config/gnbsim-s2-p2.yaml" |
| 54 | |
| 55 | The ``container.count`` variable in the ``docker`` block specifies how |
| 56 | many containers run in each server (``2`` in this example). The |
| 57 | ``router`` block then gives the network specification needed for these |
| 58 | containers to connect to the SD-Core; all of these variables are |
| 59 | described in the previous section on Networking. Finally, the |
| 60 | ``servers`` block names the configuration files that parameterize each |
| 61 | container. In this example, there are two servers with two containers |
| 62 | running in each, with ``config/gnbsim-s2-p1.yaml`` parameterizing the |
| 63 | first container on the second server. |
| 64 | |
| 65 | These config files then specify the second set of gNBsim parameters. |
| 66 | A detailed description of these parameters is outside the scope of |
| 67 | this guide (see https://github.com/omec-project/gnbsim for details), |
| 68 | but at a high-level, gNBsim defines a set of *profiles*, each of which |
| 69 | exercises a common usage scenario that the Core has to deal with. Each |
| 70 | of these sequences is represented by a ``profileType`` in the config |
| 71 | file. gNBsim supports seven profiles, which we list here: |
| 72 | |
| 73 | .. code-block:: |
| 74 | |
| 75 | - profileType: register # UE Registration |
| 76 | - profileType: pdusessest # UE Initiated Session |
| 77 | - profileType: anrelease # Access Network (AN) Release |
| 78 | - profileType: uetriggservicereq # UE Initiated Service Request |
| 79 | - profileType: deregister # UE Initiated De-registration |
| 80 | - profileType: nwtriggeruedereg # Network Initiated De-registration |
| 81 | - profileType: uereqpdusessrelease # UE Initiated Session Release |
| 82 | |
| 83 | The second profile (``pdusettest``) is selected by default. It causes |
| 84 | the specified number of UEs to register with the Core, initiate a user |
| 85 | plane session, and then send a minimal data packet over that session. |
| 86 | Note that the rest of the per-profile parameters are highly redundant. |
| 87 | For example, they specify the IMSI- and PLMD-related information UEs |
| 88 | need to connect to the Core. |
| 89 | |
| 90 | Finally, it is necessary to edit the ``core`` section of |
| 91 | ``vars/main.yml`` to indicate the address at which gNBsim can find the |
| 92 | AMF. For our running example, this would look like the following: |
| 93 | |
| 94 | .. code-block:: |
| 95 | |
| 96 | core: |
| 97 | amf: "10.76.28.113" |
| 98 | |
| 99 | |
| 100 | Install/Uninstall gNBsim |
| 101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 102 | |
| 103 | Once you have edited the parameters (and assuming you already have |
| 104 | SD-Core running), you are ready to install gNBsim. This includes starting |
| 105 | up all the containers and configuring the network so they can reach |
| 106 | the Core. This is done from the main OnRamp server you've been using, |
| 107 | where you type: |
| 108 | |
| 109 | .. code-block:: |
| 110 | |
| 111 | $ make gnbsim-docker-install |
| 112 | $ make aether-gnbsim-install |
| 113 | |
| 114 | Note that the first step may not be necessary, depending on whether |
| 115 | Docker is already installed on the server(s) you've designated to host |
| 116 | gNBsim. |
| 117 | |
| 118 | When you are finished, the following uninstalls everything: |
| 119 | |
| 120 | .. code-block:: |
| 121 | |
| 122 | $ make aether-gnbsim-uninstall |
| 123 | |
| 124 | Run gNBsim |
| 125 | ~~~~~~~~~~~~~~~~~~ |
| 126 | |
| 127 | Once gNBsim is installed and the Docker containers instantiated, you |
| 128 | can run the simulation by typing |
| 129 | |
| 130 | .. code-block:: |
| 131 | |
| 132 | $ make aether-gnbsim-run |
| 133 | |
| 134 | This can be done multiple times without reinstalling. For each run, |
| 135 | you can use Docker to view the results, which have been saved in each |
| 136 | of the containers. To do so, ssh into one of the servers designated to |
| 137 | to run gNBsim, and then type |
| 138 | |
| 139 | .. code-block:: |
| 140 | |
| 141 | $ docker exec -it gnbsim-1 cat summary.log |
| 142 | |
| 143 | Note that container name ``gnbsim-1`` is constructed from the |
| 144 | ``prefix`` variable defined in the ``docker`` section of |
| 145 | ``vars/main.yml``, with ``-1`` indicating the first container. |
Larry Peterson | 5d6b3b3 | 2023-09-05 15:11:55 -0700 | [diff] [blame] | 146 | |
| 147 | In addition to scaling up the workload you put on the Core, you can |
| 148 | also experiment with the emulation settings defined in any or all of |
| 149 | the config files in ``deps/gnbsim/config/``. Focusing on ``profile2`` |
| 150 | in particular (because it sends data packets after registering each |
| 151 | UE), variable ``defaultAs: "192.168.250.1"`` specifies the target of |
| 152 | ICMP Echo Request packets. Changing the value to the IP address of a |
| 153 | real-world server (e.g., ``8.8.8.8``) causes the emulated UE to |
| 154 | actually ping that server. Success is a good indication that your |
| 155 | Aether cluster is properly configured to support end-to-end |
| 156 | connectivity. |
| 157 | |