Netkit

The poor man's system to experiment computer networking

Warning: The web site has been migrated to a Wiki. These pages are no longer being maintained. Please head for http://www.netkit.org/ to enter the Wiki.

Frequently Asked Questions

Q01: Where can I find documentation about Netkit?

A01: 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 man page_name at a shell prompt (a suggested starting point is man netkit).

Moreover, documentation about specific networking topics is available in the form of lecture slides that are available on the Labs & Slides page.
Q02: Where can I learn how to set up a redistributable virtual lab?

A02: 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.
Q03: How can I know whether Netkit supports a given technology?

A03: 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.
Q04: How can I move files from/to a virtual machine to/from my host?

A04: 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.
Q05: I would like to start virtual machines using a kernel that I have compiled on my own. Is it possible?

A05: 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:
```
vm[kernel]=path_to_the_kernel
```
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.
Q06: I would like to set up a lab with a virtual machine connected to the Internet. How can I do that?

A06: Connecting a virtual machine to an external, real network (being it the Internet or not) requires you to have the root password handy. In order to attach virtual interface eth0 to a real network, you should pass to vstart an option like:
```
--eth0=tap,TAP-ADDRESS,GUEST-ADDRESS
```
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:
```
vm[eth0]=tap,TAP-ADDRESS,GUEST-ADDRESS
```
Notice that:
- it is not (yet) possible to use the standard syntax (vm[0]=...) for this kind of interfaces;
- the root password is only asked for the first tap interface used in the lab;
- the TAP-ADDRESS is only applied for the first virtual machine that is started with a tap interface: from then onwards, using a different TAP-ADDRESS for a different interface, even in a different lab, has no effect. If you want to reset the TAP-ADDRESS you need to stop all your virtual machines and launch
```
vclean -T
```
  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.
Q07: When I try to start a virtual machine, nothing happens or an xterm window pops up and immediately disappears. It looks like Netkit is crashing. What can I do?

A07: 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.
1. Run the script check_configuration.sh provided with Netkit to check that every required package is properly available.
2. Check if you can start an xterm alone by typing xterm inside a terminal window. If you can't, check your xterm installation.
3. If you are booting a virtual machine that had already been started previously, attempt to remove its .disk file and try again.
4. If you are forcedly starting a virtual machine with a different version of the filesystem (i.e., with the option -m of vstart), Netkit may be unable to mount it properly. Try adding the option --append=root=98:1 to vstart.
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. Sometimes the error allows to guess what's going wrong, but more often it looks like a senseless sequence of characters. If you still cannot figure out what the problem is, please send a report to one of our Contacts.
Q08: Which host architectures Netkit does Netkit run on? Are 64 bit processors supported? What about my PowerPC based Mac?

A08: As of December 2008, 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:
```
ia32-libs
libc6-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.
Q09: How can I install/upgrade packages or other additional software inside Netkit?

A09: 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:
```
apt-get update
```
(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:
```
wget http://some.download.location/dir/download_me.tar.gz
```
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 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:
```
chroot /mnt/nkfs
```
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:
```
umount /mnt/nkfs
```
Q10: I would like to start an application that has a graphical user interface inside Netkit. How can I do that?

A10: 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.
Q11: How can I build a custom kernel/filesystem from scratch for use with Netkit?

A11: 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:
- the procedure is intentionally not, and will never be, expected to work on a wide range of Linux distributions and installations (we use it for development on Debian systems, and this is the only platform on which it is tested);
- especially with reference to the filesystem build procedure, which frequently requires root access to the host, we provide no warranty that your host system will not get damaged by running the procedure. Please avoid running it unless you are aware of what you are doing.
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.

Netkit

Frequently Asked Questions

Basic questions

Netkit usage

Troubleshooting

Customizing/Tweaking