Running a lab¶
The packaged image starts with /boxen/boxen run. Containerlab supplies the node's hostname, credentials, networking, and optional startup configuration; the profile turns those inputs into commands for the guest OS.
Start with the platform's Containerlab kind¶
Choose the kind for your guest and set image to the name produced by boxen build. For example:
name: router-lab
topology:
nodes:
r1:
kind: juniper_vjunosrouter
image: boxen-juniper_vjunos-router:25.2R1.9
healthcheck:
start-period: 1200
r2:
kind: juniper_vjunosrouter
image: boxen-juniper_vjunos-router:25.2R1.9
healthcheck:
start-period: 1200
links:
- endpoints: ["r1:ge-0/0/0", "r2:ge-0/0/0"]
The Boxen profile juniper_vjunos-router contains a hyphen, while the Containerlab kind juniper_vjunosrouter does not. Use the platform list and the relevant Containerlab kind documentation for interface aliases and runtime defaults.
sudo containerlab deploy --topo router-lab.clab.yml
sudo containerlab inspect --topo router-lab.clab.yml
docker logs -f clab-router-lab-r1
Docker logs show Boxen's provisioning steps and matching diagnostics. To follow the guest's serial output on its own, including the early boot sequence:
This file starts fresh with each QEMU launch and continues recording after provisioning closes
the automation console. /boxen/package.boot.log retains the sequence from image packaging.
Runtime order¶
- Read
/boxen/profile.yamland construct the template values from the runtime flags. - Write
1 bootingto/health. - Wait for interfaces when
CLAB_INTFSspecifies a count, for at mostBOXEN_INTF_WAIT_TIMEOUT, then honorBOOT_DELAYin seconds. - Execute
preRunCommandsin the container shell. - Create the disk overlay and resolve the VM UUID, reusing both on a restart of the same container.
- Launch QEMU with the overlay and runtime hardware settings.
- Start the TC service that joins container interfaces to guest TAPs.
- Open the serial console and execute
run.process. - If
/config/startup-config.cfgexists, executerun.configProcess. - Close the automation console and write
0 runningto/health. - Keep the container running until its context is cancelled.
Provisioning errors stop the run process before it can mark the node healthy. Boxen does not rerun packaging during this phase. If the VM exits on its own afterwards, for example because the guest powered off, Boxen writes 1 vm exited to /health and the container exits.
The disk overlay¶
The VM writes to /boxen/disk.overlay.qcow2, a qcow2 overlay backed by the packaged /boxen/disk.qcow2. The packaged disk is only read, so starting a node does not copy it into the container's writable layer; the layer holds just the guest's changes. A restart of the same container reuses the overlay and keeps those changes, and a new container starts from the packaged disk again.
Startup configuration¶
Declare a startup file on the Containerlab node:
Containerlab's VM integration places the file at /config/startup-config.cfg. The profile's configProcess must enter the appropriate NOS configuration mode, send or load the file, and save or commit it. The presence of a file only triggers that process; it is not an automatic configuration loader by itself.
For CLI-oriented platforms, a typical step is:
Add the platform's mode changes and completion checks around this step. The vJunos-router profile instead loads hierarchical configuration using load merge terminal. Avoid startup commands that break management connectivity or change the console credentials expected during the next boot.
Hardware and boot overrides¶
Set environment variables in the node's container:
env:
QEMU_MEMORY: "8192"
QEMU_CPU: host
QEMU_SMP: "4"
BOOT_DELAY: "10"
CLAB_MGMT_PASSTHROUGH: "true"
These override generated QEMU fields where supported. QEMU_SMP is considered when the profile has a nonzero cpuCores. A profile's complete section override bypasses that section's normal generator. See QEMU configuration and the environment reference.
Interface wiring¶
By default, eth0 is management and eth1 through ethN are data ports. Boxen creates corresponding tap0 for transparent management and tap1 through tapN for data traffic. A background TC service redirects frames in both directions, notices interfaces that appear after startup, and reattaches recreated interfaces. It checks interfaces every two seconds and recognizes recreated interfaces by their new interface index, even when Containerlab removes and re-adds a link between polls. Containerlab therefore adds and removes links of a running Boxen node without recreating it; it recognizes Boxen images by their org.opencontainers.image.vendor=Boxen label. The guest always has nicCount data NICs, so a link to a port beyond that count is not wired.
Containerlab kind aliases map the first NOS data port to eth1; the NOS's port numbering can start at zero. CLAB_INTF_PREFIX and CLAB_MGMT_INTF let an integration supply different container interface names.
Readiness and console access¶
docker exec clab-router-lab-r1 /boxen/boxen health
docker exec clab-router-lab-r1 cat /health
docker inspect --format '{{.State.Health.Status}}' clab-router-lab-r1
The base image checks readiness every five seconds and allows a five-minute startup period. Slow nested guests can need a longer node-specific healthcheck.start-period. The readiness file records successful provisioning, including startup configuration; it does not continuously probe guest services.
After provisioning closes the automation console, connect manually:
Exit telnet with Ctrl+], then q. Avoid taking over the console while profile automation is running.
Stop and recreate¶
Removing a node removes its disk overlay and so its guest changes unless you arranged separate persistence. A newly created node uses the packaged image baseline plus its runtime and startup configuration.