Run VyOS as a container

Docker is an open-source project for deploying applications as standardized units called containers. Deploying VyOS in a container provides a simple and lightweight mechanism for both testing and packet routing for container workloads.

IPv6 support for Docker

VyOS requires an IPv6-enabled Docker network. Currently Linux distributions do not enable Docker IPv6 support by default.

You can enable IPv6 support in two ways.

Method 1: Create a docker network with IPv6 support

Here’s an example using the macvlan driver.

docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet

Method 2: Add IPv6 support to the Docker daemon

Edit /etc/docker/daemon.json to set the ipv6 key to true and specify the fixed-cidr-v6 to your desired IPv6 subnet.

{
  "ipv6": true,
  "fixed-cidr-v6": "2001:db8::/64"
}

Reload the Docker configuration.

$ sudo systemctl reload docker

Deploy container from ISO

A VyOS ISO image can be converted into an OCI (Open Container Initiative) image using the iso-to-oci helper script from the vyos-build repository. The script extracts the root filesystem from the ISO, removes components which are not usable inside a container (kernel, firmware, and the corresponding CLI nodes), and generates a tarball which can be imported by Docker.

The script requires xorriso, squashfs-tools and jq to be installed. All of them are already present in the vyos-build container.

Build a container image from a locally built ISO

If you build your own ISO from source (see Build VyOS), the oci make target converts the ISO which is generated in build/ in one step:

$ make oci
I: extracting ISO metadata
I: extracting squashfs image
I: extracting squashfs content
I: generate OCI container image vyos-1.5.1-oci-amd64.tar
I: to import the previously generated OCI image to your local images run:

   docker import vyos-1.5.1-oci-amd64.tar vyos:1.5.1 --change 'CMD ["/sbin/init"]'

Build a container image from a downloaded ISO

To use a released or nightly ISO instead, call the script directly and pass the path to the ISO image:

$ git clone https://github.com/vyos/vyos-build.git
$ ./vyos-build/scripts/iso-to-oci vyos-1.5.1-generic-amd64.iso

Import and run the container

Import the generated tarball as a local image and start the container. If you created a custom IPv6-enabled network, include it as the --net parameter to docker run.

$ docker import vyos-1.5.1-oci-amd64.tar vyos:1.5.1 \
> --change 'CMD ["/sbin/init"]'
$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \
> vyos:1.5.1
$ docker exec -ti vyos su - vyos

To stop the container, run docker stop vyos.

Hint

The very same image can also be used with Containerlab to build virtual network labs. Refer to its VyOS kind documentation for the required node settings.