umlmon

umlmon − configuration file of the UMLMON monitor

/etc/umlmon

UMLMON is a monitor that starts and communicates with virtual machines (VMs) basing on the User Mode Linux technology. This configuration file sets some aspects common of all virtual machines, specifies which virtual machines exist, and also sets the initial properties of the VMs. Note that many properties of the VMs can be changed by the user, and that these changes are stored in another file (see below). In this respect, /etc/umlmon only contains the default settings.

The configuration file uses the well−known ini format. This file is structured into sections, and every section is started by a header in brackets, e.g.

[section name]

The sections contain parameter settings in the form

parameter name = parameter value

For every VM one needs a section. The name of the section is also the name of the VM. For example, this section describes the properties of the VM foo:

[foo]
vmuser = foo_user
logfile = monitor
start = manual
kernel = /shared/kernels/linux
mem = 64
ubd0 = /disks/root.dsk
con0 = pty:con0
con1 = pty

In addition to this, there is also a global section covering the properties of the whole UMLMON system. This section has the reserved name GLOBAL.

The global section may have the following parameters:

vardir = directory

Specifies the location of the data directory where the VMs are stored. The directory must be an absolute path. Defaults to /var/lib/umlmon.

shared = directory

Specifies the location of the shared data directory. This directory can be accessed from all VMs. The directory must be given by an absolute path. Defaults to vardir/shared.

tcp = bool

Sets whether the UMLMON monitors listen on TCP ports. Every monitor will listen on its own anonymous port which is announced in the UMLMON directory service UMLDIR. The boolean value must be either true or false. Defaults to false. Note that the monitors always listen on Unix Domain sockets. Note also that TCP connections are password−protected.

tcp_redir = bool

Sets whether the UMLMON directory service UMLDIR enables its TCP redirection service. This is another way of making the monitors accessible over the network that works independently of the tcp setting. UMLDIR listens on a single, known port, and forwards the connection to the monitor controlling the selected VM.

device = device specification

This directive makes a block device of the host system available for the VMs. This directive can be used several times to deal with several block devices. The device specification has the form

device_file(name=name,target_file=file,group=group,identity=idaction)

Here, the name is the name under which the VMs see the device. The name must have the suffix .dev. The monitor will create a block special file in the directory for shared disks with this name. The target file is the block special file identifying the device on the host. All users of the specified group can access the device read/write. Example:

device_file(name=data1.dev,target_file=/dev/sdc5,group=uml)

This directive makes the host device /dev/sdc5 available as shared disk data1.dev, and it is accessible by the users of the group "uml".

The optional parameter identity allows one to check whether the (already existing) device name and the target file still refer to the same device (devices have become quite dynamic in Linux). The idaction can be one of ignore, check (the default if omitted), or update. For check, the monitor refuses to start up when an identity change is detected. For update, the identity change is propagated from the target file to the local device node. This may be useful for e.g. LVM devices, dm devices, and USB devices.

pool = pool specification

Sets the properties of the pool of MAC addresses. UMLMON can manage a pool of such addresses, and every time a network interface is set up, it is possible to fetch a MAC address from the pool. Note that you must also configure the network interface such that it uses the pool. The pool specification has the following form:

mac_pool(first_mac_address=XX:XX:XX:XX:XX:XX,number=n)

Here, the X must be hex digits. The pool contains the address range starting with the explicitly mentioned address, and containing n consecutive addresses. If the pool parameter is omitted, the pool defaults to the range starting at 0A:12:BC:AF:32:00 and containing 256 addresses.

Note that MAC addresses are visible in the whole network segment. If you have several UMLMON servers in the segment and if you use pools, it is very advisable to assign every server a distinct MAC range.

password = password

Sets the master password that allows unlimited access to the monitors over TCP connections. By default, no such password exists. The password can be given in clear text, or as MD5 sum written as 32 hex digits. Note that connections over Unix Domain sockets are not affected by this setting.

sitecmd = program

The site command is typically a user−written script that can perform certain administrative actions that are specific to the site installation. The site command can be invoked over the RPC interface. The program must be given as absolute path to an executable.

The sections describing the VMs can have the following parameters. A parameter is said to be protected if the user cannot change it, so only the administrator has the right to set it.

vmuser = username

Sets the user as which the VM will run. This parameter is required and protected.

vmgroup = groupname

Sets the main group as which the VM will run. The VM is always member of the groups the user is member of. The main group has a special meaning as new files are created with this group owner. By default, the main group is the main group of the user. This parameter is protected.

scheduler = scheduler specification

This directive may set the scheduling class and certain scheduling options of the VM process. By default, nothing special is set up regarding the scheduler. The specification may have one of these forms:

sched_default(prio=n)

Uses the standard scheduler with priority n. This is a number in the range from −20 to 19, smaller numbers mean higher priority. Priority 0 is the default process priority, so negative numbers give an increased and positive numbers a decreased priority compared to most other processes. Values −5 to −10 give already very noticeable boosts.

sched_rr(prio=n)

Uses the round−robin realtime scheduler with priority n. This is currently not recommended because the system may freeze if the VM eats up all available CPU time.

This parameter is protected.

jaildir = directory

Sets the directory where the chroot jail is set up. Defaults to vardir/vmname/jail. This parameter is protected.

logdir = directory

Sets the directory where the log files are created. Defaults to vardir/vmname/log. This parameter is protected.

logfile = file

Sets the log file for the UMLMON log. The file name should not contain a directory portion.

kernel = file

Sets the kernel executable. The file name must be given from the perspective of the chroot jail. It has usually the form /shared/kernels/name.

kernelarg = arg

Passes an additional arbitrary kernel argument.

mem = n

Sets how much memory the VM gets, given in megabytes. UMLMON automatically creates a tmpfs filesystem of this size and arranges that the memory backing file is created in it. Additionally, the kernel is informed about the memory size. This parameter is required.

mem_limit = n

Sets the administrative limit for the mem parameter. Users can change the amount of memory until the limit is reached. This parameter is protected.

conn = terminal specification

Specifies the console channel n. The UMLMON monitor can log messages sent to VM consoles, and it is even possible to set up bidirectional connections to consoles. Console con0 is always used for kernel messages and messages emitted when runlevels are changed. Consoles con1 and following are usually interactive consoles where users can log in. It is strongly recommended to configure con0 and a small number of further consoles!

The specification can have one of the forms:

pty

A pseudo terminal driver is used to manage the console connection.

pty:logfile

In addition to the pty driver, a logfile is written. The logfile should not contain a directory portion.

ssln = terminal specification

Specifies the serial channel n (from the VM it can be accessed as /dev/ttySn). The specification has the same format as for console channels.

ubdn = file

Sets the file used for the emulation of the virtual disk n. The file name is given from the perspective of the chroot jail, and must have the form /disks/name or /shared/disks/name. The first form refers to a file in the local directory of the VM, and the second form refers to a file in the shared directory used by all VMs. The name of the file must have a certain extension: .dsk for flat images, .cow for copy−on−write images, and .dev for block devices. Note that it is not necessary to specify the backing file of copy−on−write images as these are determined automatically.

ubd0 is usually the root disk of the VM.

sync_disks = disk ... | all

Determines which disks are forced to be opened in synchronous mode. For current UML kernels, this is recommended for disks containing sensitive data, and thus the default is all. However, you can also list here the ubd devices individually.

ethn = NIC specification

Configures the virtual NIC number n of the VM. The specification can be arbitrary text which is passed to the UML kernel, or one of the following special forms. This parameter is protected.

host_to_host(proxy_if=nicname,
proxy_addr=ipaddr,
proxy_hwaddr=mac,
guest_addr=ipaddr,
guest_hwaddr=mac,
host_if=nicname)

Configures a host−to−host connection that works only for IP version 4, and that needs two IP addresses. The parameters proxy_hwaddr, guest_hwaddr and host_if are optional.

On the host side a proxy interface is established using the TUN/TAP driver. The name of the proxy_if can be chosen arbitrarily. The proxy interface needs its own IP address which becomes another IP address of the host system. The VM can reach the host under this address.

On the VM side the network interface must use the IP address announced here (guest_addr). A route is set such that the host can reach the VM under this address.

Optionally, one can set the MAC addresses of the proxy and the VM interfaces. Use either the format XX:XX:XX:XX:XX:XX where the Xs are hex digits, or the special keyword pool. The addresses are then taken from the MAC pool UMLMON manages.

Optionally, one can announce the guest IP address in another LAN segment (proxy ARP). This is typically the segment connecting the host system with the Internet. Use host_if with the name of the interface of this segment.

bridged(bridge_if=nicname,
proxy_if=nicname,
proxy_hwaddr=mac,
guest_hwaddr=mac)

Configures bridged networking. It is necessary that the bridge interface already exists, i.e. create it with brctl before starting UMLMON. The rest of the setup is done automatically.

The bridge_if is the name of the bridge to connect to. The proxy_if is the name of the TUN/TAP interface the monitor creates. This can be an arbitrary name. The proxy interface is automatically added to the bridge.

In bridged networking, the VM can use an arbitrary IP address. Bridges are not restricted to IP version 4; all protocols available for Ethernet transport are possible. No routing is required to reach other hosts of the LAN segment.

Optionally, one can set the MAC addresses of the proxy and the VM interfaces. Use either the format XX:XX:XX:XX:XX:XX where the Xs are hex digits, or the special keyword pool. The addresses are then taken from the MAC pool UMLMON manages.

password = password

Sets the password of this VM that is used to authenticate TCP connections. The password can be given in clear text, or as MD5 sum written as 32 hex digits.

start = type

Sets the start type of the monitor and the VM: manual means that the monitor is started on boot but not the VM, boot means that the VM is booted, and off means that neither the monitor nor the VM is started.

The user can change unprotected parameters of the VM section. These changes are not stored in /etc/umlmon but in a second file vardir/vmname/config. The changes are usually performed by commands of the RPC interface.

In order to see the effective parameters of a VM, call the command

umladmin config vmname

UMLMON was written by Gerd Stolpmann.

Report bugs to gerd@gerd−stolpmann.de

You can get commercial support for UMLMON. Please ask Gerd Stolpmann <gerd@gerd−stolpmann.de>.

Copyright (C) 2005 Informatikbuero Gerd Stolpmann. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

umlwatch(1), umlmon(7), umlmon(8), umldir(8), umladmin(8)