=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>.

Some reasons why you I<might> want to use this include:

=over 4

=item *

You want to make a self-contained libguestfs appliance that can be
copied to another machine or platform that doesn't support
L<supermin(1)>.

=item *

You have multiple users on the same machine and want to avoid the
storage duplication and start-up overhead of having multiple cached
copies of the appliance.

=item *

You want to have very predictable performance from libguestfs (see
L<guestfs-performance(1)>).

=back

For deeper understanding of why you might need this tool, read
L<guestfs-internals(1)/FIXED APPLIANCE>.

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
F<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 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<supermin(1)>,
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-2023 Red Hat Inc.
