NetkitFAQ

From Netkit Wiki
Revision as of 16:11, 24 February 2016 by Admin (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Frequently Asked Questions

Basic questions

Netkit usage

Troubleshooting

Customizing/Tweaking



Where can I find documentation about Netkit?

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) 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.

Where can I learn how to set up a redistributable virtual lab?

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.

How can I know whether Netkit supports a given technology?

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.

How can I move files from/to a virtual machine to/from my host?

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.

I would like to start virtual machines using a kernel that I have compiled on my own. Is it possible?

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.

I would like to set up a lab with a virtual machine connected to the Internet. How can I do that?

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: 

 --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[0]=tap,TAP-ADDRESS,GUEST-ADDRESS

Notice that:

  • the root password, if asked for, only has to be entered 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.

On every attempt to start a virtual machine I get the error: "Can't execvp some_path/kernel/netkit-kernel: No such file or directory". But the kernel file is there! What is going wrong?

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.


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?

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. If this happens, 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. 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.

I have a virtual machine with a tap interface set up for Internet access. However, I am unable to reach addresses outside of the emulated network. What's going on?

The specification of a tap interface requires two IP addresses:

  • a TAP ADDRESS is assigned to a virtual network interface that is placed on your host and used to route packets to the Internet;
  • a GUEST ADDRESS is assigned to the network interface inside the virtual machine.

The following conditions apply to those addresses in order to make things work:

  • TAP ADDRESS and GUEST ADDRESS must be on the same (classful) subnet. For example, 10.0.3.1 and 10.0.3.2 are ok; 10.0.3.1 and 11.0.3.1 are not. This is required because the virtual machine only has an entry for the subnet of GUEST ADDRESS in its routing table and uses TAP ADDRESS as next hop to reach external networks.
  • Neither TAP ADDRESS nor GUEST ADDRESS must be on the same subnet of any existing interfaces on your host. For the TAP ADDRESS, this would cause your host to have two entries in its routing table for the same subnet and using different interfaces: in this situation, incoming packets may be unpredictably routed either to the real host interface or to the tap interface. As a consequence, connectivity for either the host or the virtual machine is disrupted. For the GUEST ADDRESS, this condition is an immediate consequence of the above condition, becase TAP ADDRESS and GUEST ADDRESS are supposed to be on the same subnet.

The latter is a common reason for malfunction of tap interfaces, so here is a reminder:

Never choose a TAP ADDRESS or GUEST ADDRESS that overlaps or falls in the same subnet as any physical interfaces on your host.

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.

I have set up a virtual machine with a tap interface and now I have lost Internet connectivity from my host. What can I do?

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:

  • settings for a tap interface can always be cleared by using the vclean command;
  • the only way to change the TAP ADDRESS after a tap interface has already been set up is to clear the existing tap interface beforehand using vclean -T.

For more information refer to this FAQ.


Which host architectures Netkit does Netkit run on? Are 64 bit processors supported? What about my PowerPC based Mac?

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.

It seems that I can't get iproute/ebtables tools (e.g., tc) to work. How can I work this around?

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.

How can I install/upgrade packages or other additional software inside Netkit?

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
 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: 

 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

I would like to start an application that has a graphical user interface inside Netkit. How can I do that?

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.

How can I enlarge the filesystem image to make room for additional applications?

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.

How can I build a custom kernel/filesystem from scratch for use with Netkit?

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.

About

Downloads & Docs

Labs & Slides

Support & Development

Personal tools