jesse
/
qq2clone
1
0
Fork 0
Code Issues 9 Pull Requests Packages Projects Releases Wiki Activity

modified and improved documentation

This commit is contained in:
Jesse Gardner 2021-04-15 17:02:32 -07:00
parent b3d3fcd0fb
commit e8c5077d60
4 changed files with 29 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -1,6 +1,6 @@
# README # README
qq2clone is a linux tool to simplify creating and managing copy-on-write clones of template QEMU/KVM virtual machines. It can perform batch operations in case you are working with multiple clones. For much more information, there is a markdown version of the manual page you can read above (man.md). qq2clone is a linux tool to simplify creating and managing copy-on-write clones of template QEMU/KVM virtual machines. It can perform batch operations in case you are working with multiple clones. For much more information, there is a markdown version of the manual page you can read above ([man.md](https://git.j-g-web.com/jesse/qq2clone/src/branch/master/man.md)).
qq2clone has these dependences: qq2clone has these dependences:
* virsh (qq2clone has started the transition to use the libvirt API directly, this will not remain a dependency forever) * virsh (qq2clone has started the transition to use the libvirt API directly, this will not remain a dependency forever)

26
man.md
View File

@ -12,8 +12,8 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
=========== ===========
**qq2clone** is a tool working that uese libvirt to make creating clones **qq2clone** is a tool that uses libvirt to make creating clones of
of template QEMU/KVM machines simple. By using the copy on write feature 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 for which qcow2 is named, clones of an existing virtual machine can be
made without inadvertently altering the original image (with caveats - made without inadvertently altering the original image (with caveats -
read the **LIMITATIONS** section if you aren’t already familiar with how read the **LIMITATIONS** section if you aren’t already familiar with how
@ -26,12 +26,8 @@ arbitrary commands with exec. This simplifies workflows involving large
numbers of virtual machines, or the frequent creation/destruction of numbers of virtual machines, or the frequent creation/destruction of
virtual machines. virtual machines.
If you want to easily establish graphical connections to your virtual To easily establish graphical connections to your virtual machines,
machines, you should have virt-viewer and/or spicy installed and qq2clone can use virt-viewer or spicy.
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 OPTIONS
======= =======
@ -129,11 +125,11 @@ Notice that commands operating on clones work within the context of a
template defined by the option --template/-t. Conversely, commands template defined by the option --template/-t. Conversely, commands
operating on templates specify the template as an argument to the operating on templates specify the template as an argument to the
command. There can also be a default template defined by the TEMPLATE command. There can also be a default template defined by the TEMPLATE
option in the configuration file, allowing the --template option to be configuration option, allowing the --template flag to be omitted for
omitted for commands that operate on clones. Commands operating on commands that operate on clones. Commands operating on templates do not
templates do not respect this default - the template must always be respect this default - the template must always be explicitly defined,
explicitly defined, further reducing the likelihood of accidentally further reducing the likelihood of accidentally modifying or deleting a
modifying or deleting a template. template.
TEMPLATE COMMMANDS TEMPLATE COMMMANDS
================== ==================
@ -387,7 +383,7 @@ configuration, so that the entire command would be: **qq2clone** clone
Use virsh to connect to the serial console of template Debian’s clone Use virsh to connect to the serial console of template Debian’s clone
with number 3 (as shown in **qq2clone** list) with number 3 (as shown in **qq2clone** list)
**qq2clone** **modify-template** Debian *prepare-image* **qq2clone** **modify-template** Debian **prepare-image**
Create a clone of Debian that can be used as a staging area for Create a clone of Debian that can be used as a staging area for
permanent changes to the backing template storage device permanent changes to the backing template storage device
@ -474,7 +470,7 @@ the configuration file
~/qq2clone/templates ~/qq2clone/templates
Directory in which template XML files are stored. These can be edited Directory in which template XML files are stored. These can be edited
manually, but it is more advisable to use **qq2clone** manually, but it is more advisable to use **qq2clone**
**modify-template** \[*template-name*\] edit **modify-template** \[*template-name*\] **edit**
BUGS BUGS
==== ====

20
man.pandoc
View File

@ -10,7 +10,7 @@ qq2clone - Create and manage QEMU/KVM VMs using template machines and qcow2
**qq2clone** [*OPTION*]... *COMMAND* [*ARG*]... **qq2clone** [*OPTION*]... *COMMAND* [*ARG*]...
# DESCRIPTION # DESCRIPTION
**qq2clone** is a tool working that uese libvirt to make creating clones **qq2clone** is a tool that uses libvirt to make creating clones
of template QEMU/KVM machines simple. By using the copy on write feature 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 for which qcow2 is named, clones of an existing virtual machine can be made
without inadvertently altering the original image (with caveats - read the without inadvertently altering the original image (with caveats - read the
@ -23,13 +23,9 @@ performing batch operations on them - including the execution of arbitrary
commands with exec. This simplifies workflows involving large numbers of commands with exec. This simplifies workflows involving large numbers of
virtual machines, or the frequent creation/destruction of virtual machines. virtual machines, or the frequent creation/destruction of virtual machines.
If you want to easily establish graphical connections to your virtual To easily establish graphical connections to your virtual machines, qq2clone
machines, you should have virt-viewer and/or spicy installed and configure can use virt-viewer or spicy.
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 # OPTIONS
Not every option has an effect in the context of every command. Specifying Not every option has an effect in the context of every command. Specifying
@ -123,8 +119,8 @@ Notice that commands operating on clones work within the context of a
template defined by the option \-\-template/\-t. Conversely, commands template defined by the option \-\-template/\-t. Conversely, commands
operating on templates specify the template as an argument to the operating on templates specify the template as an argument to the
command. There can also be a default template defined by the command. There can also be a default template defined by the
TEMPLATE option in the configuration file, allowing the \-\-template TEMPLATE configuration option, allowing the \-\-template
option to be omitted for commands that operate on clones. Commands flag to be omitted for commands that operate on clones. Commands
operating on templates do not respect this default - the template must operating on templates do not respect this default - the template must
always be explicitly defined, further reducing the likelihood of always be explicitly defined, further reducing the likelihood of
accidentally modifying or deleting a template. accidentally modifying or deleting a template.
@ -375,7 +371,7 @@ configuration, so that the entire command would be: **qq2clone** clone
: Use virsh to connect to the serial console of template Debian's clone : Use virsh to connect to the serial console of template Debian's clone
with number 3 (as shown in **qq2clone** list) with number 3 (as shown in **qq2clone** list)
**qq2clone** **modify-template** Debian *prepare-image* **qq2clone** **modify-template** Debian **prepare-image**
: Create a clone of Debian that can be used as a staging area for : Create a clone of Debian that can be used as a staging area for
permanent changes to the backing template storage device permanent changes to the backing template storage device
@ -462,7 +458,7 @@ option STORAGE is not changed in the configuration file
: Directory in which template XML files are stored. These can be edited : Directory in which template XML files are stored. These can be edited
manually, but it is more advisable to use **qq2clone** **modify-template** manually, but it is more advisable to use **qq2clone** **modify-template**
[*template-name*] edit [*template-name*] **edit**
# BUGS # BUGS

22
qq2clone.1
View File

@ -12,8 +12,8 @@ qcow2 images with backing files
[\f[I]ARG\f[R]]\&... [\f[I]ARG\f[R]]\&...
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
\f[B]qq2clone\f[R] is a tool working that uese libvirt to make creating \f[B]qq2clone\f[R] is a tool that uses libvirt to make creating clones
clones of template QEMU/KVM machines simple. of template QEMU/KVM machines simple.
By using the copy on write feature for which qcow2 is named, clones of By using the copy on write feature for which qcow2 is named, clones of
an existing virtual machine can be made without inadvertently altering an existing virtual machine can be made without inadvertently altering
the original image (with caveats \- read the \f[B]LIMITATIONS\f[R] the original image (with caveats \- read the \f[B]LIMITATIONS\f[R]
@ -28,12 +28,8 @@ arbitrary commands with exec.
This simplifies workflows involving large numbers of virtual machines, This simplifies workflows involving large numbers of virtual machines,
or the frequent creation/destruction of virtual machines. or the frequent creation/destruction of virtual machines.
.PP .PP
If you want to easily establish graphical connections to your virtual To easily establish graphical connections to your virtual machines,
machines, you should have virt\-viewer and/or spicy installed and qq2clone can use virt\-viewer or spicy.
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 .SH OPTIONS
.PP .PP
Not every option has an effect in the context of every command. Not every option has an effect in the context of every command.
@ -138,9 +134,9 @@ Notice that commands operating on clones work within the context of a
template defined by the option \-\-template/\-t. template defined by the option \-\-template/\-t.
Conversely, commands operating on templates specify the template as an Conversely, commands operating on templates specify the template as an
argument to the command. argument to the command.
There can also be a default template defined by the TEMPLATE option in There can also be a default template defined by the TEMPLATE
the configuration file, allowing the \-\-template option to be omitted configuration option, allowing the \-\-template flag to be omitted for
for commands that operate on clones. commands that operate on clones.
Commands operating on templates do not respect this default \- the Commands operating on templates do not respect this default \- the
template must always be explicitly defined, further reducing the template must always be explicitly defined, further reducing the
likelihood of accidentally modifying or deleting a template. likelihood of accidentally modifying or deleting a template.
@ -436,7 +432,7 @@ clone
Use virsh to connect to the serial console of template Debian\[cq]s 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) clone with number 3 (as shown in \f[B]qq2clone\f[R] list)
.TP .TP
.B \f[B]qq2clone\f[R] \f[B]modify\-template\f[R] Debian \f[I]prepare\-image\f[R] .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 Create a clone of Debian that can be used as a staging area for
permanent changes to the backing template storage device permanent changes to the backing template storage device
.TP .TP
@ -527,7 +523,7 @@ changed in the configuration file
Directory in which template XML files are stored. Directory in which template XML files are stored.
These can be edited manually, but it is more advisable to use 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]qq2clone\f[R] \f[B]modify\-template\f[R] [\f[I]template\-name\f[R]]
edit \f[B]edit\f[R]
.SH BUGS .SH BUGS
.PP .PP
As described in the options section, the implementation of the As described in the options section, the implementation of the