From 1971dddbf7451a1bf7d0264c81b5ee8fa0145332 Mon Sep 17 00:00:00 2001 From: "Jordi J. Gimenez" <87380947+jordijoangimenez@users.noreply.github.com> Date: Wed, 4 Sep 2024 08:21:49 +0200 Subject: [PATCH] Doc updates 030924 (#86) * Update end-to-end.md * Update end-to-end.md * Rename pages/5g-core-network-components/tutorials.md to pages/5g-core-network-components/tutorial/tutorials.md * Create 5gnetwork.md * Update 5gnetwork.md * Update 5gnetwork.md * Update 5gnetwork.md * Update end-to-end.md * Create end-to-end-with-5g.md * Update end-to-end-with-5g.md * Update consumption-reporting.md * Update metrics-reporting.md * Update end-to-end.md --- .../tutorial/5gnetwork.md | 331 ++++++++++++++++++ .../{ => tutorial}/tutorials.md | 0 .../tutorials/consumption-reporting.md | 2 +- .../tutorials/end-to-end-with-5g.md | 55 +++ .../tutorials/end-to-end.md | 14 +- .../tutorials/metrics-reporting.md | 2 +- 6 files changed, 395 insertions(+), 9 deletions(-) create mode 100644 pages/5g-core-network-components/tutorial/5gnetwork.md rename pages/5g-core-network-components/{ => tutorial}/tutorials.md (100%) create mode 100644 pages/5g-media-streaming/tutorials/end-to-end-with-5g.md diff --git a/pages/5g-core-network-components/tutorial/5gnetwork.md b/pages/5g-core-network-components/tutorial/5gnetwork.md new file mode 100644 index 00000000..e102a9aa --- /dev/null +++ b/pages/5g-core-network-components/tutorial/5gnetwork.md @@ -0,0 +1,331 @@ +--- +layout: default +title: 5G Network Setup with COTS UE +parent: Tutorials +grand_parent: 5G Core Network Components +has_children: false +nav_order: 0 +--- + +# Tutorial - 5G Network Setup with COTS UE + +## Introduction +These are the generic instructions to setup a 5G network using Open5GS and srsRAN. An Ettus X310 USRP and a Pixel 8 phone are used. + +## 5G Core installation and configuration + +Follow the installation procedures in the [Open5GS Quickstart guide](https://open5gs.org/open5gs/docs/guide/01-quickstart/). + +### Step 1: Install the 5G Core (Open5GS) + +We recommend installing for Ubuntu 22.04 with the following instructions: + +#### Getting MongoDB +Import the public key used by the package management system: + +``` +sudo apt update +sudo apt install gnupg +curl -fsSL https://pgp.mongodb.com/server-6.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg --dearmor +``` + +Create the list file /etc/apt/sources.list.d/mongodb-org-6.0.list for Ubuntu 22.04: + +``` +echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list +``` + +Install the MongoDB packages. + +``` +sudo apt update +sudo apt install -y mongodb-org +sudo systemctl start mongod (if '/usr/bin/mongod' is not running) +sudo systemctl enable mongod (ensure to automatically start it on system boot) +``` + +#### Install Open5GS + +``` +sudo add-apt-repository ppa:open5gs/latest +sudo apt update +sudo apt install open5gs +``` +#### Install the WebUI of Open5GS + +The WebUI allows you to interactively edit subscriber data. Node.js is required to install the WebUI of Open5GS: + +``` +sudo apt update +sudo apt install -y ca-certificates curl gnupg +sudo mkdir -p /etc/apt/keyrings +curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg + +NODE_MAJOR=20 +echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list + +sudo apt update +sudo apt install nodejs -y + +sudo zypper install nodejs8 + +curl -fsSL https://open5gs.org/open5gs/assets/webui/install | sudo -E bash - +``` + +### Step 2: Configure the 5G Core (Open5GS) + +#### IP:port addresses + +The default configurations see all of the Open5GS components fully configured for use on a single computer using the local loopback address space (127.0.0.X): +``` +MongoDB = 127.0.0.1 (subscriber data) - http://localhost:9999 + +MME-s1ap = 127.0.0.2 :36412 for S1-MME +MME-gtpc = 127.0.0.2 :2123 for S11 +MME-frDi = 127.0.0.2 :3868 for S6a + +SGWC-gtpc = 127.0.0.3 :2123 for S11 +SGWC-pfcp = 127.0.0.3 :8805 for Sxa + +SMF-gtpc = 127.0.0.4 :2123 for S5c +SMF-gtpu = 127.0.0.4 :2152 for N4u (Sxu) +SMF-pfcp = 127.0.0.4 :8805 for N4 (Sxb) +SMF-frDi = 127.0.0.4 :3868 for Gx auth +SMF-sbi = 127.0.0.4 :7777 for 5G SBI (N7,N10,N11) + +AMF-ngap = 127.0.0.5 :38412 for N2 +AMF-sbi = 127.0.0.5 :7777 for 5G SBI (N8,N12,N11) + +SGWU-pfcp = 127.0.0.6 :8805 for Sxa +SGWU-gtpu = 127.0.0.6 :2152 for S1-U, S5u + +UPF-pfcp = 127.0.0.7 :8805 for N4 (Sxb) +UPF-gtpu = 127.0.0.7 :2152 for S5u, N3, N4u (Sxu) + +HSS-frDi = 127.0.0.8 :3868 for S6a, Cx + +PCRF-frDi = 127.0.0.9 :3868 for Gx + +NRF-sbi = 127.0.0.10:7777 for 5G SBI +SCP-sbi = 127.0.0.200:7777 for 5G SBI +SEPP-sbi = 127.0.0.250:7777 for 5G SBI +SEPP-n32 = 127.0.0.251:7777 for 5G N32 +SEPP-n32f = 127.0.0.252:7777 for 5G N32-f +AUSF-sbi = 127.0.0.11:7777 for 5G SBI +UDM-sbi = 127.0.0.12:7777 for 5G SBI +PCF-sbi = 127.0.0.13:7777 for 5G SBI +NSSF-sbi = 127.0.0.14:7777 for 5G SBI +BSF-sbi = 127.0.0.15:7777 for 5G SBI +UDR-sbi = 127.0.0.20:7777 for 5G SBI +``` +#### PLMN ID and TAC information +Our setup will be using PLMN ID (MCC/MNC) 001/01 and TAC 7. This information needs to be loaded into the NRF and AMF config files (and the gNB). + +Modify `/etc/open5gs/nrf.yaml` to set the Serving PLMN ID: + +``` +nrf: + serving: # 5G roaming requires PLMN in NRF + - plmn_id: + mcc: 001 + mnc: 01 + sbi: + server: + - address: 127.0.0.10 + port: 7777 +``` + +Modify `/etc/open5gs/amf.yaml` to set the PLMN ID and TAC: + +``` +amf: + sbi: + server: + - address: 127.0.0.5 + port: 7777 + client: +# nrf: +# - uri: http://127.0.0.10:7777 + scp: + - uri: http://127.0.0.200:7777 + ngap: + server: + - address: 127.0.0.5 + metrics: + server: + - address: 127.0.0.5 + port: 9090 + guami: + - plmn_id: + mcc: 001 + mnc: 01 + amf_id: + region: 2 + set: 1 + tai: + - plmn_id: + mcc: 001 + mnc: 01 + tac: 7 + plmn_support: + - plmn_id: + mcc: 001 + mnc: 01 + s_nssai: + - sst: 1 + security: + integrity_order : [ NIA2, NIA1, NIA0 ] + ciphering_order : [ NEA0, NEA1, NEA2 ] + network_name: + full: 5GMAG + short: 5GMAG +``` + +After changing config files, please restart Open5GS daemons. + +``` +sudo systemctl restart open5gs-nrfd +sudo systemctl restart open5gs-amfd +``` + +#### Adding a route for the UE to have WAN connectivity + +In order to bridge between the PGWU/UPF and WAN (Internet), you must enable IP forwarding and add a NAT rule to your IP Tables. + +To enable forwarding and add the NAT rule, enter: + +Enable IPv4/IPv6 Forwarding + +``` +sudo sysctl -w net.ipv4.ip_forward=1 +sudo sysctl -w net.ipv6.conf.all.forwarding=1 +``` + +Add NAT Rule +``` +sudo iptables -t nat -A POSTROUTING -s 10.45.0.0/16 ! -o ogstun -j MASQUERADE +sudo ip6tables -t nat -A POSTROUTING -s 2001:db8:cafe::/48 ! -o ogstun -j MASQUERADE +``` + +Configure the firewall correctly. Some operating systems (Ubuntu) by default enable firewall rules to block traffic. + +``` +sudo ufw disable +``` + +## gNB installation and configuration + +Follow the installation procedures in the [srsRAN installation guide](https://docs.srsran.com/projects/project/en/latest/user_manuals/source/installation.html). + +### Step 1: Install the gNB (srsRAN) + +Install dependencies + +``` +sudo apt-get install cmake make gcc g++ pkg-config libfftw3-dev libmbedtls-dev libsctp-dev libyaml-cpp-dev libgtest-dev +``` + +Install UHD drivers (e.g. for Ettus USRP) +``` +sudo add-apt-repository ppa:ettusresearch/uhd +sudo apt-get update +sudo apt-get install libuhd-dev uhd-host +``` + +Download the srsRAN Project packages: + +``` +sudo add-apt-repository ppa:softwareradiosystems/srsran-project +sudo apt-get update +sudo apt-get install srsran-project -y +``` + +### Step 2: Configure the gNB (srsRAN) + +#### Prepare the system + +Before running srsRAN Project applications, we recommend tuning your system for best performance: + +``` +sudo ./scripts/srsran_performance +``` + +#### Configuration files + +When installed from packages, srsRAN Project example configs can be found in `/usr/share/srsran`. + +We've created the following 5gmag_example.yml. We recommend finding the value ARFCN through this [link](https://5g-tools.com/5g-nr-arfcn-calculator/). + +``` +# This example configuration outlines how to configure the srsRAN Project gNB to create a single TDD cell +# transmitting in band 77, with 10 MHz bandwidth and 30 kHz sub-carrier-spacing. A USRP X310 is configured +# as the RF frontend. Note in this example the internal GPDSO is used. + +amf: + addr: 127.0.0.5 # The address or hostname of the AMF. + bind_addr: 127.0.1.5 # A local IP that the gNB binds to for traffic from the AMF. + +ru_sdr: + device_driver: uhd # The RF driver name. + device_args: send_frame_size=1472,recv_frame_size=1472,type=x300 # Optionally pass arguments to the selected RF driver. + clock: gpsdo # Specify the clock source used by the RF. + srate: 15.36 # RF sample rate might need to be adjusted according to selected bandwidth. + tx_gain: 20 # Transmit gain of the RF might need to adjusted to the given situation. + rx_gain: 20 # Receive gain of the RF might need to adjusted to the given situation. + +cell_cfg: + dl_arfcn: 653668 # ARFCN of the downlink carrier (center frequency). + band: 77 # The NR band. + channel_bandwidth_MHz: 10 # Bandwith in MHz. Number of PRBs will be automatically derived. + common_scs: 30 # Subcarrier spacing in kHz used for data. + plmn: "00101" # PLMN broadcasted by the gNB. + tac: 7 # Tracking area code (needs to match the core configuration). + pci: 1 # Physical cell ID. + +log: + filename: /tmp/gnb.log # Path of the log file. + all_level: info # Logging level applied to all layers. + +pcap: + mac_enable: false # Set to true to enable MAC-layer PCAPs. + mac_filename: /tmp/gnb_mac.pcap # Path where the MAC PCAP is stored. + ngap_enable: false # Set to true to enable NGAP PCAPs. + ngap_filename: /tmp/gnb_ngap.pcap # Path where the NGAP PCAP is stored. +``` + +## Running the 5G Core (Open5GS) + +When you install the software using the package manager, it is setup to run as a systemd service. + + +## Running the gNB (srsRAN) + +Run the gNB as follows, passing the YAML configuration file: + +sudo ./gnb -c 5gmag_example.yml + +## Configure the COTS UE + +### Register Subscriber Information +Connect to http://localhost:9999 and login with admin account. + Username : admin + Password : 1423 + +To add subscriber information, you can do WebUI operations in the following order: + + Go to Subscriber Menu. + Click + Button to add a new subscriber. + Fill the IMSI, security context(K, OPc, AMF), and APN of the subscriber. + Click SAVE Button + +Enter the subscriber details of your SIM cards using this tool, to save the subscriber profile in the HSS and UDR MongoDB database backend. + +### SIM card and APN + +Insert your SIM card to the UE and set the UE’s APN to match the APN you configured in the Open5GS WebUI. We recommend to edit the existing APN. +Toggle the UE in and out of flight mode. If it doesn’t automatically connect, try manually searching for a network. If the PLMN set on the SIM card does not match the PLMN being used by the radio, you will need to ensure ‘data roaming’ on the UE is switched on. + +The UE should connect automatically. If you experience trouble, we recommend checking the 5G Core logs, e.g.: +``` +sudo tail -f /var/log/open5gs/amf.log +``` diff --git a/pages/5g-core-network-components/tutorials.md b/pages/5g-core-network-components/tutorial/tutorials.md similarity index 100% rename from pages/5g-core-network-components/tutorials.md rename to pages/5g-core-network-components/tutorial/tutorials.md diff --git a/pages/5g-media-streaming/tutorials/consumption-reporting.md b/pages/5g-media-streaming/tutorials/consumption-reporting.md index 5d09bee7..35fb9cc6 100644 --- a/pages/5g-media-streaming/tutorials/consumption-reporting.md +++ b/pages/5g-media-streaming/tutorials/consumption-reporting.md @@ -4,7 +4,7 @@ title: Consumption Reporting parent: Tutorials grand_parent: 5G Downlink Media Streaming has_children: false -nav_order: 1 +nav_order: 2 --- # Tutorial - Consumption Reporting diff --git a/pages/5g-media-streaming/tutorials/end-to-end-with-5g.md b/pages/5g-media-streaming/tutorials/end-to-end-with-5g.md new file mode 100644 index 00000000..38bfe1d8 --- /dev/null +++ b/pages/5g-media-streaming/tutorials/end-to-end-with-5g.md @@ -0,0 +1,55 @@ +--- +layout: default +title: Basic 5GMS Setup with 5G Network +parent: Tutorials +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 1 +--- + +# Tutorial - 5G MSd: Basic End-to-End Setup with 5G Network +This guide describes how to setup and configure the 5G-MAG Reference Tools to create an end to end setup consisting of the 5G Downlink Media Streaming components and a 5G Network based on Open5GS and srsRAN. + +# 5G Network with COTS UE setup +For details please refer to the [corresponding documentation](../../5g-core-network-components/tutorials/5gnetwork.html) + +# 5G Media Streaming setup +## Server-side Setup + +### Step 1: Install the Application Function + +For details please refer to the [corresponding section](end-to-end.html#1-installing-the-application-function) in +the [basic end-to-end guide](end-to-end.html). + +### Step 2: Install the Application Server + +For details please refer to the [corresponding section](end-to-end.html#2-installing-the-application-server) in +the [basic end-to-end guide](end-to-end.html). + +### Step 3: Start the Application Server + +For details please refer to the [corresponding section](end-to-end.html#3-running-the-application-server) in +the [basic end-to-end guide](end-to-end.html). + +### Step 4: Basic Configuration of the Application Function + +Follow the [basic configuration steps](end-to-end.html#configuration-of-the-af) documented in +the [basic end-to-end guide](end-to-end.html). + +### Step 5: Start the Application Function + +Follow the [command](end-to-end.html#starting-the-af) documented in the [basic end-to-end guide](end-to-end.html). + +### Step 6: Basic configuration of the Application Function + +Follow the [steps](end-to-end.html#creating-a-content-hosting-configuration) to create a content hosting configuration +and a provisioning session using the `msaf-configuration` tool. + +## Client-side Setup + +As we are all set on the server-side now we can focus on the client side. + +### Step 1: Installation, Configuration and Running the 5GMSd Client + +Please follow the [instructions](end-to-end.html#client-side-setup) documented in +the [basic end-to-end guide](end-to-end.html) setup guide. diff --git a/pages/5g-media-streaming/tutorials/end-to-end.md b/pages/5g-media-streaming/tutorials/end-to-end.md index 23b7b85d..13a4527e 100644 --- a/pages/5g-media-streaming/tutorials/end-to-end.md +++ b/pages/5g-media-streaming/tutorials/end-to-end.md @@ -1,6 +1,6 @@ --- layout: default -title: Basic End-to-End Setup +title: Basic 5GMS End-to-End Setup parent: Tutorials grand_parent: 5G Downlink Media Streaming has_children: false @@ -46,15 +46,15 @@ Now start the AS sudo 5gms-application-server ```` -For additional options, refer to the [Wiki documentation](https://github.com/5G-MAG/rt-5gms-application-server/blob/main/docs/README.md#running-the-example-without-building). Pay attention to the port configuration of the AS as it requires root permission to run on the standard ports (80 & 443). +For additional options, refer to the [documentation](../usage/application-server/testing-AS.html#running-the-example-without-building). Pay attention to the port configuration of the AS as it requires root permission to run on the standard ports (80 & 443). ### 4. Running the Application Function -Now that we installed the AF and the AS we can configure the AF. A detailed configuration guide is available in the [Wiki documentation](https://github.com/5G-MAG/rt-5gms-application-function/wiki/Configuring-the-Application-Function) of the AF. +Now that we installed the AF and the AS we can configure the AF. A detailed configuration guide is available in the [documentation](../usage/application-function/configuration-5GMSAF.html) of the AF. #### Configuration of the AF For this demo, we will run AF and AS on the same machine. As we want to access the `ServiceAccessInformation` via the `M5d` interface from our Media Session Handler running on an Android device we need to slightly modify the configuration. The goal is to expose the `M5d` interface via the IP address of our machine but have it running on a different port to not interfere with the default port of the `M3`interface on the AS (`Port 7777`). -1. Open `~/usr/local/etc/open5gs/msaf.yaml` +1. Open `/usr/local/etc/open5gs/msaf.yaml` 2. Find the settings for `msaf:m5` 3. Replace the `addr` field with `0.0.0.0` and choose a different `port`. For instance: ```` @@ -73,7 +73,7 @@ As we installed the AF as a local user, we start it with the following command: ```` #### Creating a content hosting configuration -There is a guide on how to test the AS with the AF in the [AS Wiki](https://github.com/5G-MAG/rt-5gms-application-server/blob/main/docs/README.md#testing-with-the-application-function). We are following a slightly different approach as we use the `msaf-configuration` tool that ships with version `1.3.0` of the Application Function. The `msaf-configuration` tool creates a `provisioningSession` and a `contentHostingConfiguration` based on a JSON input file. Moreover, it automatically generates the required `M8` information for us that we will later need on the client-side. +There is a guide on how to test the AS with the AF in the [documentation](../usage/application-server/testing-AS.html#testing-with-the-application-function). We are following a slightly different approach as we use the `msaf-configuration` tool that ships with version `1.3.0` of the Application Function. The `msaf-configuration` tool creates a `provisioningSession` and a `contentHostingConfiguration` based on a JSON input file. Moreover, it automatically generates the required `M8` information for us that we will later need on the client-side. First we create a configuration file to be used by the `msaf-configuration` tool: @@ -198,10 +198,10 @@ In our Android application we will use this endpoint later to derive the require #### Optional: Creating a server certificate -Optionally, you can now also [create server certificate](https://github.com/5G-MAG/rt-5gms-application-function/wiki/Testing-the-M1-Interface#server-certificates). For plain `http` based playback we can omit this step. +Optionally, you can now also [create server certificate](../usage/application-function/testing-m1-v130.html#server-certificates). For plain `http` based playback we can omit this step. #### Optional: Checking the M5 interface -The complete documentation on how to test the M5 interface for AF versions 1.2.0 and above can be found [here](https://github.com/5G-MAG/rt-5gms-application-function/wiki/Testing-the-M5-Interface-on-v1.2.0) +The complete documentation on how to test the M5 interface for AF versions 1.2.0 and above can be found [here](../usage/application-function/testing-m5-v120.html) What we will need on the client side later is the `ServiceAccessInformation`. This will be requested via `M5d` by our MediaSessionHandler. Since retrieving this information is done via a simple HTTP GET request, we can access the information directly in the browser. For that reason, call the following URL and replace `{provisioningSessionId}` with the corresponding value. For instance, diff --git a/pages/5g-media-streaming/tutorials/metrics-reporting.md b/pages/5g-media-streaming/tutorials/metrics-reporting.md index 909ee1f0..7dcd557d 100644 --- a/pages/5g-media-streaming/tutorials/metrics-reporting.md +++ b/pages/5g-media-streaming/tutorials/metrics-reporting.md @@ -4,7 +4,7 @@ title: QoE Metrics Reporting parent: Tutorials grand_parent: 5G Downlink Media Streaming has_children: false -nav_order: 1 +nav_order: 3 --- # Tutorial - QoE Metrics Reporting