[Libguestfs] [PATCH] builder: various improvements to the documentation

[Cedric Bosdonnat]

On Mon, 2017-04-10 at 11:29 +0200, Pino Toscano wrote:
> - convert the Fedora 20 examples to Fedora 25
> - convert the yum examples to dnf
> - convert the Debian 7 examples to Debian 8
> - mention that --core updates all the installed packages, not "core"
>   ones
> - convert i386 to i686 for the Fedora 32bit examples
> - mention that autogenerated root passwords are printed on stdout
> - mention --get-kernel is deprecated in favour of virt-get-kernel
> - update URL to the Puppet installation documentation
> - edit the repository index documentation to make it clearer
>   non-compressed templates are supported
> - remove old wrong paragraph about customization specified in command
>   line not processed in the same order
> - use --install instead of --run-command '$pkgmgr install ...'
> - other minor changes
> ---
>  builder/virt-builder.pod | 144 ++++++++++++++++++++++++-----------------------
>  1 file changed, 73 insertions(+), 71 deletions(-)
> 
> diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod
> index dbbd646..74bf7bb 100644
> --- a/builder/virt-builder.pod
> +++ b/builder/virt-builder.pod
> @@ -59,14 +59,14 @@ your own too (see below).
>  After choosing a guest from the list, you may want to see if there
>  are any installation notes:
>  
> - virt-builder --notes fedora-20
> + virt-builder --notes fedora-25
>  
>  =head2 Build a virtual machine
>  
> - virt-builder fedora-20
> + virt-builder fedora-25
>  
> -will build a Fedora 20 image for the same architecture as virt-builder
> -(so running it from an i386 installation will try to build an i386
> +will build a Fedora 25 image for the same architecture as virt-builder
> +(so running it from an i686 installation will try to build an i686
>  image, if available).  This will have all default
>  configuration (minimal size, no user accounts, random root password,
>  only the bare minimum installed software, etc.).
> @@ -77,57 +77,57 @@ The first time this runs it has to download the template over the
>  network, but this gets cached (see L</CACHING>).
>  
>  The name of the output file is derived from the template name, so
> -above it will be F<fedora-20.img>.  You can change the output filename
> +above it will be F<fedora-25.img>.  You can change the output filename
>  using the I<-o> option:
>  
> - virt-builder fedora-20 -o mydisk.img
> + virt-builder fedora-25 -o mydisk.img
>  
>  You can also use the I<-o> option to write to existing devices or
>  logical volumes.
>  
> - virt-builder fedora-20 --format qcow2
> + virt-builder fedora-25 --format qcow2
>  
> -As above, but write the output in qcow2 format to F<fedora-20.qcow2>.
> +As above, but write the output in qcow2 format to F<fedora-25.qcow2>.
>  
> - virt-builder fedora-20 --size 20G
> + virt-builder fedora-25 --size 20G
>  
>  As above, but the output size will be 20 GB.  The guest OS is resized
>  as it is copied to the output (automatically, using
>  L<virt-resize(1)>).
>  
> - virt-builder fedora-20 --arch i386
> + virt-builder fedora-25 --arch i686
>  
> -As above, but using an i386 template, if available.
> +As above, but using an i686 template, if available.
>  
>  =head2 Setting the root password
>  
> - virt-builder fedora-20 --root-password file:/tmp/rootpw
> + virt-builder fedora-25 --root-password file:/tmp/rootpw
>  
> -Create a Fedora 20 image.  The root password is taken from the file
> +Create a Fedora 25 image.  The root password is taken from the file
>  F</tmp/rootpw>.
>  
>  Note if you I<don’t> set I<--root-password> then the guest is given
> -a I<random> root password.
> +a I<random> root password which is printed on stdout.
>  
>  You can also create user accounts.  See L</USERS AND PASSWORDS> below.
>  
>  =head2 Set the hostname
>  
> - virt-builder fedora-20 --hostname virt.example.com
> + virt-builder fedora-25 --hostname virt.example.com
>  
>  Set the hostname to C<virt.example.com>.
>  
>  =head2 Installing software
>  
>  To install packages from the ordinary (guest) software repository
> -(eg. yum or apt):
> +(eg. dnf or apt):
>  
> - virt-builder fedora-20 --install "inkscape, at Xfce Desktop"
> + virt-builder fedora-25 --install "inkscape, at Xfce Desktop"
>  
>  (In Fedora, C<@> is used to install groups of packages.  On Debian
>  you would install a meta-package instead.)
>  
> -To update the core packages to the latest version:
> +To update the installed packages to the latest version:
>  
>   virt-builder debian-7 --update
>  
> @@ -135,7 +135,7 @@ For guests which use SELinux, like Fedora and Red Hat Enterprise
>  Linux, you may need to do SELinux relabelling after installing or
>  updating packages (see L</SELINUX> below):
>  
> - virt-builder fedora-20 --update --selinux-relabel
> + virt-builder fedora-25 --update --selinux-relabel
>  
>  =head2 Customizing the installation
>  
> @@ -149,27 +149,27 @@ I<--edit> to edit files.  I<--upload> to upload files.
>  
>  For example:
>  
> - cat <<'EOF' > /tmp/yum-update.sh
> - yum -y update
> + cat <<'EOF' > /tmp/dnf-update.sh
> + dnf -y --best update
>   EOF
>   
> - virt-builder fedora-20 --firstboot /tmp/yum-update.sh
> + virt-builder fedora-25 --firstboot /tmp/dnf-update.sh
>  
>  or simply:
>  
> - virt-builder fedora-20 --firstboot-command 'yum -y update'
> + virt-builder fedora-25 --firstboot-command 'dnf -y --best update'
>  
> -which makes the L<yum(8)> C<update> command run once the first time
> +which makes the L<dnf(8)> C<update> command run once the first time
>  the guest boots.
>  
>  Or:
>  
> - virt-builder fedora-20 \
> -   --edit '/etc/yum.conf:
> + virt-builder fedora-25 \
> +   --edit '/etc/dnf/dnf.conf:
>               s/gpgcheck=1/gpgcheck=0/'
>  
> -which edits F</etc/yum.conf> inside the disk image (during disk image
> -creation, long before boot).
> +which edits F</etc/dnf/dnf.conf> inside the disk image (during disk
> +image creation, long before boot).
>  
>  You can combine these options, and have multiple options of all types.
>  
> @@ -301,6 +301,9 @@ This option extracts the kernel and initramfs from a previously built
>  disk image called C<IMAGE> (in fact it works for any VM disk image,
>  not just ones built using virt-builder).
>  
> +Note this method is B<deprecated>: there is a separate tool for this,
> +L<virt-get-kernel(1)>, which has more options for the file extraction.
> +
>  The kernel and initramfs are written to the current directory, unless
>  you also specify the I<--output> C<outputdir> B<directory> name.
>  
> @@ -554,16 +557,16 @@ If the guest OS you are installing is similar to the host OS (eg.
>  both are Linux), and if libguestfs supports network connections, then
>  you can use I<--install> to install packages like this:
>  
> - virt-builder fedora-20 --install inkscape
> + virt-builder fedora-25 --install inkscape
>  
>  This uses the guest’s package manager and the host’s network
>  connection.
>  
>  =head3 Updating packages at build time
>  
> -To update the core set of packages in the template at build time:
> +To update the installed packages in the template at build time:
>  
> - virt-builder fedora-20 --update
> + virt-builder fedora-25 --update
>  
>  Most of the templates that ship with virt-builder come with a very
>  minimal selection of packages (known as a "JEOS" or "Just Enough
> @@ -575,7 +578,7 @@ OS from the template.  This option updates those template packages.
>  
>  Another option is to install the packages when the guest first boots:
>  
> - virt-builder fedora-20 --firstboot-install inkscape
> + virt-builder fedora-25 --firstboot-install inkscape
>  
>  This uses the guest’s package manager and the guest’s network
>  connection.
> @@ -598,7 +601,7 @@ L<virt-make-fs(1)>.  For genisoimage, use a command like this:
>   genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/
>  
>  Create a script that mounts the ISO and sets up the repository.  For
> -yum, create /tmp/install.sh containing:
> +dnf, create /tmp/install.sh containing:
>  
>   mkdir /tmp/mount
>   mount LABEL=EXTRA /tmp/mount
> @@ -610,7 +613,7 @@ yum, create /tmp/install.sh containing:
>   enabled=1
>   EOF
>   
> - yum -y install famousdatabase
> + dnf -y install famousdatabase
>  
>  For apt, create /tmp/install.sh containing:
>  
> @@ -623,7 +626,7 @@ For apt, create /tmp/install.sh containing:
>  Use the I<--attach> option to attach the CD / disk image and the
>  I<--run> option to run the script:
>  
> - virt-builder fedora-20 \
> + virt-builder fedora-25 \
>     --attach extra-packages.iso \
>     --run /tmp/install.sh
>  
> @@ -702,7 +705,7 @@ keyboard for some common Linux distributions.
>  
>  For distros that use systemd C<localectl>, use a command like this:
>  
> - virt-builder fedora-20 \
> + virt-builder fedora-25 \
>     --firstboot-command 'localectl set-keymap uk'
>  
>  See L<localectl(1)> and
> @@ -726,7 +729,7 @@ For Debian-derived distros using F</etc/default/keyboard>, upload or
>  modify the keyboard file using the I<--upload>, I<--write> or
>  I<--edit> options.  For example:
>  
> - virt-builder debian-7 \
> + virt-builder debian-8 \
>     --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'
>  
>  See L<https://wiki.debian.org/Keyboard>.
> @@ -744,9 +747,9 @@ of virt-builder to do this.
>  
>  This section contains examples for some common Linux distributions.
>  
> -=head3 Setting Japanese in Fedora 20
> +=head3 Setting Japanese in Fedora 25
>  
> - virt-builder fedora-20 \
> + virt-builder fedora-25 \
>     --size 20G \
>     --update \
>     --install @japanese-support \
> @@ -757,7 +760,7 @@ This section contains examples for some common Linux distributions.
>     --firstboot-command 'localectl set-keymap jp' \
>     --firstboot-command 'systemctl isolate graphical.target'
>  
> -=head3 Setting Japanese in Debian 7 (Wheezy)
> +=head3 Setting Japanese in Debian 8 (Jessie)
>  
>  Note that although this enables Japanese in the text console too, it
>  is unlikely that you will see properly rendered Japanese there.
> @@ -765,15 +768,14 @@ However Japanese is properly rendered in X applications and terminals.
>  
>   pkgs=locales,xfce4,\
>   ibus,ibus-anthy,\
> - ttf-sazanami-gothic,ttf-sazanami-mincho,\
> + fonts-ipafont-gothic,fonts-ipafont-mincho,\
>   fonts-takao-mincho,\
>   xfonts-intl-japanese,xfonts-intl-japanese-big,\
>   iceweasel-l10n-ja,manpages-ja
>   
> - virt-builder debian-7 \
> + virt-builder debian-8 \
>     --size 20G \
>     --install $pkgs \
> -   --edit '/etc/inittab: s,^#([1-9].*respawn.*/sbin/getty.*),$1,' \
>     --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
>     --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
>     --run-command "locale-gen"
> @@ -788,7 +790,7 @@ logged in one of the following locations:
>  
>  =item F</tmp/builder.log>
>  
> -On Linux, BSD and other guests.
> +On Linux, BSD, and other non-Windows guests.
>  
>  =item F<C:\Temp\builder.log>
>  
> @@ -975,7 +977,7 @@ I<--import> option.
>  
>   virt-install --import \
>     --name guest --ram 2048 \
> -   --disk path=disk.img,format=raw --os-variant fedora20
> +   --disk path=disk.img,format=raw --os-variant fedora25
>  
>  Notes:
>  
> @@ -1010,7 +1012,7 @@ tools probably work differently as well.
>  
>  Import the image into Glance (the OpenStack image store) by doing:
>  
> - glance image-create --name fedora-20-image --file fedora-20.img \
> + glance image-create --name fedora-25-image --file fedora-25.img \
>     --disk-format raw --container-format bare \
>     --is-public True
>  
> @@ -1020,12 +1022,12 @@ parameter should match virt-builder’s I<--format> option (or C<raw> if
>  you didn't use that option).  The I<--container-format> should always
>  be C<bare> since virt-builder doesn't put images into containers.
>  
> -You can use the S<C<glance image-show I<fedora-20-image>>> command to
> +You can use the S<C<glance image-show I<fedora-25-image>>> command to
>  display the properties of the image.
>  
>  To boot up an instance of your image on a Nova compute node, do:
>  
> - nova boot fedora-20-server --image fedora-20-image \
> + nova boot fedora-25-server --image fedora-25-image \
>     --flavor m1.medium
>  
>  Use S<C<nova flavor-list>> to list possible machine flavors.  Use
> @@ -1056,18 +1058,18 @@ at boot.
>  
>  A typical virt-builder command would be:
>  
> - virt-builder fedora-20 \
> + virt-builder fedora-25 \
>     --hostname client.example.com \
>     --update \
>     --install puppet \
> -   --edit '/etc/puppet/puppet.conf:
> -       s/^\[agent\]/[agent]\n  server = puppetmaster.example.com/' \
> +   --append-line '/etc/puppet/puppet.conf:[agent]' \
> +   --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
>     --run-command 'systemctl enable puppet' \
>     --selinux-relabel
>  
>  The precise instructions vary according to the Linux distro.  For
>  further information see:
> -L<http://docs.puppetlabs.com/guides/installation.htm>
> +L<https://docs.puppet.com/puppet/latest/install_pre.html>
>  
>  =head2 DEBUGGING BUILDS
>  
> @@ -1277,6 +1279,10 @@ clone existing guests (see L<virt-sysprep(1)>), or you could install a
>  guest by hand (L<virt-install(1)>).  To see how the templates were
>  created for virt-builder, look at the scripts in C<builder/templates>
>  
> +Virt-builder supports any image format (e.g. raw, qcow2, etc) as
> +template, both as-is, and compressed as XZ.  This way, existing images
> +(e.g. cleaned using L<virt-sysprep(1)>) can be used as templates.
> +
>  For best results when compressing the templates, use the following xz
>  options (see L<nbdkit-xz-plugin(1)> for further explanation):
>  
> @@ -1366,8 +1372,8 @@ The file can be created as follows:
>  
>  =item C<checksum[sha512]=7b882fe9b82eb0fef...>
>  
> -The SHA-512 checksum of the B<compressed> file is checked after it is
> -downloaded.  To work out the signature, do:
> +The SHA-512 checksum of the file specified in I<file=..> is checked
> +after it is downloaded.  To work out the signature, do:
>  
>   sha512sum disk.xz
>  
> @@ -1395,9 +1401,10 @@ The revision number is optional.  If omitted it defaults to C<1>.
>  
>  =item C<format=qcow2>
>  
> -Specify the format of the disk image (before it was compressed).  If
> -not given, the format is autodetected, but generally it is better to
> -be explicit about the intended format.
> +Specify the format of the disk image; in case it is compressed, that
> +is the format before the compression.  If not given, the format is
> +autodetected, but generally it is better to be explicit about the
> +intended format.
>  
>  Note this is the source format, which is different from the
>  I<--format> option (requested output format).  Virt-builder does
> @@ -1418,8 +1425,9 @@ I<--size> option.
>  
>  =item C<compressed_size=NNN>
>  
> -The compressed size of the disk image in bytes.  This is just used for
> -information (when using I<--list --long>).
> +The actual size of the disk image in bytes, i.e. what was specified
> +in I<file=..>.  This is just used for information (when using C<long>,
> +and C<json> formats of I<--list>).
>  
>  =item C<expand=/dev/sdaX>
>  
> @@ -1568,18 +1576,11 @@ To increase both speed and reliability of installing packages, you can
>  set up a local mirror of the target distribution, and point the guest
>  package manager at that.
>  
> -Because of the order in which each phase of installation happens, you
> -cannot use I<--write> (to point the package manager at a repo)
> -followed by I<--install> (to install from that repo).  The I<--write>
> -and I<--install> steps run in the opposite order, regardless of their
> -order on the command line.  You have to do this using I<--run-command>
> -instead of I<--install>.
> -
>  =head4 Using a local mirror with Fedora
>  
>  To install a Fedora guest using a local mirror:
>  
> - virt-builder fedora-20 \
> + virt-builder fedora-25 \
>     --edit '/etc/yum.repos.d/fedora.repo:
>         s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
>         s{.*metalink=.*}{};
> @@ -1588,8 +1589,8 @@ To install a Fedora guest using a local mirror:
>         s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
>         s{.*metalink=.*}{};
>     ' \
> -   --run-command 'yum -y update' \
> -   --run-command 'yum -y install pkg1 pkg2 ...'
> +   --run-command 'dnf -y update' \
> +   --install 'pkg1,pkg2,...'
>  
>  =head4 Using a local mirror with Debian
>  
> @@ -1597,10 +1598,10 @@ Assuming that you are using C<apt-proxy> to mirror the repository, you
>  should create a new F<sources.list> file to point to your proxy (see
>  L<https://help.ubuntu.com/community/AptProxy>) and then do:
>  
> - virt-builder debian-7 \
> + virt-builder debian-8 \
>     --upload sources.list:/etc/apt/sources.list \
>     --run-command 'apt-get -y update' \
> -   --run-command 'apt-get -y install pkg1 pkg2 ...'
> +   --install 'pkg1,pkg2,...'
>  
>  =head2 DIGITAL SIGNATURES
>  
> @@ -1876,6 +1877,7 @@ L<guestfish(1)>,
>  L<guestmount(1)>,
>  L<virt-copy-out(1)>,
>  L<virt-customize(1)>,
> +L<virt-get-kernel(1)>,
>  L<virt-install(1)>,
>  L<virt-rescue(1)>,
>  L<virt-resize(1)>,

LGTM
--
Cedric