builder: Copy-editing on documentation.

Plus some ideas added to TODO file.

TODO

@@ -558,6 +558,8 @@ virt-builder
 
  - set default timezone and language
 
+ - set permissions on uploaded files & created directories
+
  - how can we give users a shell?
 
  - parallel xzcat would make it much faster
@@ -572,8 +574,9 @@ virt-builder
 
  - document:
 
-   * how to upload to glance
    * how to integrate with ansible, puppet, chef
+   * how to import to OpenStack / Glance
+   * how to import to EC2
 
  - /etc/resolv.conf handling works but is best described as a hack:
    https://github.com/libguestfs/libguestfs/commit/9521422ce60578f7196cc8b7977d998159238c19

builder/virt-builder.pod

@@ -49,8 +49,8 @@ these VMs.  Everything is run from the command line and nothing
 requires root privileges, so automation and scripting is simple.
 
 Note that virt-builder does not install guests from scratch.  It takes
-cleanly prepared, digitally signed OSes and customizes them.  This
-approach is used because it is much faster, but if you need to do
+cleanly prepared, digitally signed OS templates and customizes them.
+This approach is used because it is much faster, but if you need to do
 fresh installs you may want to look at L<virt-install(1)> and
 L<oz-install(1)>.
 
@@ -80,7 +80,7 @@ will build a Fedora 20 image.  This will have all default
 configuration (minimal size, no user accounts, random root password,
 only the bare minimum installed software, etc.).
 
-Note you I<do not need to run this command as root>.
+You I<do not> need to run this command as root.
 
 The first time this runs it has to download the template over the
 network, but this gets cached (see L</CACHING>).
@@ -181,8 +181,8 @@ libguestfs appliance.  This is used to provide extra software
 repositories or other data for customization.
 
 You probably want to ensure the volume(s) or filesystems in the
-attached disks are labelled (or an ISO volume name) so that you can
-mount them by label in your run-scripts:
+attached disks are labelled (or use an ISO volume name) so that you
+can mount them by label in your run-scripts:
 
  mkdir /tmp/mount
  mount LABEL=EXTRA /tmp/mount
@@ -259,9 +259,9 @@ See L<virt-edit(1)/NON-INTERACTIVE EDITING>.
 
 =item B<--fingerprint> 'AAAA BBBB ...'
 
-Check that the digital signature is signed by the key with the given
-fingerprint.  (The fingerprint is a long string, usually written as 10
-groups of 4 hexadecimal digits).
+Check that the index and templates are signed by the key with the
+given fingerprint.  (The fingerprint is a long string, usually written
+as 10 groups of 4 hexadecimal digits).
 
 If signature checking is enabled and the I<--fingerprint> option is
 not given, then this checks the download was signed by
@@ -301,7 +301,9 @@ L</INSTALLING PACKAGES>.
 
 =item B<--format> raw
 
-Select the output format.  The default is I<raw>.
+For ordinary builds, this selects the output format.  The default is I<raw>.
+
+With I<--get-kernel> this specifies the input format.
 
 =item B<--get-kernel> IMAGE
 
@@ -353,7 +355,7 @@ List available templates.
 The alternative I<--list --long> form shows lots more details about
 each operating system option.
 
-See also: I<--source>, L</CREATING YOUR OWN TEMPLATES>.
+See also: I<--source>, I<--notes>, L</CREATING YOUR OWN TEMPLATES>.
 
 =item B<--no-logfile>
 
@@ -443,13 +445,16 @@ the install).
 =item B<--output> filename
 
 Write the output to C<filename>.  If you don't specify this option,
-then the output filename is generated by taking the C<os-version> or
-basename of the template, removing any extensions, and adding C<.img>
-(for raw format) or C<.qcow2> (for qcow2 format).
+then the output filename is generated by taking the C<os-version>
+string and adding C<.img> (for raw format) or C<.qcow2> (for qcow2
+format).
 
 Note that the output filename could be a device, partition or logical
 volume.
 
+When used with I<--get-kernel>, this option specifies the output
+directory.
+
 =item B<--password-crypto> password-crypto
 
 Set the password encryption to C<md5>, C<sha256> or C<sha512>.
@@ -496,7 +501,7 @@ If libguestfs supports it then a limited network connection is
 available but it only allows outgoing network connections.  You can
 also attach data disks (eg. ISO files) as another way to provide data
 (eg. software packages) to the script without needing a network
-connection.
+connection (I<--attach>).  You can also upload data files (I<--upload>).
 
 The alternative version I<--run-command> is the same, but it
 conveniently wraps the command up in a single line script for you.
@@ -504,7 +509,7 @@ conveniently wraps the command up in a single line script for you.
 You can have multiple I<--run> and I<--run-command> options.  They run
 in the same order that they appear on the command line.
 
-See also I<--firstboot>, I<--attach>.
+See also: I<--firstboot>, I<--attach>, I<--upload>.
 
 =item B<--scrub> FILE
 
@@ -524,13 +529,16 @@ It cannot delete directories, only regular files.
 
 =item B<--size> SIZE
 
-Select the size, where the size can be specified using common names
-such as C<32G> (32 gigabytes) etc.
+Select the size of the output disk, where the size can be specified
+using common names such as C<32G> (32 gigabytes) etc.
+
+Virt-builder will resize filesystems inside the disk image
+automatically.
 
 If the size is not specified, then one of two things happens.  If the
-output is a file, then the size is the same as the template (this is
-most likely I<not> what you want).  If the output is a device,
-partition, etc then the size of that device is used.
+output is a file, then the size is the same as the template.  If the
+output is a device, partition, etc then the size of that device is
+used.
 
 =item B<--source> URL
 
@@ -585,7 +593,7 @@ you can use I<--install> to install packages like this:
 
  virt-builder fedora-20 --install inkscape
 
-This uses the guest's package manager but the host's network
+This uses the guest's package manager and the host's network
 connection.
 
 =head3 Installing packages at first boot
@@ -599,8 +607,8 @@ connection.
 
 The downsides are that it will take the guest a lot longer to boot
 first time, and there's nothing much you can do if package
-installation fails (eg. because a network problem means the guest
-can't reach the package repositories).
+installation fails (eg. if a network problem means the guest can't
+reach the package repositories).
 
 =head3 Installing packages at build time from a side repository
 
@@ -877,12 +885,20 @@ serial console, add the following on the kernel command line:
 For serious virt-builder use, you may want to create your own
 repository of templates.
 
+=head3 Libguestfs.org repository
+
 Out of the box, virt-builder downloads the file
 L<http://libguestfs.org/download/builder/index.asc> which is an index
 of available templates plus some information about each one, wrapped
 up in a digital signature.  The command C<virt-builder --list> lists
 out the information in this index file.
 
+The templates hosted on libguestfs.org were created using shell
+scripts, kickstart files and preseed files which can be found in the
+libguestfs source tree, in C<libguestfs.git/builder/website>.
+
+=head3 Setting up the repository
+
 You can set up your own site containing an index file and some
 templates, and then point virt-builder at the site by using the
 I<--source> option:
@@ -894,6 +910,9 @@ I<--source> option:
 (Note setting the environment variables C<VIRT_BUILDER_SOURCE> and
 C<VIRT_BUILDER_FINGERPRINT> may be easier to type!)
 
+You can host this on any web or FTP server, or a local or network
+filesystem.
+
 =head3 Setting up a GPG key
 
 If you don't have a GnuPG key, you will need to set one up.  (Strictly
@@ -1139,7 +1158,7 @@ which guests are currently cached, by doing:
 
  virt-builder --print-cache
 
-The cache can be deleted after use if you want to save space by doing:
+The cache can be deleted if you want to save space by doing:
 
  virt-builder --delete-cache
 
@@ -1258,6 +1277,12 @@ are actually interpreted by L<curl(1)>, not virt-builder.
 
 Used to determine the location of the template cache.  See L</CACHING>.
 
+=item C<LIBGUESTFS_MEMSIZE>
+
+The size (in megabytes) of the appliance.  The default can be found
+using the command S<C<guestfish get-memsize>>.  Increase this if you
+find that I<--run> scripts are running out of memory.
+
 =item C<VIRT_BUILDER_FINGERPRINT>
 
 Set the default value for the GPG signature fingerprint (see