From e8c5077d602453887c0208d38aac394e5e5c6ab3 Mon Sep 17 00:00:00 2001 From: Jesse Gardner Date: Thu, 15 Apr 2021 17:02:32 -0700 Subject: [PATCH] modified and improved documentation --- README.md | 2 +- man.md | 26 +++++++++++--------------- man.pandoc | 20 ++++++++------------ qq2clone.1 | 22 +++++++++------------- 4 files changed, 29 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index edb117c..e66598b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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: * virsh (qq2clone has started the transition to use the libvirt API directly, this will not remain a dependency forever) diff --git a/man.md b/man.md index 8d6865d..03ef4fd 100644 --- a/man.md +++ b/man.md @@ -12,8 +12,8 @@ SYNOPSIS DESCRIPTION =========== -**qq2clone** is a tool working that uese libvirt to make creating clones -of template QEMU/KVM machines simple. By using the copy on write feature +**qq2clone** is a tool that uses libvirt to make 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 @@ -26,12 +26,8 @@ arbitrary commands with exec. This simplifies workflows involving large numbers of virtual machines, or the frequent creation/destruction of virtual machines. -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 +To easily establish graphical connections to your virtual machines, +qq2clone can use virt-viewer or spicy. 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 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. +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, +further reducing the likelihood of accidentally modifying or deleting a +template. 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 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 permanent changes to the backing template storage device @@ -474,7 +470,7 @@ 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 +**modify-template** \[*template-name*\] **edit** BUGS ==== diff --git a/man.pandoc b/man.pandoc index 817889a..56822d6 100644 --- a/man.pandoc +++ b/man.pandoc @@ -10,7 +10,7 @@ qq2clone - Create and manage QEMU/KVM VMs using template machines and qcow2 **qq2clone** [*OPTION*]... *COMMAND* [*ARG*]... # 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 for which qcow2 is named, clones of an existing virtual machine can be made 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 virtual machines, or the frequent creation/destruction of virtual machines. -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 - +To easily establish graphical connections to your virtual machines, qq2clone +can use virt-viewer or spicy. + # OPTIONS 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 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 +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, further reducing the likelihood of 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 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 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 manually, but it is more advisable to use **qq2clone** **modify-template** -[*template-name*] edit +[*template-name*] **edit** # BUGS diff --git a/qq2clone.1 b/qq2clone.1 index 0cd2478..4e1b021 100644 --- a/qq2clone.1 +++ b/qq2clone.1 @@ -12,8 +12,8 @@ qcow2 images with backing files [\f[I]ARG\f[R]]\&... .SH DESCRIPTION .PP -\f[B]qq2clone\f[R] is a tool working that uese libvirt to make creating -clones of template QEMU/KVM machines simple. +\f[B]qq2clone\f[R] is a tool that uses libvirt to make 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] @@ -28,12 +28,8 @@ arbitrary commands with exec. This simplifies workflows involving large numbers of virtual machines, or the frequent creation/destruction of virtual machines. .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 +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. @@ -138,9 +134,9 @@ 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. +There can also be a default template 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, further reducing the 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 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] +.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 @@ -527,7 +523,7 @@ changed in the configuration file 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 +\f[B]edit\f[R] .SH BUGS .PP As described in the options section, the implementation of the