Add Cisco IOL to Containerlab on macOS

The content in this post is intended for educational and informational purposes only. All software rights belong to their respective owners.

Cisco includes the IOS on Linux (IOL) images available with the Cisco Modeling Labs (CML) Free Tier . Because IOL runs modern Cisco IOS-XE as a native Linux binary, it offers a lightweight, resource-friendly alternative for network emulation. This post will guide you through the process of creating Cisco IOL container images using Containerlab on macOS.

Prerequisite

• Containerlab with macOS on Apple Silicon

macOS

1. Point your web browser to the CML Software Download page.

2. Click the Download icon for Cisco Modeling Labs reference platform ISO file (April 2026).

3. Log in with your Cisco.com (CCO ID) credentials when prompted.

4. Save the refplat-20260409-free-iso.zip file to your Downloads folder.

5. Open your favorite terminal emulator, and change to the Downloads directory.

cd ~/Downloads

6. Create the cml210-refplat directory and iol* subdirectories.

mkdir -p cml210-refplat/{iol,ioll2}

7. Uncompress the refplat-20260409-free-iso.zip file into the cml210-refplatdirectory.

unzip refplat-20260409-free-iso.zip -d cml210-refplat

8. Attach the refplat-20260409-freetier.iso file.

open cml210-refplat/refplat-20260409-free.iso

IOL L2

1. Extract the contents of the ioll2-xe-17-18-02.tar.gz file to the ioll2 directory.

tar -xvf /Volumes/REFPLAT/virl-base-images/ioll2-xe-17-18-02/ioll2-xe-17-18-02.tar.gz -C ~/Downloads/cml210-refplat/ioll2

2. Change to the ioll2 directory.

cd ~/Downloads/cml210-refplat/ioll2

3. List the directory contents for sha256 sorted by file size.

ls -lSh blobs/sha256/

output:

total 496016
-rw-r--r--@ 1 marc  staff   235M Apr  9 09:31 59fc7486ad1682cf83253a99ab9bb04be02304d15bf19dff5c434998c30f51c3
-rw-r--r--@ 1 marc  staff   7.1M Apr  9 09:31 9f410b46920e9ac83c762a7d41da25d2cc60ad0d5625739ab3a82fef27ca4cb0
-rw-r--r--@ 1 marc  staff   904B Apr  9 09:31 7435ed1aa8334b5c036097dd16f8f02eab81e3d9048a78336c91ba4ca0433649
-rw-r--r--@ 1 marc  staff   890B Apr  9 09:31 a7b1018acebd32e107ec8b64b4bd99761a580fa9e70b9e99b65d10de72f461f8
-rw-r--r--@ 1 marc  staff   555B Dec 31  1969 7219d143a70b3ad4afe8f7d7bbfd29d0be80ad12b56c6da0656cda0a94070c5d
-rw-r--r--@ 1 marc  staff   401B Apr  9 09:31 9d2f9bd6088d9547a3c0864d93a4f85e37001a2cfefc90cb6973fa4f080b088b

4. Determine the file type for the largest file in the directory.

file blobs/sha256/59fc7486ad1682cf83253a99ab9bb04be02304d15bf19dff5c434998c30f51c3

output:

blobs/sha256/59fc7486ad1682cf83253a99ab9bb04be02304d15bf19dff5c434998c30f51c3: POSIX tar archive

5. List the contents of the archive file.

tar -tf blobs/sha256/59fc7486ad1682cf83253a99ab9bb04be02304d15bf19dff5c434998c30f51c3

6. Extract the x86_64_crb_linux_l2-adventerprisek9-ms.iol file from the archive file.

tar -xvf blobs/sha256/59fc7486ad1682cf83253a99ab9bb04be02304d15bf19dff5c434998c30f51c3 x86_64_crb_linux_l2-adventerprisek9-ms.iol

7. Move the file to the images directory on the clab Linux machine.

orb push -m clab x86_64_crb_linux_l2-adventerprisek9-ms.iol ~/images/

8. Verify the file type.

orb -m clab -s "file ~/images/x86_64_crb_linux_l2-adventerprisek9-ms.iol"

9. Get the Cisco IOS-XE version.

orb -m clab -s "strings ~/images/x86_64_crb_linux_l2-adventerprisek9-ms.iol | grep '^Cisco IOS Software'"

IOL

1. Extract the contents of the iol-xe-17-18-02.tar.gz file to the iol directory.

tar -xvf /Volumes/REFPLAT/virl-base-images/iol-xe-17-18-02/iol-xe-17-18-02.tar.gz -C ~/Downloads/cml210-refplat/iol

2. Change to the iol directory.

cd ~/Downloads/cml210-refplat/iol

3. List the directory contents for sha256 sorted by file size.

ls -lSh blobs/sha256/

output:

total 602896
-rw-r--r--@ 1 marc  staff   287M Apr  9 09:31 ac697212b57ca1706f4a5618a2b11e42746eb8d6e11f797d2878999ca108c955
-rw-r--r--@ 1 marc  staff   7.1M Apr  9 09:31 9f410b46920e9ac83c762a7d41da25d2cc60ad0d5625739ab3a82fef27ca4cb0
-rw-r--r--@ 1 marc  staff   904B Apr  9 09:31 294714c28f337d6c2effe325333ccb3ac6683867bb8a3fdf702dc2dbf58263bc
-rw-r--r--@ 1 marc  staff   890B Apr  9 09:31 483954eb7b0eebc4965f692bb84dc3298b7e3c22ae2b2b6823c07b60807f2c4f
-rw-r--r--@ 1 marc  staff   555B Dec 31  1969 f40471aaa9e41a28f62d200f7f350761eed98fe3b590d2dc6cf77ae6c914ce02
-rw-r--r--@ 1 marc  staff   401B Apr  9 09:31 9d2f9bd6088d9547a3c0864d93a4f85e37001a2cfefc90cb6973fa4f080b088b

4. Determine the file type for the largest file in the directory.

file blobs/sha256/ac697212b57ca1706f4a5618a2b11e42746eb8d6e11f797d2878999ca108c955

output:

blobs/sha256/ac697212b57ca1706f4a5618a2b11e42746eb8d6e11f797d2878999ca108c955: POSIX tar archive

5. List the contents of the archive file.

tar -tf blobs/sha256/ac697212b57ca1706f4a5618a2b11e42746eb8d6e11f797d2878999ca108c955

6. Extract the x86_64_crb_linux-adventerprisek9-ms.iol file from the archive file.

tar -xvf blobs/sha256/ac697212b57ca1706f4a5618a2b11e42746eb8d6e11f797d2878999ca108c955 x86_64_crb_linux-adventerprisek9-ms.iol

7. Move the file to the images directory on the clab Linux machine.

orb push -m clab x86_64_crb_linux-adventerprisek9-ms.iol ~/images/

8. Verify the file type.

orb -m clab -s "file ~/images/x86_64_crb_linux-adventerprisek9-ms.iol"

9. Get the Cisco IOS-XE version.

orb -m clab -s "strings ~/images/x86_64_crb_linux-adventerprisek9-ms.iol | grep '^Cisco IOS Software'"

9. Detach the refplat-20260409-free.iso file from Finder.

Containerlab

1. Log in to the clab Linux machine.

orb -m clab

2. Change to the images directory.

cd ~/images

3. Clone the srl-labs/vrnetlab repo from GitHub.

git clone https://github.com/srl-labs/vrnetlab.git

4. Copy (and rename) the IOL L2 image to the iol directory.

cp x86_64_crb_linux_l2-adventerprisek9-ms.iol vrnetlab/cisco/iol/cisco_iol-L2-17.18.02.bin

5. Copy (and rename) the IOL image to the same iol directory.

cp x86_64_crb_linux-adventerprisek9-ms.iol vrnetlab/cisco/iol/cisco_iol-17.18.02.bin

6. Change to the iol directory.

cd vrnetlab/cisco/iol

7. Build the Cisco IOL container images.

DOCKER_DEFAULT_PLATFORM=linux/amd64 make docker-image

8. Verify the Cisco IOL container images are now listed.

docker images vrnetlab/cisco_iol

Lab

1. Change to the iol directory.

cd ~/labs/iol

2. Deploy the lab.

clab deploy

3. Test SSH connectivity to the management interface of each node.

Give the nodes some time to complete the Cisco boot process.

for i in r sw; do sshpass -padmin ssh clab-iol-${i}1 'show version | in Ver'; done

4. Destroy the lab.

clab destroy -c