The documentation of Netkit is available in two forms. If Netkit is installed properly, its man pages contain detailed instructions about the user interface and the steps to prepare virtual labs, as well as directions to modify Netkit with customized kernels or filesystems. The man pages can be obtained by typing
at a shell prompt (a suggested starting point is man netkit) or can be browsed online starting from this page.
Moreover, documentation about specific networking topics is available in the form of lecture slides that are available on the Labs & Slides page.
Detailed instructions to prepare a Netkit lab are available in the man page of lstart.
As a starting point to create a Netkit lab, you can use one of the ready-to-use labs published in the Labs & Slides page. Alternatively, you can download the contributor's pack from the Contributed Labs page, which provides the skeleton of a basic lab and a template to prepare lecture slides that can be used as a starting point.
There are several places where you can look for this piece of information, depending on which Netkit component provides the support.
One possibility is to look at the Features page, which provides a high level overview of the available tools and technologies inside Netkit.
Another possibility is to browse through the list of packages installed in the Netkit filesystem, which is available in the Download page. Here you can find the user space applications that are available in Netkit, including network tools such as ping, traceroute, tcpdump, etc.
Support for some lower level features (e.g., IPv6) must be typically compiled in the kernel. If you want to know whether the kernel of Netkit supports a particular technology, you can check its configuration file, which is again available in the Download page.
Inside every virtual machine there is a special directory named /hosthome. This directory points to your home directory on the host (typically, /home/username). Hence, anything you write into /hosthome will be made available on the host, and you can bring host files into your virtual machine as well.
Of course it is. vstart provides the option --kernel, which allows to start a virtual machine with a custom kernel. Alternatively, setting the environment variable NETKIT_KERNEL tells Netkit to use the specified kernel for any newly started virtual machine, including those that are part of virtual labs. If you are setting up a lab in which only some virtual machines need to use a different kernel, you can put inside lab.conf an entry like the following:
which tells to use the alternative kernel only for machine vm.
Instructions about how to build your own custom kernel for Netkit are provided inside the README file in the Netkit kernel package.
Connecting a virtual machine to an external, real network (being it the Internet or not) requires administrative privileges on your host. Depending on the way Netkit is configured, it may ask you to enter the root password once this is required. In order to attach virtual interface eth0 to a real network, you should pass to vstart an option like:
where TAP-ADDRESS is the IP address of a new host side interface that is used to route traffic to and from the external network, while GUEST-ADDRESS is the address that is automatically assigned to the interface inside the virtual machine. Note that TAP-ADDRESS and GUEST-ADDRESS must be on the same subnet, regardless of what this subnet is (remember that Netkit hides these addresses behind NAT). For more information about setting up tap interfaces, see the man page of vstart.
If you want to set up a lab in which a virtual machine has an Internet connected interface, you can add an option like the following inside your lab.conf:
As Netkit uses NAT, the specific TAP-ADDRESS being used is not relevant and in general there is no need to change it "on the fly". For this reason, the above command is rarely used.
Most likely, you are running a 64-bit Linux distribution. The executable of the Netkit kernel is in place, but the host OS is unable to recognize it because 32-bit compatibility libraries are required.
All you need to do is to install 32-bit compatibility libraries, which are also required to run any other 32-bit-only applications (and there are still a number around). Most Linux distributions provide these libraries in packages like:
libc6:i386 libncurses5:i386 libreadline6:i386
In practice, issuing the following command in a terminal session should be enough in most cases:
sudo apt-get install libc6:i386 libncurses5:i386 libreadline6:i386
Feel free to contact us if it is not.
First of all, check whether there are known issues with the host Linux distribution you are running. You can find the support status for most distributions in the Status page.
If none of the entries in the above page applies, or if you still experience the problem after applying the suggested fixes, proceed as follows.
Double check whether one of the above tests solves your issue.
If it is not the case, you should look deeper into the problem. Therefore, start a virtual machine with a higher level of verbosity:
vstart vm --verbose --con0=this
This usually results in a bunch of messages terminating with an error report. If the error contains a message similar to the following:
No filesystem could mount root, tried: ext3 ext2 cramfs romfs Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(98,1)
then it is very likely that the filesystem image has not been downloaded or decompressed correctly. The suggestion in this case is to re-download the filesystem from the Official releases page, check the MD5 of the downloaded file, uncompress the archive, and check the MD5 of the decompressed filesystem image against the one reported in the Downloads page.
If you still cannot figure out what the problem is, please send a report to one of our Contacts.
The specification of a tap interface requires two IP addresses:
The following conditions apply to those addresses in order to make things work:
The latter is a common reason for malfunction of tap interfaces, so here is a reminder:
On the other hand, TAP ADDRESS and GUEST ADDRESS may overlap with other addresses or subnets used outside of your host, because Netkit uses address translation (NAT) to hide TAP ADDRESS and GUEST ADDRESS from external networks.
Check whether the TAP ADDRESS or GUEST ADDRESS used in setting up the tap interface overlap with any existing addresses or subnets used by your host's network interfaces. If they do, remove the overlap by reconfiguring the tap interface with different addresses. Remember that:
For more information refer to this FAQ.
As of November 2009, Netkit can only run on Intel based architectures. The provided kernel and filesystem are built to run on an i386 architecture but, provided that you have compatibility libraries installed, you can run Netkit straightforwardly on x86_64 hosts (that is where we currently perform our tests). These libraries can usually be found in the following packages:
libc6:i386 libncurses5:i386 libreadline6:i386
However, other packages may also be required.
Porting to completely different architectures (e.g., PowerPC) is currently not planned. It may be the case that, with some adaptations, the build scripts can still come handy to generate kernels and filesystem for non-Intel hosts, but we are currently not working on this.
Most recent releases of Netkit include modified versions of some packages, in order to provide the user with MPLS support. These packages include:
ebtables iproute iproute2 quagga
We cannot exclude the existence of compatibility issues in the usage of the commands included in these packages. Therefore, we included also the commands from the original packages in the filesystem image. These commands are easily accessible by using the prefix orig- before the command name.
For example, if you are looking for the plain, non-MPLS-capable-but-more-stable version of tc you could use orig-tc instead.
Detailed instructions are provided inside the README file provided in the filesystem package. In principle, there are two ways of doing this.
One is to use an Internet connected virtual machine. You can configure a virtual machine to connect to the Internet by using tap interfaces (see the man page of vstart for more information). So, for example, you would type:
vstart vm --eth0=tap,10.0.0.1,10.0.0.2 -M 256 -W
Notice that the virtual machine has been started with an increased amount of memory (-M 256), which will be needed during the installation of the package. Also, the option -W is used in order to permanently change the filesystem, thus applying the changes to all the virtual machines launched afterwards.
Once vm has started, configure a name server inside its resolv.conf file and run the following commands:
(to refresh the list of available packages)
apt-get install package_name
(to actually install the package)
If the product you want to install is not available as a Debian package, you may download it inside virtual machine vm by using a command like:
If the downloaded package consists of source code, in order to be able to compile it you may need to install at least the following packages, which are not provided with Netkit:
gcc g++ make libc6-dev binutils automake autoconf
After installing the package, remember to safely halt the virtual machine by using halt or vhalt. Failure to do so would result in a corrupted model filesystem, which causes all virtual machines launched from now onwards to perform a check upon their boot.
An alternative solution is to mount the model filesystem on the host and to perform the installation without starting any virtual machine. To proceed in this way, you require root privileges on your host. First of all, mount the Netkit filesystem inside an empty directory (in this case, /mnt/nkfs):
mount -o loop,offset=32768 $NETKIT_HOME/fs/netkit-fs /mnt/nkfs
Change the root directory (/) to point to the mounted filesystem:
In this situation, every issued command invokes a binary file inside the Netkit filesystem (therefore, available commands are those that are available in the Netkit filesystem), and any filesystem operation only affects the Netkit filesystem.
Now configure a name server inside /etc/resolv.conf (remember that this only affects the /etc/resolv.conf in the Netkit filesystem). At this point, you can proceed normally with the package installation as explained above:
apt-get update apt-get install package_name
After installing the package, quit the shell by typing exit. This brings the root (/) directory back to its original location: every change applied from now onwards affects the filesystem of your host!
Remember to unmount the Netkit filesystem before performing any other operation:
You can't. Netkit has not been conceived as a product to experiment with GUIs. Most networking applications are distributed as command-line tools or have an equivalent command-line version. Since Netkit aims at providing an environment to experiment with networking, in most cases it is enough to take advantage of these text-mode utilities to perform the required analyses. This also reduces the size of the filesystem and makes virtual machines more lightweight.
In principle, using graphical applications would be possible by forcing them to connect to the host's X server. However, no X clients are currently installed in Netkit, which means that there are no graphical tools to play with.
A more correct approach is to collect the required information (e.g., a packet trace) inside the virtual machines by using a command-line tool (e.g., tshark), save it to a file on the host and then open it with a graphical analyzer on the host (e.g., wireshark) to perform investigations.
In the most recent releases of Netkit the filesystem image should provide enough free space to install a number of additional tools. In the unlikely event that you need even more room to accommodate your applications, it is possible to enlarge the image without any data loss.
The detailed procedure to enlarge the filesystem image is provided in the README file inside the filesystem package.
Building a customized kernel for Netkit is not always trivial. For the case of the filesystem, things are even much more difficult. That is why, starting from version K2.6 of the kernel and F5.0 of the filesystem, we provide an automated build procedure. Please keep in mind that this procedure is intended for use only by developers and advanced users who have some experience in building a filesystem image. Standard users should not, and have no reason to, fiddle with the procedure. As such:
An automated build procedure can usually be initiated by using a command similar to the following:
cd $NETKIT_HOME/kernel make -f Makefile.devel kernel
or, for the filesystem:
cd $NETKIT_HOME/fs make -f Makefile.devel filesystem
However, several prerequisites must be satisfied before this procedure can be successfully executed, which usually consist in installing packages. These prerequisites, as well the details of the operations performed by the build procedures, are described in the README files supplied inside the kernel and the filesystem packages.