Getting started

One-time setup on Linux, on Windows through WSL2, or on a Mac inside a small Linux VM. It takes ten to twenty minutes; longer the first time on a machine that has never had WSL2 or a VM. After this, every lab is a single command.

Quick start

The whole setup in four steps. Each one links to the detail below.

1. Install Docker
2. Install Containerlab
3. Download a lab
4. ./labctl deploy

What you need

• Linux, Windows with WSL2, or a Mac on macOS 13.3 or later running a small Linux VM. Ubuntu 22.04 or 24.04 is the tested path on all three.
• 4 GB of free RAM and a few GB of disk.
• sudo access. Containerlab manages network namespaces and needs it.

Install

Three tracks. Pick the one that matches the machine in front of you. All three end up at the same place: a Linux shell with Docker and Containerlab on it.

Run a lab

Every lab, free or paid, arrives as a zip. Get Lab 01 free here and the paid pack arrives by email after purchase.

Download the zip in your browser, then move it into the Linux home folder and unzip it. Pick your platform:

mkdir -p ~/labs creates the folder the first time; it's harmless afterward.

Windows (WSL2)

mkdir -p ~/labs && cp /mnt/c/Users/<your-windows-name>/Downloads/lab-01-area-boundary-trap.zip ~/labs/ && cd ~/labs && unzip lab-01-area-boundary-trap.zip

Linux

mkdir -p ~/labs && mv ~/Downloads/lab-01-area-boundary-trap.zip ~/labs/ && cd ~/labs && unzip lab-01-area-boundary-trap.zip

Mac (Multipass), first from a Mac Terminal, see whether Safari unzipped the download:

ls ~/Downloads | grep lab-01

If it shows a folder, copy the folder into the VM:

multipass exec labs -- mkdir -p /home/ubuntu/labs
multipass transfer -r ~/Downloads/lab-01-area-boundary-trap labs:/home/ubuntu/labs/

then inside the VM, cd ~/labs.

If it shows the zip, copy the zip into the VM:

multipass transfer ~/Downloads/lab-01-area-boundary-trap.zip labs:/home/ubuntu/

then inside the VM:

mkdir -p ~/labs && mv ~/lab-01-area-boundary-trap.zip ~/labs/ && cd ~/labs && unzip lab-01-area-boundary-trap.zip

Then start it:

cd lab-01-area-boundary-trap
./labctl deploy

The lab is now running. Open lab.html inside the lab folder in a browser for the topology, the symptom, the investigation questions, and the reveal for when you have a theory, then come back to the terminal to work it. It needs no network, and every lab has one. Lab 01 also has a public page, the Lab 01 page, with its topology and symptom. From WSL2, explorer.exe . opens the lab folder in Windows; on a Mac, multipass transfer the lab.html back out, or read scenario.md in the terminal.

If ./labctl reports Permission denied, run chmod +x labctl once. Some Windows unzip tools drop the executable bit, and a copy through /mnt/c always does.

Each lab folder has the same launcher with the same commands:

./labctl deploy     # bring it up and apply the scenario
./labctl tabs       # open a window per router in tmux
./labctl status     # neighbor state and routes at a glance
./labctl sh r2      # a Linux shell on that router
./labctl verify     # check your fix
./labctl reset      # back to the broken starting state
./labctl destroy    # tear it down

Paid pack

The pack arrives the same way as the free lab, as a download link in the Gumroad email. Copy it into ~/labs and unzip it exactly as above, with the pack's zip name. It unzips to one folder holding all ten labs; cd into any of them and run ./labctl deploy. Every lab inside it uses the same ./labctl commands shown above.

Working the lab

Every lab is easier with one terminal per router, and one more in the lab folder for the launcher. ./labctl tabs lays that out in one command:

./labctl tabs

It opens a tmux session named after the lab: one window per router, each already inside that router's vtysh, and a last window named ctl in the lab folder for status, verify and reveal. Run it again at any point and it reattaches to the session you left rather than building a second one.

The bar along the bottom lists the windows (1:r1* 2:r2 3:r3 4:ctl), and the asterisk marks the one you're in. To switch, press Ctrl+B, release both keys, then press the key that follows it:

Ctrl+B, then 2                 switch to r2 (any window number works)
Ctrl+B, then n / p             next / previous window
Ctrl+B, then w                 pick a window from a list
Ctrl+B, then d                 detach, leaving the lab running

./labctl tabs reattaches to the session you left.

Detaching leaves every router where you left it, so you can close the terminal, come back later, and pick the same session up mid-investigation. The point of the layout is to keep the router where the symptom shows in a window of its own, so you can re-run a command there without losing whatever you are reading on another router.

The session belongs to the lab, and ./labctl destroy closes it along with the containers. Run destroy from the ctl window and it leaves the session standing, since that is the shell you are typing in; detach first, or close it afterwards with tmux kill-session -t <lab-name>. If a session is ever left behind without its routers, ./labctl tabs rebuilds it rather than dropping you into the remains.

Each lab's scenario.md names the windows that topology needs. The same folder also has lab.html (the scenario with its diagram, readable in a browser with no network), and ./labctl reveal prints the concept and the fix once you have a theory.

Working in vtysh

FRR's shell is modeled on IOS. Get into a router with:

docker exec -it clab-<lab-name>-r1 vtysh

Many familiar operational commands work much as you'd expect:

show ip route
show ip ospf neighbor
show ip ospf database
show ip bgp summary
show running-config
configure terminal

The differences you'll notice: interfaces are named eth1, eth2 rather than GigabitEthernet; prefixes use CIDR (10.0.0.0/24) rather than wildcard masks; and in BGP, neighbors are activated under address-family ipv4 unicast. That's about the whole list for OSPF and BGP work.

The Linux side of the router

One structural difference is worth knowing before it surprises you. On a traditional platform the router owns the whole box. FRR is a routing daemon running on Linux, so the protocol is one layer and the platform is another: anything OSPF or BGP configures lives in vtysh, while properties the kernel owns (interface MTU is the one the labs run into) are reported by vtysh but changed outside it. That split is not a quirk of these labs; it is how white-box switches, SONiC and cloud routers all work.

The launcher opens that shell for you, so there is no container name to remember:

./labctl sh r2

ip, ping, ss and vtysh are all on the PATH there, and exit brings you back to the lab folder. Where a lab's fix needs it, ./labctl reveal says so and spells out the command.

If something's off

• Permission denied on Docker: you haven't re-logged in after the usermod step.
• "OSPF did not converge" from the launcher: run ./labctl status; usually the image is still starting. Run ./labctl reset.
• Containers from a previous lab still around: sudo containerlab destroy --all cleans everything.
• ./labctl tabs opens with no router windows, just ctl: a tmux session from an earlier run outlived the lab it was built for. Each router window is a connection into a container, so destroying the lab closes them and leaves the ctl shell behind. Current labs rebuild the session for you; on an older copy, close it with tmux kill-session -t <lab-name> and run ./labctl tabs again. tmux ls lists what is open, and inside Ctrl+B s gives the same list, where x then y closes the highlighted one.
• multipass: command not found on a Mac: you are inside the VM. Switch to the Mac Terminal window, the one whose prompt shows your Mac's name, and run it there.
• "The client is not authenticated with the Multipass service": the command was run with sudo. Run it again without sudo.

Start with the free lab