qemu picture

vmtools(7) man page

In this article:

NAME

vmtools — a virtual machines manager based on Qemu

DESCRIPTION

vmtools is a virtual machines manager which strives to be easy, versatile and modular to empower the user as much as possible while adhering to the principle of least privileges.
Easy
Every bootable thing should be throwable as-is to the vmup(1) command to be immediately started in a hassle-free fashion, from local standalone disk images files to remote URLs passing through .ova archives to device files.
More permanent virtual machines are represented by directories (created using vmcreate(1)) which can be stored anywhere to match user’s own taste and can be manipulated using the provided vmmv(1), vmcp(1) and vmrm(1) commands to safely move, copy or delete them.
The virtual machine settings are stored in a small human-readable text file allowing to get and update the virtual machine settings at a glance with the most basic text editor.
Versatile
vmtools commands do as few assumptions as possible on the way the user will use them, while providing as many options as possible to customize the command behavior.
All commands support the -h flag to access the help summary, while the man pages provide a more in-depth explanation. Most man pages also contain practical examples illustrating the usage of the most common options combinations.
The virtual machines themselves are not standalone entities, but can inherit settings from templates and parent virtual machines from which they have been forked (see INHERITANCE below).
Modular
Not only vmtools is entirely developped in shell script language making it easy to inspect and modify it, but it is also explicitely modular.
The process of creating, starting or cloning a virtual machine is indeed completely open for the user to complete or redefine as needed.
vmtools modules categories are as follow:
configure
These modules are invoked during the virtual machine creation process. It contains two modules sub-categories: templates which allows to select the templates to apply to the virtual machine, settings which allows to define the virtual machine actual settings. The modules either interactively prompt the user for some input or automatically determine a value (for instance depending on some properties of the image file to boot).
buildcmd
These modules rely the virtual machine settings to build the Qemu command-line which will be used to start the guest system.
clone
These modules control the cloning process which occurs when copying or forking a virtual machine.
See CUSTOMIZATION below for more information on disabling, overriding or adding new modules.
Principle of least privilege
As opposed to some other virtual machines management tools, vmtools does not require root privileges, it not require any privileged service to run and in fact do not require any background service at all.
The beauty of Qemu and KVM is to allow unprivileged users to fully manage virtual machines. Having to use a management software requiring root privileges for its own business somewhat breaks this concept, sometimes with no real advantage for the end-user.
vmtools acts as wrapper around Qemu commands to fully take advantage of Qemu and KVM least privilege design. It does not attempt to reinvent the wheel: all access permissions are handled by the underlying filesystem permissions.
The consequence of this is that there is no standardized central virtual machines repository. Instead, each user is the owner of its own virtual machines which are fundamentally just directories containing a setting file. The user is free to handle and organize them at will, optionally share them in either read-only or read-write mode, as he would do with any other file.

INHERITANCE

vmtools implements an inheritance system making a typical virtual settings file rather small as it should contain only the few variables customized for the current virtual machine.
Details on the file structure and on the available settings is available in vmtools.conf(5) man page.

Parent and child (forked) virtual machines

Virtual machines can be copied and forked using the vmcp(1) and vmfork(1) commands.
Forking a virtual machine, copying the forks, re-forking them allows to create a virtual machines tree where a leaf virtual machine inherits all its settings from its ancestors (settings from the farthest ancestor being overwritten by the settings of the closest one).
It is possible to apply a change to a whole virtual machine tree at once by simply editing a parent virtual machine as long as the childs do not redefine the value. Changing the amount of allocated RAM for a whole group of virtual machine can therefore be as simple as changing one single value in one single file.
While the leaf virtual machines can be started without restriction, forked virtual machines (those with at least one child) can only be started in snapshot or read-only mode. It is indeed forbidden to alter their storage backend file as this would break their child’s storage. If you need to apply some changes to a virtual machine with a child, just fork it.
The vminfo(1) command proposes the -t flag to visually inspect a virtual machine tree. A virtual machine can have only a single parent but may have several childs. The vmmerge(1) command allows to merge a previously forked virtual machine.

Templates

Templates implements settings inheritance for virtual machines which are not forked from each other.
The virtual machines inherits their settings from one or several templates (the templates can in turn reference one or several other templates), and may either directly use them as new defaults or overwrite inheritted values as they would do with settings inherited from a parent virtual machine.
There is two main uses of virtual machines templates:
Technical
A legacy PC will not use the same settings as a modern PC, and neither of them will use the same settings as a MacOS machine, however each of them shares common base settings with every other members of the same category.
The templates allows to implement those technical categories, providing new defaults for each classes.
Logical
As stated above, virtual machine parent inheritance allows may allow to change a setting for a whole tree by editing only one value in one file. Logical templates allows to link templates which would however not be related to they can share some settings.
For instance all virtual machines belonging to a given project or department can be logically linked by referring to the same template specific to this project or department. Some virtual machine settings (like the amount of RAM, the number of vitual CPUs, the display server port range, network settings like the VLAN number, etc.) can then be centralized in this template file.

CUSTOMIZATION

The vmtools.conf file and the content of the modules directory can be overriden at the system and optionally at the user level.

Customizing default settings

To override some default settings system-wide, set them in the /etc/vmtools/vmtools.conf file. Optionally, if cfg_include_userhome is set to “yes” (either in /etc/vmtools/vmtools.conf or by using a command-line argument such as -o), default settings can also be overriden at the user level in the ~/.config/vmtools/vmtools.conf (see FILES below for more information on how to select another location).
Settings are overriden on a per-setting basis, so there is no requirement to copy all default settings in the customized vmtools.conf, this file should contain only the customized values.
New setting names can be added to the customized vmtools.conf file. These new settings may be used for instance by custom modules and can be of any type. Settings names must contain only alphanumeric and underscore characters and begin with either the cfg_ or vm_ prefix (see for more information on settings names).
To avoid any side-effect when upgrading to newer version of vmtools, prefer to name the new settings with names beginning with either cfg_custom_ or vm_custom_ (for instance vm_custom_group would be a perfect custom setting name) as these names will never be used by vmtools.
When assigning a new default to a setting, also consider using a template (see Inheritance: templates above) to assign the new default value only to a group of selected virtual machines.

Customizing modules

To override a module system-wide, create a modules directory with a similar tree than the default /usr/local/share/vmtools/modules and store the customized version of the module there. Optionally, if cfg_include_userhome is set to “yes” (either in /etc/vmtools/vmtools.conf or by using a command-line argument such as -o), default modules can also be overriden at the user level in the ~/.config/vmtools/modules (see FILES below for more information on how to select another location).
Modules are overriden on a per-file basis: if a customized module file bears the same name as a default one, only the customized file will be used and the default one will be ignored (see FILES below for more information on location precedence).
New modules can be added in custom modules directory trees. The name of these new modules must be added to the appropriate cfg_modules_* variable to be taken into account. Module name must contain only alphanumeric characters and underscores.
To avoid any side-effect when upgrading to newer version of vmtools, prefer to name new modules with names beginning with c_ (for instance c_dev would be a perfect custom module name) as such name will never be used by vmtools.
See the various README files in the modules subdirectories for more advices and examples to build or customize a vmtools module.

COMMANDS

vmtools commands are as follows:
vmcp(1)
Copy or fork virtual machines.
vmcreate(1)
Create a new virtual machine.
vmdown(1)
Shutdown a virtual machine.
vmfix(1)
Detect and fix virtual machines issues.
vmfork(1)
Copy or fork virtual machines.
vminfo(1)
Report information on a virtual machine.
vmmerge(1)
Merge two related virtual machines.
vmmon(1)
Access the Qemu monitor shell of a virtual machine.
vmmv(1)
Move or rename a virtual machine home directory.
vmps(1)
Report information on running virtual machines.
vmrm(1)
Delete a virtual machine home directory.
vmrndmac(1)
Generate a random MAC address.
vmup(1)
Start virtual machine or a bootable file or media.

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/bin
Executable files.
/usr/local/lib/vmtools
Libraries shared by the vmtools project utilities.
/usr/local/share/man
Project man pages.
/usr/local/share/vmtools/modules
Default modules location.
/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.

SEE ALSO

vmcp(1), vmcreate(1), vmdown(1), vmfix(1), vmfork(1), vminfo(1), vmmerge(1), vmmon(1), vmmv(1), vmps(1), vmrm(1), vmrndmac(1), vmup(1), vmtools.conf(5),

REPORTING BUGS

Please send bug reports to the vmtools issues page.

Popular tags see all

Website

Author

Follow