From dd5959cd8875496594df0fdbb8a00cbe6618c9ee Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Fri, 25 Oct 2013 13:36:19 +0100 Subject: [PATCH] builder: Copy-editing on documentation. Plus some ideas added to TODO file. --- TODO | 5 ++- builder/virt-builder.pod | 73 +++++++++++++++++++++++++++------------- 2 files changed, 53 insertions(+), 25 deletions(-) diff --git a/TODO b/TODO index cfa21084c..91fbad40f 100644 --- a/TODO +++ b/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 diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod index 37c45979a..de042c3e2 100644 --- a/builder/virt-builder.pod +++ b/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 and L. @@ -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. +You I 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). @@ -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. =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. =item B<--format> raw -Select the output format. The default is I. +For ordinary builds, this selects the output format. The default is I. + +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. +See also: I<--source>, I<--notes>, L. =item B<--no-logfile> @@ -443,13 +445,16 @@ the install). =item B<--output> filename Write the output to C. If you don't specify this option, -then the output filename is generated by taking the C 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 +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, C or C. @@ -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 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 which is an index of available templates plus some information about each one, wrapped up in a digital signature. The command C 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. + +=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 and C 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, not virt-builder. Used to determine the location of the template cache. See L. +=item C + +The size (in megabytes) of the appliance. The default can be found +using the command S>. Increase this if you +find that I<--run> scripts are running out of memory. + =item C Set the default value for the GPG signature fingerprint (see