DESCRIPTION
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.
-
Fork:
-
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.
OPTIONS
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:
-
-a
-
Autonomous copy.
The resulting virtual machine will not rely on any parent.
-
-c
-
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.
-
-f
-
Fork.
The resulting virtual machine will use the source one as parent.
Other options
The other options are as follows:
-
-h
-
Show usage information summary then exit.
-
-k
-
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.
-
-n
-
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.
-
-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
-
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.
-
-r
-
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.
-
-s
-
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)).
-
-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.
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.
