appliance: Add a tool to make fixed appliances.

3 files changed, 355 insertions, 1 deletions

diff --git a/appliance/Makefile.am b/appliance/Makefile.am
index 5114275f..ac370174 100644
--- a/appliance/Makefile.am
+++ b/appliance/Makefile.am
@@ -21,6 +21,8 @@ EXTRA_DIST = \
 	excludelist.in \
 	guestfsd.suppressions \
 	init \
+	libguestfs-make-fixed-appliance.in \
+	libguestfs-make-fixed-appliance.pod \
 	make.sh.in \
 	packagelist.in
 
@@ -83,9 +85,26 @@ supermin.d/init.img: init
 	echo "init" | cpio --quiet -o -H newc > $@-t
 	mv $@-t $@
 
+# libguestfs-make-fixed-appliance script and man page.
+
+sbin_SCRIPTS = libguestfs-make-fixed-appliance
+
+man_MANS = libguestfs-make-fixed-appliance.1
+
+libguestfs-make-fixed-appliance.1 $(top_builddir)/html/libguestfs-make-fixed-appliance.1.html: stamp-libguestfs-make-fixed-appliance.pod
+
+stamp-libguestfs-make-fixed-appliance.pod: libguestfs-make-fixed-appliance.pod
+	$(top_builddir)/podwrapper.sh \
+	  --man libguestfs-make-fixed-appliance.1 \
+	  --html $(top_builddir)/html/libguestfs-make-fixed-appliance.1.html \
+	  $<
+	touch $@
+
 # Make clean.
 
-CLEANFILES = packagelist excludelist
+CLEANFILES = packagelist excludelist \
+	libguestfs-make-fixed-appliance.1 \
+	stamp-libguestfs-make-fixed-appliance.pod
 
 clean-local:
 	rm -rf supermin.d
diff --git a/appliance/libguestfs-make-fixed-appliance.in b/appliance/libguestfs-make-fixed-appliance.in
new file mode 100644
index 00000000..7d466a6a
--- /dev/null
+++ b/appliance/libguestfs-make-fixed-appliance.in
@@ -0,0 +1,161 @@
+#!/bin/bash -
+# @configure_input@
+# libguestfs-make-fixed-appliance tool
+# Copyright (C) 2012 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+unset CDPATH
+
+program="libguestfs-make-fixed-appliance"
+version="@PACKAGE_VERSION@"
+
+TEMP=`getopt \
+        -o V \
+        --long help,version,xz \
+        -n $program -- "$@"`
+if [ $? != 0 ]; then
+    echo "$program: problem parsing the command line arguments"
+    exit 1
+fi
+eval set -- "$TEMP"
+
+usage ()
+{
+    echo "Usage:"
+    echo "  $program [--options] OUTPUTDIR"
+    echo "  $program [--options] --xz"
+    echo
+    echo "Read $program(1) man page for more information."
+    exit $1
+}
+
+while true; do
+    case "$1" in
+        -V|--version)
+            echo "$program $version"
+            exit 0;;
+        --xz)
+            xz_mode=1
+            shift;;
+        --)
+            shift
+            break;;
+        *)
+            echo "Internal error!"
+            exit 1;;
+    esac
+done
+
+# Either xz_mode or we expect one extra parameter (output directory).
+if [ -n "$xz_mode" ]; then
+    if [ $# -gt 0 ]; then
+        echo "error: $program: extra parameters on the command line"
+        echo
+        usage 1
+    fi
+else
+    if [ $# -ne 1 ]; then
+        echo "error: $program: missing output directory"
+        echo
+        usage 1
+    fi
+    outputdir="$1"
+fi
+
+# end of command line parsing
+#----------------------------------------------------------------------
+
+set -e
+
+# The two ways to build the appliance are roughly the same, except for
+# --xz we build into a temporary directory and tar it up at the end.
+
+if [ -n "$xz_mode" ]; then
+    tmpdir="$(mktemp -d)"
+    outputdir="$tmpdir/appliance"
+
+    cleanup ()
+    {
+        rm -rf $tmpdir ||:
+    }
+    trap cleanup EXIT ERR
+fi
+
+# Create the output directory.
+mkdir -p "$outputdir"
+
+# Build the supermin appliance, if not already.
+guestfish -a /dev/null run
+
+# Find the location of the appliance.
+if [ -n "$TMPDIR" ]; then
+    appliancedir="$TMPDIR/.guestfs-$(id -u)"
+else
+    appliancedir="/var/tmp/.guestfs-$(id -u)"
+fi
+
+cp "$appliancedir/kernel" "$outputdir/kernel"
+cp "$appliancedir/initrd" "$outputdir/initrd"
+cp --sparse=always "$appliancedir/root" "$outputdir/root"
+
+cat <<EOF >"$outputdir/README.fixed"
+This is the "fixed appliance", a pre-built binary appliance for
+libguestfs.  This was built using $program.
+
+Unpack the appliance directory:
+
+  tar -Jxvf appliance-<VERSION>.tar.xz
+
+Then copy all four files:
+
+ * kernel
+ * initrd
+ * root
+ * README.fixed
+
+into a directory somewhere, eg. /usr/local/lib/guestfs/appliance/
+
+Then build libguestfs (>= 1.16.7 or >= 1.17.10) from source, disabling
+the normal appliance and daemon:
+
+  ./configure --disable-appliance --disable-daemon
+  make
+  sudo make install
+
+Set LIBGUESTFS_PATH to the path where you unpacked these files, eg:
+
+  export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance/
+
+and run the libguestfs programs and virt tools in the normal way.
+
+
+LICENSE
+-------
+
+This appliance contains software under a variety of open source
+licenses.  The software is from Fedora (https://fedoraproject.org/),
+and to rebuild it you need to download Fedora 17+ and
+libguestfs >= 1.17.10, and build libguestfs from source in the usual
+way.
+
+EOF
+
+# If --xz, compress the result.  Note -S option to preserve sparseness.
+if [ -n "$xz_mode" ]; then
+    tar -C "$tmpdir" -S -cf - appliance | xz --best > "appliance-$version.tar.xz"
+    rm -rf "$tmpdir" ||:
+    trap - EXIT ERR
+fi
diff --git a/appliance/libguestfs-make-fixed-appliance.pod b/appliance/libguestfs-make-fixed-appliance.pod
new file mode 100644
index 00000000..24253088
--- /dev/null
+++ b/appliance/libguestfs-make-fixed-appliance.pod
@@ -0,0 +1,174 @@
+=encoding utf8
+
+=head1 NAME
+
+libguestfs-make-fixed-appliance - Make a "fixed appliance" for libguestfs
+
+=head1 SYNOPSIS
+
+ libguestfs-make-fixed-appliance [--options] OUTPUTDIR
+
+ libguestfs-make-fixed-appliance [--options] --xz
+
+=head1 DESCRIPTION
+
+libguestfs-make-fixed-appliance lets you make a pre-built binary
+appliance for libguestfs.
+
+B<Note that ordinary users should not need to run this tool>.  The
+only reason to use it is if you want to make a self-contained
+libguestfs appliance that can be copied to another machine or platform
+that doesn't support L<febootstrap(8)>.  To understand why you might
+need to use this tool, read the section L</FIXED APPLIANCE> below.
+
+Instead of running this tool, you can download fixed appliances from
+L<http://libguestfs.org/download/binaries/appliance/>.  These
+appliances were made using this tool.
+
+There are two ways to use this tool.
+
+=over 4
+
+=item *
+
+Specify an output directory, for example:
+
+ libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
+
+The output directory is created if it does not exist.  Four files are
+created in this directory:
+
+ <OUTPUTDIR>/kernel
+ <OUTPUTDIR>/initrd
+ <OUTPUTDIR>/root
+ <OUTPUTDIR>/README.fixed
+
+Note that C<I<OUTPUTDIR>/root> is a sparse file, so take care when
+copying it.
+
+You can then run libguestfs (possibly after copying this directory to
+another machine) by setting the environment variable LIBGUESTFS_PATH
+to C<OUTPUTDIR>.
+
+=item *
+
+The alternative method is to use the I<--xz> option to create a
+compressed tarball:
+
+ libguestfs-make-fixed-appliance --xz
+
+This creates a tarball in the I<current> directory called:
+
+ appliance-<VERSION>.tar.xz
+
+(where C<VERSION> is the version of libguestfs).  The tarball contains
+the four files:
+
+ appliance/kernel
+ appliance/initrd
+ appliance/root
+ appliance/README.fixed
+
+Note that C<appliance/root> is a sparse file, so take care when
+copying it.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Display short usage information and exit.
+
+=item B<-V>
+
+=item B<--version>
+
+Display the version number and exit.
+
+=item B<--xz>
+
+Instead of creating the appliance in an output directory, create a
+compressed tarball of the appliance in the current directory called
+C<appliance-I<VERSION>.tar.xz> where C<VERSION> is the version of
+libguestfs.
+
+Using I<--xz> can take some time.  If working normally, the tool is
+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<febootstrap(8)/SUPERMIN APPLIANCE>).  libguestfs reconstructs this
+into a full appliance by running L<febootstrap-supermin-helper(8)>.
+
+However, a simpler "fixed appliance" can also be used.  libguestfs
+detects this by looking for a directory on the path containing four
+files called C<kernel>, C<initrd>, C<root> and C<README.fixed> (note
+the C<README.fixed> file must be present as well).
+
+If the fixed appliance is found, libguestfs skips febootstrap 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 febootstrap.  You build the fixed appliance on a
+platform that does support febootstrap, and copy it over, and use that
+to run libguestfs.
+
+=head1 LICENSING
+
+The fixed appliance is a complete Linux binary distro.  If you
+distribute it, you may need to distribute corresponding source files
+to remain in legal compliance with the licenses of the software in the
+appliance (such as the GNU General Public License).
+
+=head1 EXIT STATUS
+
+libguestfs-make-fixed-appliance returns I<0> if the appliance was
+built without errors.
+
+=head1 ENVIRONMENT VARIABLES
+
+For the full list of environment variables which may affect
+libguestfs, please see the L<guestfs(3)> manual page.
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<febootstrap(8)>,
+L<febootstrap-supermin-helper(8)>,
+L<xz(1)>,
+L<http://libguestfs.org/>,
+L<http://qemu.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009-2012 Red Hat Inc.
+L<http://libguestfs.org/>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.