open5Gcube is a Modular Framework for Mobile Network Laboratories. It builds and manages open-source mobile network stacks, including 2G, 4G, and 5G systems. It is designed for research, testing, and educational purposes, providing users with a customizable and extensible environment for deploying radio access networks (RAN), core networks (CN), and supporting components.

---

I. Overview II. Getting Started III. Configuration IV. Usage V. Documentation VI. License

---

📍 Overview

open5Gcube facilitates reproducible experiments across a variety of mobile network configurations by using:

• Docker containers and Docker Compose for isolated service deployments.
• Pre-built network Stacks representing different technology combinations (e.g., OAI-RAN + Open5GS core).
• Remote container orchestration across multiple physical hosts using SSH and Docker-outside-of-Docker (DooD).
• A WebUI for visual control and monitoring of the Stack deployments.
• Support for physical SDR hardware (USRP X310/B210), as well as emulated setups.

Features

• Full-stack mobile network simulation (2G/4G/5G, NSA/SA)
• Integration with:
  • Open5GS, OpenAirInterface, UERANSIM, srsRAN, osmocom, and more
• Easy-to-use WebUI
  • View and control container health and logs
  • Start/stop Stacks
• VoLTE configuration based on Open5GS + Kamailio IMS
• SIM card provisioning tools via pySim

🚀 Getting Started

Prerequisites

BIOS

For performance tuning, it is recommended to disable hyper-threading, CPU frequency control, C-States, P-States and any other power management settings.

Operating System

Ubuntu 22.04 is recommended as base host distribution.

Installation

Required Packages

sudo apt install linux-tools-common net-tools make git-lfs ca-certificates curl gnupg openssh-server python3-virtualenv

Clone the Repository

git clone https://github.com/open5Gcube/open5Gcube/
cd open5Gcube

Docker Engine

See official Docker documentation for details. Specific fixed versions of the Docker packages are installed with the script modules/base/docker/o5gc/install-docker.sh. Execute it with

make system-install-docker

Install open5Gcube systemd Startup Service

make systemd-install-unit

Build all Docker Images

To build all docker images for all sub-projects on the Controller host as well as the ran projects on the configured ran hosts, run

make build-cacher-start docker-build-all

and get yourself a big cup of coffee as this will take a few hours.

Start the open5Gcube WebUI

make webui-start

⚙️ Configuration

The configuration of the installation and the global settings across the Stacks is done via different environment files in the etc directory.

System Specific Settings

The system installation specific configuration can be adjusted in the file etc/local.env:

1. Set the CLOCK_SRCeither to external or internal, depending on whether an external clock supply is connected to the USRP or not.
2. If components of the network (especially the RANs like the gNB) are distributed across different hosts, set the Docker network driver for the corenet to macvlan. If all services are running on the same host, a bridge can be used instead.

# CORENET_DRIVER should be
#   - 'macvlan' if components (such as the gNB) are distributed across
#               different hosts
#   - 'bridge' if *all* components are running on this host
# run 'make systemd-startup-unit' after changing one of the following
# settings
CORENET_DRIVER=bridge
# If macvlan is used, set the parent interface here
CORENET_MACVLAN_IFACE=eno1

3. Set the USRP_IFACE to the interface name of the 10G adapter connected to the USRP X310 on the RAN hosts. Leave it unchanged if USRPs B210 via USB are used.
4. Configure the hostname of the enb and gnb ran hosts:

# eNB / gNB RAN hostnames
ENB_HOSTNAME=localhost
GNB_HOSTNAME=localhost

settings.env

Sets especially the 4G / 5G mobile network settings like the PLMN, TAC, APN and the used frequencies. These configurations are utilised by all Stacks if not configured explicitly to different values in the Stack directory.

# Mobile Network
MCC=001
MNC=01
TAC=1
APN=internet
# Network Slice Selection Assistance Information
NSSAI_SST=1
NSSAI_SD=ffffff
# 5G Band
NR_BAND=78
# 5G Channel Number (ARFCN)
NR_ARFCN=641280
...

uedb.env

This file contains the database for all SIM Cards, including the IMSI, Key and the OPc. On startup of the Core Networks short-living initialization containers and helper scripts uses this settings to program the corresponding databases of the particular Core Network.

UE_DB+="
#IMSI           Key                              OPc
# add one subscriper per line, like for example
001010000052100 F18E5DB0A8B5B8A0304E9113D121DFE3 E83C9CF73E3B9E82E48005A696E86AD8
...
"

In addition, each .env file in the optional directory etc/uedb.d/ is included to extend the UE_DB. This can be used to organize the subscriber information in a separate repository.

Stack specific settings

Each Stack can override all of the above settings by providing a separate settings.env file in its directory. This is useful if a Stack requires fix certain configurations to function correctly, for example if slicing is not supported.

🖵 Usage

Command Line

A Makefile is the central entry point for all commands on the console, so they start all with make followed by the target which should be executed. make help will list the most important targets. Most consoles supports Tab-completion which helps exploring the available commands as well.

Build Docker Images

The build process is managed by the Makefile, which takes care of handling the dependencies. To build all images, the following command is executed:

make docker-build-all

For building individual images, the Makefile provides the following command format:

make docker-build-<image-name>

For example:

make docker-build-oai-amf

To delete all images, the following command is used:

make docker-purge-all-images

Running Stacks

For each Stack defined in the modules, there is a make run-<stackname> command. So for example, to run the 5G-SA Stack composed of OAI-RAN and Open5GS, run

make run-oairan-open5gs-5g

This starts all containers of the Stack and attaches to their console output. To stop the Stack just press Ctrl + c.

In general, for Mobile-Network Stacks the naming follows the convention <ran-project>-<core-project>-<technology>.

The startup-scripts of the RAN containers automatically take over the execution of the containers on the remote RAN hosts, if so configured in etc/local.env.

As an alternative, it is possible to start each component separately. This is especially useful if the RAN should run on the same host. Run

make run-oairan-open5gs-5g-core

to start just the core of the Stack, and

make run-oairan-open5gs-5g-gnb

to start the gnB.

To get a better overview of the running containers on the Controller host, ctop provides a concise and condensed overview of real-time metrics. It can be started with

make ctop

WebUI

When booting the Controller host, the open5Gcube WebUI is started automatically, listening on the standard HTTP port. The WebUI provides a user-friendly interface to

• Get an overview of the currently running containers, including
  • the log output,
  • the health status
  • and detailed container information
• Start and stop Stacks, optionally with adjusted settings
• Read and write SIM Cards
• Get links to web services by the Stack

📄 Documentation

Comprehensive documentation can be found in the Doc directory as well as in the WebUI.

📜 License

This project is licensed under the terms of the Apache-2.0 license. For more details, refer to the LICENSE file.