diff options
Diffstat (limited to 'docs/installation/virtual/docker.md')
| -rw-r--r-- | docs/installation/virtual/docker.md | 77 |
1 files changed, 56 insertions, 21 deletions
diff --git a/docs/installation/virtual/docker.md b/docs/installation/virtual/docker.md index 3489b94a..6d980066 100644 --- a/docs/installation/virtual/docker.md +++ b/docs/installation/virtual/docker.md @@ -1,10 +1,10 @@ --- -lastproofread: '2026-02-02' +lastproofread: '2026-08-30' --- (docker)= -# Run VyOS in a Docker Container +# 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 @@ -14,8 +14,9 @@ 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. +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 @@ -25,7 +26,6 @@ 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 @@ -47,26 +47,61 @@ $ sudo systemctl reload docker ## Deploy container from ISO -Download the ISO you want to base the container on. In this example, -the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you -created a custom IPv6-enabled network, include it as the `--net` parameter -to `docker run`. +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](https://github.com/vyos/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 {ref}`build`), the `oci` make +target converts the ISO which is generated in `build/` in one step: + +```none +$ 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: + +```none +$ 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`. ```none -$ mkdir vyos && cd vyos -$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso -$ mkdir rootfs -$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs -$ sudo apt-get install -y squashfs-tools -$ mkdir unsquashfs -$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs -$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 -$ sudo umount rootfs -$ cd .. -$ sudo rm -rf vyos +$ 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.4-rolling-202111281249 /sbin/init +> 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](https://containerlab.dev) to build virtual network labs. Refer +to its [VyOS kind](https://containerlab.dev/manual/kinds/vyosnetworks_vyos/) +documentation for the required node settings. +::: |