NAME

lab.conf - configuration of a Netkit lab

lab.dep - dependencies on the startup order of virtual machines in a lab

DESCRIPTION

This page describes the files involved in the setup of a Netkit lab and illustrates the basic procedure to set up your own virtual network with Netkit.

CONFIGURING A NETKIT LAB

A Netkit lab is essentially a directory containing some special files and subdirectories. Each subdirectory represents a virtual machine to be started, which will be named the same way as the subdirectory itself. Unless differently specified, simply the existence of a subdirectory causes a virtual machine to be started, even if the subdirectory is empty. Because of virtual machine naming conventions, subdirectories must not contain spaces in their names.

The lab directory may contain files and subdirectories having a special meaning. In the following, lab-path is assumed to be the directory where the lab is located.

lab-path/lab.conf

This is the main lab configuration file. In this file you can specify the names of virtual machines to be started, any option that should be used when launching them, and the topology of the network that connects them. Optionally, you can also provide some descriptive information for the lab, which will be displayed upon its startup. This file is not explicitly required, but running a lab without a lab.conf file is kind of useless...

This file is a list of machine[arg]=value assignments, where arg can be an integer value or the name of a vstart option (see vstart(1)).

–

If arg is an integer value, then value is the name of the collision domain to which interface etharg of machine machine must be connected (note that the name of the collision domain must not contain spaces (' '), underscores ('_'), commas (','), and dots ('.'), unless it is a ''tap'' collision domain - see vstart(1) for more information). For example, ''pc1[0]=CD1'' means that interface eth0 of virtual machine pc1 will be connected to collision domain CD1.
The range of permitted network interfaces is configured inside the file netkit.conf (see netkit.conf(5))
The special collision domain name ''tap'' is reserved, and can be used to connect a network interface to an external network (e.g., the Internet). See vstart(1) for more information about ''tap'' collision domains.

–

If arg is an option name, then machine will be launched with option arg set to value value. arg can be the name of any vstart option, being it short (e.g., -L) or long (e.g., --mem), without the leading dashes ('-'). If the option requires an argument, it can be passed by providing a value. For those options that do not require an argument (e.g., -H), value must be omitted.
For example, ''pc1[mem]=64'' specifies that virtual machine pc1 will be equipped with 64 MB of emulated memory, and ''pc1[D]='' tells vstart to hide the .disk file for virtual machine pc1.

The special assignment ''machines=machine-list'' can be used to explicitly define the set of virtual machines that are part of the lab. This also allows to start a virtual machine even if the corresponding subdirectory does not exist. machine-list is a space separated list of virtual machine names.

It is also possible to provide descriptive information about a lab by using one of the following special assignments:

–

LAB_DESCRIPTION=string (a brief description of the purpose of the lab)

–

LAB_VERSION=string (the version of the lab)

–

LAB_AUTHOR=string (people who have prepared the lab)

–

LAB_EMAIL=string (contacts of lab authors)

–

LAB_WEB=string (useful web reources related to the lab)

A line that does not match the above syntax is supposed to be a comment and is ignored by lstart. However, in order to establish a uniform convention, comment lines should always start with a hash character ('#').

lab-path/lab.dep

If such a file exists in the lab directory, then parallel startup (see lstart(1)) for that lab is automatically enabled, even if option -p is not used. Parallel startup allows to launch several virtual machines at once while still obeying some startup order rules. The file lab.dep contains dependency rules which tell lstart the order in which virtual machines should be started.

Notice: in order to be able to use parallel startup, the make utility must be properly installed.

If you are familiar with Makefiles, lab.dep is simply a list of rules, where both targets and prerequisites are names of virtual machines.
In particular, a rule inside lab.dep has the following syntax:

   MACHINE: MACHINE1 MACHINE2 ...

where MACHINE, MACHINE1, MACHINE2, ... are names of virtual machines. The rule states that MACHINE can only be started after MACHINE1, MACHINE2, ... have completed their boot. Notice that, it they are not dependent on each other, two (or more) virtual machines can also be started simultaneously. The maximum number of virtual machines that can be started simultaneously can be set by using the -p option of lstart or by configuring the value MAX_SIMULTANEOUS_VMS inside netkit.conf (see netkit.conf(5)).

Lines starting with a hash character ('#') are assumed to be comments and simply ignored.

lab-path/machine/

Each subdirectory inside lab-path represents a virtual machine to be started, whose name will be the same as the one of the subdirectory.

Optionally, this subdirectory may contain files that you wish to make available (i.e., copy) inside the virtual machine filesystem. You can also put a full hierarchy of directories here. When organizing files inside lab-path/machine/, think of it as if it were the root ('/') directory of the virtual machine. For example, a file 'lab-path/machine/foo' will be copied into '/foo' inside virtual machine machine.

In case of conflicts, files inside this subdirectory overwrite those inside lab-path/shared/.

lab-path/machine.startup

This file is a shell script that will be launched during the startup of virtual machine machine after all the other initialization scripts have been executed. This file may be useful, for example, to automatically setup IP addresses for network interfaces. It is not required to assign this script the executable permission.
Note that this script is always executed by using /bin/sh as interpreter. If you would like to run a boot-time script using a different interpreter, just invoke it inside machine.startup.

lab-path/machine.shutdown

This file is a shell script that will be executed when virtual machine machine is either halted (not crashed) or rebooted. It is not required to assign this script the executable permission.
Note that this script is always executed by using /bin/sh as interpreter. If you would like to run a halt-time script using a different interpreter, just invoke it inside machine.shutdown.

lab-path/shared/

This subdirectory may contain files and directories that you want to make available (i.e., copy) inside every virtual machine filesystem. Files should be organized so that lab-path/shared/ corresponds to the root ('/') directory of the virtual machines.

In case of conflicts, files inside this subdirectory are overwritten by those inside lab-path/machine/.

lab-path/shared.startup

This is a shell script that will be run on every virtual machine just before lab-path/machine.startup. It is not required to assign this script the executable permission.
Note that this script is always executed by using /bin/sh as interpreter. If you would like to run a boot-time script using a different interpreter, just invoke it inside shared.startup.

lab-path/shared.shutdown

This is a shell script that will be run on every virtual machine just after lab-path/machine.shutdown. It is not required to assign this script the executable permission.
Note that this script is always executed by using /bin/sh as interpreter. If you would like to run a halt-time script using a different interpreter, just invoke it inside shared.shutdown.

lab-path/_test/

This subdirectory contains information for performing a test of the lab. It may be automatically created by ltest or may contain user created files describing customized tests. For more information about this directory, see ltest(1).

HOW TO INFLUENCE THE STARTUP ORDER OF VIRTUAL MACHINES

Virtual machines are usually launched in arbitrary order. However, there are several ways of influencing the order in which they are started up.

–

The first way is to insert a ''machines=machine-list'' assignment inside lab.conf. If such an assignment exists, lstart launches virtual machines in the same order in which they appear in the machine-list.

–

Another possibility is to provide a list of MACHINE-NAMEs as argument to lstart. This ensures that virtual machines are started in the same order in which they are listed on the lstart command line. This method overrides ordering information obtained from lab.conf.

–

It is also possible to use a lab.dep file. This would have the twofold benefit of allowing multiple virtual machines to start up simultaneously while still preserving a partial ordering among them. This method overrides ordering information passed by command line arguments.

EXAMPLES

The following one is a simple example of a Netkit lab, stored inside the directory '/home/foo/lab'.

The directory contents are the following:

lab/
|
+- lab.conf
+- lab.dep
+- pc1/
+- pc2/
+- pc3/
- router/
   |
   - etc/
      |
      - zebra/
         |
         - bgpd.conf

The file lab.conf is made up as follows:

machines="pc1 pc2 router"
pc1[0]=CD1
pc2[0]=CD2
router[0]=CD1
router[1]=CD2
pc1[mem]=64
router[mem]=128

The file lab.dep is made up as follows:

pc2: router pc1

This lab implements the following network topology, where CD1 and CD2 are collision domains:

   eth0   eth0    eth1   eth0
+---+       +------+       +---+
|pc1+-------+router+-------+pc2|
+---+  CD1  +------+  CD2  +---+
64 MB        128 MB

The lab is extremely simple: there are no automatically configured network interfaces or services. There is only a simple configuration file for the BGP routing daemon (bgpd) that is automatically deployed inside virtual machine router under '/etc/zebra/bgpd.conf'.

Assuming the current directory is '/home/foo', it is now possible to launch the lab by issuing the command:

lstart -d lab/

Since a lab.dep file has been created, this lab supports parallel startup. Because of the contents of the lab.dep file, router and pc1 will be started simultaneously, while pc2 will only be launched after they have completed their boot phase.

Notice that, even if there exists a subdirectory '/home/foo/lab/pc3/', the corresponding machine is not actually started. This happens because lab.conf contains an entry (the 'machines=' assignment) stating that pc3 does not belong to the lab.

NOTES

A Netkit lab is essentially a set of configuration files. Virtual machines filesystems (.disk files) do not provide additional data or information (except in very particular situations). Hence, when a Netkit lab is prepared for redistribution, make sure that virtual machines filesystems (.disk files) have been removed before creating the package. To this purpose, you can use the lclean(1) tool. Failure to do this would result in a useless waste of space.

Users who are preparing their labs inside an operating system that is different from Linux may experience problems due to differences in line break conventions. In particular, Windows applications usually mark line breaks in text files with a sequence of CR+NL characters, while in Linux they only consist of a single NL. Using lab configuration files that have been processed inside some Windows editor may cause problems. In such a case, we recommend to use a standard conversion utility such as flip(1) on the affected files before using them.

SEE ALSO

flip(1), lclean(1), lstart(1), vstart(1).

AUTHOR

This man page: Massimo Rimondini