Quality of Service (QoS) with OAI 5G Core Network¶
Reading time: ~ 30mins
Tutorial replication time: ~ 1hs
This tutorial explains how to configure and test Quality of Service (QoS) in the OAI 5G Core network. QoS allows different treatment of traffic flows based on their requirements, prioritising certain traffic types over others to ensure an optimal user experience for critical applications.
1. Prerequisites¶
Create a folder where you can store all the result files of the tutorial and later compare them with our provided result files. We recommend creating exactly the same folder to not break the flow of commands afterwards.
Ensure that the following tools are installed and meet the required versions:
- awk: Version >= 5.1.0
You can check the version ofawkinstalled on your system using the following command:If the version is lower than 5.1.0, updateawk --versionawkusing your package manager (e.g.,sudo apt install gawkon Ubuntu).
docker-compose-host $: mkdir -p /tmp/oai/qos-testing
docker-compose-host $: chmod 777 /tmp/oai/qos-testing
2. Architecture Overview¶
The QoS framework in OAI 5G Core enables: * Different traffic treatment based on 5QI (5G QoS Identifier) values * Control over bitrates for downlink * Definition of PCC (Policy and Charging Control) rules * QoS enforcement at the UPF using eBPF datapath
+-------+
| N6 |
+-------+
^
| DL Packet
|
v
+---------------------+
| XDP Program (Set 1) |
| (Pre-processing) |
+---------------------+
|
| XDP Program (Set 1)
| (Pre-processing)
|
v
+---------------------+
| XDP Program (Set 2) |
| (Enforce FAR) |
+---------------------+
|
| QoS Enabled?
|
+-----------------+
| Yes | No (Bypass TC)
| |
v v
+-----------------+ (Directly to N3)
| N6 TC Ingress | |
| (QoS Operations,| |
| Redirect to N3) | |
+-----------------+ |
| |
v |
+-----------------+ |
| N3 TC Egress | |
| (QoS Operation) | |
+-----------------+ |
| |
| |
| |
|<----------------+
v
+-------+
| N3 |
+-------+
3. Database Configuration¶
First, we need to configure the subscriber database with UEs having different QoS profiles in mysql database file.
In the table SessionManagementSubscriptionData add the following entries with varying QoS settings. We put a static IP to make it easier to know the expected bitrate per IP addresss:
INSERT INTO `SessionManagementSubscriptionData` (`ueid`, `servingPlmnid`, `singleNssai`, `dnnConfigurations`) VALUES
('208950000000033', '20895', '{\"sst\": 222, \"sd\": \"00007B\"}','{\"default\":{\"pduSessionTypes\":{ \"defaultSessionType\": \"IPV4\"},\"sscModes\": {\"defaultSscMode\": \"SSC_MODE_1\"},\"5gQosProfile\": {\"5qi\": 6,\"arp\":{\"priorityLevel\": 1,\"preemptCap\": \"NOT_PREEMPT\",\"preemptVuln\":\"NOT_PREEMPTABLE\"},\"priorityLevel\":1},\"sessionAmbr\":{\"uplink\":\"100Mbps\", \"downlink\":\"100Mbps\"},\"staticIpAddress\":[{\"ipv4Addr\": \"12.1.1.8\"}]}}');
4. PCF Policy Configuration¶
QoS in 5G is applied through policy configuration. We need to create several configuration files for the PCF. See the examples below.
4.1. Configure QoS Profiles¶
Create the QoS data configuration file:
# QoS settings for non-GBR flows with different 5QI values
non-gbr-qos-5qi-9:
5qi: 9
arp:
priorityLevel: 4
preemptCap: NOT_PREEMPT
preemptVuln: PREEMPTABLE
priorityLevel: 80
maxbrUl: "10Mbps"
maxbrDl: "10Mbps"
4.2. Configure PCC Rules¶
Create the PCC rules configuration file:
# PCC rules associating traffic flows with QoS profiles
non-gbr-rule-5qi-9:
flowInfos:
- flowDescription: permit out ip from any to assigned
packetFilterUsage: true
precedence: 10
refQosData:
- non-gbr-qos-5qi-9
4.3. Configure Policy Decisions¶
Create the policy decisions configuration file:
# Map UEs (by SUPI) to PCC rules
decision_supi1:
supi_imsi: "208950000000033"
pcc_rules:
- non-gbr-rule-5qi-9
5. Core Network Configuration¶
5.1. Configure PCF to Use Policy Files¶
Update the PCF configuration in the config file file to point to our policy files:
pcf:
local_policy:
policy_decisions_path: /openair-pcf/policies/policy_decisions
pcc_rules_path: /openair-pcf/policies/pcc_rules
traffic_rules_path: /openair-pcf/policies/traffic_rules
qos_data_path: /openair-pcf/policies/qos_data
5.2. Enable QoS in UPF¶
Update the UPF configuration in the config file file to enable QoS enforcement:
upf:
support_features:
enable_bpf_datapath: yes # If "yes": BPF is used as datapath else simpleswitch is used
enable_qos: yes # Enable QoS enforcement at the UPF
remote_n6_gw: oai-ext-dn
upf_info:
sNssaiUpfInfoList:
- sNssai:
sst: 222
sd: "00007B"
dnnUpfInfoList:
- dnn: "default"
5.3. Update Docker-Compose File¶
Create a docker-compose.yaml file that includes volume mounts for the policy files:
version: '3.8'
services:
oai-pcf:
volumes:
- ./policies/qos/policy_decisions:/openair-pcf/policies/policy_decisions
- ./policies/qos/pcc_rules:/openair-pcf/policies/pcc_rules
- ./policies/qos/qos_data:/openair-pcf/policies/qos_data
We will use docker-compose-basic-nrf-qos.yaml which already has the volume mounts applied.
6. Network Function Deployment¶
In the previous tutorial we explain how to deploy the core network using our python deployer. Here we will only provide quick commands needed to deploy the core network, to learn how to use the python deployer please follow this page.
- Start the core network components with QoS enabled
As a first timer, we recommend to first run without any PCAP capture.
docker-compose-host $: python3 core-network.py --type start-basic-qos --scenario 1
For CI purposes, we are deploying with an automated PCAP capture on the docker network.
REMEMBER: if you are planning to run your CN5G deployment for a long time, the PCAP file can become huge!
docker-compose-host $: python3 core-network.py --type start-basic-qos --scenario 1 --capture /tmp/oai/qos-testing/qos-testing.pcap
The output will look like this:
[2023-08-10 15:43:22,365] root:DEBUG: Starting 5gcn components...
[2023-08-10 15:43:22,365] root:DEBUG: docker-compose -f docker-compose-basic-nrf-qos.yaml up -d
Creating network "demo-oai-public-net" with the default driver
Creating mysql ...
Creating oai-nrf ...
Creating oai-udr ...
Creating oai-udm ...
Creating oai-ext-dn ...
Creating oai-ausf ...
Creating mysql ... done
Creating oai-nrf ... done
Creating oai-udr ... done
Creating oai-udm ... done
Creating oai-ausf ... done
Creating oai-ext-dn ... done
Creating oai-amf ...
Creating oai-amf ... done
Creating oai-upf ...
Creating oai-upf ... done
Creating oai-smf ...
Creating oai-smf ... done
Creating oai-pcf ...
Creating oai-pcf ... done
If you want to use docker compose directly to deploy OAI 5G Core
docker-compose-host $: docker-compose -f docker-compose-basic-nrf-qos.yaml up -d
Verify that all containers are running correctly:
docker-compose-host $: docker ps
7. Testing QoS Enforcement¶
For testing QoS, we’ll use UERANSIM to simulate UEs with different QoS profiles and measure the achieved throughput using iperf3.
7.1. Deploy UERANSIM¶
The configurations are as follows:
- ueransim/oai-cn5g-gnb.yaml: gNB configuration
- ueransim/ue-5qi-1.yaml: UE configuration for the 5QI-1 UE (3 Mbps)
- ueransim/ue-5qi-3.yaml: UE configuration for the 5QI-3 UE (100 Mbps)
You can create more UEs by creating a UE configuration file and updating the docker-compose-ueransim-qos.yaml to add the UE.
Now deploy UERANSIM:
docker-compose-host $: docker-compose -f docker-compose-ueransim-qos.yaml up -d
7.2. Test QoS Enforcement¶
First, check that the UE is registered and has an IP address:
docker-compose-host $: docker exec ueransim-ue-5qi-1 ping -c 3 -I uesimtun0 192.168.72.135
Now, start an iperf3 server in the UE to test Downlink QoS enforcement:
docker-compose-host $: docker exec -d ueransim-ue-5qi-1 iperf3 -s -B 12.1.1.10
Next, run an iperf3 client in the UE to test throughput:
docker-compose-host $: docker exec oai-ext-dn iperf3 -t 4 -c 12.1.1.10 -B 192.168.72.135 -J > /tmp/oai/qos-testing/iperf_result_ue-5qi-1.json
The output will look like this:
Connecting to host 12.1.1.10, port 5201
[ 5] local 192.168.72.135 port 48777 connected to 12.1.1.10 port 5201
[ ID] Interval Transfer Bitrate Retr Cwnd
[ 5] 0.00-1.00 sec 411 KBytes 3.36 Mbits/sec 0 47.4 KBytes
[ 5] 1.00-2.00 sec 382 KBytes 3.13 Mbits/sec 0 64.5 KBytes
[ 5] 2.00-3.00 sec 425 KBytes 3.48 Mbits/sec 0 80.3 KBytes
[ 5] 3.00-4.00 sec 379 KBytes 3.11 Mbits/sec 0 97.4 KBytes
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval Transfer Bitrate Retr
[ 5] 0.00-4.00 sec 1.56 MBytes 3.27 Mbits/sec 0 sender
[ 5] 0.00-4.33 sec 1.42 MBytes 2.75 Mbits/sec receiver
iperf Done.
Notice how the throughput stays close to but below 20 Mbps, which is the configured limit for this UE.
7.3. Test Different QoS Profiles¶
You can repeat the test with different UEs to confirm that the QoS limits are enforced correctly. You’ll need to create additional UE configurations and modify the docker-compose file for UERANSIM to include them.
For example, to test the UE with 5QI-3 (100 Mbps limit):
The throughput should be limited to approximately 100 Mbps for this UE.
Now, start an iperf3 server in the UE to test Downlink QoS enforcement:
docker-compose-host $: docker exec -d ueransim-ue-5qi-3 iperf3 -s -B 12.1.1.9
Next, run an iperf3 client in the UE to test throughput:
docker-compose-host $: docker exec oai-ext-dn iperf3 -t 4 -c 12.1.1.9 -B 192.168.72.135 -J > /tmp/oai/qos-testing/iperf_result_ue-5qi-3.json
The output will look like this:
Connecting to host 12.1.1.9, port 5201
[ 5] local 192.168.72.135 port 44757 connected to 12.1.1.9 port 5201
[ ID] Interval Transfer Bitrate Retr Cwnd
[ 5] 0.00-1.00 sec 12.6 MBytes 106 Mbits/sec 0 591 KBytes
[ 5] 1.00-2.00 sec 12.5 MBytes 105 Mbits/sec 0 1.13 MBytes
[ 5] 2.00-3.00 sec 11.2 MBytes 94.4 Mbits/sec 50 1008 KBytes
[ 5] 3.00-4.00 sec 11.2 MBytes 94.4 Mbits/sec 0 1.09 MBytes
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval Transfer Bitrate Retr
[ 5] 0.00-4.00 sec 47.6 MBytes 99.8 Mbits/sec 50 sender
[ 5] 0.00-4.14 sec 45.2 MBytes 91.6 Mbits/sec receiver
iperf Done.
8. Log Collection¶
- Stop PCAP collection: Stop the wireshark or tshark process on the docker-compose-host.
docker-compose-host $: pkill tshark
- Collect the logs of all the components:
docker-compose-host $: docker logs oai-amf > /tmp/oai/qos-testing/amf.log 2>&1
docker-compose-host $: docker logs oai-smf > /tmp/oai/qos-testing/smf.log 2>&1
docker-compose-host $: docker logs oai-nrf > /tmp/oai/qos-testing/nrf.log 2>&1
docker-compose-host $: docker logs oai-upf > /tmp/oai/qos-testing/upf.log 2>&1
docker-compose-host $: docker logs oai-udr > /tmp/oai/qos-testing/udr.log 2>&1
docker-compose-host $: docker logs oai-udm > /tmp/oai/qos-testing/udm.log 2>&1
docker-compose-host $: docker logs oai-ausf > /tmp/oai/qos-testing/ausf.log 2>&1
docker-compose-host $: docker logs oai-pcf > /tmp/oai/qos-testing/pcf.log 2>&1
docker-compose-host $: docker logs oai-ext-dn > /tmp/oai/qos-testing/ext-dn.log 2>&1
docker-compose-host $: docker logs ueransim-gnb > /tmp/oai/qos-testing/gnb.log 2>&1
docker-compose-host $: docker logs ueransim-ue-5qi-1 > /tmp/oai/qos-testing/ue-5qi-1.log 2>&1
docker-compose-host $: docker logs ueransim-ue-5qi-3 > /tmp/oai/qos-testing/ue-5qi-3.log 2>&1
9. Undeploy the network functions¶
9.1. Undeploy UERANSIM¶
docker-compose-host $: docker-compose -f docker-compose-ueransim-qos.yaml down
The output will look like this:
Stopping ueransim-ue-5qi-8 ... done
Stopping ueransim-gnb ... done
Removing ueransim-ue-5qi-8 ... done
Removing ueransim-gnb ... done
Network demo-oai-public-net is external, skipping
9.2. Undeploy the core network¶
docker-compose-host $: python3 core-network.py --type stop-basic-qos --scenario 1
The output will look like this:
[2023-08-10 16:05:54,271] root:DEBUG: UnDeploying OAI 5G core components....
[2023-08-10 16:05:54,272] root:DEBUG: docker-compose -f docker-compose-basic-nrf-qos-qos.yaml down
Stopping oai-pcf ...
Stopping oai-upf ...
Stopping oai-smf ...
Stopping oai-amf ...
Stopping oai-ausf ...
Stopping oai-udm ...
Stopping oai-udr ...
Stopping oai-ext-dn ...
Stopping oai-nrf ...
Stopping mysql ...
Removing oai-pcf ... done
Removing oai-upf ... done
Removing oai-smf ... done
Removing oai-amf ... done
Removing oai-ausf ... done
Removing oai-udm ... done
Removing oai-udr ... done
Removing oai-ext-dn ... done
Removing oai-nrf ... done
Removing mysql ... done
Removing network demo-oai-public-net
[2023-08-10 16:05:55,711] root:DEBUG: OAI 5G core components are UnDeployed....
10. Conclusion¶
You have successfully configured and tested QoS enforcement in the OAI 5G Core network. This tutorial demonstrated how to:
- Configure subscriber QoS profiles in the database
- Set up PC