NAME

netkit.conf - Netkit configuration file

DESCRIPTION

This file contains information about the Netkit configuration. It also stores the default settings to be used when starting new virtual machines. A copy of this file can be placed into the standard directories listed in the FILES section. Thus, netkit.conf can be used to define both system wide and user specific settings.

The file format is very simple. netkit.conf is nothing but a special shell script which contains definitions of environment variables. Hence, it is a list of PARAMETER=VALUE assignments.

No check is performed on the correctness of the configuration, so VALUE must always be a valid setting (allowed range of values depends on the specific PARAMETER being considered). Failure to comply to this constraint may result in unpredictable behaviour. Moreover, it is very important that no VALUE contains space characters.

PARAMETER can be one of the following.

Generic Netkit configuration parameters

LOGFILENAME

Name of the file that stores a log of the issued Netkit commands. Every time a Netkit command is executed (e.g., vstart, vhalt, etc.), an entry containing the name of the command, the user who started it and a timestamp is added to this file. Different users can share the same file. Setting this parameter to an empty string disables command logging.

Suggested value: $NETKIT_HOME/netkit_commands.log
Default if no setting: "" (logging disabled)

MCONSOLE_DIR

This is the name of a directory that stores temporary socket files used to send directives to running virtual machines. Each user should set this value to a different directory (otherwise, conflicts may occur when different users run virtual machines having the same name).

Suggested value: $HOME/.netkit/mconsole
Default if no setting: $HOME/.netkit/mconsole

HUB_SOCKET_DIR

This is the directory in which temporary socket files used by the virtual hubs are placed. Different users can share the same directory. Thus, setting this parameter to a standard temporary directory like ''/tmp/uml'' is allowed.

Suggested value: $HOME/.netkit/hubs
Default if no setting: $HOME/.netkit/hubs

HUB_SOCKET_PREFIX

Temporary socket files used by the virtual hubs are named according to a standard pattern. This parameter allows to configure the prefix that should be used in the name of every socket file. This is useful, for example, in order to ease recognizing these special files.
This parameter must not contain underscores ('_') or commas (',').

Suggested value: vhub
Default if no setting: vhub

HUB_SOCKET_EXTENSION

Similarly to HUB_SOCKET_PREFIX, it is also possible to configure the standard extension to be used for socket file names.
This parameter must not contain underscores ('_') or commas (','), and must always start with a dot ('.').

Suggested value: .cnct
Default if no setting: .cnct

HUB_LOG

Each virtual hub may produce messages reporting error conditions or information about its status. All these messages are stored inside a log file whose name is the one configured in HUB_LOG. This logging service cannot be disabled; hence, empty names are not allowed for this parameter. Different users can share the same file.

Suggested value: $HUB_SOCKET_DIR/vhubs.log
Default if no setting: $HUB_SOCKET_DIR/vhubs.log

USE_SUDO

This parameter determines how root privileges will be acquired when system-wide configurations need to be applied (e.g., a tap interface needs to be set up). If set to yes, then Netkit will use the sudo(8) command for the purpose. By suitably setting up the sudoers(5) file, this can prevent the user from having to type the root password every time.
If set to no, then Netkit will use the su command instead, which requires inserting the root password for each privileged operation that needs to be carried out.
For more information about how to set up the sudoers(5) file, see the section SETTING UP NETKIT FOR USE WITH SUDO below.

Suggested value: yes
Default if no setting: yes

Default settings for newly started virtual machines

VM_MEMORY

This is the default amount of available memory inside the virtual machines, in MB.

vstart options: --mem, -M
Suggested value: 16
Default if no setting: 16

VM_MEMORY_SKEW

Starting a virtual machine requires allocating a certain amount of memory on the host machine. This amount depends on the amount of available memory inside the virtual machine (i.e., how much memory you decided to equip the machine with). However, some extra memory is needed for kernel structures and other stuff. Hence, the actual amount of consumed memory is slightly larger than that of available memory inside the emulation. That is, there a skew between consumed memory and emulated memory.
This parameter allows adjusting the skew so that proper values are returned by commands showing memory statistics (e.g., vlist on the host machine – see vlist(1) – and 'free -m' inside the virtual machine). The skew is expressed in MB units.

Suggested value: 4
Default if no setting: 4

VM_MODEL_FS

This is the name of the default model filesystem. For more information about model filesystems, see the README in the Netkit filesystem package and the man page of vstart(1). Remember that COW files must always be used in combination with the same model filesystem (i.e., it is not possible to arbitrarily mix COW files and model files).

vstart options: --model-fs, -m
Suggested value: $NETKIT_HOME/fs/netkit-fs
Default if no setting: $NETKIT_HOME/fs/netkit-fs

VM_KERNEL

This is the name of the UML kernel used by virtual machines. Even if there is no particular restriction on the kernel to be used, the virtual machine filesystem must store system tools which are compatible with the kernel being used. Moreover, some filesystems support loading of kernel modules (the one shipped with Netkit does). If this is the case, the kernel must have been compiled with support for external modules, and modules must be available inside a special directory (see the README in the Netkit kernel package for details on how to do this).

vstart options: --kernel, -k
Suggested value: $NETKIT_HOME/kernel/netkit-kernel
Default if no setting: $NETKIT_HOME/kernel/netkit-kernel

VM_CON0

VM_CON1

These parameters allow to configure the default device to which the primary (VM_CON0) and secondary (VM_CON1) virtual machine consoles should be attached. Allowed values for this setting are:

none

Completely disable console (note that disabling both the primary and the secondary console makes you unable to reach the virtual machine unless it runs some remote shell service or other daemon).

xterm

Attach console to a terminal emulator application.

this

Attach console to the current terminal. At most one between the primary and secondary console can be configured to use the current terminal.

pty

Attach console to a pseudo terminal.

port:port-number

Attach console to TCP port port-number. You can later reach it by telnetting to this port. Consider that the virtual machine is not actually started until you do so. Moreover, disconnecting while the machine is still running and later reconnecting is not possible: only a single connection is supported. If you happen to accidentally disconnect before halting the virtual machine, you can still stop it by using either vhalt or vcrash (see vhalt, vcrash).

vstart options: --con0, --con1
Suggested value: xterm (for VM_CON0), none (for VM_CON1)
Default if no setting: xterm (for VM_CON0), none (for VM_CON1)

USE_TMUX

Run the vm inside a tmux session on the host this means you can then connect and disconnect from it when you want (using the vconnect command) and send commands to it with vcommand.

TRUE

Run VM in tmux session.

FALSE

Do not run VM in tmux session.

TMUX_OPEN_TERMS

Open a terminal with the tmux session for the machine this will run vconnect in the background to attempt to connect. N.b. this has a timeout - if the tmux session fails to open this will eventually stop polling it. This option only takes effect when USE_TMUX is true.

TRUE

Attempt to open a terminal connected to the tmux session for the machine.

FALSE

No terminals are opened. You can connect to the machine manually with vconnect.

TERM_TYPE

This parameter determines the terminal emulator application to be used for consoles attached to an xterm device. The application must be correctly installed in the host system. The following values are allowed.

xterm

Use the standard XTerm.

konsole

Use the KDE Desktop Environment konsole.

konsole-tabs

Same as konsole, but different virtual machine consoles are opened inside different tabs of the same konsole window.

gnome

Use the Gnome Desktop gnome-terminal.

vstart options: --xterm
Suggested value: xterm
Default if no setting: xterm

CON0_PORTHELPER

This parameter should only be used in debugging issues in attaching the primary console of virtual machines. When the primary console is attached to a terminal emulator, Netkit can attempt to open the emulator in two different ways:

—

by directly starting the virtual machine kernel inside the terminal emulator, or

—

by letting the virtual machine kernel open the terminal emulator on its own.

The second method is deemed as more standard when using User Mode Linux kernels (like Netkit's), but is slightly less efficient and more prone to crashes, as it relies on a separate software piece (the port-helper) for establishing a communication between the kernel and the terminal emulator. The first method is more efficient and robust and, for this reason, is currently adopted as default choice.

No matter what the value of this parameter is, the secondary terminal will always be opened using the second strategy.

Suggested value: no
Default if no setting: no

MAX_INTERFACES

This is the maximum number of network interfaces a virtual machine can be equipped with. Valid interface numbers will range from 0 to MAX_INTERFACES-1 (e.g., if MAX_INTERFACES is 2 only interfaces eth0 and eth1 can be used).

Suggested value: 40
Default if no setting: 40

MIN_MEM

MAX_MEM

These parameters define the minimum and maximum tolerated amount of available emulated memory inside virtual machines, in MB. These values can be set so that users are prevented from consuming too many resources on the host machine.

Suggested value: 8 (for MIN_MEM), 512 (for MAX_MEM)
Default if no setting: 8 (for MIN_MEM), 512 (for MAX_MEM)

Default settings for lab commands

MAX_SIMULTANEOUS_VMS

This is the maximum number of virtual machines that can be simultaneously started when using parallel startup. This value must be a positive integer. A value of 0 corresponds to setting no limit. For more information about parallel startup, see lstart(1).

lstart options: -p
Suggested value: 5
Default if no setting: 5

GRACE_TIME

This value represents the number of seconds to wait for before launching the next virtual machine. This parameter is only useful when using lstart(1) in fast mode or when using parallel startup. For more information, see lstart(1).

lstart options: --wait, -w
Suggested value: 0 (for labs with less than 4 machines), more than 5 (for labs with more than 4 machines).
Default if no setting: 0

SETTING UP NETKIT FOR USE WITH SUDO

From time to time, Netkit requires administrative privileges on the host machine to set up particular configurations (e.g., ''tap'' interfaces). Netkit can exploit either the su(1) or the sudo(8) command in order to do this. This behaviour can be configured by changing the value of the USE_SUDO parameter. Depending on this choice, Netkit will ask for a different password: for the case of su(1) it is the root password, while for the case of sudo(8) it usually is the user's password. In most setups, sudo(8) is able to keep user authentication information for a certain amount of time during which the password is not requested any longer, even for administrative operations. For this reason, by default Netkit uses sudo(8).

By changing the sudoers(5) file it is possible to completely disable the password prompt, so that the password is never requested (not even the first time) for any administrative operations.

*************************************************************** *** WARNING *** *** WARNING *** *** WARNING *** *** WARNING *** ***************************************************************

By applying the following configuration you enable the affected user to start a shell (therefore any other command) on your host with root privileges, without any passwords being asked for. Put in other words, by enabling the following setting, a user of your choice is entitled to freely gain root privileges and run whichever command she wants without anyone asking her for a password.

This may be an intentional setting on your machine if you frequently perform administrative operations, but in the general case

please apply this change only if you are aware of the consequences.

In order to allow user USERNAME to gain root privileges without being asked for a password, you need to edit the /etc/sudoers file. Since the contents of this file are deemed critical for your system security, it is recommended to edit the file using visudo(8), which prevents multiple simultaneous edits and applies other sanity checks before applying the changes. Of course, other editors may be used as well.

Once you have opened the file, you need to append the following line at the end:

USERNAME ALL = NOPASSWD: /bin/sh

where USERNAME is the name of the affected Netkit user, ALL means that this setting will work on all machines (read as: ''no matter what the name of the machine you are setting this on is, the setting will work''), NOPASSWD means that the following commands can be executed with an arbitrary user ID (including root's), and /bin/sh is the name of the command.

ENVIRONMENT VARIABLES

Some configuration parameters can be overridden by simply defining an environment variable. A list of supported variables follow.

NETKIT_FILESYSTEM

Name of the default model filesystem.

Corresponding parameter: VM_MODEL_FS

NETKIT_MEMORY

Default amount of available memory inside virtual machines.

Corresponding parameter: VM_MEMORY

NETKIT_KERNEL

Name of the UML kernel used by virtual machines

Corresponding parameter: VM_KERNEL

NETKIT_CON0

NETKIT_CON1

Device to which the primary and secondary consoles are attached.

Corresponding parameter: VM_CON0, VM_CON1

NETKIT_TERM

Terminal emulator application to be used for consoles in xterm mode.

Corresponding parameter: TERM_TYPE

SAMPLE netkit.conf FILE

#!/bin/false
# The above line prevents execution of this file

LOGFILENAME="$NETKIT_HOME/netkit_commands.log"

MCONSOLE_DIR="$HOME/.netkit/mconsole"
HUB_SOCKET_DIR="$HOME/.netkit/hubs"

HUB_SOCKET_PREFIX="vhub"
HUB_SOCKET_EXTENSION=".cnct"
HUB_LOG="$HUB_SOCKET_DIR/vhubs.log"
USE_SUDO=yes

VM_MEMORY=32
VM_MEMORY_SKEW=4
VM_MODEL_FS="$NETKIT_HOME/fs/netkit-fs"
VM_KERNEL="$NETKIT_HOME/kernel/netkit-kernel"

VM_CON0=xterm
VM_CON1=none
CON0_PORTHELPER=no
TERM_TYPE=xterm

MAX_INTERFACES=40
MIN_MEM=8
MAX_MEM=512

MAX_SIMULTANEOUS_VMS=5
GRACE_TIME=0

FILES

netkit.conf can be placed in one of the following locations. If multiple instances exist, they will be processed in the order in which they are listed below (each processed file overrides settings configured by the previous one).

/etc/netkit.conf

This instance of the netkit.conf file can be used to configure system wide settings.

$NETKIT_HOME/netkit.conf

This file may contain settings that are specific for a certain Netkit distribution.

~/.netkit/netkit.conf

This file contains user specific settings.

SEE ALSO

lstart(1), netkit(7), Netkit filesystem README, Netkit kernel README, vstart(1).

AUTHOR

This man page: Massimo Rimondini