gNBSim document update
Added release notes, gNBSim document.
Updating BESS version
Change-Id: I21fcd972389563de8b9fd4b62b3e33d1108d5bae
diff --git a/developer/gnbsim.rst b/developer/gnbsim.rst
index e09deb7..0fcf5a4 100644
--- a/developer/gnbsim.rst
+++ b/developer/gnbsim.rst
@@ -3,105 +3,8 @@
SPDX-License-Identifier: Apache-2.0
.. _gNB-Simulator:
-gNB Simulator Deployment
-========================
-
-gNB Simulator can be deployed in following modes,
-
-**gNB simulator in AIAB mode with 2 interfaces:**
--------------------------------------------------
-
-- This is default mode of deployment for gNB Simulator
-- Multus cni needs to be enabled on cluster. Required for bess-upf & gNBSim
-- `make 5gc` will by default deploy gNB Simulator in this mode
-- One interface is used for user plane traffic towards UPF
-- Second interface is used to send traffic towards control plane (i.e. AMF).
-- UPF network & default gateway is provided in the override values.
-- Route to UPF network is added when POD comes up
-- defaultAs is configured per profile. This address is used to send data traffic during test
-
-.. note::
- Multiple gNB's in one simulator instance need more changes in helm chart. This is pending work.
-
-To add UPF routes. Following is example of override values ::
-
- config:
- gnbsim:
- gnb:
- ip: 192.168.251.5/24 #user plane IP at gnb if 2 separate interface provided
- singleInterface: false
- networkTopo:
- - upfAddr: "192.168.252.3/32"
- upfGw: "192.168.251.1"
-
-
-.. image:: ../_static/images/Single-cluster_2_interface.jpg
- :width: 700px
-
-**gNB simulator running standalone with 2 or more interfaces**
---------------------------------------------------------------
-
-- Install gNB Simulator on any K8s cluster
-- Multus cni needs to be enabled on cluster. Required for bess-upf & gNB
-- Make sure gNB Simulator can communicate with AMF & UPF
-- *TODO* - New Makefile target will deploy just 5G control plane
-- *TODO* - New Makefile target will deploy only gNB Simulator
-- One interface is used for user plane traffic towards UPF
-- Second interface is used to send traffic towards control plane (i.e. AMF).
-- UPF network & default gateway is provided in the override values.
-- Route to UPF network is added when POD comes up
-- defaultAs is configured per profile. This address is used to send data traffic during test
-- configure AMF address or FQDN appropriately
-
-.. note::
- Multiple gNB's in one simulator instance need more changes in helm chart. This is pending work.
-
-
-To add UPF routes. Following is example of override values ::
-
- config:
- gnbsim:
- gnb:
- ip: 192.168.251.5/24 #user plane IP at gnb if 2 separate interface provided
- singleInterface: false
- networkTopo:
- - upfAddr: "192.168.252.3/32"
- upfGw: "192.168.251.1"
-
-.. image:: ../_static/images/Separate-cluster_2_interface.jpg
- :width: 700px
-
-
-**gNB simulator running standalone with single interface**
-----------------------------------------------------------
-
-- Install gNB Simulator on any K8s cluster
-- Multus cni needs to be enabled for the K8s cluster where bess-upf runs
-- Make sure gNB Simulator can communicate with AMF & UPF
-- *TODO* - New Makefile target will deploy just 5G control plane
-- *TODO* - New Makefile target will deploy only gNB Simulator
-- Single interface is used for user plane traffic towards UPF & as well traffic towards AMF
-- defaultAs is configured per profile. This address is used to send data traffic during test
-- configure AMF address or FQDN appropriately
-
-.. note::
- Multiple gNB's can not be simulated since only 1 gNB will be able to use 2152 port
-
-
-Following is example of override values ::
-
- config:
- gnbsim:
- singleInterface: true
- yamlCfgFiles:
- gnb.conf:
- configuration:
- gnbs: # pool of gNodeBs
- gnb1:
- n3IpAddr: "POD_IP" # set if singleInterface is true
-
-.. image:: ../_static/images/Separate-cluster_Single_interface.jpg
- :width: 700px
+gNBSim Usage
+=============
Description
-----------
@@ -114,15 +17,25 @@
* UE Initiated De-registration.
* AN Release
* Ue Initiated Service Request Procedure
+* NW triggered de-registration
+* UE Requested PDU Session Release
+* NW triggered PDU Session Release
It is also capable to generate and send user data packets (ICMP echo request)
and process down-link user data (ICMP echo response) over the established data
plane path (N3 Tunnel).
+gNBSim Code References
+----------------------
+
+* Code Repository: `github repository <https://github.com/omec-project/gnbsim>`_
+* Helm Chart: `gerrit repository <https://gerrit.opencord.org/plugins/gitiles/sdcore-helm-charts/+/refs/heads/master/5g-ran-sim/>`_
+* RAN SIM Helm Chart: `5g-ran-sim repository <https://charts.aetherproject.org>`_
+
Configure gNBSim
------------------------
-* The config file for gNBSim can be found at *<repo dir>/config/gnbsim.yaml*
+-----------------
+* The sample config file for gNBSim can be found `here <https://github.com/omec-project/gnbsim/blob/main/config/gnbsim.yaml>`_
*Note: The configuration has following major fields (Read the comments in
the config file for more details)*
@@ -133,27 +46,17 @@
* **profiles**:
List of test/simulation profiles. Each item in the list holds
configuration specific to a profile.
+ * **customProfiles**:
+ List of custom profiles. Each item in the list holds
+ configuration specific to a customProfile.
-* Enable or disable a specific profile using the **enable** field.
+* Enable or disable a specific profile using the `enable` field within profile block.
+ Note: Currently following profiles are supported
- *Note: Currently following profiles are supported*
-
- * **register**:
- Registration procedure
- * **pdusessest** (Default):
- Registration + UE initiated PDU Session Establishment + User Data packets
- * **deregister**:
- Registration + UE initiated PDU Session Establishment + User Data packets
- + Deregister
- * **anrelease**:
- Registration + UE initiated PDU Session Establishment + User Data packets
- + AN Release
- * **uetriggservicereq**:
- Registration + UE initiated PDU Session Establishment + User Data packets
- + AN Release + UE Initiated Service Request
Run gNBSim
-----------
+
* To quickly launch and test AiaB with 5G SD-CORE using gNBSim:
.. code-block:: bash
@@ -162,14 +65,20 @@
(refer AiaB documentation :ref:`aiab5g-guide`)
-* Alternatively, once 5G SD-CORE is up, you can enter into the gNBSim pod by
+* Alternatively, you can do following
running:
.. code-block:: bash
+ $ make 5g-core
+
+* Once all PODs are up then you can enter into the gNBSim pod by running
+
+ .. code-block:: bash
+
$ kubectl exec -it gnbsim-0 -n omec bash
- Then run following command to launch gNBSim:
+* Then run following command to launch gNBSim profiles:
.. code-block:: bash
@@ -184,7 +93,7 @@
$ ./gnbsim --cfg <config file path>
Build gNBSim
--------------------
+------------
* If you find a need to change gNBSim code and use the updated image in the AIAB setup then
follow below steps.
@@ -214,3 +123,122 @@
(refer AiaB documentation :ref:`aiab5g-guide`)
+gNBSim System level features
+----------------------------
+
+* Logging summary result
+
+* HTTP API to create new profile. Below configuration enables http server in gNBSim.
+ Example to use gNBSim can be found `script <https://github.com/omec-project/gnbsim/blob/main/scripts/create-new-profile.sh>`_
+
+ .. code-block:: bash
+
+ config:
+ gnbsim:
+ httpServer:
+ enable: true #enable httpServer in gnbsim
+ port: 6000
+
+* Gnbsim can generate and send user data packets (ICMP echo request)
+ and process downlink user data (ICMP echo response) over the established data
+ plane path (N3 Tunnel). Configure number of data packets to be sent. Configure
+ AS (Application Server) address. This is used to send data packets.
+
+ .. code-block:: bash
+
+ - profileType: nwtriggeruedereg # profile type
+ profileName: profile6 # uniqely identifies a profile within application
+ enable: false # Set true to execute the profile, false otherwise.
+ gnbName: gnb1 # gNB to be used for this profile
+ startImsi: 208930100007497 # First IMSI. Subsequent values will be used if ueCount is more than 1
+ ueCount: 1 # Number of UEs for for which the profile will be executed
+ defaultAs: "192.168.250.1" #default icmp pkt destination
+ perUserTimeout: 10 #if no expected event received in this time then treat it as failure
+
+
+* Executing all enabled profiles in parallel or in sequential order.
+
+ .. code-block:: bash
+
+ config:
+ gnbsim:
+ yamlCfgFiles:
+ gnb.conf:
+ configuration:
+ execInParallel: false #run all profiles in parallel
+
+.. note::
+ There is execInParallel option under each profile as well. execInParallel under profile means that all the
+ subscribers in the profile are run in parallel
+
+* Timeout for each call flow within profile
+
+ .. code-block:: bash
+
+ - profileType: nwtriggeruedereg # profile type
+ profileName: profile6 # uniqely identifies a profile within application
+ perUserTimeout: 10 #if no expected event received in this time then treat it as failure
+
+* Getting gNBSim golang profile
+
+ .. code-block:: bash
+
+ config:
+ gnbsim:
+ goProfile:
+ enable: true #enable/disable golang profile in gnbsim
+ port: 5000
+
+* Run gNBSim with single Interface or multi interface
+
+ .. code-block:: bash
+
+ config:
+ gnbsim:
+ yamlCfgFiles:
+ gnb.conf:
+ configuration:
+ singleInterface: false #default false i.e. multiInterface. Works well for AIAB
+
+* Support of Custom Profiles: User can now define your own profile. New profile can be
+ created by using existing baseline procedure. Example of custom profile can be found here.
+ Check customProfiles in `gNBSim config <https://github.com/omec-project/gnbsim/blob/main/config/gnbsim.yaml>_`
+
+ .. code-block:: bash
+
+ customProfiles:
+ customProfiles1:
+ profileType: custom # profile type
+ profileName: custom1 # uniqely identifies a profile within application
+ enable: false # Set true to execute the profile, false otherwise.
+ execInParallel: false #run all subscribers in parallel
+ stepTrigger: true #wait for trigger to move to next step
+ gnbName: gnb1 # gNB to be used for this profile
+ startImsi: 208930100007487
+ ueCount: 5
+ defaultAs: "192.168.250.1" #default icmp pkt destination
+ opc: "981d464c7c52eb6e5036234984ad0bcf"
+ key: "5122250214c33e723a5dd523fc145fc0"
+ sequenceNumber: "16f3b3f70fc2"
+ plmnId: # Public Land Mobile Network ID, <PLMN ID> = <MCC><MNC>
+ mcc: 208 # Mobile Country Code (3 digits string, digit: 0~9)
+ mnc: 93 # Mobile Network Code (2 or 3 digits string, digit: 0~9)
+ startiteration: iteration1
+ iterations:
+ #at max 7 actions
+ - "name": "iteration1"
+ "1": "REGISTRATION-PROCEDURE 5"
+ "2": "PDU-SESSION-ESTABLISHMENT-PROCEDURE 5" #5 second delay after this procedure
+ "3": "USER-DATA-PACKET-GENERATION-PROCEDURE 10"
+ "next": "iteration2"
+ - "name": "iteration2"
+ "1": "AN-RELEASE-PROCEDURE 100"
+ "2": "UE-TRIGGERED-SERVICE-REQUEST-PROCEDURE 10"
+ "repeat": 5
+ "next": "iteration3"
+ - "name": "iteration3"
+ "1": "UE-INITIATED-DEREGISTRATION-PROCEDURE 10"
+ #"repeat": 0 #default value 0 . i.e execute once
+ #"next": "quit" #default value quit. i.e. no further iteration to run
+
+* Delay between Procedures can be added using customProfiles.