VyOS build from source

I just want to say that my affiliation with VyOS project and Sentrium has nothing to do with this post. This post is completely my own opinion and work; any mistakes made in this post is not related to VyOS projects and Sentrium.

Since VyOS 1.2.0, VyOS LTS releases can only be downloaded via the subscription channel. So for the Enterprise, I would highly recommend getting the support and subscription. This blog post is not about support and subscription. This post is about building the VyOS ISO image from scratch.

I just want to mention the VyOS ISO image can be obtained in several ways. The easiest would be the rolling release. The rolling releases can be downloaded at any time and no subscription is needed. Also, the rolling release is the bleeding edge version of VyOS. Another way is to get the LTS release via the support subscription as mentioned earlier. Another way of getting the LTS release is to become a contributor to the project. Being a contributor can be a bug hunter, tester, helping the community, or by promoting VyOS via blog, podcast, etc. Another option is being in a non-profit organization or an educational institution. You may need to fill out a form if you are coming from a non-profit or an educational institution. This post is about building the ISO from the source.

See the two forms below if you are a non-profit or an educational institution:

I am going to be using Proxmox VE 6.0 as my hypervisor of choice, but building the VyOS ISO can be done with any hypervisor. The process should be the same regardless of the hypervisor. Also, I am going to be using the current Debian 10 stable release network install ISO because it is a small image.

Virtual Machine Settings

This is the specs of the Debian 10 VM:

  • 4x vCPU
  • 4GB RAM
  • 20GB Disk (VirtIO Block)
  • vNIC: VirtIO (paravirtualized)
Figure 1

Install Debian 10 Buster

Once the VM has been created, start the VM then access the console, so that we can install Debian. As shown in Figure 2, select of the method how do you want to install Debian. I picked the non-graphical way because it seems to be faster. The next is screenshots are the following from left to right – select the language > location

Figure 2

The next screenshots are the following from left to right – keyboard settings > Setting up the hostname > domain


The next screenshots are the following from left to right – the Root password > confirm the root password > new user’s username

Figure 4

The next screenshots are the following from left to right – the new user’s full name > password for the new user > confirm the user password

Figure 5

The next screenshots are the following from left to right – timezone settings > disk partition settings > select disk to partition

Figure 6

The next screenshots are the following from left to right – select the partition scheme > partition overview > confirm partition

Figure 7

The next screenshots are the following from left to right – do not scan another disk > find the mirror by country > select the Debian archive mirror

Figure 8

The next screenshots are the following from left to right – > proxy settings if you have one > Debian survey > make sure select the SSH server and Standard system utilities

Figure 9

The next screenshots are the following from left to right – Install GRUB > select the disk > click Continue to finish the Debian installation

Figure 10

Building the VyOS ISO

Once the installation is complete, SSH in using the standard user and switch to the root user.

# Switch to the root user. Enter the root password when prompted.
su -

# Update the reposistory and upgrade the system if needed.
apt update
apt dist-upgrade -y

Install the dependencies and tmux and vim .

apt install -y sudo git-all curl unzip python3 python3-pystache live-build pbuilder vim tmux

Later on, the installation will take a while, so just to be safe use tmux just in case we get disconnected from SSH.

# Enter the following command

# If gets disconnected from SSH, just SSH back in and enter the following command
tmux attach

Install the Docker Community Edition

apt 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 -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
apt update
apt install -y docker-ce

Now, while we are using the root account, let’s add the standard user to the sudo group and docker group.

# Add user to sudo group
adduser karlo sudo

# Add user to docker group
adduser karlo docker

After adding the standard user to the sudo and docker groups, exit out completely and SSH in back again for the group membership take effect. Otherwise, it will not work. Once back to the SSH session, enter the tmux mode again and verify the group membership.

# Verify the group membership with the command id

# Ensure the docker and sudo groups are listed.

Build the Docker container

This will take a while, so make sure that you are in tmux mode before you start. We need to clone the Crux branch with -b crux

# Clone the git repository
git clone -b crux --single-branch https://github.com/vyos/vyos-build

# cd to the vyos-build directory
cd vyos-build

# This is going to take between 2 to 3 hours. Once done, you will be
# back to the shell
docker build -t vyos-builder docker

After creating the container, we need to bash in

docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos-builder bash

# Once the prompt changed, it means we are inside of the Docker container. 
# Similar to this: vyos_bld@ea01057f84eb:/vyos$
# --custom-package vim # because I want to install vim
# --build-by "[email protected]"
# --version [value]
./configure --custom-package vim --architecture amd64 --build-by "[email protected]" --build-type release --version crux-201911152209

# Make the iso. This will require a root privilege to execute. This will take a while ~30 - 40 minutes.
sudo make iso

Once done, exit the container by typing exit

# Exit the container

# After exiting the container, it should bring us back to the VM.

After exiting the container, and back to the Debian VM, the VyOS .iso is located in /home/username/vyos-build/build/vyos-crux-201911152209-amd64.iso and can be transferred via scp or whatever file transfer you preferred to use.

Build a new ISO image

To build a new ISO, we would need to remove the previous build. SSH in using the standard user and delete the vyos-build directory and remove all the current Docker image and volumes.

# Delete the vyos-build
rm -rf vyos-build

# Remove all Docker images and volumes
docker system prune --all --force --volumes

Build the Docker container again. From here, start from Build the Docker container.

Hope you’ll find this helpful.


Notify of

Newest Most Voted
Inline Feedbacks
View all comments
4 years ago

Thanks, brilliant post.

JJ Duru
JJ Duru
3 years ago

That’s spot on mate, awesome job.

3 years ago

The most helpful of all – the documentation was a little confusing to me as I have never used docker before. I wanted to use scripts -which worked except for the last 2 lines. Those I just typed in.

3 years ago

Can you clarify something for me? The other tutorials (including vyos’ own documentation) say you need Debian 8 Jessie. I tried to follow those guides, but it keeps failing. Is something not going to be “correct” by doing this from Debian 10?

Would love your thoughts, please comment.x