Add Cisco IOL devices to GNS3 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 adding Cisco IOL devices using GNS3 on macOS.

Prerequisite

• GNS3 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.

6. Create the IOU directory.

mkdir -p ~/GNS3/images/IOU

7. Change to the Downloads directory.

cd ~/Downloads

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

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

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

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

10. 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 IOU directory.

mv x86_64_crb_linux_l2-adventerprisek9-ms.iol ~/GNS3/images/IOU

8. Verify the file type.

file ~/GNS3/images/IOU/x86_64_crb_linux_l2-adventerprisek9-ms.iol

9. Get the Cisco IOS-XE version.

strings ~/GNS3/images/IOU/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 IOU directory.

mv x86_64_crb_linux-adventerprisek9-ms.iol ~/GNS3/images/IOU

8. Verify the file type.

file ~/GNS3/images/IOU/x86_64_crb_linux-adventerprisek9-ms.iol

9. Get the Cisco IOS-XE version.

strings ~/GNS3/images/IOU/x86_64_crb_linux-adventerprisek9-ms.iol | grep '^Cisco IOS Software'

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

GNS3

1. Open the GNS3 client application.

2. Click the Settings button.

3. Select IOU Devices on the left side menu.

IOL L2

1. Click the New button.

2. Enter IOL L2 for the Name value.

3. Select L2 image for Type.

4. Click the Browse… button.

5. Navigate to and select the x86_64_crb_linux_l2-adventerprisek9-ms.iol file.

   • Click the Show Options button.
   • Use All file (*) in the file extension drop-down menu.

6. Click the Open button.

7. Click the Finish button after the upload completes.

8. Click the Edit button for the IOL L2 template.

9. Enter SW{0} for the Default name format value.

10. Enter :/symbols/affinity/square/blue/switch_multilayer.svg for the Symbol value.

11. Click the OK button.

12. Click the Apply button to save the template configuration.

IOL

1. Click the New button.

2. Enter IOL for the Name value.

3. Select the New Image button.

4. Select L3 image for Type.

5. Click the Browse… button.

6. Navigate to and select the x86_64_crb_linux-adventerprisek9-ms.iol file.

   • Click the Show Options button.
   • Use All file (*) in the file extension drop-down menu.

7. Click the Open button.

8. Click the Finish button after the upload completes.

9. Click the Edit button for the IOL template.

10. Enter R{0} for the Default name format value.

11. Enter :/symbols/affinity/circle/blue/router2.svg for the Symbol value.

12. Click the OK button.

13. Click the OK button to save and close the Preferences window.