umlwatch

umlwatch − User interface for the UMLMON monitor

umlwatch [OPTIONS] vmname[@host]

This command allows the user to send commands to the UMLMON monitor daemon, and to retrieve status information from it. Effectively, umlwatch is a user frontend for the RPC interface controlling the daemon.

If no options are given, umlwatch enters an interactive mode where users can enter commands. These commands are the same that can be specified as options on the command line without the preceding hyphen, e.g. one can type info to get the same status page that is also printed when the −info option is given.

When options are given, these are interpreted as commands that are executed one after the other.

One can contact locally running monitors as well as monitors running on remote hosts when these hosts enable the TCP sockets. Use the "@" syntax to contact remote hosts.

Local connections are authorized by the file permissions of the corresponding Unix Domain socket. Either one is allowed to contact the daemon or not.

TCP connections are authenticated. In this case, umlwatch asks for a password. If the user knows the password, he is also considered as authorized.

A few words about the disk interface. The current version of the daemon enforces some restrictions where disk files can be accessed and how they must be named. Note that these restrictions are implemented by the daemon and not by umlwatch.

The disk files are looked up relative to the root of the chroot jail. The user only sees the file system relative to this root. There are only two directories where disks can be stored:

/disks:

This directory is intended for disks owned by the VM (i.e. these disks can only be accessed by the current VM, and are out of reach by other VMs). One can create, delete, and manipulate disk files using the RPC interface only when they are in this directory. Files are usually owned by the user that runs the VM.

/shared/disks:

This directory is intended for disks shared by the VMs. All VMs can access the same files under this path name. Although it is possible to use these files for ubd devices directly when the file permissions permit it, one cannot create, delete, or modify them using the RPC interface. The host administrator should prepare these files, and should give them appropriate file permissions.

The types of the disk files are distinguished by the file name suffix. The extension .dsk means that the file is a flat image, i.e. an array of blocks. The extension .cow means that the file is a copy−on−write image. These images implicitly refer to a so−called backing file whose absolute name is stored in the header of the copy−on−write image. The extension .dev is used for block devices. Following the above philosophy, .dev files should only be created in /shared/disks. (Actually, one can set the device parameters of the global section of the /etc/umlmon configuration file to let the umlmon daemon create the block devices.)

Note that it might be difficult to import an existing copy−on−write image into UMLMON, because the absolute name of the backing file usually changes. However, once this problem is solved UMLMON’s naming scheme is quite useful, for example, it is no problem to copy a pair of backing file and copy−on−write image from one host to another, even if the directory location changes, because only the chroot−relative name counts, and this name does not change.

−info:

Outputs the status page. This includes the current configuration and the current run−time state. If the VM is running, the configuration is always the effective one that is actually used.

−tail file[,n]:

Outputs the tail of a log file. Use the name "monitor" to see the log file of the umlmon daemon. Use the name of a virtual console or serial line to see the logged output for the channel, e.g. "con0" to see the output of the UML kernel.

−connect (conn|ssln):

Interactively connects with the virtual console or virtual serial line. You can disconnect with the special key CTRL−].

−force−connect (conn|ssln):

Same as −connect, but it is possible to take over the session of another user.

−start:

Starts the UML kernel with default arguments.

−start−with arg:

Starts the UML kernel, and passes arg as additional argument. This can be, for example, a runlevel specification, e.g. single to eneter single user mode.

−suspend:

Suspends the UML kernel.

−continue:

Resume a suspended UML kernel.

−halt:

Immediately halts the UML kernel. This should only be used as last resort to stop the kernel running.

−ctrlaltdel:

Sends a CTRL−ALT−DEL event to the UML kernel. This is the recommended way to shut down the virtual system.

−kill:

Immediately kills the UML kernel. This should only be used as last resort to stop the kernel running.

−sysrq letter:

Sends a system request to the UML kernel. The letter indicates the request. Use −sysrq h to see a list in the kernel log file (view with −tail con0).

−rotate:

Reopens all log files. This is necessary after log file rotation.

−wait n:

Waits until the UML kernel is halted, or until n seconds are over, what ever comes first.

−port:

Outputs the TCP port number where the monitor can be contacted.

−set param=value:

Sets or adds a configuration parameter (user change). This is only possible for certain parameters, see umlmon(5) for a list. The change is in effect the next time the UML kernel is started.

−del param:

Deletes a configuration parameter (user change). This is only possible for certain parameters, see umlmon(5) for a list. The change is in effect the next time the UML kernel is started.

−disk−create name:size[:sparse]:

Creates a new virtual disk. The name must be given relative to the jail root. Actually, only names of the form /disks/base.dsk are accepted. The size is the size in megabytes. The sparse keyword arranges that the file is created sparsely, otherwise the blocks of the file are immediately allocated.

−disk−create−cow name:bfile:

Creates a new copy−on−write disk for a given backing file. Both name and bfile must be given relative to the jail root. Actually, only names of the form /disks/base.cow are accepted, and the backing file must be either /disks/base.dsk or /shared/disks/base.dsk. The copy−on−write disk has always the same size as the backing file, and it is always sparse.

−disk−delete name:

Deletes an existing disk. The name must be given relative to the jail root.

−disk−copy src:dest:

Copies a disk. The names given in src and dest must be given relative to the jail root. It is only possible to copy a .dsk file to a .dsk file, and a .cow file to a .cow file. The destination file must be in /disks.

−disk−resize name:size[:sparse]:

Resizes an existing disk of type .dsk. The name must be given relative to the jail root. In size pass the new size in megabytes. If the sparse keyword is given and the disk size grows, the new blocks are sparse, and not immediately allocated. This command changes only the file, but not the file system that might be stored in the file. When the disk grows, the file system must be resized after this command is executed. When the disk shrinks, the file system must already be resized before this command is executed.

−change−password:

Interactively change the password of the VM.

−site arg:

Executes the site script with arg as argument.

−version:

Outpus the version number and exits.

/var/lib/umlmon/vmname/ctrl:

This is the Unix Domain socket connecting to the RPC interface of the daemon for the VM 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.

umlmon(5), umlmon(7), umlmon(8), umldir(8), umladmin(8)