Skip to content

Commit

Permalink
Update 5G MBS documentation after v0.1.1 release (#100)
Browse files Browse the repository at this point in the history 
* Add new image specifying the container names mapping

* Update 5G-MBS documentation
  • Loading branch information
@Borjis131
Borjis131 authored Nov 15, 2024
1 parent 8a3db61 commit c4f7414
Show file tree
Hide file tree
Showing 4 changed files with 94 additions and 104 deletions.
Binary file added pages/5g-multicast-broadcast-services/images/5G-MBS_container_names.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 21 additions & 15 deletions pages/5g-multicast-broadcast-services/usage/creating-mbs-sessions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ The placement of the SSM in the request selects which kind of identifier is bein

The MB-UPF detects the traffic coming from the SSM and forwards it to the gNBs that have joined the multicast group defined by the LLSSM (Lower Layer Source Specific Multicast). Because of the use of GTPU, a TEID must be selected to forward the traffic, in the case of multicast transport, a C-TEID (Common TEID) is selected and is shared between all the gNBs receiving the multicast traffic.

> Warning: Currently, only one LLSSM and C-TEID are being allocated. After sending the request to create the MBS Session, a PDR is configured to detect the traffic coming from the SSM specified on the request and the traffic is forwarded to the LLSSM that is using the multicast destination address `239.0.0.4` and C-TEID `33`.
> Important note: Currently, there is a limit of 20 MBS Sessions per MB-UPF. The range of IP multicast addresses being used for the MB-UPF to forward the multicast traffic to the gNB using the LLSSM is `239.0.0.4-239.0.0.24`. That is why it is recommended to start the range for the SSM on the IP multicast address `239.0.0.25` onwards.
#### [MB-SMF <-> AMF]: AMF MBS Broadcast ContextCreate side effect

Expand All @@ -62,15 +62,16 @@ The TMGI can be created by using the `TMGI Service API` or by using the `MBS Ses

### Method 1: TMGI Service API

With this method, the AF will ask the MB-SMF to allocate the number of TMGIs present on the `tmgiNumber` field in the JSON data of the request.
With this method, the AF/AS will ask the MB-SMF to allocate the number of TMGIs present on the `tmgiNumber` field in the JSON data of the request.

```bash
# Execute this command inside the AF/AS container
# TMGI Allocate (allocate) request: /nmbsmf-tmgi/v1/tmgi
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "tmgiNumber": 1 }' \
mb-smf.open5gs.org:80/nmbsmf-tmgi/v1/tmgi
smf-mb-smf.5g-mag.org:80/nmbsmf-tmgi/v1/tmgi
```

The response of the MB-SMF, should send the list of allocated TMGIs:
Expand All @@ -81,15 +82,16 @@ The response of the MB-SMF, should send the list of allocated TMGIs:

### Method 2: MBS Session Service API

With this method, the AF will ask the MB-SMF to allocate one TMGI and an MBS Session will be created and associated with this TMGI in the same request. The SSM is used for the detection of the multicast transport over N6mb.
With this method, the AF/AS will ask the MB-SMF to allocate one TMGI and an MBS Session will be created and associated with this TMGI in the same request. The SSM is used for the detection of the multicast transport over N6mb.

```bash
# Execute this command inside the AF/AS container
# MBS Session Create request with TMGI allocate: /nmbsmf-mbssession/v1/mbs-sessions with multicast source
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "mbsSession": { "ssm": { "sourceIpAddr": { "ipv4Addr": "10.33.33.3" }, "destIpAddr": { "ipv4Addr": "239.0.0.20" } },"tmgiAllocReq": true, "serviceType":"BROADCAST" } }' \
mb-smf.open5gs.org:80/nmbsmf-mbssession/v1/mbs-sessions
--data '{ "mbsSession": { "ssm": { "sourceIpAddr": { "ipv4Addr": "<af_as_container_ip>" }, "destIpAddr": { "ipv4Addr": "<n6mb_ip_multicast_destination_address>" } },"tmgiAllocReq": true, "serviceType":"BROADCAST" } }' \
smf-mb-smf.5g-mag.org:80/nmbsmf-mbssession/v1/mbs-sessions
```

The response of the MB-SMF, should send the MBS Session with the allocated TMGI:
Expand All @@ -102,15 +104,16 @@ The response of the MB-SMF, should send the MBS Session with the allocated TMGI:

### TMGI Service API

With this method, the AF will ask the MB-SMF to refresh an existing TMGI. This method is only accesible through the `TMGI Service API` but can be combined with the allocation too:
With this method, the AF/AS will ask the MB-SMF to refresh an existing TMGI. This method is only accesible through the `TMGI Service API` but can be combined with the allocation too:

```bash
# Execute this command inside the AF/AS container
# TMGI Allocate (refresh) request: /nmbsmf-tmgi/v1/tmgi
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "tmgiList": [ { "mbsServiceId": "9236F7", "plmnId": { "mcc": "001", "mnc": "01" } } ] }' \
mb-smf.open5gs.org:80/nmbsmf-tmgi/v1/tmgi
smf-mb-smf.5g-mag.org:80/nmbsmf-tmgi/v1/tmgi
```

The response of the MB-SMF, should send the new expiration time for the refreshed TMGIs:
Expand All @@ -122,12 +125,13 @@ The response of the MB-SMF, should send the new expiration time for the refreshe
Combination of TMGI allocate request and TMGI refresh:

```bash
# Execute this command inside the AF/AS container
# TMGI Allocate (allocate + refresh) request: /nmbsmf-tmgi/v1/tmgi
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "tmgiNumber": 1, "tmgiList": [ { "mbsServiceId": "9236F7", "plmnId": { "mcc": "001", "mnc": "01" } } ] }' \
mb-smf.open5gs.org:80/nmbsmf-tmgi/v1/tmgi
smf-mb-smf.5g-mag.org:80/nmbsmf-tmgi/v1/tmgi
```

The response of the MB-SMF, should send the allocated TMGIs and the new expiration time for the refreshed TMGIs:
Expand All @@ -140,15 +144,16 @@ The response of the MB-SMF, should send the allocated TMGIs and the new expirati

### Method 1: Creating an MBS Broadcast Session and a TMGI in the same request

With this method, the AF will ask the MB-SMF to allocate one TMGI and an MBS Session will be created and associated with this TMGI in the same request. The SSM is used for the detection of the multicast transport over N6mb.
With this method, the AF/AS will ask the MB-SMF to allocate one TMGI and an MBS Session will be created and associated with this TMGI in the same request. The SSM is used for the detection of the multicast transport over N6mb.

```bash
# Execute this command inside the AF/AS container
# MBS Session Create request with TMGI allocate: /nmbsmf-mbssession/v1/mbs-sessions with multicast source
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "mbsSession": { "ssm": { "sourceIpAddr": { "ipv4Addr": "10.33.33.3" }, "destIpAddr": { "ipv4Addr": "239.0.0.20" } },"tmgiAllocReq": true, "serviceType":"BROADCAST" } }' \
mb-smf.open5gs.org:80/nmbsmf-mbssession/v1/mbs-sessions
--data '{ "mbsSession": { "ssm": { "sourceIpAddr": { "ipv4Addr": "<af_as_container_ip>" }, "destIpAddr": { "ipv4Addr": "<n6mb_ip_multicast_destination_address>" } },"tmgiAllocReq": true, "serviceType":"BROADCAST" } }' \
smf-mb-smf.5g-mag.org:80/nmbsmf-mbssession/v1/mbs-sessions
```

The response of the MB-SMF contains the allocated TMGI as MBS Session identifier and also de SSM specified in the request:
Expand All @@ -159,15 +164,16 @@ The response of the MB-SMF contains the allocated TMGI as MBS Session identifier

### Method 2: Creating a Broadcast MBS Session using an existing TMGI

With this method, the AF will ask the MB-SMF to create an MBS Session and the existing TMGI will be associated with it. The SSM is used for the detection of the multicast transport over N6mb.
With this method, the AF/AS will ask the MB-SMF to create an MBS Session and the existing TMGI will be associated with it. The SSM is used for the detection of the multicast transport over N6mb.

```bash
# Execute this command inside the AF/AS container
# MBS Session Create request with existing TMGI: /nmbsmf-mbssession/v1/mbs-sessions
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "mbsSession": { "mbsSessionId": { "tmgi": { "mbsServiceId": "9236F7", "plmnId": { "mcc":"001", "mnc":"01" } } }, "ssm": { "sourceIpAddr": { "ipv4Addr": "10.33.33.3" }, "destIpAddr": { "ipv4Addr": "239.0.0.20" } }, "serviceType":"BROADCAST" } }' \
mb-smf.open5gs.org:80/nmbsmf-mbssession/v1/mbs-sessions
--data '{ "mbsSession": { "mbsSessionId": { "tmgi": { "mbsServiceId": "9236F7", "plmnId": { "mcc":"001", "mnc":"01" } } }, "ssm": { "sourceIpAddr": { "ipv4Addr": "<af_as_container_ip>" }, "destIpAddr": { "ipv4Addr": "<n6mb_ip_multicast_destination_address>" } }, "serviceType":"BROADCAST" } }' \
smf-mb-smf.5g-mag.org:80/nmbsmf-mbssession/v1/mbs-sessions
```

The response of the MB-SMF contains the specified TMGI and SSM, using the TMGI as MBS Session identifier as specified in the request:
Expand Down
98 changes: 61 additions & 37 deletions pages/5g-multicast-broadcast-services/usage/docker-implementation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,37 +7,49 @@ has_children: false
nav_order: 0
---

# Docker Implementation
A Docker Compose implementation to deploy an MBS capable 5G Core is available in the [rt-mbs-examples](https://github.com/5G-MAG/rt-mbs-examples/) repository.
# Docker Deployments

## Deployment architecture using Open5GS
Two Docker Compose deployments of the MBS capable 5G Core are available in the [rt-mbs-examples](https://github.com/5G-MAG/rt-mbs-examples/) repository:

- The `internal` deployment connects all the developed Network Functions for MBS with one srsRAN gNB and one srsRAN UE running using the ZeroMQ driver
- The `external` deployment deploys *only* the developed Network Functions for MBS waiting for a external gNB connection

## Architecture using Open5GS

![5G-MBS architecture using Open5GS](../images/5G-MBS_5G_Core.png)

> [!NOTE]
> Ports `TCP 27017`, `SCTP 38412` and `UDP 2152` are being exposed to the host running this Docker Compose deployment
> Note: All the procedures related to the AMF, SMF and UPF of Open5GS work as expected when using the 5G-MAG components. As an example it is possible to create a standard PDU Session with a gNB and a UE while using the MBS capable 5G Core.
> Note: Port `TCP 27017` is being exposed on the host when running both `internal` and `external` deployments
> Note: Ports `SCTP 38412` and `UDP 2152` are being exposed on the host when running the `external` deployment
These ports are being used for the following:
- `TCP 27017` to add subscribers to the MongoDB database
- `SCTP 38412` from the AMF for the NGAP `N2 interface`, used for the control plane connection with the external gNB
- `UDP 2152` from the MB-UPF for the GTPU `N3mb interface`, used for the data plane connection with the external gNB

> [!NOTE]
> Modify the `.env` file present on this repository to change the values being deployed on `docker-compose.yaml`
> Note: Modify the `.env` file present on this repository to change the values being deployed on `docker-compose.yaml`
Add your host's IP address to the `DOCKER_HOST_IP` variable in the `.env` file for the MB-UPF to be reachable by external gNBs.

## Mapping of container names and the architecture

The following image shows the relationship between the `Architecture using Open5GS` image and the names of the containers.

![5G-MBS container name mapping](../images/5G-MBS_container_names.png)

# Testing

This section explains how to use the Python tests present on the `test` directory in the [rt-mbs-examples](https://github.com/5G-MAG/rt-mbs-examples/) repository.

The Python modules requirements are preinstalled on the AF container image. This container mounts the `test` directory as read-only to be able to run the tests.
The Python modules requirements are preinstalled on the AF/AS container image. This container mounts the `test` directory as read-only to be able to run the tests.

To run the tests, execute an interactive session with the AF container and navigate to the test directory:
To run the tests, execute an interactive session with the AF/AS container and navigate to the test directory:
```bash
docker exec -it af bash
docker exec -it test_mbs_af_as bash

# inside the AF container
# inside the AF/AS container
cd test

# to run the tests
Expand All @@ -59,80 +71,92 @@ The file `tests.py` contains the main logic for the tests. In this file the test

## Inspect all the traffic being sent in the network

You can use tcpdump/Wireshark to sniff all the messages being sent between the Network Functions by inspecting the `br-ogs` network bridge. This bridge is created by the Docker Compose network and is used to connect all the Network Functions.
You can use `tcpdump`/`Wireshark` to sniff all the messages being sent between the Network Functions by inspecting the `br-5g-mag` network bridge. This bridge is created by the Docker Compose network and is used to connect all the Network Functions.

```bash
$ tcpdump -i br-ogs
$ tcpdump -i br-5g-mag
```

## Connect to the AF container to start sending requests to the Network Functions
## Connect to the AF/AS container to start sending requests to the Network Functions

The AF container is not Open5GS related, in fact, it is not even an AF, it is just a container called AF being used to send curl requests to the Open5GS APIs.
The AF/AS container is not Open5GS related, in fact, it is not even an AF/AS, it is just a container called AF/AS being used to send curl requests to the Open5GS APIs.

```bash
# Connect to the AF container
docker exec -it af bash
# Connect to the AF/AS container
docker exec -it test_mbs_af_as bash
```

Use curl inside the container to send requests to the other Network Functions:

```bash
# Inside the AF container, example of the AF sending the MB-SMF the TMGI allocate request
# Inside the AF/AS container, example of the AF/AS sending the MB-SMF the TMGI allocate request
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "tmgiNumber": 1 }' \
mb-smf.open5gs.org:80/nmbsmf-tmgi/v1/tmgi
smf-mb-smf.5g-mag.org:80/nmbsmf-tmgi/v1/tmgi
```

## Configure the MB-UPF multicast

Apart from editing the `.env` for the MB-UPF to be reachable by external gNBs, the MB-UPF needs extra configuration. To be able to forward the multicast traffic to the lower layer source specific multicast (LLSSM) address, the MB-UPF needs to udpate the multicast forwarding cache (MFC) in the linux kernel.
Apart from editing the `.env` for the MB-UPF to be reachable by external gNBs, the MB-UPF needs extra configuration. To be able to detect the multicast traffic being sent and forward it to the lower layer source specific multicast (LLSSM) address, the MB-UPF needs to udpate the multicast forwarding cache (MFC) in the linux kernel.

For this purpose, the `smcroute` tool is installed on the MB-UPF container. Through the `smcroutectl` command, the MFC can be updated to the desired values. Currently this is done manually but other ways to update the MFC are being studied.

```bash
# Execute this command inside the MB-UPF container
smcroutectl add eth0 <n6mb_multicast_destination_address> ogstun
smcroutectl add eth0 <n6mb_ip_multicast_destination_address> ogstun
```

After this, and after creating the MBS Session, the MVP can be tested by using the AF to send multicast traffic to the MB-UPF and inspecting the MB-UPF output:
After this, and after creating the MBS Session, the project can be tested by using the AF/AS to send multicast traffic to the MB-UPF and inspecting the MB-UPF output:

```bash
# Execute this command inside the AF container
sendip -p ipv4 -is <af_container_ip> -id <n6mb_multicast_destination_address> <mb_upf_container_ip>
# Execute this command inside the AF/AS container
sendip -p ipv4 -is <af_as_container_ip> -id <n6mb_ip_multicast_destination_address> <mb_upf_container_ip>
```

### Full example

Create a Broadcast MBS Session using TMGI as identifier but specifying also the SSM address, this SSM will be the address that the AF will use to send the multicast traffic to the MB-UPF through the N6mb interface.
Create a Broadcast MBS Session using TMGI as identifier but specifying also the SSM address, this SSM will be the address that the AF/AS will use to send the multicast traffic to the MB-UPF through the N6mb interface.

> Important note: Currently, there is a limit of 20 MBS Sessions per MB-UPF. The range of IP multicast addresses being used for the MB-UPF to forward the multicast traffic to the gNB using the LLSSM is `239.0.0.4-239.0.0.24`. That is why it is recommended to start the range for the SSM on the IP multicast address `239.0.0.25` onwards.
Deploy the `internal` Docker Compose deployment and check everything is up and running.

From the AF/AS container execute:

```bash
# Execute this command inside the AF/AS container
# MBS Session Create request with TMGI allocate: /nmbsmf-mbssession/v1/mbs-sessions with multicast source
curl --http2-prior-knowledge \
--request POST \
--header "Content-Type: application/json" \
--data '{ "mbsSession": { "ssm": { "sourceIpAddr": { "ipv4Addr": "10.33.33.3" }, "destIpAddr": { "ipv4Addr": "239.0.0.20" } },"tmgiAllocReq": true, "serviceType":"BROADCAST" } }' \
mb-smf.open5gs.org:80/nmbsmf-mbssession/v1/mbs-sessions
--data '{ "mbsSession": { "ssm": { "sourceIpAddr": { "ipv4Addr": "<af_as_container_ip>" }, "destIpAddr": { "ipv4Addr": "<n6mb_ip_multicast_destination_address>" } },"tmgiAllocReq": true, "serviceType":"BROADCAST" } }' \
smf-mb-smf.5g-mag.org:80/nmbsmf-mbssession/v1/mbs-sessions
```

The AF with IP address 10.33.33.3 will send an IP packet to the multicast destination 239.0.0.20. The MB-UPF will receive the traffic being sent to this multicast group and then forward it to the LLSSM.
> Tip: Check AF container IP executing `ip address` from the AF container and use the `eth0` interface address as `<af_as_container_ip>`
The AF/AS with IP address `<af_as_container_ip>` will send an IP packet to the multicast destination `<n6mb_ip_multicast_destination_address>`. In order for the MB-UPF to receive the traffic being sent to this multicast group and then forward it to the LLSSM, we need to execute the following command to configure the MB-UPF:

For this, we will configure the MB-UPF like this:
```bash
# Execute this command inside the MB-UPF container
smcroutectl add eth0 239.0.0.20 ogstun
smcroutectl add eth0 <n6mb_ip_multicast_destination_address> ogstun
```

This command will update the MFC of the MB-UPF to receive the traffic for the multicast group 239.0.0.20 and forward it internally using the `ogstun` interface.
This command will update the MFC of the MB-UPF to receive the traffic for the multicast group `<n6mb_ip_multicast_destination_address>` and forward it internally using the `ogstun` interface.

After all of this is configured, the MB-UPF has been configured through PFCP to forward the traffic received to the LLSSM. The LLSSM is uses the multicast destination address `239.0.0.4` and C-TEID `33`.
After all of this is configured, the MB-UPF has been configured through PFCP to forward the traffic received to the LLSSM. The first LLSSM created uses the multicast destination address `239.0.0.4` and random C-TEID.

Now, sending traffic with the AF to the MB-UPF with the addresses configured causes the MB-UPF to forward the traffic using GTPU to the LLSSM:
Now, sending traffic with the AF/AS to the MB-UPF with the addresses configured causes the MB-UPF to forward the traffic using GTPU to the LLSSM:

```bash
# To send traffic from the AF/AS to the MB-UPF
sendip -p ipv4 -is <af_as_container_ip> -id <n6mb_ip_multicast_destination_address> upf-mb-upf.5g-mag.org
```

> [!TIP]
> Check AF container IP executing `ip address` from the AF container and use the `eth0` interface address as <af_container_ip>
You can check the traffic is being forwarded to the LLSSM executing:

```bash
# To send traffic from the AF to the MB-UPF
sendip -p ipv4 -is <af_container_ip> -id 239.0.0.20 mb-upf.open5gs.org
$ tcpdump -i br-5g-mag udp port 2152
```
Loading

0 comments on commit c4f7414

Please sign in to comment.