Guide

containerlab with netlab

netlab builds a lab from a YAML topology and starts each node under containerlab. Ze runs as one of those nodes. netlab calls this the daemon tier: one YAML file and one directory of Jinja2 templates, with no Ansible task lists and no Vagrant box.

The ze side of that integration lives in contrib/netlab/. contrib/netlab/README.md is the source of truth for the artifacts. This page explains how to run them. What the lab proves, and the automated live check that proves it, are on the netlab lab page. To run Ze outside a lab, see Choose a deployment path.

What you need

The steps below run by hand on a Linux Docker host. Install netlab, containerlab and Ansible on that host, and start each step from a Ze source checkout. The automated check on the lab page runs the same tools in a tool container instead.

Component Why
netlab 26.10 Renders the topology and calls containerlab
containerlab 0.83.0 and Docker on a Linux host Start the nodes
Ansible Core 2.22.0 with Python 3.13 or later Configures the nodes
netlab/ze:latest The lab image that Step 1 builds. docker/Dockerfile.lab

The lab image is not the deployment image. See Docker for the two images and what separates them.

Step 1: build the image

docker build -t netlab/ze:latest -f docker/Dockerfile.lab .

contrib/netlab/ze.yml sets clab.build: False and names netlab/ze:latest, so netlab starts this image and builds nothing. Change its image: value when you choose a different Docker tag.

Step 2: give netlab the daemon definition

There are two routes, and contrib/netlab/README.md gives both. The main route exports a complete working directory, including topology.yml, topology-defaults.yml and templates/ze/, without changing the netlab installation:

./le test netlab package directory /tmp/ze-lab

The destination must be new. Once the lab image is available in the target Docker daemon, this directory can be copied to another host and used without the Ze source checkout.

The other route copies the daemon definition and the templates into the netlab package. It creates no lab directory, so make one and copy the reference topology into it:

cp contrib/netlab/ze.yml  <netlab>/netsim/daemons/ze.yml
cp -R contrib/netlab/ze   <netlab>/netsim/daemons/ze
mkdir /tmp/ze-lab
cp contrib/netlab/topology.yml /tmp/ze-lab/topology.yml

Either route leaves topology.yml in /tmp/ze-lab, which Step 3 starts.

Step 3: run the reference topology

cd /tmp/ze-lab
netlab up topology.yml

contrib/netlab/topology.yml has three nodes:

r1 ---- internal ---- r2      AS 65001, iBGP + OSPF + IS-IS + BFD
 \
  ---- external ---- r3       AS 65002, eBGP only

netlab runs an IGP on internal links only, so the eBGP peer sits on its own link. r1 also carries two static routes. The topology declares every module ze.yml declares: bgp, ospf, isis, bfd, and routing.

Stop the lab from that directory with netlab down --cleanup. Stop and remove the lab says what stays behind.

To run the automated live check from the source checkout instead, with ./le test netlab run, see Run the automated live check on the lab page.

Check the lab you started

./le test netlab run is the full success check (what it checks). To look at a lab you started by hand, open a shell on a node and ask Ze for its BGP peers:

netlab connect r1
ze cli -c "show bgp peer list"

The CLI inside the node uses the lab login that ze.yml puts in the container environment (The lab login). On r1, expect the iBGP session to r2 and the eBGP session to r3.

Update the lab after a rebuild

A running node keeps the image it started from. To run a new build, stop the lab, rebuild the image, and start the lab again from the same directory:

cd /tmp/ze-lab
netlab down --cleanup
cd <ze-checkout>
docker build -t netlab/ze:latest -f docker/Dockerfile.lab .
cd /tmp/ze-lab
netlab up topology.yml

Run docker build from the Ze checkout and the two netlab commands from the lab directory. When the checkout changes contrib/netlab/, give netlab the new daemon definition again: copy it over the netlab package, or export a new directory, because package directory needs a destination that does not exist. ./le test netlab run builds its node image from the checkout on each run, so it needs no manual rebuild. To change a running node's configuration without a rebuild, see the SIGHUP reload in How netlab configures a node. Review, rollback and recovery outside a lab are in Lifecycle.

Stop and remove the lab

From the lab directory, netlab down --cleanup stops the lab and removes its containers and the files netlab generated. The automated run uses the same command, then fails if a node's container is still listed by docker ps --all. Run the same check by hand: no r1, r2 or r3 container of the lab may remain.

netlab down --cleanup
docker ps --all

The lab directory, the lab image and any daemon definition you copied into the netlab package stay. Remove them when you no longer need the lab:

docker image rm netlab/ze:latest
rm <netlab>/netsim/daemons/ze.yml
rm -r <netlab>/netsim/daemons/ze

Then delete the lab directory you exported.

How netlab configures a node

netlab renders contrib/netlab/ze/ze.j2 into one file, /etc/ze/ze.conf, and containerlab bind-mounts it into the node. Ze has no include directive, so one file holds the whole running configuration. Each other module key points at an ignore file that nothing reads.

The node starts netlab's /etc/dataplane-wait.sh under tini. That wrapper waits for initial interface configuration, then replaces itself with ze start /etc/ze/ze.conf. Ze therefore starts after its configured local addresses exist.

The rendered empty interface {} block starts interface monitoring so connected can discover the addresses netlab installed. It declares no managed addresses; netlab keeps ownership of them. Applying the empty block still clears Ze's IPv6 reverse-path checks and interface IPv6 forwarding default. Each BGP peer's redistribution attachment receives state and can send update, allowing a peer that establishes later to request the current connected prefixes.

Each BGP peer attaches four processes. bgp-rib stores the peer's routes and elects the best one, and re-advertises nothing. bgp-rs sends what one peer announced to the node's other peers: without it a node passes on only its own connected, OSPF and IS-IS prefixes, and a lab with a node between two BGP sessions cannot reach across it. bgp-adj-rib-in is what bgp-rs reads to replay those routes to a peer whose session comes up later, which in a lab is always one of them. redistribute-orchestrator carries the local prefixes into BGP.

Toward an external peer the render sets next-hop self. That is the default RFC 4271 Section 5.1.3 describes, written out because Ze's own default leaves a forwarded route's next hop as it arrived, and an external peer refuses a next hop that is another node's loopback.

The explicit clab.node_config.initial shell method runs Linux interface setup through docker exec. The Ze initial template marks successful completion for the startup wrapper. The explicit method overrides the Linux parent's host-namespace method. Setting the default configuration mode alone does not replace an inherited method.

After changing that bind-mounted file, send SIGHUP to reload it. handleSIGHUPReload runs signalReload, which stages the file as a candidate, reloads it, and never writes the file back. netlab sends no SIGHUP, and ze.yml says so with features.initial.reload: false. A configuration change in a running lab therefore needs kill -HUP on the ze process inside the node, or a node restart.

netlab validate reads the daemon through the CLI. ze.yml declares the show command as ze cli -c "show $@ | json compact", and netlab runs it with docker exec. An explicit format pipe beats the --format flag, so that command emits JSON.

The lab login

The rendered configuration declares one user, netlab, with the password netlab. ze.yml puts the same pair in the container environment, so the CLI inside the node has a credential. This is a well-known password in a throwaway container. Nothing in ze defaults to it and no image carries it.

The template writes the password as plaintext-password. Ze hashes that leaf when it loads the file, and it warns that the file still holds the secret. See Authentication.