'Qemu' tag logo

vmtools guided tour, part 1: introduction and basic usage

This the first of a short series of posts introducing vmtools main features. We will start in a gentle way by focusing on a single but central command: vmup.

Feel free to contact me if anything seems unclear or would warrant more explanation.

vmtools installation and uninstallation

Use the provided install.sh script to install vmtools on your system. The default is to install it system-wide:

sudo sh ./install.sh

To install it as unprivileged user, create a ~/.local directory and use it as installation prefix:

sh ./install.sh -p ~/.local

To uninstall vmtools, use the provided uninstall.sh script.

Centralized configuration file

System-wide settings are stored in the file /etc/vmtools/vmtools.conf, this file is optional and must be manually created.

This file lets you centrally configure the default settings to apply to all your virtual machines.

Here is an example file:

# Use VNC as the default display output:

# Set the default keyboard mapping to use:

See vmtools.conf(5) for more information.

Use vmup to boot a disk image

Simply pass a file of a URL as argument to vmup to boot it.

Here we are booting from a remote .iso file:

user@host:~$ vmup "http://tinycorelinux.net/7.x/x86/release/TinyCore-current.iso"
Answer to the questions below to define the guest properties.
You can type '?' to display the help screen at any time.

Number of vCPUs (default: 2)?

RAM size (default: 2G)?
TinyCore-current.iso: Virtual machine started.


Various protocols are supported, and data is downloaded on-the-fly.

HTTP servers must support the Range header, this depends on their configuration nevertheless Qemu raises an explicit error message when they don’t.

The configuration questions are handled by the enabled plugins. The virtual machine creation and startup process can be completely revamped by defining your own plugins.

Third-party and legacy image formats are also supported (including .ova images1 not natively supported by Qemu). vmtools proposes to automatically convert such images:

user@host:~$ vmup turnkey-lamp-14.2-jessie-amd64.ova
Answer to the questions below to define the guest properties.
You can type '?' to display the help screen at any time.

Number of vCPUs (default: 2)?

RAM size (default: 2G)?

Auto-conversion: /home/user/turnkey-lamp-14.2-jessie-amd64.ova
This file seems to be either a third-party or a legacy file, it is recommended to
convert it for regular usage.
Create a Qcow2 copy of this file [yN]? y
turnkey-lamp-14.2-jessie-amd64.ova: Virtual machine started.


Except for .ova images which are not supported natively by Qemu, the conversion is not required however in most cases unconverted third-party images will be accessed read-only (snapshot mode).

Main vmup options

-y: bypass interactive questions

Most vmtools commands propose a -y (think “yes”) flag to silently bypass all interactive questions:

user@host:~$ vmup -y tails-amd64-3.1.iso
tails-amd64-3.1.iso: Virtual machine started.


Use this option with care as vmtools will no longer ask confirmation before deleting or overwriting files!


You can set vmup -y -- as a handler for .iso files in your desktop environment, this allows you to start a virtual machine by simply clicking on any .iso file.

-c, -d: Add virtual disk devices

Use the option:

  • -c path to add a supplementary virtual hard-disk drive to the guest.
  • -d path to add a supplementary CD/DVD ROM drive.

Think of Windows’ traditional C: and D: drives3 to remember the option letters.

These options can take either a path to an image file or to a directory as parameter, the latter case is a convenient way to pass files from the host system to the guest (and is pretty unique to vmtools AFAIK):

user@host:~$ vmup -d ./WSUS_Offline/ ./Windows-7-pro_amd64.qcow2
Answer to the questions below to define the guest properties.
You can type '?' to display the help screen at any time.

Number of vCPUs (default: 2)?

RAM size (default: 2G)?
Windows-7-pro_amd64.qcow2: Virtual machine started.

The command above starts the Windows-7-pro_amd64.qcow2 hard-disk image while making the content of the WSUS_Offline directory (most probably a set of offline Windows updates) available to the guest as a virtual CD/DVD ROM reader.


There are some limitations when passing directories to the guest system:

  • -d requires the genisoimage command to be available on the host to generate an .iso file on-the-fly.

  • -c relies on Qemu native Virtual VFAT (VVFAT), an arguably obscure and little known Qemu feature2. It doesn’t require any external utility and allows to share a directory in read-write mode (prefix the directory path with rw: to enable this), however it comes with some potentially serious limitations. Due to its low use, the code of this feature may be fragile, moreover the host must not change the directory content while guest is running and the directory size is limited to 504 MB.

In sensitive environments, -d is the recommended choice. These limitations apply only when passing directories as argument to these options, they do not apply in otherwise.

-s: Enable snapshot (non-persistent) mode

-s allows to start a virtual machine in snapshot (non-persistent) mode:

user@host:~$ vmup -s -c ./hdd.raw ./kali-linux-2016.1-amd64.iso
Answer to the questions below to define the guest properties.
You can type '?' to display the help screen at any time.

Number of vCPUs (default: 2)?

RAM size (default: 2G)?
kali-linux-2016.1-amd64.iso: Virtual machine started.

In the example above, the following parameters have been used:

  • -s: Access all hard-disk image files in snapshot mode, disk image files will not be modified4.

    A similar result can be obtained by prefixing hard-disk image paths with the snap: prefix or by removing the write permission (chmod a-w ./hdd.raw) on the image files.

  • -c hdd.raw: Add a supplementary hard-disk image to the virtual machine.

  • ./kali-linux-2016.1-amd64.iso: The local .iso image to boot, as seen in the previous examples.

Here the user boots Kali Linux with a read-only raw hard-disk disk image, possibly to do some forensic analysis on a disk dump.


You should now be able to use vmup to boot disk image files more conveniently.

This post covered only the most common options and use-cases. The complete list of vmup options is available through vmup -h and on vmup(1) man page.

While this is a useful feature in itself, and might even be enough for some users, vmtools is able to do far more but this will be discussed in the second part of this guided tour.

  1. Currently only .ova images with a single virtual hard-disk are supported. Such images are handled as standalone virtual disk images, meaning that the specific virtual machines settings from the .ova archive are currently ignored by vmtools

  2. VVFAT is not documented in Qemu man pages, the only available documentation is available on Qemu online documentation and its source code (the initial announce may also be of interest). 

  3. Sorry for this incursion of Windows in a Unix world, but these letters were the only ones I found to be both easy to remember while not interfering with other current or upcoming options. 

  4. When doing forensic analysis or other sensitive operations, do not ignore due care and always work on copies, never work directly on the original file! 

Popular tags see all