diff options
author | Richard W.M. Jones <rjones@redhat.com> | 2012-03-17 09:26:20 +0000 |
---|---|---|
committer | Richard W.M. Jones <rjones@redhat.com> | 2012-03-17 10:00:59 +0000 |
commit | 05461175c48b9d7ac7c42d0a243971f489578295 (patch) | |
tree | 47335b8a9abf501c5e43cc930aa041ec84f0d066 | |
parent | fd7a5a8bbdc69b9d2a92f6d05ac555334d0516bf (diff) | |
download | libguestfs-05461175c48b9d7ac7c42d0a243971f489578295.tar.gz libguestfs-05461175c48b9d7ac7c42d0a243971f489578295.tar.xz libguestfs-05461175c48b9d7ac7c42d0a243971f489578295.zip |
appliance: Add a tool to make fixed appliances.
-rw-r--r-- | .gitignore | 4 | ||||
-rw-r--r-- | Makefile.am | 1 | ||||
-rw-r--r-- | appliance/Makefile.am | 21 | ||||
-rw-r--r-- | appliance/libguestfs-make-fixed-appliance.in | 161 | ||||
-rw-r--r-- | appliance/libguestfs-make-fixed-appliance.pod | 174 | ||||
-rw-r--r-- | configure.ac | 2 | ||||
-rw-r--r-- | po-docs/podfiles | 1 |
7 files changed, 363 insertions, 1 deletions
@@ -6,8 +6,11 @@ align/stamp-virt-alignment-scan.pod align/virt-alignment-scan align/virt-alignment-scan.1 appliance/excludelist +appliance/libguestfs-make-fixed-appliance +appliance/libguestfs-make-fixed-appliance.1 appliance/make.sh appliance/packagelist +appliance/stamp-libguestfs-make-fixed-appliance.pod appliance/stamp-supermin appliance/supermin.d autom4te.cache @@ -148,6 +151,7 @@ html/guestfs-recipes.1.html html/guestfs-ruby.3.html html/guestfs-testing.1.html html/guestmount.1.html +html/libguestfs-make-fixed-appliance.1.html html/virt-alignment-scan.1.html html/virt-cat.1.html html/virt-copy-in.1.html diff --git a/Makefile.am b/Makefile.am index dfee9c49..3aa9cfd4 100644 --- a/Makefile.am +++ b/Makefile.am @@ -187,6 +187,7 @@ HTMLFILES = \ html/guestfs-testing.1.html \ html/guestfish.1.html \ html/guestmount.1.html \ + html/libguestfs-make-fixed-appliance.1.html \ html/virt-alignment-scan.1.html \ html/virt-cat.1.html \ html/virt-copy-in.1.html \ 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. diff --git a/configure.ac b/configure.ac index 1c10b850..46b03e28 100644 --- a/configure.ac +++ b/configure.ac @@ -1119,6 +1119,8 @@ AC_SUBST([LIBTOOL]) dnl Produce output files. AC_CONFIG_HEADERS([config.h]) dnl http://www.mail-archive.com/automake@gnu.org/msg10204.html +AC_CONFIG_FILES([appliance/libguestfs-make-fixed-appliance], + [chmod +x appliance/libguestfs-make-fixed-appliance]) AC_CONFIG_FILES([clone/virt-sysprep], [chmod +x clone/virt-sysprep]) AC_CONFIG_FILES([podwrapper.sh], diff --git a/po-docs/podfiles b/po-docs/podfiles index 6c1ab45c..d207ba32 100644 --- a/po-docs/podfiles +++ b/po-docs/podfiles @@ -1,4 +1,5 @@ ../align/virt-alignment-scan.pod +../appliance/libguestfs-make-fixed-appliance.pod ../cat/virt-cat.pod ../cat/virt-filesystems.pod ../cat/virt-ls.pod |