umls3 manual

umls3 - control daemon for user-mode-linux guests

SYNOPSIS

umls3 -s [-d] [-S controlsocket] [-p pidfilename]

umls3 [-d] [-S controlsocket] [commands ...]

DESCRIPTION

Umls3 is a control daemon for user-mode-linux guests. If started with the flag -s, it starts a server process, which can be controlled by a client program which per change is called umls3 (but started without a -s flag).

-d Debug program, increase debugging level.

-h Print some help text.

-p filename Name of pid-file (only useful for server mode, default is /var/run/umls3.pid).

-S socketname Name of contol socket for server-client communication (default is /var/run/umls3.ctl).

All remaining arguments are processed as client commands, each argument corresponds to an input line. If there are no additional commandline arguments, and no server was started, then commands are read from standard input until end-of-file.

Each command must appear on a single line with the following additions:

- The backslash escapes the next character.

- The hash sign starts a comment till the end of the line.

- Characters enclosed in double quotes are treated as a single word.

- Line breakings between curly braces are ignored.

Currently the following commands are implemented:

debug Increase debugging level.

nodebug Reset debugging level to quiet.

switch name arguments Create a new switch. Se below.

killswitch switchname Stop a previously created switch.

version Print version.

logfile filename Print log output to file filename.

guest name arguments Start a new user-mode-linux guest. Se below.

killguest guestname Stop a previously created user-mode-linux guest.

mconsole guestname command Send command to user-mode-linux guest guestname via uml_mconsole emulation.

term Stop umls3 daemon (terminates the client, too).

attach guestname string Send string to standard input of user-mode-linux guest guestname. With sufficient use of double quotes und backslash-n the autor managed to rescue a user-mode-linux guest wating for console support for fixing fsck-problems on the boot partition.

include filename Read additional commands from file filename.

The general syntax of the switch command is switch name arguments, with arguments from the following list:

tap device Add a connection to the host network using the tap device. Useful arguments are tap0, tap1, etc. Your host must contain support for TUN/TAP-devices (e.g. the module tun must be loaded before).

cmdup cmd Either you use preconfigured tap-devices (see the corresponding section on the user-mode-linux homepage) or define commands, that will be executed after the tap-device is created or before it is destroyed again. Useful commands on a debian-box are ifup tap0 and ifdown tap0.

cmddn cmd See cmdup cmd.

sockname name This command creates the unix domain socket for the user-mode-linux instances. The suggested name is /tmp/uml.ctl, otherways you need a special configuration of your user-mode-linux instances. umls3 only supports the uml_switch-protocol version 3.

sockowner passwd-entry Change the ownership of the control socket to the corresponding unix user.

udpport number Port number to listen for connections from uml_switches running on other hosts (and defining the port used for sending packets to other hosts). The program enforces some kind of security by only accecpting packets originating from the same port as it listens. By using a port number below 1024 you can be sure, that the network packets from the remote host came from a program with root-privileges.

remote hostname-list Hostname or IP-address of remote hosts to send broadcast ethernet packets.

hub Act as a hub instead of a switch.

The general syntax of the guest command is guest name arguments, with arguments from the following list:

args argument ... All remaining words are used for contracting the argument list of the user-mode-linux guest.

SIGNALS

The following signals are recognized:

SIGTERM Terminate daemon.

SIGUSR1 Increase debuglevel.

SIGUSR2 Set debuglevel to zero.

SIGHUP Reopen logfile (not yet tested).

SECURITY

Depending on the configuration, any user on your network can send arbitrary network packets using the udp-port of the umls3 switch. If you configure umls3 switches to use a port below 1024, then only root-users can do this. There are maybe other security flaws. Here is some more reasoning.

BUGS

Maybe. The program works for me (TM). Your mileage may vary. I've not yet tried all options I programmed.