Libguestfs - Apr 2017 - Re: [PATCH] builder: various improvements to the documentation

- 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,@Xfce Desktop"
+ virt-builder fedora-25 --install "inkscape,@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)>,
-- 
2.9.3

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,@Xfce Desktop"
> + virt-builder fedora-25 --install "inkscape,@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

On Mon, Apr 10, 2017 at 11:29:17AM +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
All looks good, thanks for doing this rather tedious and
detailed documentation review.

ACK.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v

I'm actually going to push this because I want to build a release soon ...

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://people.redhat.com/~rjones/virt-df/