vmtools
NAME
vmps — report information on running virtual machines
SYNOPSIS
|
vmps |
[-hqrv] [-n | [-o cdehmnpqu] [-s CcDdEeHhMmNnPpQqUu]] [-a] |
|
vmps |
[-hqrv] [-n | [-o cdehmnpqu] [-s CcDdEeHhMmNnPpQqUu]] -p vmhome_dir … |
|
vmps |
[-hqrv] [-n | [-o cdehmnpqu] [-s CcDdEeHhMmNnPpQqUu]] -p pid … |
|
vmps |
[-hqrv] [-n | [-o cdehmnpqu] [-s CcDdEeHhMmNnPpQqUu]] -u user … |
DESCRIPTION
Report information on the currently running virtual machines.
The
-o and
-s flags allow to select the
vmps fields to respectively output and use as sort keys. See
vmps fields below for more information.
The expected arguments depend on the virtual machines selection method used. See
Virtual machines selection options for more information on the available methods.
vmps fields
The one-letter identifiers below can be used with the
-o and
-s flags to select vmps fields for output or as sort keys.
Their uppercase counterparts can be used with
-s to sort in descending order instead of the default ascending order. They cannot be used with
-o.
If no column has been explicitely selected for output, the default is
-o pnd.
If no column has been explicitely selected as sort key, the default is to not sort the output.
The
vmps field identifiers are as follows:
-
c
-
CPU activity (%): this value reflects ps(1) pcpu field which is loosely defined as follow in POSIX.1-2008:
The ratio of CPU time used recently to CPU time available in the same period, expressed as a percentage. The meaning of “recently” in this context is unspecified. The CPU time available is determined in an unspecified manner.
The goal of this indicator is therefore more to get a rough idea of the relative load caused by a virtual machines than to obtain any precise measure.
This value may be empty if the local ps(1) command does not support the pcpu field (this is notably the case on BusyBox-based environments).
-
d
-
Display: this value indicates the virtual machine display method and URL (if applicable). The content of this field may be one of the following:
-
disabled
-
Qemu display output has been disabled (the guest still has a graphical device enabled).
-
gtk
-
Qemu uses the GTK library.
-
none
-
No graphical device has been enabled for the guest.
-
sdl
-
Qemu uses the SDL library.
-
spice://address:port
-
A SPICE server is listening on the TCP address and port.
-
vnc://address:port
-
A VNC server is listening on the TCP address and port.
If a VNC client expects a VNC display ID instead of a TCP port number, substract 5900 from the TCP port number to obtain it (the port 5900 is equivalent to the VNC display ID 0, the port 5901 to VNC display ID 1, etc.).
-
?
-
The display mode used has not been recognized.
-
e
-
Command-line: display the complete Qemu command-line executed to start the virtual machine.
-
h
-
Virtual machine’s home directory if it has one, otherwise this field is empty.
-
m
-
Virtual memory allocated (KB): this value reflects ps(1) vsz field.
-
n
-
Virtual machine’s name if it has one, otherwise this field is empty.
-
p
-
PID of the Qemu hypervisor process running the virtual machine.
-
q
-
Qemu monitor socket: path to the socket file providing access to the Qemu monitor shell, or empty if the virtual machine doesn’t have a Qemu monitor socket file.
-
u
-
User owner of the Qemu hypervisor process running the virtual machine.
OPTIONS
Virtual machines selection options
Each of these flags is exclusive. By default
-u $LOGNAME is assumed.
These flags do not directly take an argument, but instead affect the arguments expected by
vmps.
The virtual machines selection options are as follows:
-
-a
-
Select the virtual machines from all users.
This flag does not expect any argument to be provided to vmps.
-
-d
-
Select the virtual machines by home directory.
When this flag is used, vmps expects at least one virtual machine home directory to be provided as command-line argument.
-
-p
-
Select by PID.
When this flag is used, vmps expects at least one PID to be provided as command-line argument.
-
-u
-
Select by user.
When this flag is used, vmps expects at least one username or UID to be provided as command-line argument.
Other options
The other options are as follows:
-
-h
-
Show usage information summary then exit.
-
-n
-
Do not write anything on standard output, only use the exit code to determine whether at least one running virtual machine matched the provided criterion.
This option is not compatible with -o and -s.
-
-o vmps_fields
-
Select the columns to display.
vmps_fields is a combination of vmps field identifiers. The identifiers order dictates the columns order in the output. See vmps fields above for the list and description of the available identifiers.
This flag can be specified only once.
It is not compatible with -n.
-
-q
-
Decrease verbosity. Add several -q options to decrease verbosity even more (-qq by default to get minimal output). See vmtools.conf(5) for more information about verbosity levels.
See -v to increase the verbosity level.
-
-r
-
Raw list, do not display the column headers.
-
-s vmps_fields
-
Select the sort keys.
vmps_fields is a combination of vmps field identifiers. The identifiers order dictates the keys precedency. There is no requirement to select for output the fields selected here. See vmps fields above for the list and description of the available identifiers.
This flag can be specified only once.
It is not compatible with -n.
-
-v
-
Increase verbosity. Add several -v options to increase verbosity even more (-vvv by default to get the most verbose output, including debugging messages). See vmtools.conf(5) for more information about verbosity levels.
See -q to decrease the verbosity level.
ENVIRONMENT
-
TMPDIR
-
Default location to store temporary files, by default /tmp.
-
XDG_CONFIG_HOME
-
Location of user’s configuration files, by default ~/.config.
FILES
-
/proc
-
When available, the proc(5) pseudo-filesystem is used to fetch the Qemu processes command-line.
-
/usr/local/lib/vmtools
-
Libraries shared by the vmtools project utilities.
-
/usr/local/share/vmtools/vmtools.conf
-
Virtual machine default settings, see vmtools.conf(5).
Moreover, the content of
/usr/local/share/vmtools can be overridden in the following locations (in the order of precedence):
-
~/.config/vmtools
-
User overrides (if cfg_include_userhome is set to “yes”).
-
/etc/vmtools
-
System-wide overrides.
EXIT STATUS
-
0
-
Success: at least one of the selected virtual machines is running.
-
1
-
An internal error occured.
-
2
-
Wrong usage.
-
3
-
None of the selected virtual machines is running, no result to display.
EXAMPLES
-
Example 1:
-
List all users’ running virtual machines, adding the username to the default output fields:
vmps -o upnd -a
-
Example 2:
-
An equivalent of top(1) to monitor the global virtual machines activity:
watch vmps -o pumcn -s CM -a
-
Example 3:
-
Obtain the home directory of a virtual machine from its PID:
ps -r -o h -p 1234
-
Example 4:
-
Script snippet checking that every required virtual machine is indeed running:
if vmps -nd ./vm1 && vmps -nd ./vm2 && vmps -nd ./vm3
then
# All virtual machines are running.
...
else
# At least one of them is not running.
...
fi
CAVEATS
Providing the same virtual machine several times in the selection arguments makes this virtual machine appear as many times in the output.
