vmtools
NAME
vmup, vmcreate — start or create a Qemu virtual machine
SYNOPSIS
|
vmup |
[-bhinqvyz] [-C storage] [-c storage] [-D storage] [-d storage] [-o setting=value] [-r | -s] [-t template_name] [path …] |
|
vmcreate |
[-bhinqvyz] [-C storage] [-c storage] [-D storage] [-d storage] [-o setting=value] [-r | -s] [-t template_name] [vmhome …] |
DESCRIPTION
vmup
Boot each
path as a Qemu virtual machine.
path may be a path to a virtual machine home directory created using
vmcreate or a storage path (see
Storage path below).
If no
path is given,
vmup assumes that the current working directory is a virtual machine home directory created using
vmcreate.
vmcreate
Create a new virtual machine in the directory
vmhome.
If the directory does not already exists, it will be created. If it already exists, it must not already contain a virtual machine. If no path is given, the current working directory is assumed.
Storage path
The
storage value may be one of the following:
-
A path to a media image file natively supported by Qemu.
This includes CD and DVD ISO images, raw and QCow2 hard-disk images.
-
A path to a third-party or legacy hard-disk image file.
vmcreate and vmup propose to automatically convert such files into a QCow2 file, otherwise such files are loaded in snapshot mode by default. Conversion of .ova files is also supported (Qemu doesn’t support them natively).
-
A path to a local device file.
-
A URL to a remote file or network storage.
The protocols supported by Qemu are 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 directory.
vmup and vmcreate dynamically generates a device allowing to share the directory content with the guest. Limitations and requirements vary depending on the selected device type:
-
With hard-disk devices, Qemu virtual VFAT (VVFAT) feature is used. The total directory size cannot exceed 504 MB and the host must not modify the shared directory content while the guest is running. The shared directory is accessed in read-only mode by default, but read-write mode is also supported.
This feature is not documented in the Qemu man page but is natively supported.
-
With CD-ROM devices, genisoimage(1) is used to automatically generate an ISO image storing the directory content. If this command is not available on the host this feature is not available.
Additionally, the storage path can be prefixed to explicitly set its access mode:
-
rw:
-
Read-write mode.
-
snap:
-
Snapshot / non-persistent mode.
-
ro:
-
Read-only mode.
The colon is part of the prefix (see
EXAMPLES below). Depending on the device settings and storage path used, not all modes are always available. When incompatible settings are used, starting the virtual machine fails with an (hopefully explicit) error message.
See also the Storage section in
vmtools.conf(5) for more details.
OPTIONS
The options are as follows:
-
-b
-
Display the boot media selection menu. The exact behavior depends on the BIOS used by Qemu.
-
-C storage
-
Like -c but also set the boot order to boot from a hard-disk.
Warning: Using this option only enforces booting from a hard-disk drive as opposed to another media type. It cannot ensure that the system will effectively boot from storage if it is not the guest’s first or only hard-disk device.
-
-c storage
-
Associate the guest’s first free hard-disk drive to an image file. storage may point to a regular file, a block device, a directory or be a URL (see Storage path above).
If storage points to a directory, it will be used to setup a virtual VFAT (VVFAT) share with the guest. The total size of such share cannot exceed 504 MB. Attention: it is important that the host does not attempt to modify the content of this directory as long as the guest is running.
-
-D storage
-
Like -d but also set the boot order to boot from a CD-ROM.
Warning: Using this option only enforces booting from a CD-ROM drive as opposed to another media type. It cannot ensure that the system will boot from storage if it is not the guest’s first or only CD-ROM device.
-
-d storage
-
Associate the guest’s first free CD-ROM drive to an image file (see Storage path above). storage may points to a regular file, a block device, a directory or be a URL.
If storage points to a directory, then genisoimage(1) must be available on the host and will be used to generate an ISO image on-the-fly.
-
-h
-
Show usage information summary then exit.
-
-i
-
Interactive mode: do not daemonize, when the virtual machine has been started provide a Qemu monitor shell instead of exiting.
When using this flag with vmcreate, a final confirmation is requested after shutting down the virtual machine allowing to quickly restart a guest installation in case of wrong manipulation.
-
-n
-
Do not start the virtual machine, all the other processing is done normally. This allows to create a new virtual machine or convert some files without booting them.
-
-o setting=value
-
Affect value to setting, overriding any previous value set in vmtools(7) configuration or virtual machine settings. Available settings are listed in the vmtools.conf(5) file.
When used with vmcreate, settings set using this option will also be stored in the newly created virtual machine settings file.
-
-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
-
Do not modify storage backend files: enforce access to be read-only (write attempts from the guest will fail). Depending on the device settings, Qemu may refuse to start when read-only mode is enforced.
-
-s
-
Do not modify storage backend files: use Qemu snapshot (non-persistent) mode (the storage is seen as read-write by the guest, but modifications are stored in a temporary file which is dropped once the virtual machine is stopped).
This parameter has no effect on read-only storage.
Warning: when manipulating sensitive data, ensure to always work on a copy instead of the original file and/or unset the write bit on the backing file (see chmod(1)). Files with the write bit unset seem to be automatically loaded in snapshot mode by Qemu.
-
-t template
-
Apply a template, template must be a valid template name: the name of a .inc.sh file from the templates directory without its extension (see FILES below).
When used with vmcreate, template selected using this flag will also be added to the newly created virtual machine settings file.
-
-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.
-
-y
-
Don’t ask any question: accept all confirmation requests and automatically select the default answer in any other situation.
Use this option with great care: no confirmation will be asked before deleting or overwriting any files!
-
-z
-
Compress copied or converted disk image files. This only affects QCow2 hard-disk images being copied or converted, data written by a running guest is never compressed.
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/modules/buildcmd
-
Modules used to build the Qemu command-line.
-
/usr/local/share/vmtools/modules/configure
-
Modules used to select the virtual machine templates and define its settings.
-
/usr/local/share/vmtools/templates
-
Virtual machines templates.
-
/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
-
The operation ended successfully.
-
1
-
An error occurred, incomplete tasks have been reverted.
-
2
-
Wrong usage, nothing has been done.
EXAMPLES
vmup
-
Example 1:
-
Boot from a local ISO file:
vmup ./foo.iso
-
Example 2:
-
Boot from a local hard-disk disk image, but in snapshot mode:
vmup snap:./foo.vmdk
-
Example 3:
-
Boot from a remote URL:
vmup 'http://example.com/path/to/file.iso'
-
Example 4:
-
Boot using SPICE display instead of the default one:
vmup -o vm_display_type=spice ./foo.iso
-
Example 5:
-
Boot a virtual machine created using vmcreate:
vmup ~/path/to/my_vm
-
Example 6:
-
Boot the current virtual machine created using vmcreate:
cd ~/path/to/my_vm
vmup
-
Example 7:
-
Boot a virtual machine created using vmcreate, but start from a live CD instead of the main guest’s disk:
vmup -D ~/path/to/livecd.iso ~/path/to/my_vm
-
Example 8:
-
Convert a third-party image file into a QCow2 file without booting it:
vmup -yn ./foo.ova
vmcreate
-
Example 1:
-
Use an installation CD-ROM to create a new virtual machine:
vmcreate -d ~/path/to/install.iso ~/path/to/my_new_vm
-
Example 2:
-
Use an installation CD-ROM to create a new virtual machine, and propose to quickly restart the installation if needed:
vmcreate -i -d ~/path/to/install.iso ~/path/to/my_new_vm
-
Example 3:
-
Use an already existing hard-disk image file to create a new virtual machine:
vmcreate -c ~/path/to/disk.ova ~/path/to/my_new_vm
-
Example 4:
-
Use an already existing hard-disk image file to create three new virtual machines using the settings given as parameters (-o options) and without requiring any interaction (-y flag):
vmcreate -o cpu_count=2 -o vm_ram_size=2G -y \
-c ~/path/to/disk.ova ./vm_1 ./vm_2 ./vm_3
CAVEATS
-
Qemu VVFAT is not mentioned in Qemu man page, its implementation may potentially be fragile.
-
There is a slight delay in searching free TCP ports and opening them which can lead to a race condition, specially when several virtual machines are started in parallel, making some of them to fail to start.
The recommended way to start several virtual machines at once is to pass them as parameter to a single vmup command. This will also avoid any similar limitations affecting Qemu itself.
