[Libguestfs] [PATCH 8/8] builder: update documentation
Pino Toscano
ptoscano at redhat.com
Tue Feb 25 16:29:13 UTC 2014
Update the documentation according to the new .conf files structure, the
drop of VIRT_BUILDER_SOURCE and VIRT_BUILDER_FINGERPRINT, the drop of
hardcoded source and its key, etc.
---
builder/virt-builder.pod | 154 +++++++++++++++++++++++------------------------
1 file changed, 75 insertions(+), 79 deletions(-)
diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod
index b25dffd..32c0961 100644
--- a/builder/virt-builder.pod
+++ b/builder/virt-builder.pod
@@ -292,12 +292,6 @@ URLs, then you can have either no fingerprint, one fingerprint or
multiple fingerprints. If you have multiple, then each must
correspond 1-1 with a source URL.
-The default fingerprint (if none are supplied) is
-S<F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0>
-(which is S<Richard W.M. Jones's> key).
-
-You can also set the C<VIRT_BUILDER_FINGERPRINT> environment variable.
-
=item B<--firstboot> SCRIPT
=item B<--firstboot-command> 'CMD ARGS ...'
@@ -420,7 +414,7 @@ keys are no more present).
I<--long> is a shorthand for the C<long> format.
-See also: I<--source>, I<--notes>, L</CREATING YOUR OWN TEMPLATES>.
+See also: I<--source>, I<--notes>, L</SOURCES OF TEMPLATES>.
=item B<--no-logfile>
@@ -635,12 +629,8 @@ Enable N E<ge> 2 virtual CPUs for I<--run> scripts to use.
Set the source URL to look for indexes.
You can give this option multiple times to specify multiple sources.
-If not specified it defaults to
-L<http://libguestfs.org/download/builder/index.asc>
-See also L</CREATING YOUR OWN TEMPLATES> below.
-
-You can also set the C<VIRT_BUILDER_SOURCE> environment variable.
+See also L</SOURCES OF TEMPLATES> below.
Note that you should not point I<--source> to sources that you don't
trust (unless the source is signed by someone you do trust). See also
@@ -1203,7 +1193,53 @@ serial console, add the following on the kernel command line:
=back
-=head2 CREATING YOUR OWN TEMPLATES
+=head2 SOURCES OF TEMPLATES
+
+virt-builder reads the available sources from configuration files,
+with the I<.conf> extension and located in the following paths:
+
+=over 4
+
+=item *
+
+$XDG_CONFIG_HOME/virt-builder/repos.d/ (C<$XDG_CONFIG_HOME> is
+C<$HOME/.config> if not set).
+
+=item *
+
+$XDG_CONFIG_DIRS/virt-builder/repos.d/ (where C<$XDG_CONFIG_DIRS>
+means any of the directories in that environment variable, or just C</etc/xdg>
+if not set)
+
+=back
+
+Each I<.conf> file in those paths has a simple text format like the
+following:
+
+ [libguestfs.org]
+ uri=http://libguestfs.org/download/builder/index.asc
+ gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg
+
+The part in square brackets is the repository identifier, which is
+used as unique identifier.
+
+The following fields can appear:
+
+=over 4
+
+=item C<uri=URI>
+
+The URI of the index file which this repository refers to.
+
+This field is required.
+
+=item C<gpgkey=URI>
+
+This optional field represents the URI (although only I<file://> URIs
+are accepted) of the key used to sign the index file.
+If not present, the index file referred by I<uri=..> is not signed.
+
+=back
For serious virt-builder use, you may want to create your own
repository of templates.
@@ -1223,16 +1259,17 @@ libguestfs source tree, in C<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:
+templates, and then point virt-builder at the site by creating a
+I<.conf> file pointing to it.
+
+Note that if your index is signed, you will need to properly fill
+I<gpgkey=..> in your I<.conf> file, making sure to deploy also the
+GPG key file.
virt-builder --source https://example.com/builder/index.asc \
--fingerprint 'AAAA BBBB ...' \
--list
-(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.
@@ -1246,18 +1283,10 @@ I<--no-check-signature> flag every time they use virt-builder.)
To create a key, see the GPG manual
L<http://www.gnupg.org/gph/en/manual.html>.
-Export your GPG public key and add it to the keyring of all
-virt-builder users:
+Export your GPG public key:
gpg --export -a "you at example.com" > pubkey
- # For each virt-builder user:
- gpg --import pubkey
-
-Also find the fingerprint of your key:
-
- gpg --list-keys --fingerprint
-
=head3 Create the templates
There are many ways to create the templates. For example you could
@@ -1305,7 +1334,7 @@ using the following command:
gpg --clearsign --armor index
This will create the final file called C<index.asc> which can be
-uploaded to the server (and is the I<--source> URL). As noted above,
+uploaded to the server (and is the I<uri=..> URL). As noted above,
signing the index file is optional, but recommended.
The following fields can appear:
@@ -1449,51 +1478,18 @@ images.
=back
-=head3 Running virt-builder against the alternate repository
-
-Ensure each virt-builder user has imported your public key into
-their gpg keyring (see above).
-
-Each virt-builder user should export these environment variables:
-
-=over 4
-
-=item *
-
-C<VIRT_BUILDER_SOURCE> to point to the URL of the C<index.asc> file.
-
-=item *
-
-C<VIRT_BUILDER_FINGERPRINT> to contain the fingerprint (long hex
-string) of the user who signed the index file and the templates.
-
-=back
-
-Now run virt-builder commands as normal, eg:
-
- virt-builder --list --long
-
- virt-builder os-version
-
-To debug problems, add the C<-v> option to these commands.
-
=head3 Running virt-builder against multiple sources
-It is possible to use multiple sources with virt-builder. Use either
-multiple I<--source> and/or I<--fingerprint> options, or a
-comma-separated list in the C<VIRT_BUILDER_SOURCE> /
-C<VIRT_BUILDER_FINGERPRINT> environment variables:
+It is possible to use multiple sources with virt-builder.
+The recommended way is to deploy I<.conf> files pointing to the
+index files. Another way is to specify the sources using
+multiple I<--source> and/or I<--fingerprint> options:
virt-builder \
--source http://example.com/s1/index.asc \
--source http://example.com/s2/index.asc
-or equivalently:
-
- export VIRT_BUILDER_SOURCE=http://example.com/s1/index.asc,http://example.com/s2/index.asc
- virt-builder [...]
-
-You can provide N, 1 or 0 fingerprints. In the case where you
+You can provide N or 1 fingerprints. In the case where you
provide N fingerprints, N = number of sources and there is a 1-1
correspondence between each source and each fingerprint:
@@ -1504,8 +1500,7 @@ correspondence between each source and each fingerprint:
In the case where you provide 1 fingerprint, the same fingerprint
is used for all sources.
-In the case where you provide no fingerprints, the default fingerprint
-built into virt-builder is used for all sources.
+You C<must> provide at least 1 fingerprint.
=head3 Licensing of templates
@@ -1618,8 +1613,8 @@ The source points to an index file, which is optionally signed.
Virt-builder downloads the index and checks that the signature is
valid and the signer's fingerprint matches the specified fingerprint
-(ie. I<--fingerprint>, C<VIRT_BUILDER_FINGERPRINT>, or a built-in
-fingerprint, in that order).
+(ie. the one specified in I<gpgkey=..> in the I<.conf>, or with
+I<--fingerprint>, in that order).
For checking against the built-in public key/fingerprint, this
requires importing the public key into the user's local gpg keyring
@@ -1800,21 +1795,22 @@ are actually interpreted by L<curl(1)>, not virt-builder.
=item C<HOME>
-Used to determine the location of the template cache. See L</CACHING>.
+Used to determine the location of the template cache, and the location
+of the user' sources. See L</CACHING> and L</SOURCES OF TEMPLATES>.
-=item C<VIRT_BUILDER_FINGERPRINT>
+=item C<XDG_CACHE_HOME>
-Set the default value for the GPG signature fingerprint or
-comma-separated list of fingerprints (see I<--fingerprint> option).
+Used to determine the location of the template cache. See L</CACHING>.
-=item C<VIRT_BUILDER_SOURCE>
+=item C<XDG_CONFIG_HOME>
-Set the default value for the source URL (or comma-separated list of
-URLs) for the template repository (see I<--source> option).
+Used to determine the location of the user' sources. See
+L</SOURCES OF TEMPLATES>.
-=item C<XDG_CACHE_HOME>
+=item C<XDG_CONFIG_DIRS>
-Used to determine the location of the template cache. See L</CACHING>.
+Used to determine the location of the system sources. See
+L</SOURCES OF TEMPLATES>.
=back
--
1.8.3.1
More information about the Libguestfs
mailing list