Re: [Libguestfs] [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)>,