Building VyOS

There are different ways you can build VyOS.

Building using a Docker container, although not the only way, is the easiest way as all dependencies are managed for you. It also allows you to build ARM images on a x86 host.

However, you can also set up your own build machine and build from source.

Note

Starting with VyOS 1.2 the release model of VyOS has changed. VyOS is now free as in speech, but not as in beer. This means that while VyOS is still an open source project, the release ISOs are no longer free and can only be obtained via subscription, or by contributing to the community.

The source code remains public and an ISO can be built using the process outlined here.

Docker

This will guide you though the process of building a VyOS ISO using Docker. This process has been tested on clean installs of Debian Jessie, Stretch, and Buster.

Installing Docker and prerequisites

$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg2 \
      software-properties-common
$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] \
      https://download.docker.com/linux/debian $(lsb_release -cs) stable"
$ sudo apt-get update
$ sudo apt-get install -y docker-ce

To be able to use Docker, the current non-root user should be added to the docker group by calling: usermod -aG docker yourusername

Note

It is recommended to use that non-root user for the remaining steps.

Note

The build process needs to be built on a local file system, building on SMB or NFS shares will result in the container failing to build properly!

Build Docker Container

The container can built by hand or by fetching the pre-built one from DockerHub. Using the pre-built containers from the VyOS DockerHub organisation will ensure that the container is always up-to-date. A rebuild is triggered once the container changes (please note this will take 2-3 hours after pushing to the vyos-build repository).

To manually download the container, run:

$ docker pull vyos/vyos-build:crux

The container can always be built directly from source:

$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
$ git clone -b master --single-branch https://github.com/vyos/vyos-build # For rolling release
$ cd vyos-build
$ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2
$ docker build -t vyos/vyos-build docker # For rolling release

Build ISO

If you have not build your own Docker image, you need to clone the repository to your local machine:

$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
$ git clone -b current --single-branch https://github.com/vyos/vyos-build # For rolling release

Now a fresh build of the VyOS ISO can begin. Change directory to the vyos-build directory and run:

$ cd vyos-build
$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash
vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 \
                             --build-by "[email protected]" \
                             --build-type release --version 1.2.0
vyos_bld@d4220bb519a0:/vyos# sudo make iso

The successfully built ISO should now be in the build/ directory as live-image-[architecture].hybrid.iso.

Good luck!

From source

To build from source, you will need:

Debian Buster for VyOS 1.2
Debian Stretch for the rolling releases

To start, clone the repository to your local machine:

$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
$ git clone -b current --single-branch https://github.com/vyos/vyos-build # For rolling release

For the packages required, you can refer to the docker/Dockerfile file in the repository. The ./configure script will also warn you if any dependencies are missing.

Once you have the required dependencies, you may configure the build by running ./configure with your options. For details, refer to Customizing the build.

Once you have configured your build, build the ISO by running:

$ sudo make iso

The successfully built ISO should now be in the build/ directory as live-image-[architecture].hybrid.iso.

Customizing the build

The build can be customized with the following list of configure options. The full and current list can be generated with ./configure --help:

-h, --help            show this help message and exit
--architecture ARCHITECTURE
                      Image target architecture (amd64 or i586 or armhf)
--build-by BUILD_BY   Builder identifier (e.g. [email protected])
--custom-package CUSTOM_PACKAGES
                      Custom packages to install from repositories
--build-type BUILD_TYPE
                      Build type, release or development
--debian-security-mirror DEBIAN_SECURITY_MIRROR
                      Debian security updated mirror
--version VERSION     Version number (release builds only)
--debian-mirror DEBIAN_MIRROR
                      Debian repository mirror for ISO build
--vyos-mirror VYOS_MIRROR
                      VyOS package mirror
--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR
                      Debian repository mirror for pbuilder env bootstrap
--debug               Enable debug output
--custom-apt-entry CUSTOM_APT_ENTRY
                      Custom APT entry
--custom-apt-key CUSTOM_APT_KEY
                      Custom APT key file