'Cisco' tag logo

How to add Cisco IOS-based devices in GNS3

GNS3 historical use-case was to act as a GUI around Dynamips to emulate Cisco devices. However, while stable, this emulation may not be as straightforward as it could be and has some limitations.

To understand the negatives, we first need to understand how IOS-based Cisco hardware work.

How real gear works

Professional switch and router devices cannot be reduced to a general purpose small-factor computer with a few additional network interfaces.

When using a general purpose computer with classical network adapters to build a router/firewall appliance, all the processing occurs at the software level, generally the operating system kernel.

On specialized hardware such as Cisco switches and routers, the operating system (here IOS) works tightly with some underlying specific (and usually proprietary) hardware and delegates parts or all of the processing to dedicated chips, the Application Specific Integrated Circuits or ASICs, to allow faster processing.

On general-purpose computers, this can be compared with the GPU located on graphical cards which allows to delegate 3D computation to allow a faster rendition than with the main general-purpose CPU.

Cisco IOS-based devices stacks

Data processed at the hardware level do not involve the main CPU running IOS, only the dedicated ASIC, and is handled faster resulting in lower latency. On the other side, data processed at the software level allows more complex processing.

Most of the switching logic of Cisco Catalyst devices is implemented at the hardware level. Thus, emulating a Cisco catalyst device to run its IOS images would imply to reverse-engineer and reimplement most of the switch features.

On the other side, most of Cisco routers logic occurs at the software level as part of the IOS firmware. Emulating a Cisco router hardware to run its IOS images is therefore easier than emulating Cisco switches.

Dynamips, the Cisco devices emulator used by GNS3, only emulates router devices. However, we will see some workarounds allowing to still have some Cisco switching features in your GNS3 topologies.

Cisco devices virtualization and emulation

There are several possibilities to add Cisco devices in your GNS3 topologies, some go through virtualization and other through emulation. These two notions must not be confused in order to better understand the advantages and limitations of each solution:

  • Virtualization software emulate Cisco devices hardware to execute unmodified Cisco IOS firmware images.

    This is slower and consumes more resources than emulation software, but by running a genuine IOS it provides an experience closer to using a real Cisco device.

  • Emulation software emulate a whole Cisco device, including the IOS operating system.

    This is faster and is more resource efficient, but depending on the fidelity of the emulation the final result may not have the same options or behavior as real gear.


Dynamips is a free software emulating Cisco routers hardware, thus allowing to run unmodified IOS firmware images in a virtualized environment.

While Dynamips allows to emulate a wide range of routers, two are of special interest and are the most widely used: the c3725/c3745 and c7200 devices.

Any valid image for these devices is sufficient in most situation. If, however, you require some specific features or would-like more information on the features proposed by a given firmware image, you can freely check the on-line Cisco Feature Navigator.

Cisco 3725/3745 integrated services routers

These routers accept Cisco EtherSwitch modules, allowing to add some switching ability to the router, and the good news is that Dynamips offer a basic but stable emulation of these modules.

These devices are end-of-life now, they only run IOS 12.x, but they are very versatile as they can act not only as a router but also as a layer-2 or layer-3 switch in your GNS-3 topology.

There is still a few difference between an EtherSwitch router module and an actual Catalyst switch (note that these differences come from how the EtherSwitch module itself works, not from Dynamips):

  • Some commands are slightly different. For instance, the show vlan command from Catalyst devices becomes show vlan-switch on routers with the EtherSwitch module.
  • DTP is not supported by the EtherSwitch module: no dynamic mode available on the EtherSwitch ports and the command switchport nonegotiate is not available.
  • Only standard versions of the STP and EtherChannel protocols are available, Cisco extensions are not available for these protocols.
  • No Gigabit port available (but it remains possible to “cheat” by setting the bandwidth value manually without negative impact in a virtual topology).
  • The port-security feature is not available.

The GNS3 users forum hosts a more complete list of missing features.

As we will see below, some of these limitation can be solved by using IOU.

Cisco 7200 series routers

These devices are more recent and allow to run IOS 15.x images.

They have no switching capability, but they remain useful when you want to test some feature specific to IOS 15.x (for instance entry-level Cisco certifications require students to be familiar with the new licenses management features which came with IOS 15.0).

Finding IOS firmware images for Dynamips

IOS firmware images are proprietary software. Their license forbids free redistribution (yes, even the old obsolete ones!).

  • If your company is a Cisco Partner, then it should have access to Cisco’s IOS firmwares download pages.

  • Otherwise, you are expected to extract the firmware from a device you bought (it can be a second-hand router, this doesn’t matter, as long as it is the right model) and extract its firmware image as you would do to back it up on a TFTP server.

Alternatively, you can do as Keith Barker and do some “snooping around” ;) .

Install IOS firmware images in GNS3

Installing an IOS firmware in GNS3 requires several steps. Most of them are shown during the first four minutes in this video by Anthony Sequeira (note that this video shows an older version of GNS3).

The complete procedure goes as follow:

  1. From GNS3 option tab, go in Edit > Preferences to open the Preferences window.

  2. On the left pane, go in Dynamips > IOS routers, then click the New button.

  3. Select you IOS image file location. When asked, it is recommended to accept to copy it to GNS3 own directory tree.

  4. With a sane image file, the device type should be automatically detected.

    If the selected device supports EtherSwitch modules, a supplementary checkbox labeled This is an EtherSwitch router becomes available. This checkbox tells GNS3 to consider this device more as a switch than a router.

    Ticking this box sets the following template properties:

    • It adds by default a NM-ESW16 EtherSwitch module in the first device slot. This is the only really important action, the other ones are merely cosmetic.
    • It enables the use of a specific startup script which set the default port configuration to better mimic those from a switch and set a specific hostname.
    • The device template is associated to the Switches category instead of the Routers one.
    • The device icon is changed accordingly.

    Each of these settings can also be set later manually by right-clicking on the device template to access the Configure template window.

  5. Unless you have some specific needs, the RAM size and modules can be left at their default values.

  6. Now you need to determine a valid Idle-PC value for your IOS image. Simply click on the Idle-PC finder button and let GNS3 do all the work.

    • If the Idle-PC finder does not work, try to use it several times. With some images it will work only on the second or third attempt.

      If this still doesn’t work:

      • Finish the procedure normally.
      • Add the newly created device in a new topology.
      • Start it and open its console (right-click > Console) and wait the end of boot process, when the device is indeed Idle and showing its prompt.
      • Now right-click and select Auto Idle-PC, this should work now.
    • For the curious who wonder what this value means:

      When Dynamips executes your IOS image code, at some point the execution flow enters in an infinite loop waiting for an event to happen (a incoming packet on a network interface, a key pressed on the console, etc.). This infinite loop makes Dynamips to consume 100% of a host CPU core.

      The solution is to determine the address of an instruction within the firmware file corresponding to this loop (and nothing else). This address is called the Idle-PC, it is a value of the Program Counter allowing to recognize when the device is in idle state.

      As we will see later, the Dynamips process will regularly pause for some milliseconds when the IOS execution flow passes through this instruction, thus reducing the CPU consumption to a reasonable value.

  7. Click on the Finish button to create the template.

  8. The default idle settings are very conservative. When using relatively large topologies, Dynamips will still consume a noticeable amount of CPU even while idle.

    • Right-click on your newly created device template and click Configure Template.

    • Below the Advanced tab you will find the previously determined Idle-PC accompanied by an Idlemax and an Idlesleep values.

      To reduce the host CPU consumption, Dynamips process counts the number of time the IOS firmware instruction at the address Idle-PC is executed, each time this number reaches Idlemax the Dynamips process sleeps for Idlesleep milliseconds.

      The default value for Idlemax is 500, meaning that Dynamips sleep every 500 executions of the instruction at the Idle-PC address.

      Setting Idlemax to 100 allows to reduce Dynamips CPU consumption even further with no noticeable side-effect.


IOU stands for IOS on Unix. This is a Cisco device emulator, allegedly initially designed to run on SunOS systems and later ported to other platforms such as Linux.

This was initially a internal project within Cisco, not designed to be distributed of even discussed outside of the circle of Cisco employees. If you are not a Cisco employee, you may not be authorized to use this software.

Nevertheless, an experimental version of this software leaked outside of Cisco offices. While being experimental and having its own serious issues, it is still an interesting alternative solving some of Dynamips-based IOS virtualization issues.


Unlike IOS firmwares which run in a virtualized environment controlled by the Dynamips process, IOU are native executable files which execute directly on your environment.

In other words: they are executable programs.

Would you be tempted in searching and downloading IOU from some untrusted shady sources, keep in mind that they may potentially embed some malware targeting your host and/or your network.

Several IOU binaries are available, emulating various options but more importantly emulating devices acting at the layer 2 (switching) or the layer 3 (routing). Layer 3 is well covered by Dynamips, however IOU is a really interesting alternative to test some layer 2 functionalities not available when using Dynamips.

Advantages of IOU compared to Dynamips-based virtualization:

  • This is the lighter and faster option available to emulate Cisco devices.
  • Port-security is functional (note though that while real gear CAM size is limited to a few thousands entries, on IOU it can host tens of millions of addresses, making MAC-flooding tests impractical).
  • EtherChannel is functional.
  • STP options are available, but are severely broken and nearly unusable.

Disadvantages of IOU:

  • This is not a real IOS, so several options and behavior may be different from real gear (see the CAM table size for instance).
  • While available, the Spanning Tree Protocol (STP) is severely broken. The election process works correctly, but if there is a loop in your topology (which is precisely what this protocol is meant to handle) any broadcast systematically results in a broadcast storm with a very high CPU consumption. The CPU consumption immediately gets back to normal as soon as the loop is broken (by disabling an interface through IOS for instance).
  • According to various sources, QoS is not functional either.
  • Chances are that several other things are missing or broken (impossible for instance to set a port speed).

If you want to learn more about IOU, the reference on the subject is Evil Router’s FAQ. More background information is available on Free CCNA labs, another blog maintained by the same author.

Install IOU in GNS3

I am using Debian on a 64 bit architecture, depending on your system and host architecture the exact steps you need to follow may vary.

  1. IOU is a 32 bits executable file. To use it on a 64 bit environment, you need to enable the 32-bits repository to install the GNS3 module in charge of handling IOU images and all required libraries:

    sudo dpkg --add-architecture i386
    sudo apt-get update
    sudo apt-get install gns3-iou
    sudo ln -s /usr/lib/i386-linux-gnu/libcrypto.so.1.0.0 /usr/lib/libcrypto.so.4
  2. The IOU attempts to notify the host xml.cisco.com upon start, to disable this edit your /etc/hosts/ file and associate this name to some black-hole loopback address: xml.cisco.com
  3. You usually also need a license key to run IOU, this key is calculated from your hostname and IP address. Usually a key generator (keygen.py) is provided with the IOU binaries allowing to generate the appropriate key file.

  4. In GNS3, don’t forget to specify the location of your license key file in the general IOS on UNIX section from the Preferences screen.

  5. Then go in IOU devices, click New, this should be straight-forward.


My personal guess is that IOU is an early development snapshot of what later became the vIOS once freely downloadable from Cisco website as part of their SDK Cisco’s One Platform Kit (onePK), later replaced by the paid VIRL virtualization platform not freely downloadable anymore.

vIOS usually presents itself as a virtual machine image hosting IOS. It is very similar in its form and behavior with IOU, there are images available for the layer 2 and 3 but layer 2 are the most useful ones (IMHO).

Compared to IOU, the fact that it does not run natively on the host raises some limitations:

  • It consumes more resources than IOU, even if under some condition it may remain more efficient that Dynamips images but I’m not even sure about this.
  • As with any VM-based images, GNS3 doesn’t allow to modify its network links while the VM is running. Although this is usually not a problem with real end-devices nodes such as workstations and servers, having to shutdown and restart half of your switches each time you want to change your topology seems like a major drawback to me.

The advantage compared to IOU:

  • STP is fixed.

I know, this is very short, that’s why I usually prefer to use IOU over vIOS.

Maybe there is a way to extract the emulated IOS from the virtual machine image. Due to the low benefits I did not do any research in this area, but this would allow to get the best of the two worlds.

Cisco IOS-based devices stacks

Cisco IOS-based devices stacks

Popular tags see all