How to run free5GC on Incus (1of2)

Abstract

List of documents:
How to run free5GC on Incus (1of2): free5GC VM preparation on Incus
How to run free5GC on Incus (2of2): free5GC Installation on Incus

• Recently I've succeed to run free5gc v3.4.4 (2024-11-12) and UERANSIM on VMs managed by incus on Host OS Ubuntu 20.24 TLS as intrduced in this document.
• In summary, I have one private subnet (192.168.0.0/24) for the Internet access and I put one Host (MiniPC) to run such VMs as shown in the below figure.

Prerequisites

One client laptop PC that has:

• One NIC belongs to the private subnet to access to:
  the Internete via the default GW; and
  the Host 1st NIC (ssh:22 and free5gc-WebConsole:5000).

One Host (Mini PC) that has:

• Ubuntu 22.04 TLS (e.g. installed by ubuntu-22.04.5-live-server-amd64.iso)
• 1st NIC
  Set a static IP belongs to the private subnet to access to the Internet via the default GW, and to be accessed from the client laptop PC (ssh:22 and free5gc-WebConsole:5000).
  NOTE: DHCP dynamic IP allocation is not allowed to proxy to free5gc-WebConsole.
• 2nd NIC
  Don't set IP addresses, just used to attach MACVLAN NICs for each VM
  NOTE: WiFi NIC is not allowed to configure MACVLANs on the NIC.
• running sshd so that you can acess from the client laptop PC.

One Unmanged L2SW just to linkup Host's 2nd NIC.
NOTE: Each VM 2nd NIC IP is reachable from the L2SW side. So, you may connect other IP nodes (e.g. real gNBs) here to communicate with each VM regarding N1/N2 and N3 protocols.

This document assumes IP allocations and NIC names as listed in the below table. It is environment specific and you may replace them for your purpose.

	Item	IP alloc. on the private subnet	Default GW	Host NIC name
1	Host 1st NIC	192.168.0.199/24	192.168.0.1	enp89s0
2	Host 2nd NIC	No IP addrs	--	enp87s0

Also, this document assumes IP allocations through the procedure of this document. It is environment specific and you may replace them for your purpose.

	Item	IP alloc. on the Incus subnet	Default GW	VM NIC name
1	free5gc VM 1st NIC	10.194.245.2/24	10.194.245.1	enp5s0
2	free5gc VM 2nd NIC	192.168.56.101/24	--	enp6s0
3	ueransim VM 1st NIC	10.194.245.x/24 (dhcp dynamic)	10.194.245.1	enp5s0
4	ueransim VM 2nd NIC	192.168.56.102/24	--	enp6s0

1 Install Incus on Host Ubuntu 22.04

1.1 Install Incus

Install Incus as guided in Ref1 and Ref2.

• Ref1: https://linuxcontainers.org/incus/docs/main/installing/
• Ref2: https://github.com/zabbly/incus

First, verify that the fingerprint of key.asc matches 4EFC 5906 96CB 15B8 7C73 A3AD 82CC 8797 C838 DCFD:

curl -fsSL https://pkgs.zabbly.com/key.asc | gpg --show-keys --fingerprint

You should ge a return that is:

pub   rsa3072 2023-08-23 [SC] [expires: 2025-08-22]
      4EFC 5906 96CB 15B8 7C73  A3AD 82CC 8797 C838 DCFD
uid                      Zabbly Kernel Builds <[e-mail]>
sub   rsa3072 2023-08-23 [E] [expires: 2025-08-22]

Save the key locally.
NOTE: sudo is needed.

sudo curl -fsSL https://pkgs.zabbly.com/key.asc -o /etc/apt/keyrings/zabbly.asc

Add the package repository of TLS.
NOTE: sudo is needed.

sudo sh -c 'cat <<EOF > /etc/apt/sources.list.d/zabbly-incus-lts-6.0.sources
Enabled: yes
Types: deb
URIs: https://pkgs.zabbly.com/incus/lts-6.0
Suites: $(. /etc/os-release && echo ${VERSION_CODENAME})
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/zabbly.asc

EOF'

Install incus.
NOTE: sudo is needed. apt might be fine instead of apt-get though I didn't try it.

sudo apt-get update
sudo apt-get install incus

To run virtual machines, also install qemu-system as per Ref1.

sudo apt install qemu-system

1.2 Initialize Incus

• Ref3: https://linuxcontainers.org/incus/docs/main/tutorial/first_steps/
• Ref4: https://linuxcontainers.org/incus/docs/main/howto/initialize/

To run the incus command without sudo, add yourself to the 'incus-admin' group as per Ref3.

sudo adduser YOUR-USERNAME incus-admin
newgrp incus-admin

Initialize Incus with default options.

incus admin init --minimal

2 Prepare a VM Ubuntu 20.04 for free5GC on Incus

2.1 Create a profile to attach 2 NICs for a VM

During the VM creation, the default profile attaches 1 NIC device on a created VM. First, prepare another profile which attaches one more NIC additionally. You can do it by copying the default one to new one and editing it.

incus profile list
incus profile show default
incus profile copy default default2nics
incus profile list
incus profile show default2nics
incus profile edit default2nics

About the above edit default2nics, insert eth1 part to attach the 2nd NIC additionally and also modify description part as exampled below, namely from:

$ incus profile show default2nics
config: {}
description: Default Incus profile
devices:
  eth0:
    name: eth0
    network: incusbr0
    type: nic
  root:
    path: /
    pool: default
    type: disk
name: default
used_by: []
project: default

into:

$ incus profile show default2nics
config: {}
description: Default Incus profile with 2 NICs
devices:
  eth0:
    name: eth0
    network: incusbr0
    type: nic
  eth1:
    name: eth1
    nictype: macvlan
    parent: enp87s0
    type: nic
  root:
    path: /
    pool: default
    type: disk
name: default2nics
used_by: []
project: default

About parent:, replace 'enp87s0' to another one suitable for your environment. It should be one of NIC names confirmed by ip a command on your Host Ubuntu.

2.2 Launch a VM (ubuntu-free5gc)

• Ref5: https://linuxcontainers.org/incus/docs/main/howto/images_remote/
• Ref6: https://images.linuxcontainers.org/

First, list the image of Ubuntu 20.04 desktop VM.
NOTE: images:ubuntu/focal/desktop is avaiable for Incus as listed in Ref6. It includes the 'sctp' kernel module which is required for free5GC. That's why I installed Incus instead of LXD.

incus image list images:ubuntu/focal/desktop

Then, launch a new VM with the profile.
NOTE: This initial launch will take a few minutes to download the image.

incus launch -p default2nics images:ubuntu/focal/desktop ubuntu-free5gc --vm

List instances and confirm the VM is STATE RUNNING.

incus list

2.3 Configure a VM (ubuntu-free5gc)

• Ref7: https://linuxcontainers.org/incus/docs/main/tutorial/first_steps/
• Ref8: https://linuxcontainers.org/incus/docs/main/reference/devices_proxy/

Stop the VM for now to set further configrations on it. Confirm the VM is STATE STOPPED.

incus stop ubuntu-free5gc
incus list

Set configurations to limit VM resources.
NOTE: free5GC requires to disable the secureboot.
NOTE: Here, / (root) disk size is modified to 16GiB. override command is to override settings on the original defined in the profile default2nics. Note that it is effective only for the specified VM. Other VMs, if any, using the same profile are not affected.

incus config show ubuntu-free5gc
incus config set ubuntu-free5gc security.secureboot=false
incus config set ubuntu-free5gc limits.cpu=2
incus config set ubuntu-free5gc limits.memory=2GiB
incus config device override ubuntu-free5gc root size=16GiB
incus config show ubuntu-free5gc

Set configurations for free5gc webconsole access via eth0 device.

incus config device override ubuntu-free5gc eth0 ipv4.address=10.194.245.2
incus config device add ubuntu-free5gc port5000 \
proxy listen=tcp:192.168.0.199:5000 connect=tcp:10.194.245.2:5000 nat=true

By default of Incus, '10.194.245.1' should be the IPv4 address of your Host Ubuntu's incusbr0 bridge, confirmed by ip a command on your Host Ubuntu. Intention of '10.194.245.2' is to set a static IP for ubuntu-free5gc on incusbr0 bridge.

About listen=, replace '192.168.0.199' to another one suitable for your environment. It is an IPv4 address of the 1st NIC confirmed by ip a command on your Host Ubuntu.

Finally you can see your modifications done by the above incus config commands.

$ incus config show ubuntu-free5gc
architecture: x86_64
config:
(...)
  limits.cpu: "2"
  limits.memory: 2GiB
  security.secureboot: "false"
(...)
devices:
  eth0:
    ipv4.address: 10.194.245.2
    name: eth0
    network: incusbr0
    type: nic
  port5000:
    connect: tcp:10.194.245.2:5000
    listen: tcp:192.168.0.199:5000
    nat: "true"
    type: proxy
  root:
    path: /
    pool: default
    size: 16GiB
    type: disk
(...)
profiles:
- default2nics
(...)

Then, start the VM again and confirm the VM is STATE RUNNING.

incus start ubuntu-free5gc
incus list

2.4 Initial setup inside a VM (ubuntu-free5gc)

Enter the VM.

incus exec ubuntu-free5gc -- bash

Confirm VM resources and NIC devices.
NOTE: ip a should show enp5s0 for the 1st NIC and enp6s0 for the 2nd NIC.

Inside the VM (ubuntu-free5gc)

lscpu
df -h
free -m
ip a

Configure a static IPv4 address '192.168.56.101' for the 2nd NIC.

Inside the VM (ubuntu-free5gc)

touch /etc/netplan/95-manualconf.yaml
chmod 600 /etc/netplan/95-manualconf.yaml
vi /etc/netplan/95-manualconf.yaml

Configured 95-manualconf.yaml is:

Inside the VM (ubuntu-free5gc)

# cat /etc/netplan/95-manualconf.yaml
network:
  version: 2
  renderer: networkd
  ethernets:
    enp6s0:
      dhcp4: false
      addresses:
        - 192.168.56.101/24

Apply it.

Inside the VM (ubuntu-free5gc)

netplan try

Now you can see the configured IP for the 2nd NIC and ping should be reachable to the Internet via the 1st NIC.

Inside the VM (ubuntu-free5gc)

ip a
ip route
ping 192.168.56.101
ping 8.8.8.8
ping www.google.com

Exit from the VM.

Inside the VM (ubuntu-free5gc)

exit

3 Prepare another VM Ubuntu 20.04 for UERANSIM on Incus

3.1 Launch to Initial setup a VM (ubuntu-ueransim)

The procedure for UERANSIM VM is similar to one for free5gc VM.
Differences are:

• profle default2nics was already created. Skip its creation.
• proxy port5000 was just for free5gc. Skip its configuration.
• 2nd NIC IP '192.168.56.101' was for free5gc. Set another '192.168.56.102'.

incus launch -p default2nics images:ubuntu/focal/desktop ubuntu-ueransim --vm
incus list

incus stop ubuntu-ueransim
incus list

incus config show ubuntu-ueransim
incus config set ubuntu-ueransim security.secureboot=false
incus config set ubuntu-ueransim limits.cpu=2
incus config set ubuntu-ueransim limits.memory=2GiB
incus config device override ubuntu-ueransim root size=16GiB
incus config show ubuntu-ueransim

incus start ubuntu-ueransim
incus list

incus exec ubuntu-ueransim -- bash

Inside the VM (ubuntu-ueransim)

lscpu
df -h
free -m
ip a

touch /etc/netplan/95-manualconf.yaml
chmod 600 /etc/netplan/95-manualconf.yaml
vi /etc/netplan/95-manualconf.yaml

# cat /etc/netplan/95-manualconf.yaml
network:
  version: 2
  renderer: networkd
  ethernets:
    enp6s0:
      dhcp4: false
      addresses:
        - 192.168.56.102/24

netplan try
ip a
ip route
ping 192.168.56.102
ping 8.8.8.8
ping www.google.com
exit

3.2 Confirm the IP reachability between VMs

Now 2 VMs are running. Check the IP reachability between VMs over the 2nd NICs.

incus exec ubuntu-ueransim -- bash
(ubuntu-ueransim)# ping 192.168.56.101
(ubuntu-ueransim)# exit

incus exec ubuntu-free5gc -- bash
(ubuntu-free5gc)# ping 192.168.56.102
(ubuntu-free5gc)# exit

That's all for the VM preparation on Incus.
See the next document for free5GC installation on the VM.

The next document:
How to run free5GC on Incus (2of2): free5GC Installation on Incus