Running Cisco IOS/IOL with QEMU in Docker on MacBooks

Apple’s transition to Apple Silicon (M1/M2/M3 chips) brought significant improvements in performance and efficiency. However, it also introduced some complexity when working with virtualization and emulation tools like Docker, QEMU, and GNS3, especially when trying to emulate Cisco network operating systems like Cisco IOS or Cisco IOL (IOS on Linux). So we gonna use QEMU in Docker on MacBooks

In this article, we walk you through setting up a Docker-based environment on Apple Silicon MacBooks to run QEMU-based Cisco images and integrate them with GNS3.

📌 Prerequisites

Hardware & OS

• Apple Silicon MacBook (M1, M2, M3)

• macOS Ventura or newer

Software Requirements

• Docker Desktop for Mac (Apple Silicon version)

• GNS3 (local GUI + GNS3 VM in a remote or local server setup)

• QEMU (via Docker container or directly)

• Cisco QEMU/IOL images (for lab use only, ensure proper licensing)

🔧 Step 1: Install Docker for Apple Silicon

1. Go to the Docker Desktop download page.

2. Download the Apple Chip version.

3. Install it and run Docker Desktop.

4. Verify Docker is working:

   bash

   CopyEdit

   docker run --rm hello-world


🛠️ Step 2: Use ARM-Compatible Base Image for QEMU

Because your Mac uses an ARM-based chip, you need to run containers compatible with ARM64 architecture.

You can either:

• Use multi-arch QEMU builds, or

• Emulate x86 using QEMU within the container (with performance cost)

To build a basic ARM64-compatible QEMU Docker image:

Sample Dockerfile for QEMU + IOS/IOL

Replace cisco-ios.img with your actual image filename.

Build and Run the Container

Note: If your IOS image is compiled for x86, ensure you use qemu-system-x86_64, and enable TCG (Tiny Code Generator) emulation.

🔄 Step 3: Enable Host-Networking for Docker (GNS3 Compatibility)

Docker on macOS does not support --network=host, which can be problematic when trying to bridge containers directly into GNS3. To work around this:

Option 1: Use GNS3 Remote VM (Recommended)

1. Run GNS3 VM on a remote Linux server or a cloud VM (like Proxmox, ESXi, or Oracle Cloud).

2. Connect your Mac GNS3 client to the remote GNS3 server.

3. Inside the GNS3 VM (Linux), you can:

   • Install Docker natively.

   • Build and run your QEMU in Docker on MacBooks

   • Link it using Cloud interfaces or Ethernet switches in GNS3.

This avoids the networking limitations of macOS Docker.

Option 2: Use TAP/Bridge Interface via UTM or Multipass

You can also run a Linux VM on your Mac (using UTM or Multipass), install Docker there, and bridge its network to the host. GNS3 can then communicate with the containers via a virtual interface.

🔗 Step 4: Integrate Docker/QEMU with GNS3

In GNS3:

1. Go to Preferences → Docker Containers.

2. Click New and configure:

   • Name: Cisco IOS Container

   • Docker Image: cisco-ios-qemu

   • Console Type: Telnet or VNC

3. Under Networking, ensure the correct adapter is set.

   • If using a remote GNS3 server, interfaces can be directly mapped.

   • If on local macOS, you may need to use a Cloud node to bridge traffic via TAP.

Running the Node

• Drag the container into your topology.

• Connect it with virtual switches, routers, or GNS3 VMs.

• Start the container — it will boot the QEMU image within Docker.

⚙️ Advanced Configuration

Serial Output Redirection

To make console access easy, redirect QEMU serial output:

Then, map port 3000 from Docker to Mac:

Now, you can telnet localhost 3000 to access the console.

Add Virtual NICs

You can attach multiple network interfaces using:

Or bridge them to Docker networks.

❗ Challenges on Apple Silicon

• Many Cisco IOS images are compiled for x86, so they need full emulation (QEMU-TCG), which is slow.

• Docker networking on macOS is limited compared to Linux.

• You may experience performance bottlenecks due to architecture mismatch and lack of native KVM support.

✅ Best Practices

• Use remote Linux servers for running GNS3 VM, Docker, and QEMU efficiently.

• Avoid running performance-heavy network labs locally on Mac M-series unless using ARM-compatible images.

• Leverage cloud-native GNS3 servers for scalability.

🔚 Conclusion

Running Cisco IOS/IOL with QEMU in Docker on Apple Silicon MacBooks is possible, but it comes with caveats due to architecture mismatches and macOS’s networking restrictions. The best approach is to offload heavy emulation to a remote Linux server or VM and use your MacBook as the GNS3 frontend.

By combining Docker, QEMU, and GNS3 smartly, you can still create powerful network labs for certification, testing, or simulations—even on Apple Silicon.

Author Profile

Nickajay

Latest entries

• Tips & TricksNovember 7, 2025master_not_discovered_exception in Palo Alto Networks Log Collector
• Tech NewsAugust 17, 2025Malware Analysis For Remcos Remote Access Trojan (RAT)
• Tech NewsJune 10, 2025How to register and install iOS 26, iPadOS 26, and macOS Tahoe
• Tech NewsJune 1, 2025How to Install Cisco and Juniper Images in EVE-NG