Version: Next

vlist - manpage

NAME

vlist - show information about running netkit virtual machines

SYNOPSIS

vlist [options] [MACHINE-ID...]

DESCRIPTION

The vlist command shows several information about currently running virtual machines. If no arguments are provided, it shows a list of virtual machines that have been started by the current user. The list entries have the following format: USER, VHOST, PID, SIZE, INTERFACES, where:

USER

is the name of the user who started the virtual machine (virtual machine owner).

VHOST

is the name of the virtual machine.

PID

is the PID of the virtual machine.

SIZE

is the actual amount of memory consumed by the virtual machine, in KB.

INTERFACES

is a (possibly empty) list of the network interfaces of the virtual machine, together with the virtual collision domains (hubs) they are attached to.

At the bottom of the list the following summary information are shown:

โ€“

the number of running virtual machines belonging to the current user and to all users;

โ€“

the amount of memory consumed by running virtual machines owned by the current user and by all users.

The vlist command can also be used to get detailed information about specific virtual machines. In this case the virtual machines list is not shown. You can select virtual machines for which you want to get such information by providing one or more MACHINE-IDs on the command line. A MACHINE-ID can be either the name or the PID of a virtual machine. Detailed information consist of the following data:

Accounting information

PID

virtual machine PID.

Owner

name of the user who started the virtual machine.

Used mem

amount of memory consumed by the virtual machine.

Emulation parameters

Kernel

name of the UML kernel used by the virtual machine.

Memory

amount of available memory inside the virtual machine.

Model fs

name of the model (backing) filesystem used by the virtual machine.

Filesystem

name of the (COW) filesystem used by the virtual machine.

Interfaces

list of network interfaces of the virtual machine, and the collision domains they are attached to.

Hostfs at

directory of the host filesystem that is made available inside the virtual machine under '/hosthome'.

Boot cmd

name of a command (or a script) that has been executed by the virtual machine during the boot phase.

Hostlab at

directory of the host filesystem that is made available in the virtual machine under '/hostlab'. This directory stores information about the configuration of a laboratory.

Host WD at

directory of the host filesystem that is made available in the virtual machine under '/hostwd'. This directory stores some temporary files for a laboratory.

Console 1, Console 2

devices to which the primary and secondary consoles of the virtual machine are attached.

Other args

additional parameters or arguments that have been appended to the virtual machine kernel command line.

Mconsole

name of the temporary socket file that will be used to send directives to the virtual machine (e.g., to halt the virtual machine).

Depending on the configuration of the virtual machine, some of the above entries may not be shown. For example, for a virtual machine without network interfaces, the Interfaces entry is not shown.

OPTIONS

The following options can be used to influence the output of vlist.

-n
--no-header

Suppress both header line and summary information in the list of virtual machines. This option has no effect if you requested detailed information about specific virtual machines.

-u USERNAME
--user=USERNAME

Only show virtual machines owned by USERNAME. The special user name '-' is reserved and can be used to show virtual machines owned by all users.
By default, only virtual machines started by the current user (i.e., the one who launched the vlist command) are shown.

This option also limits virtual machines for which detailed information can be requested. By providing a USERNAME, you can only ask information about virtual machines owned by USERNAME.

Consider that different users may start virtual machines having the same name. Hence, special care must be taken when USERNAME is '-' and you are requesting detailed information about a virtual machine by providing its name. In this case, information about only one virtual machine are reported, even if several virtual machines with the same name exist. In particular, vlist considers the first machine with a matching name in the list returned by 'vlist --user=-'.

The following generic options are also supported.

-h
--help

Show usage information.

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

Apart from this, vlist supports no other environment variables.

EXAMPLES

The following is an example of the output of vlist when launched with no arguments.

USER             VHOST               PID       SIZE  INTERFACES
foo              pc1                 300      12684
foo              pc2                1126      69720  eth0 @ A, eth1 @ B

Total virtual machines:       2    (you),        2    (all users).
Total consumed memory:    82404 KB (you),    82404 KB (all users).

The following example shows detailed information about a specific virtual machine, which you can get by typing 'vlist pc1'.

============= Information for virtual machine "pc1" =============
 --- Accounting information ---
   PID:        300
   Owner:      foo
   Used mem:   12684 KB
 --- Emulation parameters ---
   Kernel:     /home/foo/netkit/kernel/netkit-kernel
   Modules:    /home/foo/netkit/kernel/modules
   Memory:     8 MB
   Model fs:   /home/foo/netkit/fs/netkit-fs
   Filesystem: /home/foo/pc1.disk
   Hostfs at:  /home/foo
   Console 1:  terminal emulator
   Console 2:  disabled
   Other args: umid=pc1 root=98:1 uml_dir=/home/foo/.netkit/mconsole quiet
   Mconsole:   /home/foo/.netkit/mconsole/pc1/mconsole

SEE ALSO

vclean(1), vconf(1), vcrash(1), vhalt(1), vstart(1).

AUTHOR

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