more documentation
This commit is contained in:
parent
7e033f0089
commit
0bfe4fe8a7
|
@ -0,0 +1,541 @@
|
||||||
|
NAME
|
||||||
|
====
|
||||||
|
|
||||||
|
qq2clone - Create and manage QEMU/KVM VMs using template machines and
|
||||||
|
qcow2 images with backing files
|
||||||
|
|
||||||
|
SYNOPSIS
|
||||||
|
========
|
||||||
|
|
||||||
|
**qq2clone** \[*OPTION*\]… *COMMAND* \[*ARG*\]…
|
||||||
|
|
||||||
|
DESCRIPTION
|
||||||
|
===========
|
||||||
|
|
||||||
|
**qq2clone** is a tool working on top of virsh that makes creating
|
||||||
|
clones of template QEMU/KVM machines simple. By using the copy on write
|
||||||
|
feature for which qcow2 is named, clones of an existing virtual machine
|
||||||
|
can be made without inadvertently altering the original image (with
|
||||||
|
caveats - read the **LIMITATIONS** section if you aren’t already
|
||||||
|
familiar with how copy on write works). **qq2clone** makes creating and
|
||||||
|
managing these clones simple and efficient.
|
||||||
|
|
||||||
|
**qq2clone** supports creating numerous clones of a template and
|
||||||
|
performing batch operations on them - including the execution of
|
||||||
|
arbitrary commands with exec. This simplifies workflows involving large
|
||||||
|
numbers of virtual machines, or the frequent creation/destruction of
|
||||||
|
virtual machines.
|
||||||
|
|
||||||
|
In addition to virsh, basic linux utilities and QEMU/KVM, qq2clone
|
||||||
|
requires:
|
||||||
|
|
||||||
|
Bash 4.0+
|
||||||
|
qemu-img
|
||||||
|
libvirt tools:
|
||||||
|
virt-clone
|
||||||
|
virt-xml
|
||||||
|
virt-xml-validate
|
||||||
|
xmllint (from libxml2)
|
||||||
|
|
||||||
|
If you want to easily establish graphical connections to your virtual
|
||||||
|
machines, you should have virt-viewer and/or spicy installed and
|
||||||
|
configure your templates to use Spice graphics. This is not strictly
|
||||||
|
necessary, and with the use of **qq2clone** **exec** and a small script
|
||||||
|
of your own you can automate connecting to Spice/VNC clients of your
|
||||||
|
choice without too much hassle
|
||||||
|
|
||||||
|
OPTIONS
|
||||||
|
=======
|
||||||
|
|
||||||
|
Not every option has an effect in the context of every command.
|
||||||
|
Specifying an option that has no effect in the context of the command
|
||||||
|
being invoked will not produce an error, it simply will not do anything
|
||||||
|
|
||||||
|
Options are parsed left to right, and right-hand options override
|
||||||
|
left-hand options. The only exception is for -Q/--quieter, which *must*
|
||||||
|
be the first option listed to work properly.
|
||||||
|
|
||||||
|
-c, --connection \[*URI*\]
|
||||||
|
Specify a non-default connection URI: sets the value of
|
||||||
|
LIBVIRT\_DEFAULT\_URI
|
||||||
|
|
||||||
|
-f, --no-spice
|
||||||
|
Do not attempt to connect to a virtual machine’s Spice graphics.
|
||||||
|
Overrides USE\_SPICE setting in configuration
|
||||||
|
|
||||||
|
-g, --use-spice
|
||||||
|
Attempt to connect to a virtual machine’s spice graphics. Overrides
|
||||||
|
SPICE setting in configuration
|
||||||
|
|
||||||
|
-h, --help
|
||||||
|
Print basic help information and exit
|
||||||
|
|
||||||
|
-n, --no-run
|
||||||
|
After making a clone of a template, do not run it. Overrides NORUN
|
||||||
|
setting in configuration
|
||||||
|
|
||||||
|
-q, --quiet
|
||||||
|
Suppress most non-error output. Overrides QUIET setting in
|
||||||
|
configuration. Also suppresses various prompts for user choices, either
|
||||||
|
exiting with an error or making a safe default choice depending on the
|
||||||
|
command. Recommended only once familiar with the behavior of
|
||||||
|
**qq2clone**
|
||||||
|
|
||||||
|
-Q, --quieter
|
||||||
|
This option is (currently) required to appear immediately following the
|
||||||
|
invocation of **qq2clone**. Suppresses all output, error message or
|
||||||
|
otherwise, except when running interactive commands or commands that
|
||||||
|
require output to be useful. The commands for which output is not
|
||||||
|
entirely supressed are: config list, config info, list, list-templates,
|
||||||
|
exec, edit, modify-template edit, and check. Other commands will receive
|
||||||
|
only an exit code as output. This option is intended for calling
|
||||||
|
qq2clone from a script.
|
||||||
|
|
||||||
|
-r, --run
|
||||||
|
Run a clone when creating it. Overrides NORUN setting in configuration
|
||||||
|
|
||||||
|
-s, --storage \[*LOCATION*\]
|
||||||
|
When creating a clone, place new disk image file(s) at location
|
||||||
|
specified by \[*LOCATION*\]. \[*LOCATION*\] may be one of an absolute
|
||||||
|
filepath, or the name of a libvirt directory type storage pool. Also
|
||||||
|
defines where state files will be saved when using **save** command.
|
||||||
|
Overrides STORAGE option in configuration
|
||||||
|
|
||||||
|
-S, --spicy
|
||||||
|
Use spicy rather than virt-viewer when connecting to the spice graphics
|
||||||
|
of a clone. Overrides SPICY setting in configuration
|
||||||
|
|
||||||
|
-t, --template \[*NAME*\]
|
||||||
|
Use template of given name as context when executing a clone command
|
||||||
|
(see TYPES OF COMMAND section above). Overrides TEMPLATE option in
|
||||||
|
configuration
|
||||||
|
|
||||||
|
-v, --verbose
|
||||||
|
Enable all output. Overrides QUIET setting in configuration
|
||||||
|
|
||||||
|
-V, --virt-viewer
|
||||||
|
Use virt-viewer rather than spicy when connecting to the spice graphics
|
||||||
|
of a clone. Overrides SPICY setting in configuration
|
||||||
|
|
||||||
|
TYPES OF COMMAND
|
||||||
|
================
|
||||||
|
|
||||||
|
There are two main classes of commands: commands that operate directly
|
||||||
|
on templates, and commands that create or operate on clones of
|
||||||
|
templates. In order to make it less likely that the user may
|
||||||
|
unintentionally invoke a command of one class when they intended to
|
||||||
|
invoke one of the other, they use a different syntax. Commands that
|
||||||
|
operate on templates use the syntax:
|
||||||
|
|
||||||
|
**qq2clone** **command** \[*template-name*\] \[*ARG*\] …
|
||||||
|
|
||||||
|
while commands that operate on clones use the syntax:
|
||||||
|
|
||||||
|
**qq2clone** --template \[*template-name*\] **command** \[*ARG*\] …
|
||||||
|
|
||||||
|
Notice that commands operating on clones work within the context of a
|
||||||
|
template defined by the option --template/-t. Conversely, commands
|
||||||
|
operating on templates specify the template as an argument to the
|
||||||
|
command. There can also be a default template defined by the TEMPLATE
|
||||||
|
option in the configuration file, allowing the --template option to be
|
||||||
|
omitted for commands that operate on clones. Commands operating on
|
||||||
|
templates do not respect this default - the template must always be
|
||||||
|
explicitly defined, further reducing the likelihood of accidentally
|
||||||
|
modifying or deleting a template.
|
||||||
|
|
||||||
|
TEMPLATE COMMMANDS
|
||||||
|
==================
|
||||||
|
|
||||||
|
**copy-template** \[*CURRENT-NAME*\] \[*NEW-NAME*\]
|
||||||
|
Copy the XML of template *CURRENT-NAME* to a new template with
|
||||||
|
*NEW-NAME*. The new template will not receive a copy of the old
|
||||||
|
template’s storage devices - it will point to the same locations
|
||||||
|
|
||||||
|
**delete-template** \[*NAME*\]
|
||||||
|
Delete the template *NAME*. This operation will succeed only if there
|
||||||
|
are currently no clones of the template
|
||||||
|
|
||||||
|
**import-template** \[*LIBVIRT-DOMAIN*\] \[*NAME*\], **import-template**
|
||||||
|
\[*XML-LOCATION*\] \[*NAME*\] : Import a new template from either an
|
||||||
|
existing libvirt domain, or a fully qualified filepath to a libvirt
|
||||||
|
domain XML file on disk. If argument *NAME* is ommited, qq2clone will
|
||||||
|
assume you want to use the machine’s name as described in the XML file
|
||||||
|
as the template name
|
||||||
|
|
||||||
|
**list-templates**
|
||||||
|
List the names of all existing templates
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **sub-command** \[*ARG*\] …
|
||||||
|
Templates can be modified in various ways by invoking
|
||||||
|
**modify-template**. Each subcommand is described below
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **commit-image**
|
||||||
|
After an image has been created and modified as desired using
|
||||||
|
**modify-template** \[*NAME*\] **prepare-image**, **commit-image** is
|
||||||
|
used to alter a template’s underlying storage device by commiting any
|
||||||
|
changes made using prepare-image. See the commit command described in
|
||||||
|
**man** **qemu-img** for more information on how this works
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **destroy-image**
|
||||||
|
Invoke virsh destroy on a running image created/run through
|
||||||
|
**modify-template** \[*NAME*\] **prepare-image**. This is generally not
|
||||||
|
wise, as it is equivalent to unplugging a physical machine and could
|
||||||
|
cause corruption to the image that will later be commited as a permanent
|
||||||
|
change to the template’s image
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **discard-image**
|
||||||
|
Delete an image produced by **modify-template** \[*NAME*\]
|
||||||
|
**prepare-image** without commiting any changes
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **edit**
|
||||||
|
Edit the XML document defining a template
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **rename** \[*NEW-NAME*\]
|
||||||
|
Change the name of a template, and all of its clones
|
||||||
|
|
||||||
|
**modify-template** \[*NAME*\] **prepare-image**
|
||||||
|
Create and/or run a clone that acts as a staging area for changes to the
|
||||||
|
`template's` actual image. For instance, you could update the
|
||||||
|
`template's` software by running **modify-template** \[*NAME*\]
|
||||||
|
**prepare-image**, updating the clone produced by this command, shutting
|
||||||
|
it down, and then running **modify-template** \[*NAME*\]
|
||||||
|
**commit-image**. This serves a twofold purpose - to prevent incidental
|
||||||
|
damage to an underlying image by providing a safe buffer to work in, and
|
||||||
|
to allow modifications to be safely prepared for an underlying image
|
||||||
|
even while that image has existing clones.
|
||||||
|
|
||||||
|
CLONE COMMANDS
|
||||||
|
==============
|
||||||
|
|
||||||
|
A description of the argument *SET* is described in the **SETS** section
|
||||||
|
below
|
||||||
|
|
||||||
|
**clone** \[*NUMBER*\]
|
||||||
|
Invoke without any argument to produce a single clone. Supply a number
|
||||||
|
as an argument to specify the number of clones to create
|
||||||
|
|
||||||
|
**connect** \[*SET*\]
|
||||||
|
Start any machine in *SET* that `isn't` already running. If any machine
|
||||||
|
in *SET* has spice graphics and spicy or virt-viewer is installed, use
|
||||||
|
one or the other (chosen by command-line option or configuration) to
|
||||||
|
connect to the graphical console
|
||||||
|
|
||||||
|
**destroy** \[*SET*\]
|
||||||
|
Invoke virsh destroy on any running machine in *SET* (in other words, if
|
||||||
|
the domain is running forcibly turn it off)
|
||||||
|
|
||||||
|
**edit** \[*NUMBER*\]
|
||||||
|
Edit the XML file of the clone with given number
|
||||||
|
|
||||||
|
**exec** \[*SET*\] \[*command-string*\]
|
||||||
|
For every machine in *SET*, sequentially, execute the contents of the
|
||||||
|
command string in an environment where the following variables are
|
||||||
|
defined per clone: `"$uuid"`, `"$name"`, `"$disks"` (a newline delimited
|
||||||
|
string containing the machine’s qcow2 disk device filepaths). This is
|
||||||
|
done using bash’s eval command, so be sure to put any instances of these
|
||||||
|
variables in single quotes (double quotes inside the single quotes is
|
||||||
|
best practice) or they will not be set properly. If any instance of exec
|
||||||
|
has a non-zero return value, execution stops.
|
||||||
|
|
||||||
|
**list** \[*ARG*\]
|
||||||
|
Without arguments, list all clones of the current template and their
|
||||||
|
state. With argument “all”, provide list including all clones of every
|
||||||
|
template. With argument “xml”, produce an XML document with information
|
||||||
|
about every template, their clones, and their state. The XML option is
|
||||||
|
not complete - its format is at this point defined only implicitly, by
|
||||||
|
the output of this command.
|
||||||
|
|
||||||
|
**resume** \[*SET*\]
|
||||||
|
Resume any suspended machines in *SET*
|
||||||
|
|
||||||
|
**rm** \[*SET*\]
|
||||||
|
Destroy every domain in *SET* (if running), undefine them and delete
|
||||||
|
their storage volumes
|
||||||
|
|
||||||
|
**rm-wipe** \[*SET*\]
|
||||||
|
Destroy every domain in *SET* (if running), undefine them and wipe their
|
||||||
|
storage volumes using virsh
|
||||||
|
|
||||||
|
**rm-shred** \[*SET*\]
|
||||||
|
Destroy every domain in *SET* (if running), undefine them and shred
|
||||||
|
their storage volumes
|
||||||
|
|
||||||
|
**save** \[*SET*\]
|
||||||
|
Save execution state of every running domain in *SET* to file
|
||||||
|
|
||||||
|
**save-rm** \[*SET*\]
|
||||||
|
Delete the state file associated with every machine in *SET*
|
||||||
|
|
||||||
|
**start** \[*SET*\]
|
||||||
|
Start every machine in *SET* that is currently not running. For saved
|
||||||
|
domains, their state will be restored
|
||||||
|
|
||||||
|
**suspend** \[*SET*\]
|
||||||
|
Suspend execution of every machine in *SET*
|
||||||
|
|
||||||
|
OTHER COMMANDS
|
||||||
|
==============
|
||||||
|
|
||||||
|
**check** \[*TEMPLATE-NAME*\]
|
||||||
|
As described in the limitations section, there are ways that qq2clone
|
||||||
|
can lose track of a clone. If this happens, it will remain in qq2clone’s
|
||||||
|
database, its ID number will remain reserved, and its image files may
|
||||||
|
not be deleted and take up space doing nothing. the **check** command
|
||||||
|
tries to find and fix this and other problems. The *TEMPLATE-NAME*
|
||||||
|
argument is optional, and restricts the check to that template and its
|
||||||
|
clones. Otherwise, all templates are checked
|
||||||
|
|
||||||
|
**config** list, **config** info \[*OPTION*\], **config** edit \[*OPTION*\]
|
||||||
|
List all configuration options and their current value, get info about a
|
||||||
|
particular option, or edit one
|
||||||
|
|
||||||
|
SETS
|
||||||
|
====
|
||||||
|
|
||||||
|
*SET* is listed as an argument to many commands. *SET* simply describes
|
||||||
|
a set of virtual machines - clones of a given template. *SET* is a comma
|
||||||
|
delimited list with no whitespace. *SET* can be an individual machine or
|
||||||
|
several individual machines designated by number:
|
||||||
|
|
||||||
|
1 (Machine 1)
|
||||||
|
3,7 (Machines 3 and 7)
|
||||||
|
|
||||||
|
Machine numbers can be shown with **qq2clone** **list**. Ranges and
|
||||||
|
omitted values are supported as well:
|
||||||
|
|
||||||
|
1,2-5,^3 (Machines 1 and 2-5 excluding 3)
|
||||||
|
1-10,^3-7 (Machines 1-10 excluding 3-7)
|
||||||
|
|
||||||
|
Lastly, groups of machines can be addressed by their state:
|
||||||
|
|
||||||
|
all (All machines)
|
||||||
|
all,^running (All machines that aren't running)
|
||||||
|
^running,1-10 (Machines 1-10 except those that are running)
|
||||||
|
|
||||||
|
The possible states of a virtual machine are based on the states listed
|
||||||
|
in **man virsh**, with some modifications. States in qq2clone are:
|
||||||
|
|
||||||
|
all
|
||||||
|
crashed
|
||||||
|
idle
|
||||||
|
in-shutdown
|
||||||
|
off
|
||||||
|
paused
|
||||||
|
pmsuspended
|
||||||
|
running
|
||||||
|
saved
|
||||||
|
|
||||||
|
Specifying machines that do not exist will not cause an error: i.e.,
|
||||||
|
1-10 is a valid set even if only machines 3-7 exist. A set will only
|
||||||
|
cause an error if it is malformed, includes zero existing machines,
|
||||||
|
contains no machines that the command being invoked may act upon, or
|
||||||
|
includes numbers less than 1.
|
||||||
|
|
||||||
|
CONFIG
|
||||||
|
======
|
||||||
|
|
||||||
|
There is no need to refer to the manual to understand configuration
|
||||||
|
options. Use “**qq2clone** config list” to see all options and their
|
||||||
|
current values, and “**qq2clone** config info \[*OPTION*\]” to get
|
||||||
|
information about a particular option. However, here is the same
|
||||||
|
information provided by **qq2clone** info for each option
|
||||||
|
|
||||||
|
TEMPLATE
|
||||||
|
|
||||||
|
> This template will be used for commands like clone, rm, destroy when
|
||||||
|
> option --template/-t is not specified
|
||||||
|
>
|
||||||
|
> Default value: Default value: `'0'`
|
||||||
|
|
||||||
|
TEMPLATE\_DIR
|
||||||
|
|
||||||
|
> This is the where template XML files will be kept
|
||||||
|
>
|
||||||
|
> Default value: `'${HOME}/storage-qq2clone/templates'`
|
||||||
|
|
||||||
|
QUIET
|
||||||
|
|
||||||
|
> If set to 1, most non-error output will be suppressed
|
||||||
|
>
|
||||||
|
> Default value: `'0'`
|
||||||
|
|
||||||
|
USE\_SPICE
|
||||||
|
|
||||||
|
> If set to 1, attempt to connect to the spice graphics of a virtual
|
||||||
|
> machine by default when cloning it, if it is configured to use spice
|
||||||
|
> graphics. qq2clone can do this using the programs spicy and
|
||||||
|
> virt-viewer. If either is installed on your system during the first
|
||||||
|
> run, the default value is `'1'` (enabled). Otherwise, the default
|
||||||
|
> value is `'0'`
|
||||||
|
|
||||||
|
S\_TIMEOUT
|
||||||
|
|
||||||
|
> Wait this many seconds before timing out when trying to connect to a
|
||||||
|
> virtual `machine's` spice graphics.
|
||||||
|
>
|
||||||
|
> Default value: `'10'`
|
||||||
|
|
||||||
|
STORAGE
|
||||||
|
|
||||||
|
> The default location to store clone images when creating them.
|
||||||
|
> Changing this location is fine, but it is a good idea to ensure that
|
||||||
|
> whatever location you do choose is only used by qq2clone
|
||||||
|
>
|
||||||
|
> Default value: `'${HOME}/storage-qq2clone/qq2clone-pool'`
|
||||||
|
|
||||||
|
EXAMPLES
|
||||||
|
========
|
||||||
|
|
||||||
|
**qq2clone** --template Debian --run --virt-viewer clone
|
||||||
|
Make a clone of Debian, run it, and connect to its spice graphics using
|
||||||
|
virt-viewer. All of these options could have instead been defined in the
|
||||||
|
configuration, so that the entire command would be: **qq2clone** clone
|
||||||
|
|
||||||
|
**qq2clone** --template Debian exec 3 ‘virsh console “$uuid”’
|
||||||
|
Use virsh to connect to the serial console of template Debian’s clone
|
||||||
|
with number 3 (as shown in **qq2clone** list)
|
||||||
|
|
||||||
|
**qq2clone** **modify-template** Debian *prepare-image*
|
||||||
|
Create a clone of Debian that can be used as a staging area for
|
||||||
|
permanent changes to the backing template storage device
|
||||||
|
|
||||||
|
**qq2clone** **modify-template** Debian **commit-image**
|
||||||
|
Commit changes to the image Debian staged with the previous command
|
||||||
|
|
||||||
|
**qq2clone** **copy-template** Debian Debian\_2
|
||||||
|
Copy the XML of template Debian, creating a new template with the same
|
||||||
|
backing storage device that you can edit as you please
|
||||||
|
|
||||||
|
LIMITATIONS
|
||||||
|
===========
|
||||||
|
|
||||||
|
The largest limitation of **qq2clone** is that it cannot protect your
|
||||||
|
template images from the actions of other software. If nothing else
|
||||||
|
touches a template’s storage volumes, qq2clone can safely handle them
|
||||||
|
(barring unknown bugs or bad luck during a commit-image). However, if
|
||||||
|
something else alters the image upon which a template is based, its
|
||||||
|
existing clones may be corrupted and future clones may behave
|
||||||
|
differently than expected. It is the user’s responsibility to understand
|
||||||
|
this aspect of copy on write and carefully manage template images.
|
||||||
|
Future updates to qq2clone may add features that give some additional
|
||||||
|
protections, but this risk is inherent to copy on write.
|
||||||
|
|
||||||
|
Libvirt has permissions errors when a storage pool is in a “hidden”
|
||||||
|
directory with a name beginning with “.” and qcow2 files with backing
|
||||||
|
files are involved. This may be due to apparmor, or it may be an issue
|
||||||
|
with libvirt. It is unknown how widespread this issue is, but it is the
|
||||||
|
reason that the default directory storage-qq2clone does not start with
|
||||||
|
‘.’
|
||||||
|
|
||||||
|
If the UUID of a clone is changed, qq2clone will no longer be able to
|
||||||
|
track it and will not be able to perform commands on it anymore. If
|
||||||
|
virsh undefine is run on a clone, qq2clone will not be able to see it
|
||||||
|
once it is turned off. This limitation will be eliminated or reduced in
|
||||||
|
the future, when qq2clone moves away from relying on virsh and
|
||||||
|
implements direct usage of the libvirt API. It could be addressed now by
|
||||||
|
using transient domains, but that would require qq2clone to do more
|
||||||
|
things manually instead of just invoking virsh. Since the plan is to
|
||||||
|
transition to a different approach later, that would be wasted effort.
|
||||||
|
For now, if you find yourself in this position just use **qq2clone**
|
||||||
|
check.
|
||||||
|
|
||||||
|
qq2clone can only produce clones by making qcow2 image files. The
|
||||||
|
backing file need not be qcow2, but the images produced by qq2clone
|
||||||
|
always will be. This is unlikely to ever change - levaraging the
|
||||||
|
features of qcow2 is the entire purpose of qq2clone. If it does change,
|
||||||
|
qq2clone will need a new name.
|
||||||
|
|
||||||
|
qq2clone does not support creating images in pool types other than
|
||||||
|
directories, and attempting to use a machine as a template when it has
|
||||||
|
storage volumes in a non-directory pool is likely to fail or have
|
||||||
|
unexpected results. Support for some other pool types may be added in
|
||||||
|
the future.
|
||||||
|
|
||||||
|
qq2clone currently cannot copy storage volumes when importing a template
|
||||||
|
(it just references the originals), or when copying a template. This
|
||||||
|
will change in the future, and qq2clone will also be able to handle more
|
||||||
|
complex relationships between templates, clones and their images
|
||||||
|
|
||||||
|
FILES
|
||||||
|
=====
|
||||||
|
|
||||||
|
~/.config/qq2clone
|
||||||
|
This document simply contains a string defining the location at which
|
||||||
|
qq2clone will store files, including the database containing the rest of
|
||||||
|
it configuration options. Currently, qq2clone cannot run without ${HOME}
|
||||||
|
being defined unless a few lines are altered to refer to a new location
|
||||||
|
|
||||||
|
~/storage-qq2clone
|
||||||
|
Directory where qq2clone stores all files and binary executables. Can be
|
||||||
|
changed by modifying ~/.config/qq2clone. This directory is not named
|
||||||
|
“qq2clone” because it can then slightly interfere with bash completion
|
||||||
|
when in the home directory, and it does not start with a ‘.’ for the
|
||||||
|
reasons described in the **LIMITATIONS** section above
|
||||||
|
|
||||||
|
~/storage-qq2clone/qq2clone.db
|
||||||
|
sqlite3 database containing the configuration information for qq2clone,
|
||||||
|
as well as data about templates and clones
|
||||||
|
|
||||||
|
~/storage-qq2clone/qq2clone-pool
|
||||||
|
Storage pool used for clone images and saved state files, if the
|
||||||
|
--storage option is not used when creating or saving a clone and the
|
||||||
|
option STORAGE is not changed in the configuration file
|
||||||
|
|
||||||
|
~/qq2clone/templates
|
||||||
|
Directory in which template XML files are stored. These can be edited
|
||||||
|
manually, but it is more advisable to use **qq2clone**
|
||||||
|
**modify-template** \[*template-name*\] edit
|
||||||
|
|
||||||
|
BUGS
|
||||||
|
====
|
||||||
|
|
||||||
|
As described in the options section, the implementation of the
|
||||||
|
--quieter/-Q option needs some work. Its current behavior is the easiest
|
||||||
|
functional approach without complicating the options parser, but it will
|
||||||
|
eventually be modified and become better behaved. In addition to the
|
||||||
|
previously described problem, very early error messages will not be
|
||||||
|
suppressed. Most likely, the solution is to implement a better options
|
||||||
|
parser and make it the first thing to run when executing qq2clone.
|
||||||
|
However, the impact of this bug is minimal and other improvements are
|
||||||
|
likely to come before this bug fix.
|
||||||
|
|
||||||
|
If you find any worse bugs, and I’m sure I missed some, please let me
|
||||||
|
know and I will fix them as time allows.
|
||||||
|
|
||||||
|
EXIT VALUES
|
||||||
|
===========
|
||||||
|
|
||||||
|
**10**
|
||||||
|
No permission to access file or file doesn’t exist
|
||||||
|
|
||||||
|
**11**
|
||||||
|
Required software dependencies are not met (see description for a list),
|
||||||
|
or are cannot be found in PATH
|
||||||
|
|
||||||
|
**12**
|
||||||
|
Invalid command line argument specified, or command specifies an invalid
|
||||||
|
action
|
||||||
|
|
||||||
|
**13**
|
||||||
|
Problem with a template - i.e., specified template does not exist, or
|
||||||
|
import-template failed because template of specified name already exists
|
||||||
|
|
||||||
|
**14**
|
||||||
|
Invocation of an external command failed
|
||||||
|
|
||||||
|
**15**
|
||||||
|
Problem with a libvirt XML file
|
||||||
|
|
||||||
|
**16**
|
||||||
|
Attempted action with a libvirt tool resulted in failure
|
||||||
|
|
||||||
|
**17**
|
||||||
|
Could not establish graphical spice connection to machine before timeout
|
||||||
|
expired
|
||||||
|
|
||||||
|
**18**
|
||||||
|
A file is of the wrong type or does not exist
|
||||||
|
|
||||||
|
**19**
|
||||||
|
Unexpected error - a bug in qq2clone, or a highly unexpected failure of
|
||||||
|
some command
|
|
@ -0,0 +1,3 @@
|
||||||
|
#!/bin/bash
|
||||||
|
pandoc -s -f markdown -t markdown_strict -o man.md man.pandoc
|
||||||
|
pandoc -s -f markdown -t man -o qq2clone.1 man.pandoc
|
|
@ -0,0 +1,601 @@
|
||||||
|
.\" Automatically generated by Pandoc 2.5
|
||||||
|
.\"
|
||||||
|
.TH "QQ2CLONE" "1" "February 2021" "qq2clone 0.1" ""
|
||||||
|
.hy
|
||||||
|
.SH NAME
|
||||||
|
.PP
|
||||||
|
qq2clone \- Create and manage QEMU/KVM VMs using template machines and
|
||||||
|
qcow2 images with backing files
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.PP
|
||||||
|
\f[B]qq2clone\f[R] [\f[I]OPTION\f[R]]\&... \f[I]COMMAND\f[R]
|
||||||
|
[\f[I]ARG\f[R]]\&...
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.PP
|
||||||
|
\f[B]qq2clone\f[R] is a tool working on top of virsh that makes creating
|
||||||
|
clones of template QEMU/KVM machines simple.
|
||||||
|
By using the copy on write feature for which qcow2 is named, clones of
|
||||||
|
an existing virtual machine can be made without inadvertently altering
|
||||||
|
the original image (with caveats \- read the \f[B]LIMITATIONS\f[R]
|
||||||
|
section if you aren\[cq]t already familiar with how copy on write
|
||||||
|
works).
|
||||||
|
\f[B]qq2clone\f[R] makes creating and managing these clones simple and
|
||||||
|
efficient.
|
||||||
|
.PP
|
||||||
|
\f[B]qq2clone\f[R] supports creating numerous clones of a template and
|
||||||
|
performing batch operations on them \- including the execution of
|
||||||
|
arbitrary commands with exec.
|
||||||
|
This simplifies workflows involving large numbers of virtual machines,
|
||||||
|
or the frequent creation/destruction of virtual machines.
|
||||||
|
.PP
|
||||||
|
In addition to virsh, basic linux utilities and QEMU/KVM, qq2clone
|
||||||
|
requires:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
Bash 4.0+
|
||||||
|
qemu\-img
|
||||||
|
libvirt tools:
|
||||||
|
virt\-clone
|
||||||
|
virt\-xml
|
||||||
|
virt\-xml\-validate
|
||||||
|
xmllint (from libxml2)
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
If you want to easily establish graphical connections to your virtual
|
||||||
|
machines, you should have virt\-viewer and/or spicy installed and
|
||||||
|
configure your templates to use Spice graphics.
|
||||||
|
This is not strictly necessary, and with the use of \f[B]qq2clone\f[R]
|
||||||
|
\f[B]exec\f[R] and a small script of your own you can automate
|
||||||
|
connecting to Spice/VNC clients of your choice without too much hassle
|
||||||
|
.SH OPTIONS
|
||||||
|
.PP
|
||||||
|
Not every option has an effect in the context of every command.
|
||||||
|
Specifying an option that has no effect in the context of the command
|
||||||
|
being invoked will not produce an error, it simply will not do anything
|
||||||
|
.PP
|
||||||
|
Options are parsed left to right, and right\-hand options override
|
||||||
|
left\-hand options.
|
||||||
|
The only exception is for \-Q/\-\-quieter, which \f[I]must\f[R] be the
|
||||||
|
first option listed to work properly.
|
||||||
|
.TP
|
||||||
|
.B \-c, \-\-connection [\f[I]URI\f[R]]
|
||||||
|
Specify a non\-default connection URI: sets the value of
|
||||||
|
LIBVIRT_DEFAULT_URI
|
||||||
|
.TP
|
||||||
|
.B \-f, \-\-no\-spice
|
||||||
|
Do not attempt to connect to a virtual machine\[cq]s Spice graphics.
|
||||||
|
Overrides USE_SPICE setting in configuration
|
||||||
|
.TP
|
||||||
|
.B \-g, \-\-use\-spice
|
||||||
|
Attempt to connect to a virtual machine\[cq]s spice graphics.
|
||||||
|
Overrides SPICE setting in configuration
|
||||||
|
.TP
|
||||||
|
.B \-h, \-\-help
|
||||||
|
Print basic help information and exit
|
||||||
|
.TP
|
||||||
|
.B \-n, \-\-no\-run
|
||||||
|
After making a clone of a template, do not run it.
|
||||||
|
Overrides NORUN setting in configuration
|
||||||
|
.TP
|
||||||
|
.B \-q, \-\-quiet
|
||||||
|
Suppress most non\-error output.
|
||||||
|
Overrides QUIET setting in configuration.
|
||||||
|
Also suppresses various prompts for user choices, either exiting with an
|
||||||
|
error or making a safe default choice depending on the command.
|
||||||
|
Recommended only once familiar with the behavior of \f[B]qq2clone\f[R]
|
||||||
|
.TP
|
||||||
|
.B \-Q, \-\-quieter
|
||||||
|
This option is (currently) required to appear immediately following the
|
||||||
|
invocation of \f[B]qq2clone\f[R].
|
||||||
|
Suppresses all output, error message or otherwise, except when running
|
||||||
|
interactive commands or commands that require output to be useful.
|
||||||
|
The commands for which output is not entirely supressed are: config
|
||||||
|
list, config info, list, list\-templates, exec, edit, modify\-template
|
||||||
|
edit, and check.
|
||||||
|
Other commands will receive only an exit code as output.
|
||||||
|
This option is intended for calling qq2clone from a script.
|
||||||
|
.TP
|
||||||
|
.B \-r, \-\-run
|
||||||
|
Run a clone when creating it.
|
||||||
|
Overrides NORUN setting in configuration
|
||||||
|
.TP
|
||||||
|
.B \-s, \-\-storage [\f[I]LOCATION\f[R]]
|
||||||
|
When creating a clone, place new disk image file(s) at location
|
||||||
|
specified by [\f[I]LOCATION\f[R]].
|
||||||
|
[\f[I]LOCATION\f[R]] may be one of an absolute filepath, or the name of
|
||||||
|
a libvirt directory type storage pool.
|
||||||
|
Also defines where state files will be saved when using \f[B]save\f[R]
|
||||||
|
command.
|
||||||
|
Overrides STORAGE option in configuration
|
||||||
|
.TP
|
||||||
|
.B \-S, \-\-spicy
|
||||||
|
Use spicy rather than virt\-viewer when connecting to the spice graphics
|
||||||
|
of a clone.
|
||||||
|
Overrides SPICY setting in configuration
|
||||||
|
.TP
|
||||||
|
.B \-t, \-\-template [\f[I]NAME\f[R]]
|
||||||
|
Use template of given name as context when executing a clone command
|
||||||
|
(see TYPES OF COMMAND section above).
|
||||||
|
Overrides TEMPLATE option in configuration
|
||||||
|
.TP
|
||||||
|
.B \-v, \-\-verbose
|
||||||
|
Enable all output.
|
||||||
|
Overrides QUIET setting in configuration
|
||||||
|
.TP
|
||||||
|
.B \-V, \-\-virt\-viewer
|
||||||
|
Use virt\-viewer rather than spicy when connecting to the spice graphics
|
||||||
|
of a clone.
|
||||||
|
Overrides SPICY setting in configuration
|
||||||
|
.SH TYPES OF COMMAND
|
||||||
|
.PP
|
||||||
|
There are two main classes of commands: commands that operate directly
|
||||||
|
on templates, and commands that create or operate on clones of
|
||||||
|
templates.
|
||||||
|
In order to make it less likely that the user may unintentionally invoke
|
||||||
|
a command of one class when they intended to invoke one of the other,
|
||||||
|
they use a different syntax.
|
||||||
|
Commands that operate on templates use the syntax:
|
||||||
|
.PP
|
||||||
|
\f[B]qq2clone\f[R] \f[B]command\f[R] [\f[I]template\-name\f[R]]
|
||||||
|
[\f[I]ARG\f[R]] \&...
|
||||||
|
.PP
|
||||||
|
while commands that operate on clones use the syntax:
|
||||||
|
.PP
|
||||||
|
\f[B]qq2clone\f[R] \-\-template [\f[I]template\-name\f[R]]
|
||||||
|
\f[B]command\f[R] [\f[I]ARG\f[R]] \&...
|
||||||
|
.PP
|
||||||
|
Notice that commands operating on clones work within the context of a
|
||||||
|
template defined by the option \-\-template/\-t.
|
||||||
|
Conversely, commands operating on templates specify the template as an
|
||||||
|
argument to the command.
|
||||||
|
There can also be a default template defined by the TEMPLATE option in
|
||||||
|
the configuration file, allowing the \-\-template option to be omitted
|
||||||
|
for commands that operate on clones.
|
||||||
|
Commands operating on templates do not respect this default \- the
|
||||||
|
template must always be explicitly defined, further reducing the
|
||||||
|
likelihood of accidentally modifying or deleting a template.
|
||||||
|
.SH TEMPLATE COMMMANDS
|
||||||
|
.TP
|
||||||
|
.B \f[B]copy\-template\f[R] [\f[I]CURRENT\-NAME\f[R]] [\f[I]NEW\-NAME\f[R]]
|
||||||
|
Copy the XML of template \f[I]CURRENT\-NAME\f[R] to a new template with
|
||||||
|
\f[I]NEW\-NAME\f[R].
|
||||||
|
The new template will not receive a copy of the old template\[cq]s
|
||||||
|
storage devices \- it will point to the same locations
|
||||||
|
.TP
|
||||||
|
.B \f[B]delete\-template\f[R] [\f[I]NAME\f[R]]
|
||||||
|
Delete the template \f[I]NAME\f[R].
|
||||||
|
This operation will succeed only if there are currently no clones of the
|
||||||
|
template
|
||||||
|
.PP
|
||||||
|
\f[B]import\-template\f[R] [\f[I]LIBVIRT\-DOMAIN\f[R]] [\f[I]NAME\f[R]],
|
||||||
|
\f[B]import\-template\f[R] [\f[I]XML\-LOCATION\f[R]] [\f[I]NAME\f[R]] :
|
||||||
|
Import a new template from either an existing libvirt domain, or a fully
|
||||||
|
qualified filepath to a libvirt domain XML file on disk.
|
||||||
|
If argument \f[I]NAME\f[R] is ommited, qq2clone will assume you want to
|
||||||
|
use the machine\[cq]s name as described in the XML file as the template
|
||||||
|
name
|
||||||
|
.TP
|
||||||
|
.B \f[B]list\-templates\f[R]
|
||||||
|
List the names of all existing templates
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]sub\-command\f[R] [\f[I]ARG\f[R]] \&...
|
||||||
|
Templates can be modified in various ways by invoking
|
||||||
|
\f[B]modify\-template\f[R].
|
||||||
|
Each subcommand is described below
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]commit\-image\f[R]
|
||||||
|
After an image has been created and modified as desired using
|
||||||
|
\f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]prepare\-image\f[R],
|
||||||
|
\f[B]commit\-image\f[R] is used to alter a template\[cq]s underlying
|
||||||
|
storage device by commiting any changes made using prepare\-image.
|
||||||
|
See the commit command described in \f[B]man\f[R] \f[B]qemu\-img\f[R]
|
||||||
|
for more information on how this works
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]destroy\-image\f[R]
|
||||||
|
Invoke virsh destroy on a running image created/run through
|
||||||
|
\f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]prepare\-image\f[R].
|
||||||
|
This is generally not wise, as it is equivalent to unplugging a physical
|
||||||
|
machine and could cause corruption to the image that will later be
|
||||||
|
commited as a permanent change to the template\[cq]s image
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]discard\-image\f[R]
|
||||||
|
Delete an image produced by \f[B]modify\-template\f[R] [\f[I]NAME\f[R]]
|
||||||
|
\f[B]prepare\-image\f[R] without commiting any changes
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]edit\f[R]
|
||||||
|
Edit the XML document defining a template
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]rename\f[R] [\f[I]NEW\-NAME\f[R]]
|
||||||
|
Change the name of a template, and all of its clones
|
||||||
|
.TP
|
||||||
|
.B \f[B]modify\-template\f[R] [\f[I]NAME\f[R]] \f[B]prepare\-image\f[R]
|
||||||
|
Create and/or run a clone that acts as a staging area for changes to the
|
||||||
|
\f[C]template\[aq]s\f[R] actual image.
|
||||||
|
For instance, you could update the \f[C]template\[aq]s\f[R] software by
|
||||||
|
running \f[B]modify\-template\f[R] [\f[I]NAME\f[R]]
|
||||||
|
\f[B]prepare\-image\f[R], updating the clone produced by this command,
|
||||||
|
shutting it down, and then running \f[B]modify\-template\f[R]
|
||||||
|
[\f[I]NAME\f[R]] \f[B]commit\-image\f[R].
|
||||||
|
This serves a twofold purpose \- to prevent incidental damage to an
|
||||||
|
underlying image by providing a safe buffer to work in, and to allow
|
||||||
|
modifications to be safely prepared for an underlying image even while
|
||||||
|
that image has existing clones.
|
||||||
|
.SH CLONE COMMANDS
|
||||||
|
.PP
|
||||||
|
A description of the argument \f[I]SET\f[R] is described in the
|
||||||
|
\f[B]SETS\f[R] section below
|
||||||
|
.TP
|
||||||
|
.B \f[B]clone\f[R] [\f[I]NUMBER\f[R]]
|
||||||
|
Invoke without any argument to produce a single clone.
|
||||||
|
Supply a number as an argument to specify the number of clones to create
|
||||||
|
.TP
|
||||||
|
.B \f[B]connect\f[R] [\f[I]SET\f[R]]
|
||||||
|
Start any machine in \f[I]SET\f[R] that \f[C]isn\[aq]t\f[R] already
|
||||||
|
running.
|
||||||
|
If any machine in \f[I]SET\f[R] has spice graphics and spicy or
|
||||||
|
virt\-viewer is installed, use one or the other (chosen by command\-line
|
||||||
|
option or configuration) to connect to the graphical console
|
||||||
|
.TP
|
||||||
|
.B \f[B]destroy\f[R] [\f[I]SET\f[R]]
|
||||||
|
Invoke virsh destroy on any running machine in \f[I]SET\f[R] (in other
|
||||||
|
words, if the domain is running forcibly turn it off)
|
||||||
|
.TP
|
||||||
|
.B \f[B]edit\f[R] [\f[I]NUMBER\f[R]]
|
||||||
|
Edit the XML file of the clone with given number
|
||||||
|
.TP
|
||||||
|
.B \f[B]exec\f[R] [\f[I]SET\f[R]] [\f[I]command\-string\f[R]]
|
||||||
|
For every machine in \f[I]SET\f[R], sequentially, execute the contents
|
||||||
|
of the command string in an environment where the following variables
|
||||||
|
are defined per clone: \f[C]\[dq]$uuid\[dq]\f[R],
|
||||||
|
\f[C]\[dq]$name\[dq]\f[R], \f[C]\[dq]$disks\[dq]\f[R] (a newline
|
||||||
|
delimited string containing the machine\[cq]s qcow2 disk device
|
||||||
|
filepaths).
|
||||||
|
This is done using bash\[cq]s eval command, so be sure to put any
|
||||||
|
instances of these variables in single quotes (double quotes inside the
|
||||||
|
single quotes is best practice) or they will not be set properly.
|
||||||
|
If any instance of exec has a non\-zero return value, execution stops.
|
||||||
|
.TP
|
||||||
|
.B \f[B]list\f[R] [\f[I]ARG\f[R]]
|
||||||
|
Without arguments, list all clones of the current template and their
|
||||||
|
state.
|
||||||
|
With argument \[lq]all\[rq], provide list including all clones of every
|
||||||
|
template.
|
||||||
|
With argument \[lq]xml\[rq], produce an XML document with information
|
||||||
|
about every template, their clones, and their state.
|
||||||
|
The XML option is not complete \- its format is at this point defined
|
||||||
|
only implicitly, by the output of this command.
|
||||||
|
.TP
|
||||||
|
.B \f[B]resume\f[R] [\f[I]SET\f[R]]
|
||||||
|
Resume any suspended machines in \f[I]SET\f[R]
|
||||||
|
.TP
|
||||||
|
.B \f[B]rm\f[R] [\f[I]SET\f[R]]
|
||||||
|
Destroy every domain in \f[I]SET\f[R] (if running), undefine them and
|
||||||
|
delete their storage volumes
|
||||||
|
.TP
|
||||||
|
.B \f[B]rm\-wipe\f[R] [\f[I]SET\f[R]]
|
||||||
|
Destroy every domain in \f[I]SET\f[R] (if running), undefine them and
|
||||||
|
wipe their storage volumes using virsh
|
||||||
|
.TP
|
||||||
|
.B \f[B]rm\-shred\f[R] [\f[I]SET\f[R]]
|
||||||
|
Destroy every domain in \f[I]SET\f[R] (if running), undefine them and
|
||||||
|
shred their storage volumes
|
||||||
|
.TP
|
||||||
|
.B \f[B]save\f[R] [\f[I]SET\f[R]]
|
||||||
|
Save execution state of every running domain in \f[I]SET\f[R] to file
|
||||||
|
.TP
|
||||||
|
.B \f[B]save\-rm\f[R] [\f[I]SET\f[R]]
|
||||||
|
Delete the state file associated with every machine in \f[I]SET\f[R]
|
||||||
|
.TP
|
||||||
|
.B \f[B]start\f[R] [\f[I]SET\f[R]]
|
||||||
|
Start every machine in \f[I]SET\f[R] that is currently not running.
|
||||||
|
For saved domains, their state will be restored
|
||||||
|
.TP
|
||||||
|
.B \f[B]suspend\f[R] [\f[I]SET\f[R]]
|
||||||
|
Suspend execution of every machine in \f[I]SET\f[R]
|
||||||
|
.SH OTHER COMMANDS
|
||||||
|
.TP
|
||||||
|
.B \f[B]check\f[R] [\f[I]TEMPLATE\-NAME\f[R]]
|
||||||
|
As described in the limitations section, there are ways that qq2clone
|
||||||
|
can lose track of a clone.
|
||||||
|
If this happens, it will remain in qq2clone\[cq]s database, its ID
|
||||||
|
number will remain reserved, and its image files may not be deleted and
|
||||||
|
take up space doing nothing.
|
||||||
|
the \f[B]check\f[R] command tries to find and fix this and other
|
||||||
|
problems.
|
||||||
|
The \f[I]TEMPLATE\-NAME\f[R] argument is optional, and restricts the
|
||||||
|
check to that template and its clones.
|
||||||
|
Otherwise, all templates are checked
|
||||||
|
.TP
|
||||||
|
.B \f[B]config\f[R] list, \f[B]config\f[R] info [\f[I]OPTION\f[R]], \f[B]config\f[R] edit [\f[I]OPTION\f[R]]
|
||||||
|
List all configuration options and their current value, get info about a
|
||||||
|
particular option, or edit one
|
||||||
|
.SH SETS
|
||||||
|
.PP
|
||||||
|
\f[I]SET\f[R] is listed as an argument to many commands.
|
||||||
|
\f[I]SET\f[R] simply describes a set of virtual machines \- clones of a
|
||||||
|
given template.
|
||||||
|
\f[I]SET\f[R] is a comma delimited list with no whitespace.
|
||||||
|
\f[I]SET\f[R] can be an individual machine or several individual
|
||||||
|
machines designated by number:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
1 (Machine 1)
|
||||||
|
3,7 (Machines 3 and 7)
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Machine numbers can be shown with \f[B]qq2clone\f[R] \f[B]list\f[R].
|
||||||
|
Ranges and omitted values are supported as well:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
1,2\-5,\[ha]3 (Machines 1 and 2\-5 excluding 3)
|
||||||
|
1\-10,\[ha]3\-7 (Machines 1\-10 excluding 3\-7)
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Lastly, groups of machines can be addressed by their state:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
all (All machines)
|
||||||
|
all,\[ha]running (All machines that aren\[aq]t running)
|
||||||
|
\[ha]running,1\-10 (Machines 1\-10 except those that are running)
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
The possible states of a virtual machine are based on the states listed
|
||||||
|
in \f[B]man virsh\f[R], with some modifications.
|
||||||
|
States in qq2clone are:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
all
|
||||||
|
crashed
|
||||||
|
idle
|
||||||
|
in\-shutdown
|
||||||
|
off
|
||||||
|
paused
|
||||||
|
pmsuspended
|
||||||
|
running
|
||||||
|
saved
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Specifying machines that do not exist will not cause an error: i.e.,
|
||||||
|
1\-10 is a valid set even if only machines 3\-7 exist.
|
||||||
|
A set will only cause an error if it is malformed, includes zero
|
||||||
|
existing machines, contains no machines that the command being invoked
|
||||||
|
may act upon, or includes numbers less than 1.
|
||||||
|
.SH CONFIG
|
||||||
|
.PP
|
||||||
|
There is no need to refer to the manual to understand configuration
|
||||||
|
options.
|
||||||
|
Use \[lq]\f[B]qq2clone\f[R] config list\[rq] to see all options and
|
||||||
|
their current values, and \[lq]\f[B]qq2clone\f[R] config info
|
||||||
|
[\f[I]OPTION\f[R]]\[rq] to get information about a particular option.
|
||||||
|
However, here is the same information provided by \f[B]qq2clone\f[R]
|
||||||
|
info for each option
|
||||||
|
.PP
|
||||||
|
TEMPLATE
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
This template will be used for commands like clone, rm, destroy when
|
||||||
|
option \-\-template/\-t is not specified
|
||||||
|
.PP
|
||||||
|
Default value: Default value: \f[C]\[aq]0\[aq]\f[R]
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
TEMPLATE_DIR
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
This is the where template XML files will be kept
|
||||||
|
.PP
|
||||||
|
Default value: \f[C]\[aq]${HOME}/storage\-qq2clone/templates\[aq]\f[R]
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
QUIET
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
If set to 1, most non\-error output will be suppressed
|
||||||
|
.PP
|
||||||
|
Default value: \f[C]\[aq]0\[aq]\f[R]
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
USE_SPICE
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
If set to 1, attempt to connect to the spice graphics of a virtual
|
||||||
|
machine by default when cloning it, if it is configured to use spice
|
||||||
|
graphics.
|
||||||
|
qq2clone can do this using the programs spicy and virt\-viewer.
|
||||||
|
If either is installed on your system during the first run, the default
|
||||||
|
value is \f[C]\[aq]1\[aq]\f[R] (enabled).
|
||||||
|
Otherwise, the default value is \f[C]\[aq]0\[aq]\f[R]
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
S_TIMEOUT
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
Wait this many seconds before timing out when trying to connect to a
|
||||||
|
virtual \f[C]machine\[aq]s\f[R] spice graphics.
|
||||||
|
.PP
|
||||||
|
Default value: \f[C]\[aq]10\[aq]\f[R]
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
STORAGE
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
The default location to store clone images when creating them.
|
||||||
|
Changing this location is fine, but it is a good idea to ensure that
|
||||||
|
whatever location you do choose is only used by qq2clone
|
||||||
|
.PP
|
||||||
|
Default value:
|
||||||
|
\f[C]\[aq]${HOME}/storage\-qq2clone/qq2clone\-pool\[aq]\f[R]
|
||||||
|
.RE
|
||||||
|
.SH EXAMPLES
|
||||||
|
.TP
|
||||||
|
.B \f[B]qq2clone\f[R] \-\-template Debian \-\-run \-\-virt\-viewer clone
|
||||||
|
Make a clone of Debian, run it, and connect to its spice graphics using
|
||||||
|
virt\-viewer.
|
||||||
|
All of these options could have instead been defined in the
|
||||||
|
configuration, so that the entire command would be: \f[B]qq2clone\f[R]
|
||||||
|
clone
|
||||||
|
.TP
|
||||||
|
.B \f[B]qq2clone\f[R] \-\-template Debian exec 3 `virsh console \[lq]$uuid\[rq]'
|
||||||
|
Use virsh to connect to the serial console of template Debian\[cq]s
|
||||||
|
clone with number 3 (as shown in \f[B]qq2clone\f[R] list)
|
||||||
|
.TP
|
||||||
|
.B \f[B]qq2clone\f[R] \f[B]modify\-template\f[R] Debian \f[I]prepare\-image\f[R]
|
||||||
|
Create a clone of Debian that can be used as a staging area for
|
||||||
|
permanent changes to the backing template storage device
|
||||||
|
.TP
|
||||||
|
.B \f[B]qq2clone\f[R] \f[B]modify\-template\f[R] Debian \f[B]commit\-image\f[R]
|
||||||
|
Commit changes to the image Debian staged with the previous command
|
||||||
|
.TP
|
||||||
|
.B \f[B]qq2clone\f[R] \f[B]copy\-template\f[R] Debian Debian_2
|
||||||
|
Copy the XML of template Debian, creating a new template with the same
|
||||||
|
backing storage device that you can edit as you please
|
||||||
|
.SH LIMITATIONS
|
||||||
|
.PP
|
||||||
|
The largest limitation of \f[B]qq2clone\f[R] is that it cannot protect
|
||||||
|
your template images from the actions of other software.
|
||||||
|
If nothing else touches a template\[cq]s storage volumes, qq2clone can
|
||||||
|
safely handle them (barring unknown bugs or bad luck during a
|
||||||
|
commit\-image).
|
||||||
|
However, if something else alters the image upon which a template is
|
||||||
|
based, its existing clones may be corrupted and future clones may behave
|
||||||
|
differently than expected.
|
||||||
|
It is the user\[cq]s responsibility to understand this aspect of copy on
|
||||||
|
write and carefully manage template images.
|
||||||
|
Future updates to qq2clone may add features that give some additional
|
||||||
|
protections, but this risk is inherent to copy on write.
|
||||||
|
.PP
|
||||||
|
Libvirt has permissions errors when a storage pool is in a
|
||||||
|
\[lq]hidden\[rq] directory with a name beginning with \[lq].\[rq] and
|
||||||
|
qcow2 files with backing files are involved.
|
||||||
|
This may be due to apparmor, or it may be an issue with libvirt.
|
||||||
|
It is unknown how widespread this issue is, but it is the reason that
|
||||||
|
the default directory storage\-qq2clone does not start with `.'
|
||||||
|
.PP
|
||||||
|
If the UUID of a clone is changed, qq2clone will no longer be able to
|
||||||
|
track it and will not be able to perform commands on it anymore.
|
||||||
|
If virsh undefine is run on a clone, qq2clone will not be able to see it
|
||||||
|
once it is turned off.
|
||||||
|
This limitation will be eliminated or reduced in the future, when
|
||||||
|
qq2clone moves away from relying on virsh and implements direct usage of
|
||||||
|
the libvirt API.
|
||||||
|
It could be addressed now by using transient domains, but that would
|
||||||
|
require qq2clone to do more things manually instead of just invoking
|
||||||
|
virsh.
|
||||||
|
Since the plan is to transition to a different approach later, that
|
||||||
|
would be wasted effort.
|
||||||
|
For now, if you find yourself in this position just use
|
||||||
|
\f[B]qq2clone\f[R] check.
|
||||||
|
.PP
|
||||||
|
qq2clone can only produce clones by making qcow2 image files.
|
||||||
|
The backing file need not be qcow2, but the images produced by qq2clone
|
||||||
|
always will be.
|
||||||
|
This is unlikely to ever change \- levaraging the features of qcow2 is
|
||||||
|
the entire purpose of qq2clone.
|
||||||
|
If it does change, qq2clone will need a new name.
|
||||||
|
.PP
|
||||||
|
qq2clone does not support creating images in pool types other than
|
||||||
|
directories, and attempting to use a machine as a template when it has
|
||||||
|
storage volumes in a non\-directory pool is likely to fail or have
|
||||||
|
unexpected results.
|
||||||
|
Support for some other pool types may be added in the future.
|
||||||
|
.PP
|
||||||
|
qq2clone currently cannot copy storage volumes when importing a template
|
||||||
|
(it just references the originals), or when copying a template.
|
||||||
|
This will change in the future, and qq2clone will also be able to handle
|
||||||
|
more complex relationships between templates, clones and their images
|
||||||
|
.SH FILES
|
||||||
|
.TP
|
||||||
|
.B \[ti]/.config/qq2clone
|
||||||
|
This document simply contains a string defining the location at which
|
||||||
|
qq2clone will store files, including the database containing the rest of
|
||||||
|
it configuration options.
|
||||||
|
Currently, qq2clone cannot run without ${HOME} being defined unless a
|
||||||
|
few lines are altered to refer to a new location
|
||||||
|
.TP
|
||||||
|
.B \[ti]/storage\-qq2clone
|
||||||
|
Directory where qq2clone stores all files and binary executables.
|
||||||
|
Can be changed by modifying \[ti]/.config/qq2clone.
|
||||||
|
This directory is not named \[lq]qq2clone\[rq] because it can then
|
||||||
|
slightly interfere with bash completion when in the home directory, and
|
||||||
|
it does not start with a `.' for the reasons described in the
|
||||||
|
\f[B]LIMITATIONS\f[R] section above
|
||||||
|
.TP
|
||||||
|
.B \[ti]/storage\-qq2clone/qq2clone.db
|
||||||
|
sqlite3 database containing the configuration information for qq2clone,
|
||||||
|
as well as data about templates and clones
|
||||||
|
.TP
|
||||||
|
.B \[ti]/storage\-qq2clone/qq2clone\-pool
|
||||||
|
Storage pool used for clone images and saved state files, if the
|
||||||
|
\-\-storage option is not used when creating or saving a clone and the
|
||||||
|
option STORAGE is not changed in the configuration file
|
||||||
|
.TP
|
||||||
|
.B \[ti]/qq2clone/templates
|
||||||
|
Directory in which template XML files are stored.
|
||||||
|
These can be edited manually, but it is more advisable to use
|
||||||
|
\f[B]qq2clone\f[R] \f[B]modify\-template\f[R] [\f[I]template\-name\f[R]]
|
||||||
|
edit
|
||||||
|
.SH BUGS
|
||||||
|
.PP
|
||||||
|
As described in the options section, the implementation of the
|
||||||
|
\-\-quieter/\-Q option needs some work.
|
||||||
|
Its current behavior is the easiest functional approach without
|
||||||
|
complicating the options parser, but it will eventually be modified and
|
||||||
|
become better behaved.
|
||||||
|
In addition to the previously described problem, very early error
|
||||||
|
messages will not be suppressed.
|
||||||
|
Most likely, the solution is to implement a better options parser and
|
||||||
|
make it the first thing to run when executing qq2clone.
|
||||||
|
However, the impact of this bug is minimal and other improvements are
|
||||||
|
likely to come before this bug fix.
|
||||||
|
.PP
|
||||||
|
If you find any worse bugs, and I\[cq]m sure I missed some, please let
|
||||||
|
me know and I will fix them as time allows.
|
||||||
|
.SH EXIT VALUES
|
||||||
|
.TP
|
||||||
|
.B \f[B]10\f[R]
|
||||||
|
No permission to access file or file doesn\[cq]t exist
|
||||||
|
.TP
|
||||||
|
.B \f[B]11\f[R]
|
||||||
|
Required software dependencies are not met (see description for a list),
|
||||||
|
or are cannot be found in PATH
|
||||||
|
.TP
|
||||||
|
.B \f[B]12\f[R]
|
||||||
|
Invalid command line argument specified, or command specifies an invalid
|
||||||
|
action
|
||||||
|
.TP
|
||||||
|
.B \f[B]13\f[R]
|
||||||
|
Problem with a template \- i.e., specified template does not exist, or
|
||||||
|
import\-template failed because template of specified name already
|
||||||
|
exists
|
||||||
|
.TP
|
||||||
|
.B \f[B]14\f[R]
|
||||||
|
Invocation of an external command failed
|
||||||
|
.TP
|
||||||
|
.B \f[B]15\f[R]
|
||||||
|
Problem with a libvirt XML file
|
||||||
|
.TP
|
||||||
|
.B \f[B]16\f[R]
|
||||||
|
Attempted action with a libvirt tool resulted in failure
|
||||||
|
.TP
|
||||||
|
.B \f[B]17\f[R]
|
||||||
|
Could not establish graphical spice connection to machine before timeout
|
||||||
|
expired
|
||||||
|
.TP
|
||||||
|
.B \f[B]18\f[R]
|
||||||
|
A file is of the wrong type or does not exist
|
||||||
|
.TP
|
||||||
|
.B \f[B]19\f[R]
|
||||||
|
Unexpected error \- a bug in qq2clone, or a highly unexpected failure of
|
||||||
|
some command
|
||||||
|
.SH AUTHORS
|
||||||
|
Jesse Gardner.
|
Loading…
Reference in New Issue