Skip to content
This repository was archived by the owner on Feb 16, 2023. It is now read-only.

Application Note

Jump to bottom
David Rupprecht edited this page Oct 18, 2021 · 12 revisions

The CoreScope application combines the gNodeB and UE components of srsRAN for the purposes of exercising 5G core networks, without the need for RF-hardware. It does this by emulating control and data RAN traffic identical to that generated by real UE and eNodeB/gNodeB devices. CoreScope is 5G SA ready.

It's main use-cases are to:

  • Exercise core network functionality and analyze key performance metrics to quickly detect and resolve problems.
  • Rapidly identify network misconfigurations and highlight bottlenecks.
  • Test for security vulnerabilities and easily integrate CoreScope with third-party tools using our non-proprietary logging and packet capture outputs.

Introduction

In this application note we will connect CoreScope to a 3rd-party 5G core, namely Open5GS, to exercise and test the core. We will do this without RF-hardware, and use Open5GS in a virtual environment. All of this will be done locally, on one machine.

Dependencies & 3rd Party Applications

CoreScope requires both OAT++ and srsRAN, as well as their associated dependencies to run correctly. The process for downloading and installing these will be detailed here. OAT++ will need to be installed before CoreScope, as it is required for CoreScope to compile correctly.

Details on how to download and install Open5GS can be found here. Note for this application note we will be using Open5GS within a virtual machine, running through VirtualBox.

OAT++

First, you will need to install OAT++ for the REST API that CoreScope uses. This can be done using the following commands:

git clone https://github.com/oatpp/oatpp
cd oatpp
mkdir build
cd build
cmake ..
sudo make install

Once this is complete you will need the OAT++ Swagger module. This can be downloaded and installed with the following commands:

git clone https://github.com/oatpp/oatpp-swagger
cd oatpp-swagger
mkdir build
cd build
cmake ..
sudo make install

CoreScope

To install CoreScope you will need to install these dependencies first, and make sure they are up to date:

sudo apt-get install cmake libfftw3-dev libmbedtls-dev libboost-program-options-dev libconfig++-dev libsctp-dev

CoreScope includes srsRAN as a submodule, this means you are not required to have srsRAN pre-installed before building CoreScope. If you already have srsRAN installed then it is recommended that you either run CoreScope from the build folder (i.e. do not install it), or else create a local install for CoreScope. This stops any possible conflicts with other installations of srsRAN. For this example we will be running CoreScope from within the build folder.

To download and build CoreScope use the following commands:

git clone git@github.com:softwareradiosystems/corescope.git --recurse-submodules
cd corescope
mkdir build
cd build
cmake ../
make -j $(nproc)
make test -j $(nproc)

If you want to create a local install of CoreScope you can add the following flag to the cmake command:

cmake .. -DCMAKE_INSTALL_PREFIX=~/<install location>

CoreScope

To configure CoreScope changes need to be made to the configuration file. The AMF, N1C and GTP addresses need to be chnaged, as well as the PLMN and TAC.

First, copy the configuration file to your home folder:

corescope$ mkdir -p $HOME/.config/srsran
corescope$ cp ./corescope/corescope.conf.example $HOME/.config/srsran/corescope.conf

The following addresses should be used for the AMF, N1C and GTP:

  • AMF: Outgoing IP of VM
  • N1C: IP of VM host-only adapter on local machine
  • GTP: IP of VM host-only adapter on local machine

Using the values of the IPs from the example set-up, we use 192.168.56.101 and 192.168.56.1.

The PLMN and TAC also need to be changed in the config file to match the values used in the Core. The defualt values from Open5GS are:

  • TAC: 0x01
  • MCC: 901
  • MNC: 70

These values can be found in the config file sample.yaml found in the Open5GS config folder in the VM.

The CoreScope configuration file should then look like the following:

#####################################################################
[gnb]
gnb_id  = 0x19B
name    = "srsgnb"
cell_id = 0x01
tac     = 0x01
mcc     = 901
mnc     = 70

amf_addr      = 192.168.56.101
gtp_bind_addr = 192.168.56.1
n1c_bind_addr = 192.168.56.1
#####################################################################

CoreScope is now configured to test the core.

Testing the Core

To exercise the core network using CoreScope, Open5GS needs to be running on the VM, CoreScope should then be run from your local machine. It will automatically connect to the core. Once the connection has been made tests can be run to exercise the core.

Running CoreScope

First make sure the core is running. If not, CoreScope will be unable to register.

To run CoreScope, navigate to the build folder and run CoreScope with the following command:

cd corescope/build/corescope/src 
sudo ./corescope

CoreScope should now run and automatically connect to the core. You should see something similar to the following in the console running CoreScope:

=== CoreScope started ===
API server running on port 8000
PDU Session Establishment successful. IP: 10.45.0.3

Note:

If you run CoreScope and receive error messages, check that the IPs, the PLMN and the TAC are consistent between the core and CoreScope. If needs be, edit the config files and restart both the core and CoreScope.

Example Test Application

To quickly test the connection, CoreScope comes with a python test application called corescope-tester.py. This aims to demonstrate a simple test, by adding a UE, and pinging the core.

First, locate the file where it is stored in the corescope folder:

cd examples/core-scope-api-client

Now configure the application so that is uses the correct IP for the core. This is done on line 13 of the source code, it should look like the following:

client = Client(base_url="http://127.0.0.1:8000", timeout=5)

The tester can now be run:

./corescope-tester.py

You should see the following in the console once the test has run successfully:

Adding UE
Added UE with ue_id 0
Switching UE on
Sending data over tun interface...
PING 10.45.0.1 (10.45.0.1) from 10.45.0.3 tun_ue_0: 56(84) bytes of data.
64 bytes from 10.45.0.1: icmp_seq=1 ttl=64 time=0.541 ms
64 bytes from 10.45.0.1: icmp_seq=2 ttl=64 time=0.601 ms
64 bytes from 10.45.0.1: icmp_seq=3 ttl=64 time=0.460 ms

--- 10.45.0.1 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2031ms
rtt min/avg/max/mdev = 0.460/0.534/0.601/0.057 ms
Sleeping for a while

CoreScope will automatically add a TUN/TAP interface for each successfully connected UE, which then allows it to send traffic to the network.

Swagger UI

CoreScope has an integrated Web UI through the use of OAT++ and the Swagger module. This allows users to explore the complete functionality of CoreScope and view live reports of metrics.

It can be accessed via your web broswer by visiting http://localhost:8000/swagger/ui while CoreScope is running.

The following functions are currently supported:

  • GET/corescope​/api​/gnb​/{gnbId}​/status => Get gNodeB status by gnbID
  • GET/corescope​/api​/gnb​/{gnbId}​/config => Get gNodeB current configuration by gnbID
  • POST/corescope​/api​/gnb​/{gnbId}​/ue => Create a UE at a gNodeB.
  • GET/corescope​/api​/gnb​/{gnbId}​/ue​/{ueId} => Gets the current UE configuration
  • GET/corescope​/api​/gnb​/{gnbId}​/ue​/{ueId}​/status => Gets the current UE status
  • PUT/corescope​/api​/gnb​/{gnbId}​/ue​/{ueId}​/status => Update UE Status (Switch on and off)

When you launch the UI you should see the following:

ui

Further Functionality

Python API for CoreScope can be generated with the openapi-python-client.

With the WebUI running, the following command can be used to generate the code:

openapi-python-client generate --url http://localhost:8000/api-docs/oas-3.0.0.json

This API code is already provided in the /corescope/examples/corescope-api-client folder.

These applications can be used to spawn UEs and gNBs while CoreScope is running to excercise the core as per the users needs.

UE Configuration

UEs are created via the API (OpenAPI), which is provided by Corescope on localhost:8000. A tester Python script to spawn UEs can be found in /$HOME/corescope/examples/corescope-api-client/corescope-tester.py. We already provide you the Python API code including an example script in: /corescope/examples/corescope-api-client/.

Optional: Generate Python code.

The Python API code can by generated with openapi-python-client and the following command.

openapi-python-client generate --url http://localhost:8000/api-docs/oas-3.0.0.json

USIM Configuration

The test script can be modified to adjust USIM parameters. Enter valid credentials to attach to the mobile network.

ue_args.usim = dto_ue_args.DtoUeUsimArgs(
    # mode: Union[Unset, str] = "soft"
    # algo: Union[Unset, str] = "mil"
    # using_op: Union[Unset, bool] = False
    # op: Union[Unset, str] = ""
    # opc: Union[Unset, str] = "63bfa50ee6523365ff14c1f45f88737d"
    # imsi: Union[Unset, str] = "001010123456780"
    # imei: Union[Unset, str] = "353490069873310"
    # k: Union[Unset, str] = "00112233445566778899aabbccddeeff"
    # pin: Union[Unset, str] = ""
    # reader: Union[Unset, str] = ""
)

APN Configuration

Parameters important for the NAS, such as APN configuration can be adjusted aswell. The core network might require specific APN settings. Uncomment and edit the following lines:

ue_args.nas_5g = dto_ue_args.DtoUeNas5gArgs(
    # force_imsi_attach: Union[Unset, bool] = False
    # eia: Union[Unset, str] = "1, 2"
    # eea: Union[Unset, str] = "0, 1, 2"
    # pdu_sessions: Union[Unset, List[DtoUeNasPduSessionArgs]] = UNSET
    # ia5g: Union[Unset, str] = "1, 2"
    # ea5g: Union[Unset, str] = "0, 1, 2"
)
ue_args.nas_5g.pdu_sessions = list()

pdu_session_1 = dto_ue_nas_pdu_session_args.DtoUeNasPduSessionArgs()
pdu_session_1.apn_name = "internet"
ue_args.nas_5g.pdu_sessions.append(pdu_session_1)

Adding the UE

add_ue_data: Response[dto_ue_id.DtoUeId] = create_ue.sync_detailed(
    client=client, gnb_id=0, json_body=ue_args)

Limitations

Troubleshooting

CoreScope Wiki

Clone this wiki locally