NAME

vstart - start a new netkit virtual machine

SYNOPSIS

vstart [options] MACHINE-NAME

DESCRIPTION

The vstart command can be used to start a new virtual machine named MACHINE-NAME. Names of virtual machines must be unique for each user. Yet, different users can run machines having the same name.

Without providing options, vstart starts a virtual machine whose configuration reflects the defaults stored inside the netkit.conf file (see netkit.conf(5)). The options described below can be used to adjust the features of a virtual machine upon starting it.

Notice: unless differently stated, command line arguments (MACHINE-NAME), option arguments (e.g., names of collision domains), and any path name (including the path to the current directory at the time of invoking vstart) should not contain space characters. Not complying to this causes vstart to raise an error.

Hardware/Kernel settings

-k FILENAME

--kernel=FILENAME

Each virtual machine can have its own kernel. By using this option, it is possible to explicitly choose which kernel should be used for the machine being started. FILENAME must be a UML kernel. The default kernel is configured inside the netkit.conf file (see netkit.conf(5)).

-M MEMORY

--mem=MEMORY

Set the amount of available RAM inside the virtual machine to MEMORY MB. The range of valid amounts and the default amount of memory are both defined inside the netkit.conf file (see netkit.conf(5)). Notice that the memory consumed by the virtual machine processes on the host machine can be slightly larger than this value.

Networking settings

--ethN=DOMAIN

Equip virtual machine with a network interface ethN. N is an integer ranging from 0 to a maximum value stored inside the netkit.conf file (see netkit.conf(5)).

Interface ethN will be attached to a (virtual) collision domain whose name is DOMAIN. A collision domain can be seen as a sort of virtual hub. Thus, attaching interfaces of different virtual machines to the same collision domain allows them to exchange network traffic. DOMAIN must not contain underscores ('_'), commas (',') and dots ('.'), unless a ''tap'' collision domain is being configured (see below).

The special domain name ''tap'' is reserved. When attaching an interface to a ''tap'' domain, an external (i.e., real) network can be reached through this interface. A ''tap'' collision domain must be declared with the following syntax:

--ethN=tap,TAP-ADDRESS,GUEST-ADDRESS

where TAP-ADDRESS is the IP address of the host side of the interface and GUEST-ADDRESS is the IP address of the interface inside the virtual machine (guest side). TAP-ADDRESS and GUEST-ADDRESS must be on the same (sub)network and, most important, this network must not already exist on your host network (otherwise routing would be messed up). Interfaces connected to a ''tap'' collision domain are automatically configured and brought up inside virtual machines.

There can be at most one ''tap'' collision domain for each user. Hence, if different virtual machines are configured for using ''tap'' connected interfaces, they also are on the same collision domain. TAP-ADDRESS is mandatory, but is only taken into account when a ''tap'' collision domain is first used (i.e., this is the first interface the current user ever connected to a ''tap'' collision domain). Otherwise, it simply ignored.

*** IMPORTANT NOTES ABOUT USING ''tap'' COLLISION DOMAINS ***

–

Configuring ''tap'' domains for the first time requires administrative (root) privileges. The vstart script will take care of asking you for the root password if needed. For more information about how Netkit gains root privileges, see USE_SUDO and SETTING UP NETKIT FOR USE WITH SUDO in the man page of netkit.conf(5). The following operations are performed when working as root:

1) The '/dev/net/tun' device is created (if it does not exist).
2) Permissions for the '/dev/net/tun' device are set to 666 (read/write for all users).
3) Any existing network device named 'nk_tap_USERNAME' is brought down and removed (USERNAME is the name of the current user).
4) A tap network device named 'nk_tap_USERNAME' is created and configured to have IP address TAP-ADDRESS.
5) Kernel based IP forwarding is enabled via the '/proc/sys/net/ipv4/ip_forward' special file.
6) If the iptables firewall is found, packet forwarding for data coming from the tap interface is enabled. Also, masquerading is enabled. More precisely, the following rules are added to the current iptables configuration:

*nat
-A POSTROUTING -j MASQUERADE
*filter
-A FORWARD -i nk_tap_+ -j ACCEPT

All these configuration settings can be easily removed by using the vclean command (see vclean(1)).

–

Using ''tap'' domains requires some host-side configurations. These configurations are not automatically removed after halting virtual machines. The vclean command must be used for this purpose (see vclean(1)).

Filesystem settings

-H

--no-hosthome

By default, the home directory of the current user is made available for reading/writing inside the virtual machine under the special directory '/hosthome'. This option disables this behaviour, thus not making the host filesystem accessible from inside the virtual machine.

-m MODEL-FILESYSTEM

--model-fs=MODEL-FILESYSTEM

-f FILESYSTEM

--filesystem=FILESYSTEM

Virtual machines need two special files which contain their filesystem.

–

The whole filesystem of the virtual machine is stored inside a model file (also called backing file). Upon first startup, every virtual machine has the same filesystem, which is the one stored in the model file.
The default name of this file is stored inside the file netkit.conf (see netkit.conf(5)). By explicitly specifying a MODEL-FILESYSTEM, a different model file can be used. MODEL-FILESYSTEM is the name of a file that stores an entire model filesystem for the virtual machines.

–

Changes being made to the model filesystem are stored in a different file, based on a COW (Copy on Write) strategy: whatever is written to the filesystem is stored in an external file instead of overwriting the model filesystem.
By default, every virtual machine has its own COW file. Such file is created in the current directory as soon as the virtual machine is first started. Its name is the same as the name of the virtual machine plus the suffix ''.disk''. For example, assuming the current directory is '/home/foo/', starting a new virtual machine named ''pc1'' automatically creates the file '/home/foo/pc1.disk'.
By passing a FILESYSTEM name it is possible to use a different COW file. If FILESYSTEM is not found, a new file with this name is created. Otherwise, FILESYSTEM must be the name of a COW file that has been previously created by a virtual machine.
Consider that COW files are never automatically removed after a machine has been halted or crashed (unless proper options of vhalt or vcrash are being used). This allows to preserve filesystem contents across reboots of the virtual machine.

Both MODEL-FILESYSTEM and FILESYSTEM must not contain commas (',') in their names.

Options -f and --filesystem cannot be used in conjunction with -W or --no-cow.

Notice: it is not possible to combine a COW file with different model files. Hence, virtual machines must always be started with the combination of model and COW file used upon their first startup.

*** IMPORTANT NOTES ABOUT THE HOST MACHINE FILESYSTEM ***

In principle, there is no particular restriction on the choice of the filesystem (of the host machine) on which MODEL-FILESYSTEM and FILESYSTEM are located. However, installing Netkit on a machine that uses a non-standard Linux filesystem (e.g., FAT32) may introduce performance losses and/or malfunctions. Please refer to the README file in the Netkit filesystem package for more information about this.

-W

--no-cow

Instead of using two different files for storing filesystem data (as explained above), write filesystem changes directly on the model filesystem.

Never start two virtual machines with the -Wq option, or your filesystem image may get corrupted!

This option cannot be used in conjunction with -f,

--filesystem,

-D, or

--hide-disk-file.

Warning: by using this option, all the changes being made to the filesystem of the virtual machine are made permanent. Do not use this option unless you know what you are doing!

-D

--hide-disk-file

By using this option, the ''.disk'' file of virtual machines is no longer created (actually, it is deleted soon after it is created). This is useful if you do not want to scatter temporary disk images around your filesystem. Using this option does not compromise in any way the operation of virtual machines, except, of course, that the contents of virtual machine filesystems are irremediably lost as soon as the machines are stopped.

This option cannot be used in conjunction with -W or

--no-cow.

Console settings

--con0=MODE

--con1=MODE

Each virtual machine can have at most two console windows, which correspond to the virtual terminals (ttys) of the real host. con0 is the primary console, and con1 is an optional, secondary console. Depending on the value of MODE, each console can be configured to be attached to different terminal emulator programs or devices. MODE can be one of the following:

xterm

Attach console to a terminal emulator application (the application must be correctly installed).

this

Attach console to stdin/stdout (i.e., use the current terminal); this mode cannot be used for both the primary and the secondary console at the same time.

pty

Attach console to a pseudo-terminal. You can later reach it by connecting a terminal emulator to the corresponding tty (for example, 'screen /dev/ttyp0').

port:tcp-port

Attach console to TCP port tcp-port. This console can then be accessed by telnetting to that port. The virtual machine will not be actually started until the first connection is established. Notice that, if the connection is closed while the virtual machine is still running, it won't be possible to access the console by telnetting again to tcp-port. In such a case, the virtual machine can still be halted by using one of the commands vhalt or vcrash.

none

Disable console (primary console cannot be disabled).

Default console settings (including the default terminal emulator application to be used) are stored inside the netkit.conf configuration file (see netkit.conf(5)).

Using the --con0=this option also implies --foreground.

--xterm=TYPE

Consoles enabled in xterm MODE can make use of different terminal emulator applications. In particular, TYPE can assume one of the following values:

gnome

use the Gnome Desktop gnome-terminal.

konsole

use the KDE Desktop Environment konsole.

konsole-tab

same as konsole, except different virtual machines are opened in different tabs of the same konsole window.

xterm

use the standard xterm.

When attaching a console to a terminal emulator, make sure that the corresponding application is properly installed.
The default terminal emulator application to be used is configured inside the netkit.conf file (see netkit.conf(5)).

Laboratory settings

The following options can be used when setting up virtual laboratories. In general, it is unlikely that you need to directly use them. Instead, laboratories should be set up by using the lstart command (see lstart(1)).

-e COMMAND

--exec=COMMAND

Run a specific command inside the virtual machine during the boot phase. COMMAND should be the name of an executable command or script.

-l DIRECTORY

--hostlab=DIRECTORY

Tell the virtual machine that the base directory for the laboratory is DIRECTORY. DIRECTORY is a directory on the host machine which contains information about the configuration of the laboratory.

-w DIRECTORY

--hostwd=DIRECTORY

Set the lab working directory to DIRECTORY. DIRECTORY is a directory on the host machine which is used to store some temporary files (e.g., files that indicate that a virtual machine has completed the boot process).

Notice: options -l,

--hostlab,

-w, and

--hostwd

make the host filesystem accessible inside the virtual machine even if the option -H or

--no-hosthome

is being used. In particular, DIRECTORY is made available for reading/writing under the '/hostlab' or '/hostwd' directory in the virtual machine (depending on the option being used).

Other options

--append=PARAMETER

Append additional kernel command line parameters when running the virtual machine kernel. PARAMETER can be the name of a kernel option (e.g., ''quiet'') or a pair PARAMETER=VALUE. Documentation about supported parameters can be found inside the kernel source tree (which you can download at http://www.kernel.org).

This option can be used multiple times, so that several parameters can be appended. Parameters will be passed to the kernel in the same order in which they are provided.

-F

--foreground

By default, virtual machines are started in background. By using this option, vstart waits for the virtual machine to halt (or crash) before giving the command line prompt back. Virtual machines are also started in foreground when using the --con0=this or --con1=this option.

Regardless of this option, virtual hubs are always started in background.

--tmux-attached

Run each VM in a tmux session and start a terminal attached to this tmux session. This is the same as setting USE_TMUX=TRUE and TMUX_OPEN_TERMS=TRUE in netkit.conf

--tmux-detached

Run each VM in a tmux session without opening any terminals. This is the same as setting USE_TMUX=TRUE and TMUX_OPEN_TERMS=FALSE in netkit.conf

-h

--help

Show usage information. This option also prints out the default values for several settings (i.e., those that have been configured inside netkit.conf — see netkit.conf(5)).

-p

--print

Instead of actually starting the virtual machine, just show which commands would be executed, including those used to start virtual hubs.

-q

--quiet

Suppress any output except errors and warnings.

-v

--verbose

This option enables verbose kernel messages during the virtual machine boot phase.

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

ENVIRONMENT VARIABLES

All Netkit commands require that the NETKIT_HOME variable contains the name of the directory Netkit is installed in.

Default settings for newly started virtual machines can be overridden if the following environment variables are defined:

NETKIT_FILESYSTEM

Name of the default model filesystem (must be the name of a file storing the whole model filesystem). Can be changed by using the -m or --model-fs option.

NETKIT_MEMORY

Amount of available RAM inside the virtual machine (in megabytes). Can be changed by using the -M or --mem option.

NETKIT_KERNEL

Name of the virtual machine kernel (must be the name of a UML kernel). Can be changed by using the -k or --kernel option.

NETKIT_CON0

Console mode for the primary console. Can be changed by using the --con0 option (see above the documentation of this option for a list of permitted values).

NETKIT_CON1

Console mode for the secondary console. Can be changed by using the --con1 option (see above the documentation of this option for a list of permitted values).

NETKIT_TERM

Terminal emulator program to be used for consoles in xterm mode. Can be changed by using the --xterm option (see above the documentation of this option for a list of permitted values).

FILES

MACHINE-NAME.disk

This is the default COW filesystem used by virtual machines. This file is automatically created in the current directory as soon as virtual machine MACHINE-NAME is started, if it does not exist yet. It stores all the differences between the model filesystem and the current filesystem contents.

$NETKIT_HOME/netkit.conf

/etc/netkit.conf

~/.netkit/netkit.conf

These files store global defaults for newly started virtual machines. They are considered in the order in which they are listed, so that users can override system wide settings. For more information about the contents of this file, see netkit.conf(5).

~/.netkit/hubs/

This directory stores temporary socket files that are needed for the virtual hubs to work properly. These files are automatically removed when unused. A different directory may also be configured inside the netkit.conf file (see netkit.conf(5)).

~/.netkit/mconsole/

This directory stores temporary socket files that are used to send special directives to the virtual machines (e.g., halting commands). These files are automatically removed when the corresponding virtual machine is halted or crashed. A different directory may also be configured inside the netkit.conf file (see netkit.conf(5)).

EXAMPLES

vstart pc1

Start a new virtual machine named pc1. The 'pc1.disk' file is also created in the current directory.

vstart mypc1 -k /home/foo/kernel/uml-kernel -M 128 -m /home/foo/filesystems/model-fs

Start a new virtual machine named mypc1. The machine will run using kernel

'/home/foo/kernel/uml-kernel',

will be equipped with 128 MB of RAM and its filesystem contents upon first boot will be those of the model file

'/home/foo/filesystems/model-fs'.

vstart producer --eth0=A

vstart consumer --eth0=A

Start two virtual machines named producer and consumer, which will be able to exchange data with each other by using their network interfaces eth0. Such interfaces will have to be configured with an IP address before the communication can actually take place.

vstart router --eth0=tap,10.0.0.1,10.0.0.2 --eth1=A

Start a new virtual machine named router. The machine will have two network interfaces. Interface eth0 will be automatically configured to have IP address 10.0.0.2 when the virtual machine is started. It will be connected to the real network, and will have host side IP address 10.0.0.1. Interface eth1 will be attached to the virtual collision domain (i.e., hub) named A and will have to be configured by hand inside the virtual machine (for example, by using ifconfig).

vstart test --eth0=A --eth1=B -f /home/foo/myFilesystem -p

Instead of actually starting a virtual machine, show which commands would be executed for running one named test, with two network interfaces attached to collision domains A and B and using filesystem

'/home/foo/myFilesystem'.

vstart conTest --con0=xterm --con1=xterm --xterm=konsole-tab

Start a virtual machine named conTest having two consoles. They will be shown inside different tabs of the terminal emulator konsole.

SEE ALSO

lstart(1), netkit.conf(5), vclean(1), vconf(1), vcrash(1), vhalt(1), vlist(1), Netkit filesystem README.

AUTHOR

vstart script: Massimo Rimondini
This man page: Massimo Rimondini, Fabio Ricci

REPORTING BUGS

Report bugs to the Github issues page: https://github.com/netkit-jh/netkit-jh-build/issues

Please follow the recommended templates when reporting bugs.