qq2clone/qq2clone.1

.\" Automatically generated by Pandoc 2.5
.\"
.TH "QQ2CLONE" "1" "February 2021" "qq2clone" ""
.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 for creating and managing clones of
QEMU/KVM virtual machines.
By using the copy on write feature of qcow2, clones of an existing
virtual machine can be made using few system resources and little time
or effort.
.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 \f[B]qq2clone\f[R] exec.
This simplifies workflows involving large numbers of virtual machines,
or the frequent creation/deletion of virtual machines.
.PP
To easily establish graphical connections to your virtual machines,
qq2clone can use virt\-viewer or spicy.
.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.
.TP
.B \-c, \-\-connection [\f[I]URI\f[R]]
Specify a non\-default connection URI: sets the value of
LIBVIRT_DEFAULT_URI
.TP
.B \-C, \-\-copy\-disks
When importing or copying a template, make a (full) copy of its image(s)
.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 as the first argument to
\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.
Other commands will receive only an exit code as output.
This option is intended for calling qq2clone from a script.
.TP
.B \-r, \-\-run
Start a clone after 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 below).
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.
To prevent unintended actions, these two command types use slightly
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
Commands operating on clones work within the context of a template
defined by \-\-template/\-t.
Conversely, commands operating on templates specify the template as an
argument to the command.
.PP
A default template can be defined by the TEMPLATE configuration option,
allowing the \-\-template flag 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, 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 contain the command
string in single quotes to avoid unexpected behavior.
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]]
If a clone is deleted, has its UUID changed or is otherwise unavailable,
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 finds and fixes occurences of this problem.
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
.TP
.B \f[B]copyright\f[R]
Output copyright information
.TP
.B \f[B]license\f[R]
Output the GNU GPL v2 complete text
.TP
.B \f[B]setup\f[R]
Perform initial setup.
This is run automatically by the installer script, but can be invoked
manually to reset the database to its initial fresh state
.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: \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] \f[B]import\-template\f[R] Debian
Import a domain on the current libvirt connection of name Debian.
Now Debian can be used as a template to produce clone machines
.TP
.B \f[B]qq2clone\f[R] \f[B]import\-template\f[R] /home/user/Debian.xml
Import domain from a libvirt domain XML file to be used as a template
.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[B]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
Understand what copy on write is.
If you modify an image, you will corrupt images using it as a backing
file.
If you don\[cq]t understand what that means, use a search engine to
research copy on write.
To safely modify a template\[cq]s underlying image, use the
prepare\-image and commit\-image subcommands of \f[B]qq2clone\f[R]
modify\-template.
.PP
qq2clone uses a virtual machine\[cq]s UUID as defined in its libvirt XML
file to track it.
Don\[cq]t change a clone\[cq]s UUID.
.PP
qq2clone does not support pool types other than directories.
If there is another pool type you wish it could use, email me at
jgardner7289\[at]protonmail.com and let me know.
.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 (at least on
Ubuntu 20.04) default Bash completion scripts will see a file starting
with \[lq]qq2clone\[rq] as well as a command in PATH of that name, and
fail to insert a space after \[lq]qq2clone\[rq] when in the home
directory
.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, 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]]
\f[B]edit\f[R]
.SH BUGS
.PP
If you find a bug, please check to see if it already appears in
https://git.j\-g\-web.com/jesse/qq2clone/issues.
If not, email me at jgardner7289\[at]protonmail.com.
.SH COPYRIGHT 2021, Jesse Gardner
.PP
This file is part of qq2clone.
.PP
qq2clone is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 2 of the License, or (at your
option) any later version.
.PP
qq2clone is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with qq2clone.
If not, see <https://www.gnu.org/licenses/>.
.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.