Preparing a SONiC Box or Container

netlab supports SONiC running in a VM or in a container. Unfortunately, there’s no ready-to-use Vagrant box or Docker container that you could pull down from a public registry; you have to build the box or download and install the container manually.

Building a SONiC Vagrant Box

You can use the netlab libvirt package command to build a SONiC Vagrant box for a SONiC virtual machine:

  • Download the sonic-vs.img.gz image from Azure or SONiC.software into an empty directory.

  • Unzip image with gunzip gz-file-name.

  • Execute netlab libvirt package sonic img-file-name and follow the instructions

Warning

If you’re using a Linux distribution other than Ubuntu, please read the box-building caveats first.

Initial Device Configuration

During the box-building process, you might have to disable ZTP or clean up the initial configuration database. The netlab libvirt config sonic command displays the build recipe:

Sonic: Disabling ZTP and Cleaning Initial Configuration
=======================================================

* Wait for the 'login' prompt
* Login as 'admin', password 'YourPaSsWoRd'
* If needed, disable zero-touch with 'sudo config ztp disable --yes'.
  Don't despair, disabling ZTP takes a long while to complete.
* Remove BGP, interface, and MAC address configuration from the initial
  configuration (required on Azure images)
---------------------
sudo bash
cd /etc/sonic
jq "del(.INTERFACE,.BGP_NEIGHBOR,.LOOPBACK_INTERFACE,.DEVICE_METADATA.localhost.mac)" config_db.json >config_db.new
mv config_db.new config_db.json
---------------------
* Power down the virtual machine with 'sudo poweroff'
* If the device starts reloading instead of shutting down, disconnect
  from the console (ctrl-] usually works).

Downloading and Installing SONiC containers

SONiC also runs under containerlab using the community docker-sonic-vs container. The container is published as a build artifact of the sonic-buildimage project, so you either download a build or make one.

Download a Published Build

The SONiC container image is published as an artifact of the SONiC Azure build pipelines. From https://sonic-build.azurewebsites.net/ui/sonic/pipelines:

  • Scroll to the bottom of the pipeline list, where the vs platform is listed;

  • Pick a branch – the newest release branch (for example 202605) or master – and open Build History;

  • Choose the latest build whose Result is succeeded and open Artifacts. Builds that were canceled are listed alongside the successful ones, and they have an Artifacts link too;

  • Open the artifact (there is only one, sonic-buildimage.vs) and find target/docker-sonic-vs.gz in the file list. Take care not to pick target/docker-sonic-vs-asan.gz, which sits next to it – that is an AddressSanitizer build.

The file list is long; if you would rather not scroll it, the download URL can be built by hand once you know the branch and the build ID from the Build History page:

https://sonic-build.azurewebsites.net/api/sonic/artifacts?branchName=202605&platform=vs&buildId=1166687&target=target%2Fdocker-sonic-vs.gz

After downloading the container, unpack and load it:

gunzip docker-sonic-vs.gz
docker load -i docker-sonic-vs

The archive carries the tag docker-sonic-vs:latest, which is what the device definition expects, so there is usually nothing to retag.

Warning

docker load replaces any existing docker-sonic-vs:latest image – it prints The image docker-sonic-vs:latest already exists, renaming the old one with ID ... to empty string and leaves the previous image untagged. If you want to keep the image you already have, tag it first (for example docker tag docker-sonic-vs:latest docker-sonic-vs:previous) and select between them with defaults.devices.sonic.clab.image.

You can check which build you got with:

docker run --rm --entrypoint cat docker-sonic-vs:latest /etc/sonic/sonic_version.yml

Build a SONiC Container

Use this process in an empty directory to build a SONiC container from the sonic-buildimage repository:

git clone --recurse-submodules https://github.com/sonic-net/sonic-buildimage.git
cd sonic-buildimage
make init
make configure PLATFORM=vs
make target/docker-sonic-vs.gz
docker load -i target/docker-sonic-vs.gz

The device definition expects the image to be tagged docker-sonic-vs:latest; override defaults.devices.sonic.clab.image in your topology if yours is tagged differently.

How SONiC Container Works

docker-sonic-vs is a single monolithic container running FRR (vtysh) (unlike the VM, which runs FRR in a nested bgp container). The container does not start the SSH daemon; netlab pushes device configuration and runs validation with docker exec commands.

The device inherits from the frr device and uses FRR control-plane configuration templates.

See the SONiC caveats for what is and is not supported.