qemu picture

vmcp(1) man page


vmcp, vmforkcopy or fork virtual machines


vmcp [-hkqRrsvyz] [-M module_name] [-m module_name] [-o setting=value] [-a [-n] | -c | -f] source … directory

vmcp [-hkqRrsvyz] [-M module_name] [-m module_name] [-o setting=value] [-a [-n] | -c | -f] source destination

vmfork [-hkqRrsvyz] [-M module_name] [-m module_name] [-o setting=value] [-a [-n] | -c | -f] source destination …


Create a copy of an currently existing virtual machine.
Several copy modes are supported, in each mode each copied virtual machine has a similar content than source:
Default copy:
The resulting virtual machines shares the same parent as its source. This is the default operation mode for vmcp.
The resulting virtual machine is a child of source. This is the default operation mode for vmfork.
Autonomous copy:
The resulting virtual machined does not depend on any parent VM.
The only differences between source and the resulting virtual machines are handled by the customizables clone modules. By default they only affect, if applicable, the virtual machine MAC address and its storage path. For more information on customizable modules, see vmtools(7).
source must be a valid virtual machine home directory (unless -r has been provided) and the virtual machine must not be currently running.
If only one source and one destination are provided, the resulting virtual machine home directory will be destination if it does not already exists, or a subdirectory of it if destination is an already existing directory.
If more than two paths are provided:
  • vmcp expects the latest path to be a writable directory, a copy of each source virtual machines will be created below directory.
  • vmfork expects the first path to be the source vitual machine, all subsequent paths are handled as destination paths to create as many copies of the source virtual machine.


Copy mode selection options

Each of these flags is valid for both vmcp and vmfork, which means that it is possible to create a fork using vmcp by using the -f flag and create default copies using vmfork by using the -c flag. This allows to take advantage of the different behavior of these commands in presence of multiple source or destination arguments.
The copy mode selection options are as follows:
Autonomous copy.
The resulting virtual machine will not rely on any parent.
Default copy.
The resulting virtual machine will rely on the same parent as the source one. If the source virtual machine has no parent, using either -a or -c produces the same result.
The resulting virtual machine will use the source one as parent.

Other options

The other options are as follows:
Show usage information summary then exit.
Keep parent’s unique properties.
The clone modules are still called to do the required processing to ensure the source virtual machine integrity (like handling storage image files), however the resulting virtual machines will share the same unique properties (like the MAC address) than the source.
-M module_name
Do not invoke the clone module module_name.
This is equivalent than removing module_name from the cfg_modules_clone setting (see vmtools.conf(5)).
module_name may not exist and may not be present in cfg_modules_clone.
-m module_name
Invoke the clone module module_name.
This is equivalent than adding module_name to the cfg_modules_clone setting (see vmtools.conf(5)).
module_name must exist, it may be already present in cfg_modules_clone in which case the module will be invoked only once.
Do not modify the source virtual machine during an autonomous copy.
Using this setting is generally not recommended unless the parent virtual machine is located on some read-only storage where any lock attempt would fail.
This setting can be used only in conjunction with -a (autonomous copy).
-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.
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.
Recurse over child virtual machines: each child of source is recursively copied as a new child of the destination virtual machine.
Each of these new child virtual machines is created as a subdirectory of its parent, independantly of the location of it matching source.
See also -r for directory-based recursion, both recursion modes can be associated.
Recurse over directory content: each subdirectory of source containing a virtual machine home directory is copied below destination (including source itself if it is a virtual machine home), keeping relative paths intact.
When this option is used, source only requires to be directory, it does not need to be virtual machine home.
See also -R for child-based recursion. Both recursion modes can be associated, in such a case directory-based recursion takes precedence to preserve the directory tree layout even if this means that a child may not be a direct subdirectory of its parent.
Enable Qemu snapshot (non-persistent) mode for the resulting virtual machines.
The created virtual machines are volatile and do not store any change to their storage backends. Restarting such a virtual machine effectively rolls it back to a state similar to the source virtual machine. This is useful to span virtual machines for quick tests purpose from a clean master virtual machine.
When using this option, when possible vmcp and vmfork do not create any disk image at all for the resulting virtual machines but instead make them directly access the source virtual machine storage in snapshot mode.
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)).
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.
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!
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.
Before creating a compressed copy, ensure from wihtin the guest that the storage is correctly trimmed (on Linux systems, see fstrim(8)) as this shrinks the storage files to their minimum size.


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).
Moreover, the content of /usr/local/share/vmtools can be overridden in the following locations (in the order of precedence):
User overrides (if cfg_include_userhome is set to “yes”).
System-wide overrides.


The operation ended successfully.
An error occurred, incomplete tasks have been reverted.
Wrong usage, nothing has been done.



Example 1:
Fork a virtual machine:
vmfork ./fooOS-base ./fooOS-20170515
Example 2:
Create a snapshot fork of a virtual machine:
vmfork -s ./foo ./foo-tests
Example 3:
Create several forks of one virtual machine (compare it to the vmcp example 2, the relationship here is one-to-many):
vmfork ./foo ./fork1 ./fork2 ./fork3


Example 1:
Copy several virtual machines to a directory:
vmcp ./foo ./bar ~/archives
Example 2:
Create a fork of all virtual machines located directly below a directory (compare it to the vmfork example 3, the relationship here is many-to-one):
vmcp -f ~/archived_vms/* ~/work
Example 4:
Recursively copy all the virtual machines stored in a directory:
vmcp -r ~/Documents/VMs ~/backup


Please send bug reports to the vmtools issues page.

Popular tags see all