gNBSim Usage

Description

The gNBSim tool simulates gNodeB and UE by generating and processing NAS and NGAP messages for the configured UEs and call flows. The tool currently supports simulation profiles for the following procedures,

Registration
UE Initiated PDU Session Establishment
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
Helm Chart: gerrit repository
RAN SIM Helm Chart: 5g-ran-sim repository

Configure gNBSim

The sample config file for gNBSim can be found here
Note: The configuration has following major fields (Read the comments in the config file for more details)
- gnbs:
  List of gNB’s to be simulated. Each item in the list holds configuration specific to a gNB.
- 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 within profile block.
Note: Currently following profiles are supported

Run gNBSim

To quickly launch and test AiaB with 5G SD-CORE using gNBSim:
$ make 5g-test
(refer AiaB documentation Aether In a Box - 5G)
Alternatively, you can do following
running:
$ make 5g-core
Once all PODs are up then you can enter into the gNBSim pod by running
$ kubectl exec -it gnbsim-0 -n omec bash
Then run following command to launch gNBSim profiles:
$ ./gnbsim
Note: By default, the gNB Sim reads the configuration from /gnbsim/config/gnb.conf file. To provide a different configuration file, use the below command
$ ./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.

To modify gNBSim and build a new docker image:

$ git clone https://github.com/omec-project/gnbsim.git
$ cd gnbsim
$ make docker-build  #requires golang installed on the machine

To use newly created image in the AiaB cluster:

Update ~/aether-in-box/sd-core-5g-values.yaml to point to the newly built image, then run:

$ cd ~/aether-in-a-box/
$ make reset-5g-test
$ make 5g-test
(refer AiaB documentation Aether In a Box - 5G)

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

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.

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

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

- 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

config:
  gnbsim:
    goProfile:
      enable: true #enable/disable golang profile in gnbsim
      port: 5000

Run gNBSim with single Interface or multi interface

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

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

Support of Multiple gNBs: Two gnbs are configured by default. So User can create profiles by using these gnbs. Configuration of two gNBs can be found here

gnb:
  ips:
  - '"192.168.251.5/24"' #gnb1 IP
  - '"192.168.251.6/32"' #gnb2 IP
configuration:
  runConfigProfilesAtStart: true
  singleInterface: #this will be added thorugh configmap script
  execInParallel: false #run all profiles in parallel
  gnbs: # pool of gNodeBs
    gnb1:
      n2IpAddr: # gNB N2 interface IP address used to connect to AMF
      n2Port: 9487 # gNB N2 Port used to connect to AMF
      n3IpAddr: 192.168.251.5 # gNB N3 interface IP address used to connect to UPF
      n3Port: 2152 # gNB N3 Port used to connect to UPF
      name: gnb1 # gNB name that uniquely identify a gNB within application
      globalRanId:
        plmnId:
          mcc: 208 # Mobile Country Code (3 digits string, digit: 0~9)
          mnc: 93 # Mobile Network Code (2 or 3 digits string, digit: 0~9)
        gNbId:
          bitLength: 24
          gNBValue: "000102" # gNB identifier (3 bytes hex string, range: 000000~FFFFFF)
      supportedTaList:
      - tac: "000001" # Tracking Area Code (3 bytes hex string, range: 000000~FFFFFF)
        broadcastPlmnList:
          - plmnId:
              mcc: 208
              mnc: 93
            taiSliceSupportList:
                - sst: 1 # Slice/Service Type (uinteger, range: 0~255)
                  sd: "010203" # Slice Differentiator (3 bytes hex string, range: 000000~FFFFFF)
      defaultAmf:
        hostName: amf # Host name of AMF
        ipAddr: # AMF IP address
        port: 38412 # AMF port
    gnb2:
      n2IpAddr: # gNB N2 interface IP address used to connect to AMF
      n2Port: 9488 # gNB N2 Port used to connect to AMF
      n3IpAddr: 192.168.251.6 # gNB N3 interface IP address used to connect to UPF
      n3Port: 2152 # gNB N3 Port used to connect to UPF
      name: gnb2 # gNB name that uniquely identify a gNB within application
      globalRanId:
        plmnId:
          mcc: 208 # Mobile Country Code (3 digits string, digit: 0~9)
          mnc: 93 # Mobile Network Code (2 or 3 digits string, digit: 0~9)
        gNbId:
          bitLength: 24
          gNBValue: "000112" # gNB identifier (3 bytes hex string, range: 000000~FFFFFF)
      supportedTaList:
      - tac: "000001" # Tracking Area Code (3 bytes hex string, range: 000000~FFFFFF)
        broadcastPlmnList:
          - plmnId:
              mcc: 208
              mnc: 93
            taiSliceSupportList:
                - sst: 1 # Slice/Service Type (uinteger, range: 0~255)
                  sd: "010203" # Slice Differentiator (3 bytes hex string, range: 000000~FFFFFF)
      defaultAmf:
        hostName: amf # Host name of AMF
        ipAddr: # AMF IP address
        port: 38412 # AMF port

Delay between Procedures can be added using customProfiles.