This repository comprises a collection of scripts designed to facilitate the deployment of instances of the free5GC project.
The comprehensive documentation available on the project's official website is highly advisable for individuals new to free5GC to familiarize themselves with. The underlying processes are to be carefully studied, as the scripts are designed to replicate the steps outlined in the "Build free5GC from scratch" guide in an automated manner.
In the course of my research, I've been utilizing the free5GC project. During the experimentation with this 5G Core (5GC) advanced setup and its associated Network Functions (NFs), I discovered an opportunity to streamline the installation process. By automating various installation tasks, I significantly reduced deployment time, optimizing efficiency and enabling a more agile research environment.
During the process of seeking a similar tool, I've found 301 repositories hosted on Github that had the word "free5gc" on them. As I took a deeper look, I noted that:
- 23 (7.6%) were related to Kubernetes;
- 27 (9.0%) were related to docker but not to Kubernetes;
- 35 (11.6%) were written in Shell Script;
- Additional forms of automation (e.g. For AWS environments) were found too
However the focus of my scripts were to (semi-)automatically deploy free5GC, and I couldn't find any projects that would fit this purpose.
Entering into the spirit of FSFE's (FSF Europe) campaign "Public Money? Public Code!" and given that my research is currently being funded by public administration entities (namely CAPES and RNP) I decided to share my code with the community as it may help others in the future.
The scripts were tested within an environment that possessed the following characteristics:
- Bash shell 5.0.17 (or later)
- Ubuntu Server 20.04.6
- 20GB HDD
- 2GB RAM
- 1x i5 processor CPU core
- 40GB HDD
- 4GB RAM
- 2x i5 processor CPU core
For more information see this FAQ
Download the scripts
curl -LO https://github.com/oliveiraleo/free5gc-auto-deploy/raw/main/install-go.sh
curl -LO https://github.com/oliveiraleo/free5gc-auto-deploy/raw/main/deploy-free5gc.sh
chmod +x deploy-free5gc.sh install-go.sh # gives execution permission
Tip: Use -LOSs instead of -LO to suppress curl's output messages (for more information see this page)
Install Go and reload the environment vars
./install-go.sh && source ~/.bashrc
Then install free5gc
./deploy-free5gc.sh
Note: Unless otherwise specified, the script will automatically install the stable version defined by the FREE5GC_VERSION variable, without making any changes to the N3IWF configuration
Currently, deploy-free5gc.sh script accepts two parameters:
-nightly: Clones free5GC nightly version set by FREE5GC_NIGHTLY_COMMIT variable instead of the stable one-n3iwf: Prepares the configuration file of the N3IWF during the installation
Example usage:
./deploy-free5gc.sh -nightly -n3iwf
Download the script
curl -LO https://github.com/oliveiraleo/free5gc-auto-deploy/raw/main/deploy-UERANSIM.sh
chmod +x deploy-UERANSIM.sh # gives execution permission
Then install UERANSIM
./deploy-UERANSIM.sh -stable
Currently, deploy-UERANSIM.sh script accepts four parameters:
-stable: Clones UERANSIM stable version-nightly33: Clones UERANSIM nightly version compatible with free5GC v3.3.0 or below-nightly: Clones UERANSIM nightly version compatible with free5GC v3.4.0 or above-keep-hostname: Disables changing the machine hostname during the deploy
Example usage:
./deploy-UERANSIM.sh -nightly
Note: This script requires a "version related" parameter to work. Please select one from the list provided above that is compatible with your environment
Please, follow the instructions from this page here
To deploy the gNB:
cd ~/UERANSIM
build/nr-gnb -c config/free5gc-gnb.yaml
To deploy the UE:
cd ~/UERANSIM
sudo build/nr-ue -c config/free5gc-ue.yaml # for multiple-UEs, use -n and -t for number and delay
Download the scripts
curl -LO https://github.com/oliveiraleo/free5gc-auto-deploy/raw/main/install-go.sh
curl -LO https://github.com/oliveiraleo/free5gc-auto-deploy/raw/main/deploy-n3iwue.sh
chmod +x deploy-n3iwue.sh install-go.sh # gives execution permission
Install Go and reload the environment vars
./install-go.sh && source ~/.bashrc
Then install N3IWUE
./deploy-n3iwue.sh
Note: Currently the script will install the v1.0.0 stable branch
Currently, deploy-n3iwue.sh script accepts one parameter:
-keep-hostname: Disables changing the machine hostname during the deploy
Example usage:
./deploy-n3iwue.sh -keep-hostname
Please, follow the instructions from this page here
On a new machine, download the script
curl -LO https://github.com/oliveiraleo/free5gc-auto-deploy/raw/main/deploy-both-UEs.sh
Then execute it using an interactive shell
bash -i deploy-both-UEs.sh
Note: By default shells invoked by a script are non-interactive, running this script in a non-interactive shell will cause the bash environment variable reload after Go installation to fail. For more information see this page
The community is encouraged to contribute to this project. If you identify any opportunities for improvement or areas that require updates due to upstream changes, please feel free to open an issue or pull request
All contributions to this repository are subject to its licensing terms. For more information, please see here and here.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.