This setup is implemented by installing the Free5GC Core and UERANSIM (UE/gNB) in separate virtual machines. Please refer to the official documentation before following the steps in our wiki.

Virtual Machine Setup

Base Ubuntu Installation

The following are the prerequisites for installing Free5GC and UERANSIM (assuming Ubuntu 22.04.5 LTS):

1. Create Ubuntu VM with two network adapters:

   • Adapter 1: NAT
   • Adapter 2: Host-only Adapter

2. Basic system setup:

sudo apt install net-tools
sudo apt update
sudo apt upgrade

3. Clone the VM for both Free5GC and UERANSIM setups:
   • Select "Generate new MAC addresses for all network adapters"
   • Create as "Linked clone"

5G Core (Free5GC VM)

Network Configuration

1. Configure hostname:

sudo nano /etc/hostname
# Change to: free5gc

2. Update hosts file:

sudo nano /etc/hosts
# Change 127.0.1.1 entry to: free5gc

3. Configure network:

cd /etc/netplan
sudo nano 00-installer-config.yaml  # File name may vary

sudo netplan try Test the configuration

sudo netplan apply Apply the configuration

ifconfig Verify enp0s8 shows IP address 192.168.56.101

Installation

Install Go Language

wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
mkdir -p ~/go/{bin,pkg,src}

# Add to ~/.bashrc
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export GOROOT=/usr/local/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin:$GOROOT/bin' >> ~/.bashrc
echo 'export GO111MODULE=auto' >> ~/.bashrc
source ~/.bashrc

Install MongoDB

sudo apt install gnupg
sudo apt install curl

curl -fsSL https://pgp.mongodb.com/server-6.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg --dearmor

echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

sudo apt update
sudo apt install -y mongodb-org
sudo systemctl enable mongod

Install Dependencies

sudo apt -y install git gcc g++ cmake autoconf libtool pkg-config libmnl-dev libyaml-dev

Network Configuration

sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o enp0s3 -j MASQUERADE
sudo systemctl stop ufw

Install Free5GC

git clone --recursive https://github.com/free5gc/free5gc.git
cd free5gc
make

cd ~
git clone https://github.com/free5gc/gtp5g.git
cd gtp5g
make
sudo make install

Verify installation: lsmod | grep gtp

Web Console Setup

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm install -g corepack
corepack enable
corepack prepare yarn@stable --activate

cd free5gc
make webconsole
cd webconsole

Configuration Files

1. amfcfg.yaml

2. smfcfg.yaml

3. upfcfg.yaml

Register Subscriber Information

1. Start Free5GC:

cd ~/free5gc
./run.sh

2. Start Web Console:

cd webconsole
go run server.go

3. Access web interface:

   • URL: http://192.168.56.101:5000
   • Username: admin
   • Password: free5gc

4. Add default subscriber through web interface

UE/gNB (UERANSIM VM)

Network Configuration

1. Configure hostname:

sudo nano /etc/hostname
# Change to: ueransim

2. Update hosts file:

sudo nano /etc/hosts
# Change 127.0.1.1 entry to: ueransim

3. Configure network (IP: 192.168.56.102):

cd /etc/netplan
sudo nano 00-installer-config.yaml

Installation

Install Dependencies

sudo apt update
sudo apt upgrade
sudo apt install make gcc g++
sudo apt install libsctp-dev lksctp-tools
sudo apt install iproute2
sudo snap install cmake --classic

Install UERANSIM

cd ~
git clone https://github.com/aligungr/UERANSIM
cd UERANSIM
make

Configuration Files

1. free5gc-gnb.yaml

2. free5gc-ue.yaml - Use default configuration for default subscriber

Running the System

Start Free5GC

sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o enp0s3 -j MASQUERADE
sudo systemctl stop ufw
sudo iptables -I FORWARD 1 -j ACCEPT
cd ~/free5gc
./run.sh

Start UERANSIM (In separate terminals)

1. Start gNB:

cd ~/UERANSIM
build/nr-gnb -c config/free5gc-gnb.yaml

2. Start UE:

sudo build/nr-ue -c config/free5gc-ue.yaml

3. Verify connectivity:

ping -I uesimtun0 google.com

Success Indicators:

• "NG Setup Procedure Successful" message
• "TUN interface is up" message
• Successful ping to google.com without packet loss

Troubleshooting

1. If network connectivity fails:

   • Verify IP addresses in configuration files
   • Check firewall status
   • Verify network interface configurations

2. If UE connection fails:

   • Check AMF logs
   • Verify subscriber information
   • Check gNB configuration

3. Common issues:

   • MongoDB connection errors
   • Network routing issues
   • Firewall blocking connections