Cisco Simulator: Cisco IOS-On-UNIX (Cisco IOU)

By Ammar Rasheed - December 15, 2011

cisco-iou-faq

https://learningnetworkstore.cisco.com/market/prod/listSubCatLearnLab.se.work?TRGT=85&/nxt/rcrs/=2559

Preface

This list of frequently asked questions has been compiled in response to an overwhelming number of requests for information about Cisco IOS-on-UNIX (IOU). It is not intended to be comprehensive or complete and will be updated from time to time.

If you wish to share or link to the FAQ, please use this permanent URL: http://evilrouters.net/cisco-iou-faq.
Most of the information in this FAQ has been gathered from documentation that is several years old. Some of it has been discovered on my own or contributed by other users of IOU (thank you!). I make no assurances as to the accuracy of any of the information herein. Your mileage may vary, void where prohibited, for a limited time only. All sales are final.

An Introduction to IOU
Legal Warnings
Supported Features
Downloading IOU
Installing IOU
IOU Licensing
Using Cisco IOU
Connecting IOU to Physical Networks
Error Messages
How to Help

An Introduction to IOU

What is IOU?

From the Cisco Engineering Education Web Site (a long time ago):

Cisco IOS on UNIX (IOU) is a fully working version of IOS that runs as a user mode UNIX (Solaris) process. IOU is built as a native Solaris image and run just like any other program. IOU supports all platform independent protocols and features.

With regard to functionality, it is very similar to GNS3 but it does not require nearly the resources that several virtual routers running under dynamips does.
IOU allows you to build out a network topology on a single PC without the need for physical routers. This is useful for validating network designs, proof-of-concept testing, and certification self-study.

What operating systems does IOU run on?

It is my understanding that, initially, IOU was Solaris (SPARC) only. Nowadays, however, there are also builds for Linux and OS X (though I’m not sure the OS X builds are still maintained).
The versions of IOU that have been available via BitTorrent are all Linux only, I believe.
While the images should run on any 32- or 64-bit (x86/amd64) Linux host, I highly recommend using Debian GNU/Linux. Any examples that I provide in this FAQ will be based upon Cisco IOU running on Debian.

What skills do I need to run IOU?

Dynamips, dynagen, and GNS3 are all cross-platform and can be run on Windows, Linux, and OS X. A graphical installer allows pretty much anyone capable of clicking “Next” to get the software up and running.
This is not the case with IOU. To successfully install and run Cisco IOU, you will need to be familiar with the UNIX command line. Knowledge of vi (or other UNIX text editors) and basic shell scripting would be useful.
If you have never used a UNIX CLI before, you probably want GNS3 instead.

Legal Warnings

Is it legal to use Cisco IOU?

If you are not an authorized Cisco employee (or trusted partner), usage of Cisco IOU is potentially a legal gray area. From an old, internal-only Cisco web page:

Cisco IOS on Unix is a tool intended for internal use only. Distribution of IOU images to customers or external persons, or discussion of IOU with customers or external persons, is prohibited. Don’t do it or we’ll have to come and kill you.

Is it legal to distribute Cisco IOU?

If you have to ask, you’re probably not one of the few persons at Cisco authorized to distribute it, so no. I have managed to acquire copies of several versions but I have not, do not, and will not distribute them.
Cisco IOU, just like IOS, is copyrighted software that belongs to cisco Systems, Inc. Distribution of copyrighted software is a federal crime in the United States. I cannot speak regarding the laws of other countries.
DO NOT ASK ME FOR CISCO IOU.
In addition, any requests for Cisco IOU images in the comments section of this blog will be deleted, regardless if distribution is legal in your country.

Can I be tracked if I’m using IOU?

Potentially, yes.
At startup, Cisco IOU attempts to make an HTTP POST of some XML data to a host at xml.cisco.com. The data includes your (short) hostname (e.g. not the FQDN), the (UNIX) username of the user running IOU, the version of IOU in use, etc.
At the time of this writing, port 80/TCP on xml.cisco.com is not reachable from the Internet, however, so the connection (and submission of identifying data) will not be successful. That could change at any time in the future, however, so you may want to do run the following command (as root) on the host running IOU:

# echo '127.42.42.42 xml.cisco.com' >> /etc/hosts

This will redirect any traffic for the host xml.cisco.com to localhost.

Supported Features

What features does IOU support

Pretty much everything I’ve tested is supported by IOU, depending on the image that you’re using (e.g. IP Base versus Advanced Enterprise Services). The “L2IOU” images have some limitations and do not support certain features, such as voice, QoS, or Etherchannel.

What version of IOS is IOU based on?

As I understand it, IOU images are built for each version of IOS. The images that are available via BitTorrent are the “ipbase” and “adventerprisek9″ 12.4 featuresets. In addition, I personally have version 15.x (Linux) images that I have acquired, as well as older Solaris and OS X IOU images.

Are there pagent images?

Yes, in addition to the “regular” IOU images, there are also “pagent” images in existence that support the traffic generation (and other) features.

Downloading and Installing IOU

Where can I download IOU?

As mentioned in the “Legal Warnings” section above, Cisco IOU is copyrighted software and in the United States at least, distributing it is a federal crime and I don’t do it.
I am told that the software is available via BitTorrent, however you will have to find those torrents on your own.

Are there VMware images of IOU or Live CDs?

I am aware of both IOU Live CDs as well as pre-built VMware virtual machine images that contain a complete environment for running and using Cisco IOU software. I have not used any of them, however, and cannot speak to their quality.
I have been told that these are available via BitTorrent as well.

Okay, I’ve got the files, how do I use them?

Once you have obtained the Cisco IOU images, you will need to transfer them to the Linux host that you wish to run them on (if you haven’t already). The method that you use will depend on what services your host provides (e.g. FTP, SSHd, etc.).
I recommend creating a new directory just to contain the IOU images and related files, for example a directory named “iou” inside your home directory:

$ cd $HOME
$ mkdir iou
$ cd iou

Put your IOU images in this directory.

Where’s the installation program?

There is no installation program for Cisco IOU. Installation is simply a matter of transferring the files to your Linux host that you wish to run them on.

IOU Licensing

Do I need a license to use IOU?

Probably.
Older IOU images apparently do not need a license key to work, such as the older Solaris images that I have.
Newer images, however, including the ones I’ve seen that are available via BitTorrent, do require a valid license key in order to run them.
While I was teaching higher-ed networking courses, I made a video showing why these basic checks are often not enough to adequately “protect” software. This video is available on the Cisco IOU Licensing page on Free CCNA Labs, another website of mine.

Where is your Perl script to patch the IOU images?

At the end of the above video, I mentioned a Perl script that would patch the IOU images so that a valid license key was not necessary. In the interest of not violating the DMCA and staying out of prison, however, I ultimately decided to never share it.
Someone else has posted a quick way to patch the IOU binaries to bypass the license key check from the Linux command-line, however.

Where do I get a license key?

Valid license keys can be obtained via an internal-only web page at Cisco. License keys are specific to a host, based upon its hostname and IP address. This means that a license key obtained from someone else will likely not work on your PC.
Various third parties, however, have reverse engineered the Cisco IOU software and created their own license generators, such as iougen.

Using Cisco IOU

Is my system compatible with IOU?

You will need to be running the operating system that your IOU image was built for, obviously. In most cases, this will be the Linux operating system. The software will run on both 32-bit and 64-bit platforms and do not have any special requirements (for the most part).
Cisco IOU is not CPU-intensive like GNS3 is. A several-years-old PC will run Cisco IOU just fine.

Besides the IOU images, what else do I need?

You’ll obviously need the IOU software images in order to use IOU, but you’ll also need an IOURC file and a NETMAP file (see below).

What’s the IOURC file?

The IOURC file is a configuration file for Cisco IOU. Cisco IOU looks in this file for your license key at startup.

Where do I put the IOURC file?

There are a few different places that IOU will look for its configuration. Any of the following are valid locations:

a file named “iourc” in the current working directory
a file named “.iourc” in the user’s home directory
a file pointed to by the IOURC environment variable

Because I use different topologies and often switch back and forth between them, I prefer to create a separate directory for each topology and store the IOURC file and NETMAP file (see below) in each topology’s directory.

What is the format of the IOURC file?

While there is other information that can be contained in the IOURC file, we’ll use it mainly for storing our license key. In this case, the license stanza of your IOURC file should resemble the following:

[license]
hostname = 4242424242424242;

In this example, replace “hostname” with the actual hostname of your machine and the rest with your actual license key.
If you are unsure of the proper value to use for the hostname, simply run the following command on the command-line and use the value that it returns:

# hostname -s

What is the NETMAP file?

The network topology map, or NETMAP, file describes the topology of your virtual network. It is used for controlling the layout of the “virtual cabling”. If you have used dynagen, this is the equivalent of the .net file.

Where does the NETMAP file go?

Like the IOURC file, your NETMAP file can exist in several locations. Any of the following are valid locations:

a file named “NETMAP” in the current working directory
a file named “.NETMAP” in the user’s home directory
a file pointed to by the NETIO_NETMAP environment variable

Because I use different topologies and often switch back and forth between them, I prefer to create a separate directory for each topology and store the IOURC file (see above) and NETMAP file in each topology’s directory.

What is the format of the NETMAP file?

I’ve posted an example Cisco IOU topology that you should refer to. It includes a network diagram, the corresponding NETMAP file, and shows how to define point-to-point serial and “multipoint” Ethernet connections between routers.
You may also wish to refer to the Free CCNA Labs Topology that I use on that website. That article shows the network diagram being used for the topology and also has links to the NETMAP file being used (with lots of frame-relay, serial, and Ethernet connections) as well as the configuration for the frame-relay switch.
Between these two, you should be able to discern how to create NETMAP files corresponding to network topologies of your own design.

How do I run Cisco IOU?

Once you have the software images in place and your IOURC and NETMAP files created, you’re ready to fire up your routers!
The usage and available parameters you can pass to the IOU binaries are shown here:

Usage: <image> [options] <application id>
<image>: unix-js-m | unix-is-m | unix-i-m | ...
<application id>: instance identifier (0 < id <= 1024)
Options:
-e <n>          Number of Ethernet interfaces (default 2)
-s <n>          Number of Serial interfaces (default 2)
-n <n>          Size of nvram in Kb (default 16K)
-c <name>       Configuration file name
-d              Generate debug information
-t              Netio message trace
-q              Suppress informational messages
-h              Display this help
-C              Turn off use of host clock
-m <n>          Megabytes of router memory (default 64)
-L              Disable local console, use remote console
-u <n>          UDP port base for distributed networks

The simplest method to start up an IOU instance is to simply run the binary and pass in an “application id” (a number between 1 and 1024), for example:

$ ./i86bi_linux-adventerprisek9_ivs-ms.151-4 42

How do I stop a router in IOU?

Simply press CTRL-C and the process will exit.

What is the “wrapper”?

When you start up an IOU router from the command-line, it will stay in the foreground and you’ll be connected to the “console”. This may not always be the desired behavior, especially if you wish to telnet to the console from another host on the network (similar to dynamips).
The wrapper program can be used to redirect a TCP port to the “console” of the router so that you can do exactly this.

How do I use the wrapper?

$ ./wrapper
Usage: ./wrapper [-v] -m<image name> -p<port number> -- [iou options] <router ID>
 where <port number> is in the range <1024-65550>
 all options after the '--' are passed to iou
 [-v] Display version

For example, instead of just running ./imagename <application id>, you would use something like this:

$ ./wrapper -m ./imagename -p 2000 -- -e0 -s1 -m 64 100

This would instruct the wrapper to startup the IOU image named ./imagename and listen on TCP port 2000. Any options after the double-hyphen (“–”) are passed off to the IOU image so, in this case, our IOU instance would start up with zero Ethernet interfaces (“-e0″), one serial interface (“-s1″) — which actually means four serial interfaces in newer images, due to a feature called “Wide Port Adapters” — and 64 MB of RAM (“-m 64″). The “application ID”, which we’ll use to refer to this instance in the NETMAP file (see above), is 100.
The wrapper is most useful in a shell script to start up and background a number of IOU instances at once. For a complete example showing a NETMAP file and a corresponding shell script to startup all IOU instances, see my article “iou2net.pl, an IOUlive replacement”.

How do I stop IOU when using the wrapper?

If you are using the wrapper and have background the IOU instances, you’ll need to find the process ID of the instance you want to stop and use the kill command.
To see all of your running IOU instances, use this command:

$ ps -ef | grep [w]rapper

Find the instance you want to stop and pass the corresponding process IDs to the kill command.
To stop all running IOU instances in a single fell swoop, use the following:

$ ps -ef | grep [w]rapper | awk '{ print $2 }' | xargs kill

Connecting IOU to Physical Networks

What is IOUlive?

IOUlive is a separate application that allows one to bridge an IOU instance to a physical network, similar to what can be done with dynamips and GNS3 using dynagen’s NIO_linux_eth descriptor.
By connecting an IOU instance to IOUlive, your virtual routers can talk to devices on your physical network, as shown in this example Cisco IOU topology.

Where can I download IOUlive?

Unfortunately, binaries of IOUlive are not quite as available as the IOU images themselves. Like IOU itself, IOUlive is copyrighted software belonging to Cisco.

Are there alternatives for IOUlive?

I am aware of at least two individuals who have reverse engineered IOUlive and created their own applications that provide the same functionality. (Note that both require root privileges to run, by default.)
The first application, iou2net.pl, is a Perl script written by “einval” that bridges an IOU instance with the physical network. The scripts itself as well as instructions for using it are available on the Internetworkpro wiki. In addition, my example Cisco IOU topology includes a NETMAP file and a shell script showing how to use iou2net.pl.
Downoad link: Connect IOU with real networks or dynamips.
Another application, an x86 binary named “ioulive86″, was written by a CCIE whose identify I will not reveal. He claims that it offers greater performance and higher forwarding throughput than iou2net.pl. He was going to publish the source code to the application but, unfortunately, that was lost when he deleted a virtual machine without backing up the code first! Because it requires root privileges, run it at your own risk.
Download link: ioulive86.

Cisco IOU Error Messages

What does “UNIX ERR:tcgetattr:Invalid argument” mean?

I’m not sure, honestly, but it doesn’t seem to hurt anything or cause any loss of functionality. It appears that it can be safely ignored.

./i86bi_linux_adventerprisek9-ms: No such file or directory

You’re probably running a 64-bit version of Linux. On Debian and Ubuntu, installing the ia32-libs package will fix this for you (for other distros, you’re on your own):

$ sudo apt-get install ia32-libs

./i86bi_linux_adventerprisek9-ms: error while loading shared libraries: libcrypto.so.4: cannot open shared object file: No such file or directory

You either do not have libssl installed or your version is much newer than what Cisco has linked against when building the IOU images.
First, ensure that libssl is installed. On Debian and Ubuntu:

$ sudo apt-get install libssl0.9.8

Next, you’ll need to make a symbolic link pointing to the libcrypto.so.4 file that IOU is looking for.
On 32-bit hosts:

$ sudo ln -s /usr/lib/libcrypto.so.0.9.8 /usr/lib/libcrypto.so.4

On 64-bit hosts:

$ sudo ln -s /usr/lib32/libcrypto.so.0.9.8 /usr/lib32/libcrypto.so.4

I’m getting a “host not found in iourc file” error message.

Use the correct hostname in your IOURC file. See above.

How can I add an NM-16ESW module?

You can’t.

Oh, come on! There must be some way to add ATM or NM-16ESW modules!

Nope.

When running “./wrapper-linux -m i86bi_linux-adventerprisek9-ms …”, I get a “No such file or directory” error message.

Provide the correct path to the IOU image as the “-m” option. If it is in the current directory, refer to it as “./i86bi_linux-adventerprisek9-ms”, for example.

I’ve tried everything and I can’t get it to work. What should I do?

Use GNS3 instead.