🧪 Rootless Netlab + Containerlab on Ubuntu
A concise, CI-ready installation and configuration guide
1. – Install netlab and its toolchain (no sudo)
Why?
netlaborchestrates networks using: - KVM/libvirt for virtual machines - Docker + Containerlab for containers - Ansible for configurationThe fastest way to install all required tools is with
netlab install.
🛠️ Installation Steps
This guide assumes you are using Ubuntu 24.04+ and is based on the netlab installation guide.
# Step 1-a: Install system prerequisites
sudo apt-get update && sudo apt-get install -y python3-pip
# Step 1-b: Install netlab via pipx
sudo python3 -m pip install networklab
⚠️ Note
Use--break-system-packagesonly on throwaway VMs or CI runners to suppress Ubuntu 22.04+ pip complaints. For persistent setups, use a proper virtual environment (which is much more complex, and untested by us).
# Step 1-c: Install all backend tooling (Ansible, libvirt, Docker, Containerlab)
netlab install ubuntu ansible libvirt containerlab # no `sudo` here!
⚠️️️ Run this without
sudoto ensure proper file permissions, group setup, and home-directory configs.
✅ Validate installation
This runs a minimal lab with FRR containers and tears it down to validate your install.
All systems (Ansible, Docker, libvirt, etc.) must pass.
If you're integrating with the testing framework, continue with the Testing Framework guide: /development/testing-framework/
2. – Configure Rootless Containerlab
Why? In the default setup netlab uses
sudoto run Containerlab commands, which is not ideal for CI or automation.Since version 0.63, Containerlab allows rootless operation using a setuid helper and group-based access via
clab_admins. By default netlab uses an older version of Containerlab that requiressudoto run, so we need to upgrade it and configure netlab to use it without sudo.
2.1. Enable password-free Containerlab
# Upgrade to a recent Containerlab version (>= 0.63)
sudo containerlab version upgrade
# Ensure the binary is setuid-root
sudo chmod u+s $(command -v containerlab)
# Add yourself to required groups
sudo groupadd -r clab_admins # safe to repeat
sudo usermod -aG docker,clab_admins $USER
# Apply new group memberships in current session
newgrp clab_admins
✅ Check that it works
You should see the version banner without any password prompt.
2.2. Configure netlab to stop using sudo
By default, netlab wraps Containerlab calls in sudo. We override that:
netlab defaults --user \
providers.clab.start='containerlab deploy --reconfigure -t clab.yml'
netlab defaults --user \
providers.clab.stop='containerlab destroy --cleanup -t clab.yml'
🔍 These commands write to
~/.netlab.ymlusing the correct key structure.
Do not includedefaults.in user-level YAML — it will be ignored.
✅ Verify override
netlab show defaults providers.clab.start
# should output: containerlab deploy --reconfigure -t clab.yml
(Optional) 2.3. Enable VRF support for FRR labs (Ubuntu)
Important for FRR labs:
To run FRR labs rootless, Ubuntu requires the VRF kernel module to be installed and loaded.
# Install VRF kernel module
sudo apt update
sudo apt install linux-modules-extra-$(uname -r) || sudo apt install linux-generic
# Load the VRF module
sudo modprobe vrf
# Verify VRF module is loaded
lsmod | grep vrf
3. – Run your first (rootless) lab
Create a simple lab file topology.yml in a directory of your choice, e.g., ~/my-lab/.:
# Create a minimal topology file (topology.yml):
---
provider: clab
defaults.device: frr
module: [ ospf ]
nodes: [ r1, r2 ]
links: [ r1, r2, r1-r2 ]
Then run the following commands to start and stop your lab:
netlab up # Starts your lab without sudo
# ... run your tests ...
netlab down # Cleans up lab and files
No sudo, no password prompt — ideal for CI.
4. – Cisco IOL images (optional)
netlabsupports Cisco IOL (IOS on Linux) via Containerlab.These images run fast and light — ideal for routing/switching labs.
⚠️️️ You need to provide the Cisco IOL binary files yourself, as they are not freely distributable.
📦 Images in zebbra quay.io
On the zebbra quay.io registry you can find the cisco_iol images.
To clone them to your local machine, run:
docker pull quay.io/zebbra/neops-labs/cisco_iol:17.15.01
docker pull quay.io/zebbra/neops-labs/cisco_iol:L2-17.15.01
📝 These images are built from the same source as the
vrnetlabimages, but are pre-built and ready to use.
🔨 Build the images
First Clone vrnetlab.
Make sure to use the fork compatible with containerlabs and not the original repo.
# 1. Clone the vrnetlab repository
git clone ssh://github.com/hellt/vrnetlab.git
# 2. Place Cisco IOL binary in build directory
cp x86_64_crb_linux-adventerprisek9-ms.iol \
vrnetlab/cisco/iol/cisco_iol-17.15.01.bin
cp x86_64_crb_linux-adventerprisek9-ms-l2.iol \
vrnetlab/cisco/iol/cisco_iol-L2-17.15.01.bin
📝 The
.binextension is required.
🔍 Check the images
Expected output:
🧩 Set image defaults in Netlab
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: iolmakes it the default device type — optional.
You can override this per-topology.
✅ Verify image config
You should see:
🧪 Test your IOL lab
Create a simple IOL lab file topology.yml in a directory of your choice, e.g., ~/iol-lab/:
🧰 Troubleshooting Cheatsheet
| Issue | Check with |
|---|---|
| Containers fail to start | groups $USER – you must be in docker and clab_admins |
| Wrong or missing image | netlab show images |
netlab up asks for sudo password |
Ensure containerlab runs without sudo, and you're in the right groups |
You now have a fully rootless, scriptable Netlab setup that works cleanly in CI and without passwords or privilege escalation.