Containerlab Cisco Images Simplified 🐳✨

Running Cisco VMs in containerlab can feel surprisingly unintuitive if you’re coming from tools like EVE-NG or CML. This post will walk you through the first crucial step: building the images.

TL;DR

vrnetlab

Vrnetlab is the glue that allows us to join VMs to _container_lab. It does quite a few useful things:

Configures & runs VMs inside containers
Enables “container native” networking
Exposes serial to telnet on port 5000
Loads configuration on startup
Checks node state & health

In sum this enables us to deploy containerlab nodes in a declarative and predictable manner.

Build

Each node type/image type has its own set of instructions makefile, Dockerfile, launcher script and default configuration. The process for building the images vary slightly, but contains two general steps:

Copy the required files, typically qcow2 disk image(s)
Build the image with make

Example:

sudo mount refplat-20250616-fcs.iso /mnt
cd vrnetlab/cisco/iol
cp /mnt/virl-base-images/iol-xe-17-16-01a/x86_64_crb_linux-adventerprisek9-ms.iol cisco_iol-17.16.01a.bin
make docker-image

Once it has been built you should see it in your local docker images:

torbbang@boxbox:~/Code/blogtmp$ docker images | grep -E "REPO|iol"
REPOSITORY                        TAG                                   IMAGE ID       CREATED        SIZE
vrnetlab/cisco_iol                17.16.01a                             dd18baa12563   3 minutes ago   713MB

At this point you should be able to deploy them in your containerlab topologies.

While this process is fairly straight forward, it is pretty tedious to do for all of your images. It also does not lend itself to being part of any automated workflows, hence I saw the need to build the “refplatinator”.

Refplatinator

The refplatinator automates the extraction and building of Cisco images from CML reference platform (refplat) ISO/ZIP files. Instead of manually mounting ISOs and copying files, it handles everything automatically.

Supported Platforms

The refplatinator supports extracting and building images for the following Cisco platforms:

vrnetlab-compatible platforms:

ASAv - Adaptive Security Appliance Virtual
CAT9KV - Catalyst 9000V Switch (including UADP configuration)
N9KV - Nexus 9000V Switch
XRv9K - IOS XRv 9000 Router
CSR1000V - Cloud Services Router 1000V
C8000V - Catalyst 8000V Router
IOL - IOS on Linux (L2 and L3 variants)
vIOS - Virtual IOS Router
vIOSL2 - Virtual IOS L2 Switch
FTDv - Secure Firewall Threat Defense Virtual
SD-WAN Components - vManage, vSmart, vBond

Generic VM platforms (require manual containerlab configuration):

ISE - Identity Services Engine
FMC - Secure Firewall Management Center
C9800-CL - Catalyst 9800 Wireless Controller

Usage

I have made an installer script to set up the prerequisites for running the refplatinator. Note however that it is generally not advisable to pipe scripts from the internet directly into a local shell. For that reason I also outline the manual procedure below.

Quick install:

curl -fsSL https://raw.githubusercontent.com/torbbang/clab-refplatinator/main/install.sh | bash

Manual install:

git clone https://github.com/torbbang/clab-refplatinator
cd clab-refplatinator
python3 -m pip venv .venv 
source .venv/bin/activate
pip install -r requirements.txt

Once the prerequisites have been met you should place your refplat ISOs/ZIPs in refplats/ and run:

python3 refplatinator.py

If you supply all 3(fcs, supplemental and ise) refplats the script takes about 10 minutes to complete on my machine. There are some options to specify source and destination directories. Further information about this can be found with the --help flag.

Summary

Getting Cisco images working in containerlab using the refplatinator:

# 1. Install refplatinator
curl -fsSL https://raw.githubusercontent.com/torbbang/clab-refplatinator/main/install.sh | bash
# 2. Place CML refaplats(zip or iso) in refpats/ 
cp ~/Downloads/refplat*.zip refplats/
# 3. Run the refplatinator
python3 refplatinator.py
# 4. Have fun with containerlab!

That’s it. No more manual ISO mounting or tedious image builds.

Table of contents