vmtools
NAME
vmdown — shutdown a Qemu virtual machine
SYNOPSIS
|
vmdown |
[-kstw] [vmhome_path …] |
DESCRIPTION
Shutdown selected virtual machines using the selected method.
See
OPTIONS below for more details on the virtual machines and shutdown methods selection.
OPTIONS
Virtual machines selection options
The virtual machines selection options are as follows:
-
-a
-
Shutdown all running virtual machines.
-
-p pid …
-
Shutdown the virtual machine running with the PID pid.
The default is to shutdown the virtual machine designated by the home directory
vmhome_path. If no home directory is provided, the current working directory is used.
Shutdown methods selection options
The shutdown methods selection options are as follows:
-
-k
-
Kill the virtual machine process (send a SIGKILL to the Qemu process).
This is the most brutal way to shutdown a virtual machine. The host operating system immediatly terminates the Qemu hypervisor process. It should only be used against stuck Qemu hypervisor processes.
-
-s
-
Send an ACPI shutdown request to the virtual machine guest.
This is cleanest way to shutdown a virtual machine as it allows the guest operating system and the application it runs to gracefully close themselves. However, the guest operating system must be able to handle ACPI events for this method to have any effect. In particular, this won’t work against legacy or stuck guest operating systems.
-
-t
-
Terminate the virtual machine process (send a SIGTERM to the Qemu process).
The Qemu hypervisor process immediatly terminates the guest operating system, but will still ensure that from the hypervisor side all pending data gets correclly flushed and all opened resources gets closed correctly.
This shutdown method however leaves no way for the guest’s operating system and application to save their data, it should be used only against either legacy and stucked guests which do not respond to ACPI shutdown requests, or against stateless guests (vitual machines in read-only or snapshot mode).
The default is to try every shutdown method (equivalent to
-kst).
When several methods are selected,
-w is assumed and the methods are always processed in the following order, independantly of the flags order in the command-line:
-
If -s is enabled, send an ACPI shutdown request to the guests of all selected processes.
-
If -t is enabled, send a SIGTERM signal to the selected processes still running.
-
If -k is enabled, send a SIGKILL signal to the selected processes still running.
Other options
The other options are as follows:
-
-h
-
Show usage information summary then exit.
-
-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.
-
-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.
-
-w
-
Wait for the virtual machine to terminate before proceeding. The wait ends when all selected virtual machines have stopped or after the vm_qemu_shutdown_timeout timer expired (20 seconds by default, see vmtools.conf(5)), whichever happens first.
This flag is automatically enabled when several shutdown methods are selected. In this case vmdown waits between each selected shutdown method and after the last one.
ENVIRONMENT
-
TMPDIR
-
Default location to store temporary files, by default /tmp.
-
XDG_CONFIG_HOME
-
Location of user’s configuration files, by default ~/.config.
FILES
-
/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: all selected virtual machines have been shut down.
-
1
-
An error occurred, more information is available on the error output.
-
2
-
Wrong usage, nothing has been done.
-
3
-
Partial success: some virtual machines may have been shutdown.
EXAMPLES
-
Example 1:
-
Shutdown the current virtual machine:
cd ~/my-vm
vmdown
-
Example 2:
-
Shutdown all running virtual machines (particularly useful in a system shutdown script):
vmdown -a
-
Example 3:
-
Quickly stop the virtual machine bearing a certain PID:
vmdown -tk -p 1234
CAVEATS
The
ACPI-based guest shutdown requires
socat(1) to be available on the host system and the virtual machine to have a monitor file (the virtual machine typically needs a home directory for this). This functionality will not work and will raise an appropriate warning message if these prerequisites are not fulfilled (witout impact on any other shutdown method selected).
This limitation is not very damaging as it mostly affects
HDD-less guests started from live-CDs, which usually do not mind being brutally shut down anyway.
This limitation is caused by Qemu. A feature request has been opened
upstream.
