Move the "FIXED APPLIANCE" section from libguestfs-make-fixed-appliance(1) to the "INTERNALS" section of guestfs(3), so it's more visible and less hidden in the documentation of a rarely-used tool. Also slightly improve it. Expand the FAQ question about libguestfs without supermin, mentioning the build options needed and pointing to the aforementioned new section. --- appliance/libguestfs-make-fixed-appliance.pod | 28 ++------------------ examples/guestfs-faq.pod | 11 +++++++- src/guestfs.pod | 37 +++++++++++++++++++++++++++ 3 files changed, 49 insertions(+), 27 deletions(-) diff --git a/appliance/libguestfs-make-fixed-appliance.pod b/appliance/libguestfs-make-fixed-appliance.pod index 9807f80..99c55fa 100644 --- a/appliance/libguestfs-make-fixed-appliance.pod +++ b/appliance/libguestfs-make-fixed-appliance.pod @@ -38,8 +38,8 @@ L<guestfs-performance(1)>). =back -For deeper understanding of why you might need this tool, read the -section L</FIXED APPLIANCE> below. +For deeper understanding of why you might need this tool, read +L<guestfs(3)/FIXED APPLIANCE>. Instead of running this tool, you can download fixed appliances from L<http://libguestfs.org/download/binaries/appliance/>;. These @@ -120,30 +120,6 @@ completely silent when it is running. =back -=head1 FIXED APPLIANCE - -When libguestfs (or libguestfs tools) are run, they search a path -looking for an appliance. The path is built into libguestfs, or can -be set using the C<LIBGUESTFS_PATH> environment variable. - -Normally a supermin appliance is located on this path (see -L<supermin(1)/SUPERMIN APPLIANCE>). libguestfs reconstructs this -into a full appliance by running C<supermin --build>. - -However, a simpler "fixed appliance" can also be used. libguestfs -detects this by looking for a directory on the path containing four -files called F<kernel>, F<initrd>, F<root> and F<README.fixed> (note -the F<README.fixed> file must be present as well). - -If the fixed appliance is found, libguestfs skips supermin entirely -and just runs qemu with the kernel, initrd and root disk from the -fixed appliance. - -Thus the fixed appliance can be used when a platform or Linux distro -does not support supermin. You build the fixed appliance on a -platform that does support supermin, and copy it over, and use that -to run libguestfs. - =head1 LICENSING The fixed appliance is a complete Linux binary distro. If you diff --git a/examples/guestfs-faq.pod b/examples/guestfs-faq.pod index 8d52ab2..bc54c54 100644 --- a/examples/guestfs-faq.pod +++ b/examples/guestfs-faq.pod @@ -431,7 +431,16 @@ enough supermin installed, then see the previous question. If supermin 5 doesn't support your distro at all, you will need to use the "fixed appliance method" where you use a pre-compiled binary -appliance. See: L<http://libguestfs.org/download/binaries/appliance/> +appliance. To build libguestfs without supermin, you need to pass +C<--disable-appliance --disable-daemon> to either F<./autogen.sh> or +F<./configure> (depending whether you are building respectively from +git or from tarballs). Then, when using libguestfs, you B<must> set +the C<LIBGUESTFS_PATH> environment variable to the directory of a +pre-compiled appliance, as also described in +L<guestfs(3)/FIXED APPLIANCE>. + +For pre-compiled appliances, see also: +L<http://libguestfs.org/download/binaries/appliance/>. Patches to port supermin to more Linux distros are welcome. diff --git a/src/guestfs.pod b/src/guestfs.pod index fa04c86..a524fdf 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -3795,6 +3795,43 @@ The daemon self-limits the frequency of progress messages it sends (see C<daemon/proto.c:notify_progress>). Not all calls generate progress messages. +=head2 FIXED APPLIANCE + +When libguestfs (or libguestfs tools) are run, they search a path +looking for an appliance. The path is built into libguestfs, or can +be set using the C<LIBGUESTFS_PATH> environment variable. + +Normally a supermin appliance is located on this path (see +L<supermin(1)/SUPERMIN APPLIANCE>). libguestfs reconstructs this +into a full appliance by running C<supermin --build>. + +However, a simpler "fixed appliance" can also be used. libguestfs +detects this by looking for a directory on the path containing all +the following files: + +=over 4 + +=item * F<kernel> + +=item * F<initrd> + +=item * F<root> + +=item * F<README.fixed> (note that it B<must> be present as well) + +=back + +If the fixed appliance is found, libguestfs skips supermin entirely +and just runs the virtual machine (using qemu or the current backend, +see L</BACKEND>) with the kernel, initrd and root disk from the fixed +appliance. + +Thus the fixed appliance can be used when a platform or a Linux +distribution does not support supermin. You build the fixed appliance +on a platform that does support supermin using +L<libguestfs-make-fixed-appliance(1)>, copy it over, and use that +to run libguestfs. + =head1 LIBGUESTFS VERSION NUMBERS Since April 2010, libguestfs has started to make separate development -- 2.1.0