Content-type: text/html Man page of LSTART

LSTART

Section: Netkit (1)
Updated: November 2009
Index Return to Main Contents

NAME

lstart - start a netkit lab

SYNOPSIS

lstart [options] [MACHINE-NAME...]

lrestart [options] [MACHINE-NAME...]

DESCRIPTION

In order to ease setting up complex network experiences with Netkit it is possible to completely describe them into special configuration files, so that the experience can later be started with a single command as if it were a virtual network ``laboratory''.

The lstart command can be used to achieve this purpose. In particular, it starts a set of virtual machines that are part of a Netkit lab and configures them according to the parameters contained in the lab description. There is no difference between lstart and lrestart. The latter is just provided for backward compatibility.
By default, all the virtual machines that make up the lab are started. If a list of MACHINE-NAMEs is provided, then only virtual machines with a matching name and that are part of the lab are started.

The configuration of a Netkit lab consists of some files and directories whose names, locations and contents are described in the section below.

The following options are supported by lstart:

-d DIRECTORY

Start the Netkit lab that is located inside DIRECTORY. If no -d option is provided, lstart assumes that the lab is located in the current directory. The path to the lab directory (being that the current directory or one provided by -d) must never contain spaces.

Note that using lstart without options while the current directory does not contain a Netkit lab would result in starting undesired virtual machines.

-F

--force-lab

As a native behaviour, Netkit starts a virtual machine for each directory that it finds in a designed path, by default the current directory. In order to prevent the user from accidentally starting random virtual machines from a directory that does not contain a lab, lstart requires the presence of at least a ``lab.conf'' or a ``lab.dep'' file in the affected directory. If these files are not required for your setting, and you still want to launch your lab without creating either one, you can use option -F or --force-lab to convince Netkit that a certain directory is indeed a lab.

-f

--fast

lstart always waits for a virtual machine to complete its boot phase before launching the next one. This option disables this behaviour, and allows to launch several virtual machines at once.
This option has no effect if parallel startup is being used and is not impacted by the -p option.

-l

--list

Show a list of currently running virtual machines after the lab has been started up. This is useful to check whether all the hosts are up and running. Notice that, when the -f (or --fast) option is being used, lstart does not wait for all the virtual machines of the lab to start up before printing this list, resulting in a possibly incomplete report. Hence, it is advised not to use -l (or --list) together with -f (or --fast).

-o OPTION

--pass=OPTION

lstart acts as a frontend to vstart (see vstart(1)). This option allows to pass an OPTION unaltered to every invocation of vstart. This means that all the virtual machines of the lab will be launched with option OPTION. OPTION should be specified exactly as it would be on the vstart command line, but always make sure that space characters are quoted (e.g., `-fdummy.disk' or `--append=debug' are ok, `-M 32' should be written as either `-M32' or `"-M 32"').

-p[VALUE]

Parallel startup is a special startup mode that allows to simultaneously boot several virtual machines. It is automatically enabled whenever a `lab.dep' file is found to exist inside the lab directory. This option forces parallel startup, even if the `lab.dep' file does not exist. It also allows to set the maximum number of virtual machines that can be simultaneously launched when starting up the lab. VALUE must be a positive integer. A VALUE of 0 corresponds to setting no limit. If no VALUE is provided, the default configured inside netkit.conf is assumed (see netkit.conf(5)).
This option conflicts with -s (or --sequential).

This option overrides the default value of MAX_SIMULTANEOUS_VMS inside netkit.conf (see netkit.conf(5)).

Notice: parallel startup requires that the make utility is properly installed on your system.

-s

--sequential

Disable parallel startup, even if a `lab.dep' file is found to exist in the lab directory. This option is useful when you just want to launch specific virtual machines. In fact, if you just provide their MACHINE-NAMEs on the command line, lstart would still attempt to satisfy the dependencies, and this may result in starting other undesired virtual machines.
This option cannot be used together with -p.

-w SECONDS

--wait=SECONDS

Wait for the specified amount of time before launching the next virtual machine. This option is always enforced, but it just becomes handy (for example, to reduce the load on the host machine) when using either -f (or --fast) or parallel startup.

This option overrides the default value of GRACE_TIME inside netkit.conf (see netkit.conf(5)).

The following standard options are also supported.

-h

--help

Show usage information.

-v

--verbose

Show details about virtual machines while starting them.

--version

Print information about the installed Netkit release and the host kernel version and exit. If ``<unavailable>'' is printed instead of a version number, then the corresponding information could not be retrieved (for example because a non-standard Netkit kernel or filesystem is being used).

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[L]='' tells vstart to avoid producing a log 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 written 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 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 by 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.

FILES

Apart from the lab configuration files, running a lab requires creating some temporary files inside the current directory (i.e., the one the lstart command is executed from) as well as inside the lab directory. Such files are:

./machine.ready

These files are created by lstart and are used to synchronize virtual machines when they are started. These files are automatically deleted when all the machines in the lab have properly started up. Yet, sometimes (e.g., when a virtual machine crashes in the boot phase) there may be `.ready' files left in the current directory even after the lab has been stopped. In this case you have to launch lclean (see lclean(1)) to get rid of them before the lab can be restarted.

./machine.disk

This is the COW filesystem for virtual machine machine. These files are automatically removed when the lab is crashed with lcrash (see lcrash(1)), so that virtual machines can revert to their original state when the lab is restarted. If you want to preserve .disk files, use the -F (or --keep-fs) option of lcrash. On the other hand, lhalt(1) (see lhalt(1)) never removes .disk files, unless explicitly told to do it (with the -r or --remove-fs option).

See the README in the Netkit filesystem package for more information about COW filesystems.

./machine.log

This file contains the messages issued by virtual machine machine during its boot phase. It may be useful for debugging purposes.

lab-path/readyfor.test

This file is automatically created by ltest (see ltest(1)). It is used to ensure that the status of running virtual machines is only retrieved when they have all completed their boot phase.

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

lstart is essentially a wrapper for vstart. Hence, if something goes wrong, try to investigate the parameters used in the invocation of vstart (they are reported in the lstart output) and read the vstart(1) documentation.

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. 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 dos2unix(1) on the affected files before using them.

AUTHOR

lstart script: Stefano Pettini, Fabio Ricci, Massimo Rimondini
This man page: Fabio Ricci, Massimo Rimondini

REPORTING BUGS

Report bugs to <netkit.users@list.dia.uniroma3.it> or, alternatively, to <contact@netkit.org>.

Bug reports should always include the following information:

-: Bug description (e.g., expected and actual behaviour).
-: One or more command lines that can be used to reproduce the bug.
-: Name and version of the offending command (e.g., vstart 1.0). You can get the command version by starting it with the option --version.
-: Complete output of the offending command (any --verbose option should be used when producing this report).
-: Version of the Netkit filesystem being used.
-: Version of the Netkit kernel being used.
-: Name and release of the Linux distribution being used on the host machine (e.g., Debian, Ubuntu, Mandrake, Red Hat, Fedora, Gentoo, etc.).
-: Host kernel release and platform. You can get these information by using the `uname -a' command.
-: Description of any patch or changes applied to kernels (host and UML) and filesystems.

Index

NAME
SYNOPSIS
DESCRIPTION
CONFIGURING A NETKIT LAB
HOW TO INFLUENCE THE STARTUP ORDER OF VIRTUAL MACHINES
FILES
EXAMPLES
NOTES
SEE ALSO
AUTHOR
REPORTING BUGS

This document was created by man2html, using the manual pages.
Time: 11:38:54 GMT, January 29, 2010