qemu picture

vmup(1) man page

NAME

vmup, vmcreatestart 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.

REPORTING BUGS

Please send bug reports to the vmtools issues page.

Popular tags see all

Website

Author

Follow