Magma Orchestrator & NMS

Prerequisite

Hardware: x68_64 PC
OS: Ubuntu 22.04 server

Environment Setup

Install the docker.

sudo apt update && sudo apt install -y docker.io

sudo curl -SL https://github.com/docker/compose/releases/download/v2.12.2/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose

sudo chmod +x /usr/local/bin/docker-compose

# Add docker to sudo group
sudo groupadd docker
sudo gpasswd -a ${USER} docker
sudo service docker restart

Download the magma source code.

git clone https://github.com/magma/magma.git
cd magma
git checkout v1.8.0-rc1

Build Orchestrator & NMS

export MAGMA_ROOT=${PWD}

cd ${MAGMA_ROOT}/orc8r/cloud/docker
./build.py --all

cd ${MAGMA_ROOT}/nms
docker-compose build

Run Orchestrator & NMS

# Run Orchestrator
cd ${MAGMA_ROOT}/orc8r/cloud/docker
./run.py --metrics

# Run NMs
cd ${MAGMA_ROOT}/nms/
docker-compose up -d

# Create default organization & admin account
./scripts/dev_setup.sh

Add Host Record on Your OM PC

<PC_IPAddress>  magma-test.localhost

- URL: https://magma-test.localhost
- Username: admin@magma.test
- Password: password1234

Create a network.

Create Access Gateway.

Get rootCA.pem from the magma server.

cat ${MAGMA_ROOT}/.cache/test_certs/rootCA.pem

Copy rootCA.pem to access the gateway.

ssh ubuntu@<agw.ipaddress>

cat > /var/opt/magma/certs/rootCA.pem <<EOF
-----BEGIN CERTIFICATE-----
MIIDNTCCAh2gAwIBAgIUBW6xfiqamgwsci+GBx8BBsIOEUgwDQYJKoZIhvcNAQEL
BQAwKTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEXJvb3RjYS5tYWdtYS50ZXN0MCAX
DTIyMTAxMTA2MjEzNFoYDzMwMjIwMjExMDYyMTM0WjApMQswCQYDVQQGEwJVUzEa
MBgGA1UEAwwRcm9vdGNhLm1hZ21hLnRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IB
DwAwggEKAoIBAQDYGFIFOVxbNHY57RG+3ggK5EoMFpEfDAmeSWN16BEfWx0ylGBa
szH6h1viSMSkaOWRpty/xrtzpI7WYaIf6nqAvQ516a1Gg2J5sV6BfqiqgzmgLlaw
g0WaqjCE4PfUgS9ua1mllLcqQXZxegIk7evgdQtnpzJZL3NG0WRNdYvQx1W7QpCf
Q1GJu1/8nViKDU+kWXp1+sihn7d8zBF7lDTWBF45slYD2CWxt/6BnLYzSCarUqxL
gl4XkTu0zsVDl0ePwCGOjiPI59nFDlmZpqu3/GX4S3NnnCb0NvsvZWNmZjLvNuUj
eaN6GS+OsJ9yMOC9i3gg7mZEzf2uoT653adJAgMBAAGjUzBRMB0GA1UdDgQWBBSM
F+lu40xk2KoZN2HdungLYfR92zAfBgNVHSMEGDAWgBSMF+lu40xk2KoZN2HdungL
YfR92zAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQCk2e6bvXMQ
t1NfVQa/GnaJnH6Og1dzNGHTILTMYGIuAY1RS240jZtV0gU63tpkAEMbsqm6sVwH
0xTy0r7ihkHl2ndbakyKbgH/UF7qbp+tOvq8q6FlcMyDX/x9vZHAK86yOhxgzcjo
PtI0U3SNTB3WMtP3FsMjOiU1ouZV63YiJljpYet0tUGB4L3cJRwDfp4mOykhwGz/
k/Z56pAnW9EiLtcriZm4Icpmf4f6KZ4JJu1H9O4ho5bNU+mGXsRJgKuxskw+MMKU
YDSttPPIcpyMjzfsZHhSoEizFXX8RcRXSNcE38QlwbZKPXqoUQX0/686DJszOc9V
12Tqonmf3R0G
-----END CERTIFICATE-----
EOF

Add host records to /etc/hosts of the AGW.

# append these lines to /etc/hosts file of AGW
<PC_IPAddress> controller.magma.test
<PC_IPAddress> bootstrapper-controller.magma.test
<PC_IPAddress> fluentd.magma.test

Get the hardware ID & challenge key from Access Gateway.

# Login to access gateway via ssh
ssh ubuntu@<agw.ipaddress>

cd /var/opt/magma/docker

sudo docker-compose exec magmad show_gateway_info.py

 Hardware ID
 -----------
 01235b62-6d55-ec47-ee10-00000074****

 Challenge key
 -------------
 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQ********************************IH6l8fYxpEJ5xCWk3trokmOWDupEmvQ8tKoqdtg3lvmGyMzhUHwg==

 Build info
 -------------
  Commit Branch: unknown
  Commit Tag: unknown
  Commit Hash: unknown
  Commit Date: unknown

 Notes
 -----
 - Hardware ID is this gateway's unique identifier
 - Challenge key is this gateway's long-term keypair used for
   bootstrapping a secure connection to the cloud
 - Build info shows git commit information of this build

📝 NOTE:

Hardware ID: 01235b62-6d55-ec47-ee10-00000074****
Challenge key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQ********************************IH6l8fYxpEJ5xCWk3trokmOWDupEmvQ8tKoqdtg3lvmGyMzhUHwg==

Create access gateway in NMS.

Restart the access gateway

ssh ubuntu@<agw.ipaddress>
cd /var/opt/magma/docker
sudo docker-compose restart

Dockerized Magma AGW 1.8.0 Installation Guide

RAKwireless shipped the MagmaBox with Ubuntu 20.04.5 LTS(64-BIT) installed for our customers. It is an unmodified originally official Ubuntu image for Raspberry Pi 4.

For those who want to replace the SD card or just want to re-install the Ubuntu OS themselves, feel free to re-install and follow the steps in the Ubuntu Server 20.04 LTS (64-BIT) Installation and IP Address Configuration sections.

For those who want to install dockerized Magma AGW directly, execute the following steps described in Power Up Magma Box and Dockerized Magma AGW 1.8.0 Installation.

📝 NOTE: The operations on the PC described are based on MacBook Pro.

Ubuntu Server 20.04 LTS (64-BIT) Installation

Take out the SD card from Magma Box.

Plug the SD card into your PC via an adapter.

Download and install the Raspberry Pi Imager.

Open the Imager and click the CHOOSE OS button.

Select Other general-purpose OS.

Then choose the Ubuntu item to list the available Ubuntu OS images. Make sure you choose the Ubuntu Server 20.04.5 LTS (64-bit).

Back to the main page of Raspberry Pi Imager, click the CHOOSE STORAGE button to choose the SD card just plugged in.

Click WRITE to flush the Ubuntu OS into the SD card.

The Ubuntu Server 20.04.5 LTS (64-bit) is now flashed to the SD card.

IP Address Configuration

Before anything else, configure first the IP addresses before powering up the Magma Box.

Plug the SD card back into the Magma Box. Make sure it has an IP address configured so it can SSH or connect the 4G radio to the box.

Here shows the traditional network architecture for Magma Box developments.

Usually, configuring a static IP address for the Magma Box's eth1 port is needed, and a dynamic IP address is allocated from the home router for Magma Box's eth0 port.

Follow the steps below to setup the IP addresses:

Take out the SD card from the PC and re-plug it again.
Edit the network-config file under the SD card's root directory.

Add the eth port's configuration. Configure eth1 static IP address to 10.0.2.1/24.

 # vim /Volumes/system-boot/network-config
 eth1:
 dhcp4: false
 optional: true
 addresses: [10.0.2.1/24]

Save the changes and quit, then push the SD card out of the PC.

Power Up the Magma Box

After the installation and configuration, connect and power up the Magma Box. This guide assumes that your PC's eth0 port has been configured with a static IP address that's in the same subnet as Magma Box's eth1 port. For example, 10.0.2.2/24.

Plug the SD card into the Magma Box.

Connect the Magma Box eth0, the native ethernet port, to the home router with the ethernet cable.

Plug the USB-to-Ethernet adapter into the blue-colored USB port on the Magma Box.

Connect your PC to the USB-to-Ethernet adapter with the ethernet cable.

Plug the power supply into the Magma Box.

Now the Magma Box is powered up. The Magma Box's status can be verified via ping 10.0.2.1 from the PC.

Dockerized Magma AGW 1.8.0. Installation

After powering up the Magma Box, connect it with SSH with the initial Ubuntu password to install the latest dockerized Magma AGW 1.8.0.

Ubuntu will ask you to change the password the first time SSH to the Magma Box.

Then, SSH to Magma Box again after the password is changed.

Create an empty rootCA.pem before the installation.

# sudo mkdir -p /var/opt/magma/certs
# sudo touch /var/opt/magma/certs/rootCA.pem

Download the installation bash script from Magma's GitHub repository and execute.

# wget https://github.com/magma/magma/raw/v1.8/lte/gateway/deploy/agw_install_docker.sh
# sudo bash agw_install_docker.sh

📝 NOTE:

If anything wrong happens in this stage, refer directly to Installation Errors and Solution. (Optional)
If all goes well, just wait until the installation is finished. It may take half an hour, depending on your home router's internet speed.

After that, the dockerized Magma AGW 1.8.0 is now successfully installed on the Magma Box. You can verify the docker container's status using the command:

sudo
docker ps

📝 NOTE: Normally, the control_proxy is restarting all the time because of an empty rootCA.pem that is unavailable.

Installation Errors and Solution

Things may go wrong when executing Magma's official bash script agw_install_docker.sh.

Error 1: Waiting for cache lock: Could not get lock/var/lib/dpkg/lock-frontend. It is held by process xxx.

This error is caused by Ubuntu's self-update process which held the lock before the execution of the bash script agw_install_docker.sh.
Solution: Reboot to terminate or wait for Ubuntu's self-update progress done, and then re-execute the bash script again.

Error 2: Failed to download key.

This error may be caused by the network.
Solution: Manually download and apply the key as the commands shown below, and then re-execute the bash script again.

# cat << EOF > /etc/apt/apt.conf.d/99insecurehttpsrepo
Acquire::https::artifactory.magmacore.org/artifactory/debian {
Verify-Peer "false";
Verify-Host "false";
};
EOF
# wget -qO - https://artifactory.magmacore.org:443/artifactory/api/gpg
/key/public | sudo apt-key add -
# sudo bash agw_install_docker.sh

📝 NOTE: If you have experienced errors not listed above, feel free to contact us.

Dockerized Magma AGW 1.8.0 Configuration Guide

Orc8r Configuration

AGW provides network services and policy enforcement. In an LTE network, the AGW implements an evolved packet core (EPC), and a combination of an AAA and a PGW. It works with existing, unmodified commercial radio hardware.

After the installation of Magma AGW on Magma Box, customers can run their local LTE network directly, or connect it to the Magma Orc8r, depending on the usage scenario.

Orc8r is a cloud service that provides a simple and consistent way to configure and monitor the wireless network securely. The Orc8r can be hosted on a public/private cloud or local server/PC. The metrics acquired through the platform allows you to see the analytics and traffic flows of the wireless users through the Magma web UI.

When the user decides to connect the AGW to an installed Orc8r, the AGW running on Magma Box needs some configuration:

Upload the Orc8r's rootCA.pem to Magma Box's /var/opt/magma/certs/. An empty rootCA.pem was initially created so when installing the AGW, delete it first.

Update the Orc8r's address in /etc/magma/control_proxy.yml, includes cloud_address, cloud_port, bootstrap_address, bootstrap_port, fluentd_address and fluentd_port.

For example:

# Cloud address for reaching out to the cloud.
cloud_address: controller.magma.rakwireless.com
cloud_port: 7443

bootstrap_address: bootstrapper-controller.magma.rakwireless.com
bootstrap_port: 7444

fluentd_address: fluentd.magma.rakwireless.com
fluentd_port: 24224

Then, restart AGW services or reboot Magma Box to make it work.

# cd /var/opt/magma/docker && sudo docker-compose restart

# sudo reboot

The Magma AGW is now configured for connecting to Orc8r. But, to accept the AGW’s connecting request, some work has to be done to the Orc8r. Refer to Magma’s NMs document Adding a New Gateway

Radio Spectrum Provision

The customers should comply with the local laws and regulations for radio spectrum setting of their 4G or 5G radio.

For USA customers, Magma AGW supports CBRS SAS procedures to help radios set up spectrum automatically. Refer to the following Magma documents for details: Enodebd CBRS Support, Domain Proxy Debug, and Google SAS Quick start guide, etc.

Radio Connection to AGW

The Magma AGW running on Magma Box’s default PLMN is 00101, and its binding SCTP IP address is exactly Magma Box eth1 port's address, 1 0.0.2.1/24 if the customers install Magma AGW according to IP Address Configuration.

A 4G eNodeB or 5G gNodeB, at least, needs to set its PLMN and MME/AMF IP to connect to the EPC/5GC. This can be done by configuring the eNodeB/gNodeB via its local Web Manager or GUI. Take Baicells Neutrino 430 as an example, Chapter 3.5.6 Configure Quick Settings in Baicells Neutrino430 Installation Guide describes how to configure the PLMN and MME IP.

Edge Computing Support

RAKwireless' Magma Box was developed based on a Raspberry Pi 4, running with a Quad core Cortex-A72 (ARM v8), and also 4 GB LPDDR4 for Black, 8 GB LPDDR4 for Gold. This means that the Magma Box have enough computing resource to run the customers' edge computing application along with Magma AGW services, such as a simple FTP server. In this case, customers can simply run an FTP download test with a UE, a radio, and Magma Box. No need to run an FTP server on a single server.

📝 NOTE: Magma Box allows customers to run their application on it, still the application can also run on somewhere else as you wish.

There are two key points of running an Edge Computing application:

Deploy the application to the Magma Box via docker or binary. For example, running a simple FTP server docker container on Magma Box:

# sudo docker run -d -p 60021:21 -p 60020:20 -p 21100-21110:21100-21110
\
-v /home/ubuntu:/home/vsftpd/ftp \
-e FTP_USER=ftp \
-e FTP_PASS=123456 \
-e PASV_ADDRESS=0.0.0.0 \
-e PASV_MIN_PORT=21100 \
-e PASV_MAX_PORT=21110 \
--name vsftpd \
--restart=always dotkevinwong/vsftpd-arm

Enable the local network access on Magma Box for the UEs. The feature is off by default. Change pipelined's block_agw_local_ips item from true to false to enable this feature.

# sudo vim /etc/magma/pipelined.yml

...
# Pipeline application level configs
access_control:
# Blocks access to all AGW local IPs from UEs.
block_agw_local_ips: false
...

Now the UE can ping to the Magma Box's internal IP address, and download or upload files to the FTP server running on Magma Box.

Integrated 5G Standalone

With Magma's v1.8.0 released, the 5G Standalone (SA) feature have been good enough for your 5G network developments, but this feature is off by default. In reference to Magma's document Integrated 5G SA, the 5G feature can be disabled or enabled using swagger API after AGW connected to Orc8r, but this can also be done without Orc8r when the AGW deployed is a standalone.

The root cause is that the changes via swagger API will generate a new gateway.mconfig file under Magma Box's directory /var/opt /magma/, but the file is not mandatory to running an AGW. The AGW will take configuration files under /etc/magma/ as first priority.

Enabling 5G SA Feature Manually Without Orc8r

SSH login to Magma Box.
For example:

# ssh ubuntu@10.0.2.1

Add or modify enable5g_features item to true in mme.yml, pipelined.yml, sessiond.yml, subscriberdb.yml under /etc/magma/ directory.
For example:

# sudo bash -c 'echo "enable5g_features: true" >> /etc/magma/mme.yml'
# sudo bash -c 'echo "enable5g_features: true" >> /etc/magma/pipelined.
yml'
# sudo bash -c 'echo "enable5g_features: true" >> /etc/magma/sessiond.
yml'
# sudo bash -c 'echo "enable5g_features: true" >> /etc/magma
/subscriberdb.yml'

Restart AGW services or reboot Magma Box to make it work.

# cd /var/opt/magma/docker && sudo docker-compose restart

# sudo reboot

Subscriber Configuration

It is easy to create, update, or delete subscribers via NMs. After connecting the AGW to Orc8r, refer to Magma's document Subscriber Configuration. This can also be done without Orc8r when the AGW deployed is a standalone.

Each AGW running on Magma Box have its own database, actually, it's sqlite3, to store the subcriber data, and Magma offers a python script subscriber_cli.py to manage them. Here are the commands it offers:

# sudo docker exec subscriberdb /usr/local/bin/subscriber_cli.py --help

Adding New Subscriber

This shows how to add a new subscriber to the Magma Box:

For example:
Adding a New Subscriber with IMSI 001010000000022:

# sudo docker exec subscriberdb /usr/local/bin/subscriber_cli.py add --
lte-auth-key 46006050000000191946006050000000 --lte-auth-opc
75C161CAAE5C323E551BF0341F03A2CA IMSI001010000000022

Showing Subscriber Details

After adding a new subscriber, the subscription details can be shown via the command below:

# sudo docker exec subscriberdb /usr/local/bin/subscriber_cli.py get
IMSI001010000000022

Updating Subscriber

As seen above, after adding a new subscriber, there's no APN configured. The subscriber's data has to be updated to make it complete.

Here takes APN internet and ims as an example:

# sudo docker exec subscriberdb /usr/local/bin/subscriber_cli.py update
--apn-config ims,5,15,1,1,2000000000,2000000000,0,,,, --apn-config
internet,9,15,1,1,2000000000,2000000000,0,,,, IMSI001010000000022

Deleting Subscriber

A subscriber can be deleted via this python script:

# sudo docker exec subscriberdb /usr/local/bin/subscriber_cli.py delete
$SID

Updated October 24, 2024 03:21

How To Configure Magma Orchestrator & NMS

Magma Orchestrator & NMS

Prerequisite

Environment Setup

Build Orchestrator & NMS

Run Orchestrator & NMS

Add Host Record on Your OM PC

Dockerized Magma AGW 1.8.0 Installation Guide

Ubuntu Server 20.04 LTS (64-BIT) Installation

IP Address Configuration

Power Up the Magma Box

Dockerized Magma AGW 1.8.0. Installation

Installation Errors and Solution

Dockerized Magma AGW 1.8.0 Configuration Guide

Orc8r Configuration

Radio Spectrum Provision

Radio Connection to AGW

Edge Computing Support

Integrated 5G Standalone

Subscriber Configuration

Adding New Subscriber

Showing Subscriber Details

Updating Subscriber

Deleting Subscriber

<%= previousTitle %>

<%= nextTitle %>

In this article

Categories

Toggle navigation menu

<%= category.name %>

Search

Magma Orchestrator & NMS

Prerequisite

Environment Setup

Build Orchestrator & NMS

Run Orchestrator & NMS

Add Host Record on Your OM PC

Dockerized Magma AGW 1.8.0 Installation Guide

Ubuntu Server 20.04 LTS (64-BIT) Installation

IP Address Configuration

Power Up the Magma Box

Dockerized Magma AGW 1.8.0. Installation

Installation Errors and Solution

Dockerized Magma AGW 1.8.0 Configuration Guide

Orc8r Configuration

Radio Spectrum Provision

Radio Connection to AGW

Edge Computing Support

Integrated 5G Standalone

Subscriber Configuration

Adding New Subscriber

Showing Subscriber Details

Updating Subscriber

Deleting Subscriber

<%= previousTitle %>

<%= nextTitle %>

In this article

Categories

Toggle navigation menu

<%= category.name %>

Categories

Categories