SCN currently runs the LTE-specific components of the Open5GS 4G/5G Non-Standalone (NSA) core.
You can find more detailed documentation and diagrams of the Open5GS software architecture at the Open5GS Quickstart page. Their software supports both 4G and 5G, and you only need to run a subset of the software components for 4G.
In SCN we will typically perform these installation steps using a fresh install of Ubuntu 22.04 on an x86-64-based computer; however, any operating system that open5gs supports should work.
In SCN we will typically perform these installation steps using a fresh install of Ubuntu 24.04 on an x86-64-based computer; however, any operating system that open5gs supports should work.
Note: When you're installing Ubuntu, we suggest choosing the "minimal install" option that doesn’t install extra unnecessary software. In prior installs this has led to version conflicts.
As of November 2024, in the Open5GS software package, the LTE-specific components (which run on Ubuntu as systemd services) are as follows:
@@ -174,43 +174,47 @@open5gs-upfd.serviceWe would also recommend running the optional WebUI (Web User Interface) service: open5gs-webui.service.
The following steps will walk you through this installation process.
-Install Open5GS following the Open5GS Quickstart documentation based on your operating system and desired implementation (e.g. "bare metal" directly on the operating system vs. Docker). -There are even VoLTE and Dockerized VoLTE implementations of Open5GS. -A similar step-by-step tutorial to this one can be found here.
-In SCN we have run Open5GS successfully using Ubuntu 20.04 and 22.04, on bare metal or in Virtual Machines, installed via the apt package manager (see Step "2. Install Open5GS with a Package Manager" of the Quickstart).
+
The following steps will walk you through this installation process.1
+Complete at least Section 2 of the guide based on your operating system (OS) and desired implementation (e.g. "bare metal" directly on the OS vs. Docker).2
+In SCN we have run Open5GS successfully using Ubuntu 20.04, 22.04, and 24.04 (on bare metal or in Virtual Machines) and installed via the apt package manager (see Step "2. Install Open5GS with a Package Manager" of the Quickstart).
First install MongoDB as described in the Quickstart. Then follow instructions under the "Ubuntu" section to install Open5GS via apt.
Note: If installing over a ssh connection, we recommend using tmux or another program in case you get disconnected from the session in the process.
Note that for our LTE setup, the MME and SGWU are the only components whose config files you will really need to change from the defaults.
-We also recommend Section 3, though it is not required. +This will later allow you to register subscribers via the GUI steps provided in the "Register Subscriber Information" section of the Quickstart.
+After these two sections of the Quickstart, you can mostly return to our tutorial here. +However, later on in the Networking section we will also be completing the Quickstart steps to "enable forwarding and add the NAT rule" section called "Adding a route for the UE to have WAN connectivity," so you can complete them now if you wish.
+Note: If installing Open5GS over a ssh connection, we recommend using tmux or another program in case you get disconnected from the session in the process.
For our LTE setup, the MME and SGWU are the only components whose config files you will need to change from the defaults.
+Edit the /etc/open5gs/mme.yaml file (as root or using sudo) as follows:
-- Under mme: -> s1ap: -> server: -> address:, set the IP address you will assign to the network interface (likely an ethernet port) on your EPC computer which will be connecting to the eNB. In this tutorial (to match with the Network Configuration section that follows), we will use 192.168.150.1.
+- Under mme: -> s1ap: -> server: -> address:, set the IP address you will assign to the network interface (likely an ethernet port) on your EPC computer which will be connecting to the eNB. In this tutorial (to match with the Network Configuration section that follows), we will use 192.168.150.2.
- Under both mme: -> gummei: and mme: -> tai:, you will need to change the plmn_id: (mcc: and mnc: values) to match the PLMN you are using for your network. In SCN we use 315 for the MCC and 010 for the MNC, as explained in the "Quick explanation" below.
Quick explanation: "PLMN" refers to the Public Land Mobile Network, in which every network has to have a unique carrier ID defined by the 3-digit "mobile country code (MCC)" and a 2 or 3-digit "mobile network code (MNC)". Alternately, for iPhone compatibility in the US, SCN uses the CBRS "private LTE" PLMN assigned by Apple as described in this doc.
mme: -> tai: -> tac: will need to match the TAC number configured on the eNB (using the default of 1 is fine). network_name: (full and short) and mme_name: as desired. One of these names will show up on smartphones' lock screens as the "carrier" when the phone is attached to the network.Edit the /etc/open5gs/sgwu.yaml file (as root or using sudo) as follows:
-- Under sgwu: -> gtpu: -> server: -> address:, set the IP address you will assign to the network interface on your EPC computer which will be connecting to the eNB (this should be the same as the IP address of the MME set above, if the MME and SGWU are running on the same machine). In this tutorial we will use 192.168.150.1.
sgwu: -> gtpu: -> server: -> address:, set the IP address you will assign to the network interface on your EPC computer which will be connecting to the eNB (this should be the same as the IP address of the MME set above, if the MME and SGWU are running on the same machine). In this tutorial we will use 192.168.150.2.
As mentioned in the Quickstart, after changing the config files, you will need to restart the corresponding Open5GS daemons:
sudo systemctl restart open5gs-mmed
sudo systemctl restart open5gs-sgwud
However, the MME will likely not start correctly until networking is configured, as described below.
-Remember to follow all the network configuration steps in the Open5GS Quickstart documentation. For SCN's Ubuntu machines, this means:
-sudo sysctl -w net.ipv4.ip_forward=1
-However, the MME will not start correctly until networking is configured, as described below.
+Setting up networking can be the most finicky part of Open5GS configuration, and the source of most failures/bugs.
+For SCN's Ubuntu machines, this means:
bash
+ sudo sysctl -w net.ipv4.ip_forward=1/etc/sysctl.conf remove the # comment symbol from the front of the line that says net.ipv4.ip_forward=1iptables so that traffic from the eNB can reach the Internet and vice versaiptables so that traffic from the eNB can reach the Internet and vice versa. The latter two steps are explained in detail below.
For Ubuntu 22.04, we're currently using the Netplan program to manage our network configuration. +
For Ubuntu 24.04, we're currently using the Netplan program to manage our network configuration.
Create a file in the /etc/netplan directory (i.e. a folder) named
99-open5gs-config.yaml, and add the following lines, substituting the correct
interface names and subnets for your configuration:
192.168.0.2). Until those IP addresses exist on your machine,
+addresses (in this case 192.168.150.2). Until those IP addresses exist on your machine,
the MME will continually throw errors if you try to run it.
iptables NAT rules to connect the eNB to the InternetAs explained above, the eNB currently has the IP addresses 192.168.150.1 and 192.168.151.1-- private IP addresses that cannot be used on the public Internet. Therefore, to successfully route the eNB's network traffic to the Internet, we have to add a routing rule in the EPC computer that performs NAT, allowing packets from the eNB's subnet to exit the WAN port of the EPC masquerading as coming from the EPC's IP address to the upstream network.
There might be an easier way to do this, but we've found the cleanest and most reliable way so far to be using the iptables command line tool. In the Terminal on the EPC, run the following command to add a NAT rule for the eNB's subnet:
sudo iptables -t nat -A POSTROUTING -s 192.168.151.0/24 -j MASQUERADE
+sudo iptables -t nat -A POSTROUTING -s 10.45.0.0/16 ! -o ogstun -j MASQUERADE
Quick explanation: The -t nat option tells IPTables to install the rule in the correct "table" containing all the NAT rules, and the -A option means we're Adding the rule as opposed to Deleting it (-D). POSTROUTING is the "chain," or particular list of rules, that this type of NAT rule should go in (more on that here and in this diagram if you're interested). -s 192.168.151.0/24 means that we're applying this rule to packets from the Source IP addresses described by the subnet 192.168.151.0/24. -j MASQUERADE means the action we'll be Jumping to as a result of this rule is "masquerading" the source IP address as my EPC's WAN IP address.
Quick explanation: The -t nat option tells IPTables to install the rule in the correct "table" containing all the NAT rules, and the -A option means we're Adding the rule as opposed to Deleting it (-D). POSTROUTING is the "chain," or particular list of rules, that this type of NAT rule should go in (more on that here and in this diagram if you're interested). -s 192.168.151.0/24 means that we're applying this rule to packets from the Source IP addresses described by the subnet 192.168.151.0/24. -j MASQUERADE means the action we'll be Jumping to as a result of this rule is "masquerading" the source IP address as my EPC's WAN IP address.
+The second rule allows traffic from the LTE clients on the open5gs subnet to get routed out to the Internet as well.
We use IPTables rules to make sure packets are routed correctly within the EPC. IPTables rules must be made persistent across reboots with the iptables-persistent package:
sudo apt install iptables-persistent
@@ -306,14 +312,14 @@ 'Persist' IPTables Configuration
sudo iptables-save > /etc/iptables/rules.v4
sudo iptables-restore < /etc/iptables/rules.v4
-Step 3: Start and monitor Open5GS software services
+Step 4: Start and monitor Open5GS software services
Ubuntu’s built-in logging and monitoring services can be used to monitor the core network services. For example, for seeing the output logs of the MME software component we described in the first section, run the following command in the Terminal:
sudo journalctl -f -u open5gs-mmed.service
OR
sudo systemctl status open5gs-mmed.service
-Tab complete may be able to fill in the service name for systemctl at least.
+Tab complete may be able to fill in the service name for systemctl though often not for journalctl.
Learning to read output logs is really important for managing software infrastructure! Simply Googling output messages that seem important but that you don't understand can be a good first step to figuring out how a system is working. Another interesting tool to investigate is Wireshark, which is essentially a graphical user interface (GUI) version of the tcpdump command line tool that can show you the communications packets flowing through the various network cards on your computer.
Here are some more useful commands for managing systemd services, which can be used to start, stop, and reload the software components after you've changed their configuration or they've run into errors and need to be restarted:
sudo systemctl start open5gs-mmed.service
@@ -324,16 +330,18 @@ Step 3: Start and mo
The following command will start only the systemd services required for LTE. However, you do not need to stop or disable the other components of the 5G core for it to run 4G LTE network hardware correctly- the full Open5GS 5G core is backwards compatible with LTE hardware if you configure the LTE components correctly.
sudo systemctl start open5gs-hssd.service open5gs-mmed.service open5gs-sgwud.service open5gs-sgwcd.service open5gs-pcrfd.service open5gs-upfd.service open5gs-smfd.service
-Install and Start the WebUI
-The WebUI is another systemd service and runs by default on your local computer at port 9999.
-It requires some more dependencies to install, such as nodejs (see Step "3. Install the WebUI of Open5GS" in the Quickstart). You can reach it by navigating to http://localhost:9999 in your web browser.
-If not already started, start it with the following command:
+Start the WebUI
+The WebUI is another (optional) systemd service you may have chosen to install while following the Open5gs Quickstart.
+It is a web portal that runs by default on port 9999 on the EPC computer.
+You can reach it by navigating to http://localhost:9999 in your web browser.
+It requires some more dependencies to install, such as nodejs (see Step "3. Install the WebUI of Open5GS" in the Quickstart).
+If the service has not already started, start it with the following command:
sudo systemctl start open5gs-webui.service
The default WebUI login credentials are as follows:
- Username : admin
- Password : 1423
-Step 4: Add Users to Open5GS database
+Step 5: Add Users to Open5GS database
(Note that an important pre-condition to adding users is to have SIM cards or eSIMs to give to the users for authentication, along with their respective IMSIs and secret keys to register them onto the EPC. These must be procured separately.
WIP- We will endeavor to make guides for these processes available soon.)
You can manage users using the Open5GS WebUI, or using a script provided in the Open5GS GitHub repository.
@@ -352,7 +360,7 @@
Step 4: Add Users to Open5GS datab
add_ue_with_apn {imsi key opc apn}: adds a user to the database with a specific apn
The help text also tells you that "default values are as follows: APN "internet", dl_bw/ul_bw 1 Gbps, PGW address is 127.0.0.3, IPv4 only".
-Step 5: Maintenance and Management
+Step 6: Maintenance and Management
Updating Open5GS
WIP: We are working on an Ansible-based management script for updates and will post updates as they occur.
Backup and Restore
@@ -362,6 +370,17 @@ Deprecated: CoLTE/EPC (LTE C
For information on how to install and configure CoLTE, visit the tutorial we wrote with them, on which this document is based.
Comments and Feedback
Please get in touch with us at support@seattlecommunitynetwork.org if you have questions or feedback about this tutorial! We want your feedback so we can make this better.
+
+
+
+-
+
A similar step-by-step tutorial to this one can be found here. ↩
+
+-
+
There are even VoLTE and Dockerized VoLTE implementations of Open5GS. ↩
+
+
+