free5GC 4.2.3 (5G Core) on Ubuntu 24.04 on Azure User Guide

Overview

free5GC is an open-source implementation of the 3GPP Release 15+ 5G Core (5GC) maintained by the free5GC project. It provides the full service-based architecture of control-plane network functions — the NRF, AMF, SMF, AUSF, UDM, UDR, PCF, NSSF, CHF and NEF — together with the UPF user-plane function that carries subscriber data traffic. A built-in web console manages subscribers and SIM identities. Paired with a radio access network (real hardware, or a software simulator such as UERANSIM), free5GC authenticates a user equipment (UE), establishes a PDU session and routes that session out through the user plane.

The cloudimg image builds free5GC v4.2.3 from source and installs the whole all-in-one core on a single VM. The out-of-tree gtp5g UPF data-path kernel module is packaged with DKMS so it rebuilds automatically against the customer's kernel. MongoDB is bound to loopback only, and no default console login ships: at first boot each instance seeds a unique WebConsole administrator password into MongoDB before the console can serve, so the upstream default credential (admin/free5gc) is never a live login. Every network function and the WebConsole run as systemd services that come up in the right order after boot.

What is included:

• free5GC v4.2.3 control plane (NRF, AMF, SMF, AUSF, UDM, UDR, PCF, NSSF, CHF, NEF) + UPF, under /opt/free5gc (Apache-2.0)
• gtp5g v0.10.2 UPF data-path kernel module, DKMS-registered (auto-rebuilds on kernel upgrade)
• MongoDB 8.0 subscriber / policy / session store, bound to 127.0.0.1
• WebConsole (subscriber management UI) on loopback, fronted by nginx TLS on 443
• A per-VM WebConsole admin minted at first boot, written to /stage/scripts/free5gc-credentials.log (0600 root)
• UERANSIM (software gNB + UE) staged at /opt/ueransim as an optional self-test RAN, with a one-command subscriber provisioner
• Ubuntu 24.04 LTS base, latest security patches applied at build time
• 24/7 cloudimg support, 24h response SLA

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet. Recommended VM size: Standard_B2s — the full core plus a UERANSIM self-test comfortably fits (it uses under 1 GB of RAM). You will reach the WebConsole over HTTPS (port 443). To attach a real or remote simulated RAN you will also open SCTP 38412 (N2) and UDP 2152 (N3 / GTP-U).

Step 1: Deploy from the Azure Portal

Search the Azure Marketplace for free5GC 4.2.3 (5G Core) on Ubuntu 24.04. Create the VM with an NSG that allows:

• TCP 22 (SSH) from your management network
• TCP 443 (the WebConsole over TLS) from your admin network
• SCTP 38412 (N2 / NGAP) and UDP 2152 (N3 / GTP-U) from the network your RAN lives on — only needed once you attach an external gNB

Step 2: Deploy from the Azure CLI

RG="free5gc-lab"; LOCATION="eastus"; VM_NAME="free5gc-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/free5gc/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az network vnet create -g "$RG" --name f5gc-vnet --address-prefix 10.90.0.0/16 --subnet-name f5gc-subnet --subnet-prefix 10.90.1.0/24
az network nsg create -g "$RG" --name f5gc-nsg
az network nsg rule create -g "$RG" --nsg-name f5gc-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name f5gc-nsg --name allow-webconsole --priority 110 \
  --source-address-prefixes "<your-admin-cidr>" --destination-port-ranges 443 --access Allow --protocol Tcp
az vm create -g "$RG" --name "$VM_NAME" --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name f5gc-vnet --subnet f5gc-subnet --nsg f5gc-nsg --public-ip-sku Standard

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

Step 4: Verify the 5G Core Services

Every network function, MongoDB and the WebConsole are systemd services that start automatically after the first-boot provisioning completes. Confirm the posture:

for s in mongod free5gc-nrf free5gc-amf free5gc-smf free5gc-upf free5gc-ausf \
         free5gc-udm free5gc-udr free5gc-pcf free5gc-nssf free5gc-webconsole nginx; do
  printf '  %s = %s\n' "$s" "$(systemctl is-active $s)"
done
modinfo -F version gtp5g
mongosh free5gc --quiet --eval 'db.NfProfile.countDocuments()'   # NFs registered with the NRF

Step 5: Retrieve the WebConsole Admin Password

The per-VM WebConsole administrator password is minted at first boot and written to a root-only file. There is no shared or default login in the image — the upstream admin/free5gc default is never a working credential.

sudo cat /stage/scripts/free5gc-credentials.log

# free5GC v4.2.3 — Per-VM Credentials
#
# WebConsole (HTTPS via nginx):  https://<vm-ip>/
# Sign in:                       admin / <password below>
#
FREE5GC_WEBUI_USER=admin
FREE5GC_WEBUI_PASSWORD=<unique-per-VM-password>
FREE5GC_URL=https://<vm-ip>/

Step 6: Sign in to the WebConsole over TLS

Browse to https://<vm-ip>/ and sign in as admin with the per-VM password from Step 5. The WebConsole is served on the VM's loopback interface and fronted by nginx TLS on 443; the raw console port is never directly reachable.

Step 7: Manage Subscribers

The WebConsole's Subscribers view lists the SIM identities the core will authenticate. Each subscriber is a SUPI (IMSI) with its permanent key (K), operator code (OPc), PLMN, network slice and DNN. This is where you provision the SIMs your RAN and devices will use.

Opening a subscriber shows its full 5G-AKA security configuration — the SUPI, GPSI, authentication method, key material, slice and data network:

Step 8: Run the Built-in Self-Test (establish a real PDU session)

The image ships UERANSIM — a software gNB and UE — at /opt/ueransim so you can prove the core works end-to-end with no radio hardware. The one-shot self-test below provisions the default test subscriber (via the WebConsole API with your per-VM admin), starts the software gNB and UE in the background, and shows the UE getting a data-plane IP:

# Provision the default test subscriber (idempotent) and run the software RAN self-test
sudo /opt/ueransim/provision-test-subscriber.sh || true
cd /opt/ueransim
sudo nohup ./bin/nr-gnb -c ./config/free5gc-gnb.yaml >/tmp/gnb.log 2>&1 &
sleep 5
sudo nohup ./bin/nr-ue -c ./config/free5gc-ue.yaml >/tmp/ue.log 2>&1 &
sleep 20
grep -E 'NG Setup procedure is successful' /tmp/gnb.log || true
grep -E 'Registration is successful|PDU Session establishment is successful' /tmp/ue.log || true
ip addr show uesimtun0 || true

When the UE registers and the SMF/UPF establish the session, the UE gets an IP on the uesimtun0 tunnel interface from the UPF's DNN pool (10.60.0.0/16). You can then route application traffic through the 5G user plane:

# route an application's traffic through the 5G tunnel (source IP = the UE's 10.60.x address):
cd /opt/ueransim/bin && sudo ./nr-binder 10.60.0.1 curl -s https://ifconfig.me || true

To stop the self-test: sudo pkill -f nr-ue; sudo pkill -f nr-gnb.

Step 9: Attach a Real or Remote RAN

The shipped self-test runs the RAN on the same host over loopback. To attach an external gNB (real hardware or a remote UERANSIM), rebind the AMF's N2 address and the UPF's N3 GTP-U address to the VM's own IP and point your gNB at it:

# AMF N2 (NGAP) — set ngapIpList to the VM's private IP
sudo sed -i "s/127.0.0.18/<private-ip>/" /opt/free5gc/config/amfcfg.yaml
# UPF N3 (GTP-U) — set the gtpu addr to the VM's private IP
sudo sed -i "s/127.0.0.8/<private-ip>/" /opt/free5gc/config/upfcfg.yaml
sudo systemctl restart free5gc-amf free5gc-upf

Then open SCTP 38412 (N2) and UDP 2152 (N3) in the NSG from your RAN's network, and configure your gNB's AMF address to the VM IP. Provision each device's SIM (SUPI, K, OPc, slice, DNN) in the WebConsole to match the SIMs in your handsets or test UEs.

Step 10: Managing the Services

# The whole core is enabled and starts at boot. To inspect or restart a function:
sudo systemctl status free5gc-amf
sudo systemctl restart free5gc-smf free5gc-upf
sudo journalctl -u free5gc-amf -f      # follow a network function's log

The UPF data-path module gtp5g is registered with DKMS, so it is rebuilt automatically when Ubuntu ships a new kernel — dkms status shows it installed for the running kernel.

Step 11: Security Recommendations

• Keep the WebConsole (443) restricted to your admin network in the NSG. It manages SIM credentials and must not be exposed to the internet.
• Only open the RAN ports (SCTP 38412, UDP 2152) to the networks your gNBs live on. The N2/N3 interfaces have no application-layer authentication and rely on network isolation.
• MongoDB is bound to loopback in this image — keep it that way; the network functions and console reach it locally.
• Rotate the WebConsole admin password from the console's user management, and provision one SIM per device rather than sharing a single test SIM in production.

Step 12: Support and Licensing

free5GC is licensed under Apache-2.0; UERANSIM under GPL-3.0 (shipped as an optional self-test tool). This image is provided by cloudimg with 24/7 support and a 24-hour response SLA.

Need Help?

Contact cloudimg support through the Azure Marketplace listing or at cloudimg.co.uk.