In this article:
NAMEvmtools.conf — vmtools configuration files
DESCRIPTIONvmtools(7) commands obtain their configuration data from the following sources in the following order:
- Default settings (/usr/local/share/vmtools.conf).
- System-wide settings (/etc/vmtools/vmtools.conf).
- User settings (~/.config/vmtools/vmtools.conf, see FILES below for more information).
- Virtual machine settings, if applicable (including potential templates and parent files).
- Command-line options (in particular t the -o setting=value option).
Two classes of characters are distinguished:
- Safe strings are composed of alphanumeric characters and the underscore character (_).
Extended strings do not need to be quoted (though it is allowed) when they only contain characters from the following classes:
- Safe characters.
- The dash (-), dot (.) and forward slash (/) characters.
- Empty lines and lines starting with a ‘#’ are comments.
The general syntax for assigning a value to a setting is:
vmtools(7) general settings.
Virtual machine definition settings.
In addition to settings assignment, templates and virtual machine settings files can also invoke templates using the following syntax:
template template_name ...
Child virtual machines invoke their parent’s settings using the following syntax:
VMTOOLS GENERAL SETTINGSvmtools general settings describe vmtools behavior and are shared between all virtual machines. They are all using the prefix cfg_. They cannot be set in virtual machines and templates settings files.
If yes, allow files in the user’s configuration directory to override default and system-wide settings and modules. Otherwise user’s configuration files are silently ignored.
Prefix to build the Qemu command-line.
File storing the path to every child forked from the current virtual machine.
File (acutally a symbolic link) used to lock access to a virtual machine, preventing concurrent access issues.
File storig the PID of the Qemu hypervisor process running the current virtual machine.
Socket file providing access to the Qemu monitor shell.
Pattern for the name of the directory used to store temporary backup files.
File storing the virtual machine settings.
Maximum nesting level for templates and child virtual machines nesting. This value is used to detect infinite loops.
Time (in seconds) after which vmtools(7) commands will give up after unsuccessful attempts to acquire a lock.
ModulesThese settings are space-separated lists of names of vmtools modules to be called in certain circumstances. The modules are invoked in their order of appearance in these lists.
Modules handling the copy and fork of virtual machines.
Modules building the Qemu command-line to execute to boot the guest.
Configuration modules used to select a template.
Configuration modules used to define the various vitual machine settings.
If yes, do not ask any question to the user, assume a positive answer (y) for user confirmation requests and automatically accept the default value for multiple choices questions.
Makes vmtools(7) commands to produce more or less output on stderr.
- Minimal output (error messages, listening port, etc.).
- Output informational messages like the name of a correctly started or created virtual machines.
- Adds progress information on slow tasks (image file creation, lock, etc.), progress information may include control character not suitable for log files.
- Provide feedback on each main intermediary step (modules loaded, modified virtual machine, etc.).
- Provide deeper information (locks and file management, settings dump, etc.).
- Print each executed shell command.
VIRTUAL MACHINES SETTINGSThese settings describe the devices and environment available to the virtual machine guest system.
Path to the virtual machine home directory.
The virtual machine name appears in various locations, like the title bar of some display interface and as output of some commands to help the user to identify a virtual machine.
A combination of letters defining Qemu devices boot order.
- a, b
- The first and second floppy disk device.
- The first hard disk device.
- The first CD-ROM device.
- Etherboot from the network adapters 1-3.
If yes, enable the boot media selection menu.
Number of virtual CPUs available for the guest.
Type of virtual CPUs available for the guest.
Select the display device to emulate to the guest.
- For legacy systems.
- For 2000-era systems (Windows XP and higher).
- Unix: natively supported by any modern XFree86/Xorg, Windows: requires appropriate drivers to be installed in the guest.
- Automativally selected when vm_display_type is set to spice.
- For Sun machines.
- For legacy Sun machines.
- No display device is available for the guest. vm_display_type is ignored.
Listening interface when a remote display type is used.
Listening TCP port when a remote display type is used. If the port is not free, the virtual machine will fail to start.
First port to try when vm_display_port is empty. If the port is not free, the next port will be tried until a free port is found.
Select display output to use.
- The Qemu hypervisor acts as a VNC server. This is the historical and most widely supported headless output mode as it has no requirement guest-side.
- Automatically sets vm_display_device to qxl. More efficient than VNC, this requires the guest to have a driver for the QXL paravirtualized graphic card device. This is natively supported with any recent X.org, on Windows a freely available driver needs to be installed.
- The Qemu hypervisor will not produce any display output (and will, therefore, not open any TCP port). The guest however will see have the display device selected using the vm_display_device setting enabled.
- This is the most basic windowed display mode. Some Linux distributions which enable only headless modes (like Alpine Linux) do not support this mode, appart than that it is quite widely supported.
- This windowed display mode has more features. Due to the amount of library dependencies, some Linux distributions (like Debian) choose not to enable it.
Select a keyboard mapping.
MacOSSpecific settings for running Apple MacOS guests.
This key stored in Apple’s hardware SMC (System Management Center) chip is used to decrypt some MacOS system files, ensuring the system can be run only on genuine Apple hardware. Qemu does not implement (yet) any passthrough so you must fetch the key from your own hardware before trying to start an OSX guest in Qemu.
NetworkingNetworking setting are divided in two groups:
- The default settings whose values are used to override unset interface settings.
The interface settings, their name contain the ifacen string where n is a counter (the first interface will have its settings variable labelled iface1, the second one iface 2, etc.).
Default network virtual device type. This setting replaces empty vm_networking_ifacen_device settings.
Default MAC address. If empty, a random MAC address will be used. A partial address is taken as a MAC prefix, and dynamically completed using a random value.
Default operating mode. This setting replaces empty vm_networking_ifacen_mode settings.
Use the default user mode network stack which requires no administrator privilege to run.
This example extends from the previous case by changing a few defaults:
- The host system will not forward by default anymore packets coming fom the guests to the external network. This has the consequence of isolating the guest from any external network.
The guest will be connected to the virtual network VLAN 2 instead of the default VLAN 0. It will be able to communicate only with guests also connected to VLAN 2, and will be unable to communicate with hosts connected to other VLAN.
The Qemu hypervisor process will listen on port 12345 on the host interface 127.0.0.1, and forward all incoming connections to the guest on port 22. This particular settings allows to connect to the guest from the host using SSH.
Use the default network helper (usually /usr/lib/qemu/qemu-bridge-helper) to automatically create and delete a TAP network interface when the virtual machine starts and stop, providing a direct access to the external network to the guest.
A bridge interface must be created on the system.
The helper is not executable by default, must be explicitely enabled and be able gain sufficient privileges to create the TAP network interface.
chown root:kvm \ /usr/lib/qemu/qemu-bridge-helper chgrp 750 /usr/lib/qemu/qemu-bridge-helper setcap cap_net_admin=ep \ /usr/lib/qemu/qemu-bridge-helper
The helper must be explicitely authorized to use the bridge interface created earlier.
echo "allow br0" >/etc/qemu/bridge.conf
- A bridge interface must be created on the system.
Device type of the virtual network interface n.
If set to yes, enable the virtual network interface n. Otherwise, all other settings related to this interface are ignored.
MAC address of the virtual network interface n.
Operating mode for the virtual network interface n.
Name of the architecture emulated by Qemu.
If yes, compress copied and converted images.
Let the Qemu hypervisor process run in the background.
Space-separated list of supplementary parameters to pass to the Qemu command-line.
The maximum amount of time (in seconds) to wait when shutting down a virtual machine.
Amount of RAM allocated to the guest.
- A value too low for the guest may turn an healthy guest into a senile slug, making the guest slow, irresponsive and affected by a wide range of issues indirectly caused by the lack of usable RAM, including but not limited to guest boot failures.
- A value to high for the host will basically have the same consequences, this time not because of the lack of usable RAM for the guest but because of the inability for the host to properly execute the Qemu hypervisor process.
StorageThere are three access modes to a storage backend:
The storage is seen as writable by the guest, and guest’s write operations are applied to the storage backend.
Also known as non-persistant mode, the storage is seen as writable by the guest but guest’s write operations are not applied to the storage backend. Instead, they are stored in a temporary area and are deleted when the virtual machine exits. This allows to rollback to the same initial state upon each start of the virtual machine.
chmod a-w image_file
The storage is seen as read-only by the guest, all write attempt result in a failure.
The storage backend default mode.
The access mode provided as prefix in the storage path.
The highest access mode allowed by the vm_storage_rwmode setting.
An optional prefix explicitely stating the access mode to use:
- Read-write mode.
- Snapshot mode.
- Read-only mode.
A storage backend location:
First virtual CD-ROM reader device backend.
- A path to an ISO file.
A path to a local directory.
- A path to one of host’s physical CD/DVD reader device file (like /dev/cdrom).
A URL to a remotely hosted ISO file.
- Open it Qemu monitor shell using the vmmon(1) command.
Type the following command to list available virtual block devices:
(qemu) info block
If there is already a disk present in the CD-ROM reader device, eject it using the following command:
(qemu) eject device_identifier
Now mount the new disk backend:
(qemu) change device_identifier file_path
If set to yes, the first virtual CD-ROM device is enabled.
Second CD-ROM device backend.
If set to yes, the second virtual CD-ROM device is enabled.
First hard disk device backend.
A path to a hard disk image file.
A path to a directory.
- The content of a directory shared this way must not be changed by the host while the guest is running.
- The total size of this directory is limited to 504MB.
- While natively supported by Qemu, this is not a widely used feature which is not even mentionned in the qemu-system(1) man page, so you may want to avoid it for sensitive tasks (you may either mount the directory as a CD-ROM reader, use SMB sharing or, for Unix and Unix-like guest use the VirtFS paravirtualized filesystem).
- A path to a local device file (like /dev/sda). Qemu handles it like a RAW storage file.
- A URL to a remotely hosted image file or a network storage. Qemu natively supports FTP(S), HTTP(S), iSCSI, NBD, SSH and TFTP. Such files are loaded in snapshot mode by default, except iSCSI and NBD URLs which are accessed in read-write mode by default. See qemu-system(1) to get more information regarding the URL syntax.
- A path to a hard disk image file.
Size of a new empty image to create for the first virtual hard disk.
If set to yes, the first virtual hard disk device is enabled.
Second hard disk device backend.
Size of a new empty image to create for the second virtual hard disk.
If set to yes, the second virtual hard disk device is enabled.
Maximum access mode allowed for storage backends:
There is no restriction: backends supporting it are accessed in read-write mode.
- Storage backend which would otherwise be accessed in read-write are accessed in snapshot mode instead. Storage accessed in snapshot mode or in read-write mode are not affected.
- Read-only access is enforced to all storage backends.
- Default location to store temporary files, by default /tmp.
- Location of user’s configuration files, by default ~/.config.
- Libraries shared by the vmtools project utilities.
- Modules handling the virtual machine copying process.
- Virtual machine default settings, see vmtools.conf(5).
- User overrides (if cfg_include_userhome is set to “yes”).
- System-wide overrides.