Skip to content

Vendor setup

For the decision — which vendor fits your tests — see Topology format → Vendor defaults. This page is the operator’s how-to once the decision is made.

If you have not installed Netlab + Containerlab yet, start with Netlab host and come back here once netlab test clab passes.

Authoritative platform reference is on netlab.tools

netlab.tools/platforms is the source of truth for the Netlab view (per-platform supported modules, image conventions, configuration semantics). containerlab.dev/manual/kinds is the source of truth for the container-runtime view.

Pick the vendor you’re setting up

FRR is the open-source default. Containerlab pulls the upstream frrouting/frr image; Netlab configures the daemons via vtysh-equivalent templates. No license, no manual image build, no setup beyond netlab test clab passing.

Minimal FRR topology

examples/topologies/minimal_frr.yml
provider: clab
defaults:
  device: frr

nodes:
  r1:
  r2:

links:
  - r1-r2

netlab up pulls frrouting/frr from Docker Hub on first run, then uses the cached image afterward.

For when FRR is the right call and what its limitations are (no vendor CLI, no hardware-specific behavior, VRF-module dependency), see Topology format → When FRR is the right call.

Nokia SR Linux is Nokia’s container-native NOS — a real network operating system distributed as a public Docker image, free under Nokia’s EULA.

Pull the image

Containerlab pulls SR Linux automatically the first time a topology references kind: srl, but pre-pulling avoids latency on the first lab:

docker pull ghcr.io/nokia/srlinux:latest

For reproducible CI, pin a specific release tag rather than latest. The release tag list on GHCR shows what’s available; recent releases follow 24.10.1-492 style (year.release.build).

Set SR Linux as the default device

Add to ~/.netlab.yml:

cat > ~/.netlab.yml << 'EOF'
---
device: srlinux
devices.srlinux:
  clab.image: "ghcr.io/nokia/srlinux:24.10.1-492"
EOF

Per-topology selection works the same as for any other Netlab device:

examples/topologies/minimal_srlinux.yml
provider: clab
defaults:
  device: srlinux

nodes:
  spine1:
  spine2:
  leaf1:
  leaf2:

links:
  - leaf1-spine1
  - leaf1-spine2
  - leaf2-spine1
  - leaf2-spine2

Verify

netlab show images | grep -i srlinux

You should see your srlinux device pointing at the image you pinned.

For when SR Linux is the right call and its trade-offs vs FRR/IOL, see Topology format → When SR Linux is the right call.

Cisco IOL (IOS on Linux) is the IOS image packaged for Containerlab via the vrnetlab fork by hellt. Use it when the function block under test depends on IOS CLI semantics that neither FRR nor SR Linux can replicate.

Cisco IOL license required — and the binaries — before this section works

Cisco IOL binaries are licensed software. Cisco distributes them only under specific commercial agreements (Cisco Modeling Labs subscription, EFT/CCO program access, partner agreements). This guide does not distribute the binaries and cannot help you obtain them. Acquire them from your Cisco contact, then continue.

The two binaries you will need:

  • x86_64_crb_linux-adventerprisek9-ms.iol — L3 router image
  • x86_64_crb_linux-adventerprisek9-ms-l2.iol — L2 switch image

The exact filenames depend on the Cisco release you receive. Treat the versions in the example commands below (17.15.01, L2-17.15.01) as placeholders for whatever your binaries report.

Build the IOL container images

Use the hellt/vrnetlab fork — the upstream vrnetlab is not Containerlab-compatible.

# 1. Clone the vrnetlab fork
git clone https://github.com/hellt/vrnetlab.git

# 2. Place your Cisco IOL binaries into the build directory
#    (replace the source paths with the location of your licensed binaries;
#    keep the .bin extension — the build expects it)
cp /path/to/your/x86_64_crb_linux-adventerprisek9-ms.iol \
   vrnetlab/cisco/iol/cisco_iol-17.15.01.bin

cp /path/to/your/x86_64_crb_linux-adventerprisek9-ms-l2.iol \
   vrnetlab/cisco/iol/cisco_iol-L2-17.15.01.bin

# 3. Build the Docker images
cd vrnetlab/cisco/iol
make docker-image

The .bin extension is required

The vrnetlab build expects .bin. If your Cisco-supplied file has a different extension, copy or symlink it to .bin before running make docker-image.

Verify the images are present

docker images --format '{{.Repository}}:{{.Tag}}' | grep cisco_iol

Expected output (versions reflect what you built):

vrnetlab/cisco_iol:17.15.01
vrnetlab/cisco_iol:L2-17.15.01

Tell Netlab which IOL image to use

Point Netlab at the images you just built by writing your defaults to ~/.netlab.yml:

cat > ~/.netlab.yml << 'EOF'
---
device: iol
devices.iol:
  clab.image: "vrnetlab/cisco_iol:17.15.01"
devices.ioll2:
  clab.image: "vrnetlab/cisco_iol:L2-17.15.01"
EOF

Setting device: iol is optional

The top-level device: iol makes IOL the default device type for topologies that don’t specify one. Omit it if you’d rather pick the device per topology.

Verify Netlab sees the images

netlab show images

You should see:

iol     → vrnetlab/cisco_iol:17.15.01
ioll2   → vrnetlab/cisco_iol:L2-17.15.01

Test your IOL lab

topology.yml
---
provider: clab
defaults.device: iol
module: [ ospf ]

nodes: [ r1, r2 ]
links: [ r1, r2, r1-r2 ]

netlab up from that directory boots two IOL routers running OSPF.

The recipe below is generic and applies to any platform Netlab knows about. For platforms Netlab does not know about, you’d need to upstream a new device profile to the Netlab platform definitions — that’s an upstream contribution, not something this project’s docs cover.

1. Confirm the platform is supported

netlab show devices

The output lists every device kind your installed Netlab understands. If the platform you want is not listed, upgrade Netlab (uv tool upgrade networklab or pipx upgrade networklab) and check again. If still missing, the platform isn’t supported by Netlab yet.

2. Acquire the container image

Three image sources, in descending order of convenience:

  • Public registry (FRR, SR Linux) — docker pull works directly.
  • Vendor-gated public registry (Arista cEOS, Cumulus VX) — manual download from the vendor’s site, then docker load.
  • Build from source via vrnetlab (Cisco IOL, Juniper vMX, …) — clone hellt/vrnetlab, drop your licensed binary into the platform directory, run make docker-image. The Cisco IOL tab above is the canonical example.

Confirm the image is present:

docker images --format '{{.Repository}}:{{.Tag}}'

3. Tell Netlab which image to use

Edit ~/.netlab.yml to map the device kind to your specific image tag:

---
devices.<device-kind>:
  clab.image: "<registry>/<image>:<tag>"

4. Boot a tiny test topology

provider: clab
defaults.device: <device-kind>
nodes: [ r1, r2 ]
links: [ r1-r2 ]

netlab up
netlab down --cleanup

If both succeed, the new platform is ready to use in neops-remote-lab topologies — set device: <device-kind> in your test topology and declare a remote_lab_fixture against it.

See also