.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SUPERMIN 1"
.TH SUPERMIN 1 2024-05-10 supermin-5.2.2 "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
supermin \- Tool for creating and building supermin appliances
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& supermin \-\-prepare \-o OUTPUTDIR PACKAGE [PACKAGE ...]
\&
\& supermin \-\-build \-o OUTPUTDIR \-f chroot|ext2 INPUT [INPUT ...]
.Ve
.SH EXAMPLE
.IX Header "EXAMPLE"
.Vb 1
\& supermin \-\-prepare bash mount util\-linux coreutils \-o /tmp/supermin.d
\& 
\& cat > init <<EOF
\& #!/bin/bash
\& mount \-t proc /proc /proc
\& mount \-t sysfs /sys /sys
\& echo Welcome to supermin
\& bash \-i
\& EOF
\& 
\& chmod +x init
\& tar zcf /tmp/supermin.d/init.tar.gz ./init
\& 
\& supermin \-\-build /tmp/supermin.d \-f ext2 \-o /tmp/appliance.d
\& 
\& qemu\-system\-$ARCH \e
\&          \-nodefaults \-nographic \e
\&          \-kernel /tmp/appliance.d/kernel \e
\&          \-initrd /tmp/appliance.d/initrd \e
\&          \-hda /tmp/appliance.d/root \e
\&          \-serial stdio \-append "console=ttyS0 root=/dev/sda"
\& ...
\& Welcome to supermin
\& bash\-4.3#
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Supermin is a tool for building supermin appliances.  These are tiny
appliances (similar to virtual machines), usually around 100KB in
size, which get fully instantiated on-the-fly in a fraction of a
second when you need to boot one of them.
.PP
This program used to be called febootstrap.  This manual page
documents supermin 5.x which is a complete rewrite and quite different
from febootstrap 2.x.  If you are looking for the febootstrap 2.x
tools, then this is not the right place.
.SS "BASIC OPERATION"
.IX Subsection "BASIC OPERATION"
The supermin tool can be used in two modes, \fBpreparing\fR a tiny
supermin appliance, which is done on a build system.  And \fBbuilding\fR,
which takes the supermin appliance and constructs a full, bootable
appliance, which is done on the end user's system.
.PP
Supermin does not need to be run as root, and generally \fIshould not\fR
be run as root.  It does not affect the host system or the packages
installed on the host system.
.PP
\fIPREPARE MODE\fR
.IX Subsection "PREPARE MODE"
.PP
\&\fI\-\-prepare\fR creates the tiny supermin appliance in the given output
directory.  You give it a list of packages that you want installed,
and supermin will automatically find the dependencies.  The list of
packages has to be installed on the host machine.
.PP
For example:
.PP
.Vb 1
\& supermin \-\-prepare bash coreutils \-o supermin.d
.Ve
.PP
creates a supermin appliance containing the packages \f(CW\*(C`bash\*(C'\fR and
\&\f(CW\*(C`coreutils\*(C'\fR.  Specifically, it creates some files in directory
\&\fIsupermin.d\fR.  This directory \fIis\fR the supermin appliance.  (See
"SUPERMIN APPLIANCES" below).
.PP
It is intended that the \fI\-\-prepare\fR step is done on a central build
machine, and the supermin appliance is distributed to end users (which
is easy because supermin appliances are so small).
.PP
\fIBUILD MODE\fR
.IX Subsection "BUILD MODE"
.PP
\&\fI\-\-build\fR (previously a separate program called \f(CW\*(C`supermin\-helper\*(C'\fR)
builds the full appliance from the supermin appliance:
.PP
.Vb 1
\& supermin \-\-build \-\-format ext2 supermin.d \-o appliance.d
.Ve
.PP
This will create files called \fIappliance.d/kernel\fR,
\&\fIappliance.d/root\fR etc, which is the full sized bootable appliance.
.PP
It is intended that the \fI\-\-build\fR step is done on the end user's
machine at the last second before the appliance is needed.  The
packages in the supermin appliance (those specified when the supermin
appliance was prepared) must be installed on the end user's machine.
.PP
Build and cache
.IX Subsection "Build and cache"
.PP
Typically you want to rebuild the appliance on the end user machine
only on demand.  Supermin has some extra options to make this easy:
.PP
.Vb 3
\& supermin \-\-build \e
\&   \-\-if\-newer \-\-lock /run/user/\`id \-u\`/supermin.lock \e
\&   \-\-format ext2 supermin.d \-o appliance.d
.Ve
.PP
If multiple programs run this command in parallel, the instances will
wait on the lock file.  The full appliance only gets rebuilt if it
doesn't exist or if it is older than the input files and host package
database.
.PP
Note that the lock file \fBmust not\fR be stored inside the \fI\-o\fR
directory.
.PP
\fIPACKAGES\fR
.IX Subsection "PACKAGES"
.PP
By "package" we mean the RPM, Debian, (etc.) package,
eg. \f(CW\*(C`coreutils\*(C'\fR, \f(CW\*(C`perl\*(C'\fR.
.PP
In all cases supermin can only build a supermin appliance which is
identical in distro, version and architecture to the host.  It does
\&\fInot\fR do cross-builds.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-help\fR 4
.IX Item "--help"
Display brief command line usage, and exit.
.IP \fB\-\-build\fR 4
.IX Item "--build"
Build the full appliance from the supermin appliance.  This used to be
a separate program called \f(CW\*(C`supermin\-helper\*(C'\fR.
.IP \fB\-\-copy\-kernel\fR 4
.IX Item "--copy-kernel"
(\fI\-\-build\fR mode only)
.Sp
Copy the kernel (and device tree, if created) instead of symlinking to
the kernel in \fI/boot\fR.
.Sp
This is fractionally slower, but is necessary if you want to change
the permissions or SELinux label on the kernel or device tree.
.IP "\fB\-f\fR FORMAT" 4
.IX Item "-f FORMAT"
.PD 0
.IP "\fB\-\-format\fR FORMAT" 4
.IX Item "--format FORMAT"
.PD
(\fI\-\-build\fR mode only)
.Sp
Select the output format for the full appliance.
.Sp
There is no default.  When using \fI\-\-build\fR you must specify the
\&\fI\-\-format\fR option.
.Sp
Possible formats are:
.RS 4
.IP chroot 4
.IX Item "chroot"
A directory tree in the host filesystem.
.Sp
The filesystem tree is written to \fIOUTPUTDIR\fR (ie. the \fI\-o\fR option).
.Sp
This is called a \f(CW\*(C`chroot\*(C'\fR because you could literally \fBchroot\fR\|(1)
into this directory afterwards, although it's a better idea to use a
container technology (LXC, etc.).
.Sp
No kernel or initrd is generated in this mode because it is
assumed that you will be running the appliance using the host kernel.
.IP ext2 4
.IX Item "ext2"
An ext2 filesystem disk image.
.Sp
The output kernel is written to \fIOUTPUTDIR/kernel\fR,
a small initramfs which can mount the
appliance to \fIOUTPUTDIR/initrd\fR, and the ext2 filesystem image to
\&\fIOUTPUTDIR/root\fR.  (Where \fIOUTPUTDIR\fR is specified by the \fI\-o\fR
option).
.Sp
The filesystem (\fIOUTPUTDIR/root\fR) has a default size of 4 GB
(see also the \fI\-\-size\fR option).
.RE
.RS 4
.RE
.IP "\fB\-\-host\-cpu\fR CPU" 4
.IX Item "--host-cpu CPU"
(\fI\-\-build\fR mode only)
.Sp
Specify the host CPU (eg. \f(CW\*(C`i686\*(C'\fR, \f(CW\*(C`x86_64\*(C'\fR).  This is used as a
substring match when searching for compatible kernels.  If not
specified, it defaults to the host CPU that supermin was compiled on.
.IP \fB\-\-if\-newer\fR 4
.IX Item "--if-newer"
(\fI\-\-build\fR mode only)
.Sp
The output directory is checked and it is \fInot\fR rebuilt unless it
needs to be.
.Sp
This is done by consulting the dates of the host package database
(\fI/var/lib/rpm\fR etc), the input supermin files, and the output
directory.  The operation is only carried out if either the host
package database or the input supermin files are newer than the output
directory.
.Sp
See also \fI\-\-lock\fR below.
.IP \fB\-\-include\-packagelist\fR 4
.IX Item "--include-packagelist"
(\fI\-\-build\fR mode only)
.Sp
Add a \fI/packagelist\fR file inside the generated chroot or ext2
filesystem, containing a sorted list of all the packages used to
build the appliance.
.Sp
Mostly useful for debugging, as it makes it easier to find out e.g.
which version of a package was copied in the appliance.
.IP \fB\-\-list\-drivers\fR 4
.IX Item "--list-drivers"
List the package manager drivers compiled into supermin, and whether
the corresponding package manager is detected on the current system.
.IP "\fB\-\-lock\fR LOCKFILE" 4
.IX Item "--lock LOCKFILE"
(\fI\-\-build\fR mode only)
.Sp
If multiple parallel runs of supermin need to build a full appliance,
then you can use the \fI\-\-lock\fR option to ensure they do not stomp on
each other.
.Sp
The lock file is used to provide mutual exclusion so only one instance
of supermin will run at a time.
.Sp
Note that the lock file \fBmust not\fR be stored inside the output
directory.
.IP "\fB\-o\fR OUTPUTDIR" 4
.IX Item "-o OUTPUTDIR"
Select the output directory.
.Sp
When using \fI\-\-prepare\fR, this is the directory where the supermin
appliance will be written.  When using \fI\-\-build\fR, this is the
directory where the full appliance, kernel etc will be written.
.Sp
\&\fBAny previous contents of the output directory are deleted\fR, and a
new output directory is created.
.Sp
The output directory is created (nearly) atomically by constructing a
temporary directory called something like \fIOUTPUTDIR.abc543\fR, then
renaming the old output directory (if present) and deleting it, and
then renaming the temporary directory to \fIOUTPUTDIR\fR.  By combining
this option with \fI\-\-lock\fR you can ensure that multiple parallel runs
of supermin do not conflict with each other.
.IP "\fB\-\-packager\-config\fR CONFIGFILE" 4
.IX Item "--packager-config CONFIGFILE"
(\fI\-\-prepare\fR mode only)
.Sp
Set the configuration file for the package manager.  This allows you
to specify alternate software repositories.
.Sp
For ArchLinux, this sets the pacman configuration file (default
\&\fI/etc/pacman.conf\fR).  See \fBpacman.conf\fR\|(5).
.Sp
For Yum/RPM distributions, this sets the yum configuration file
(default \fI/etc/yum.conf\fR).  See \fByum.conf\fR\|(5).
.IP \fB\-\-prepare\fR 4
.IX Item "--prepare"
Prepare the supermin appliance.
.IP \fB\-\-use\-installed\fR 4
.IX Item "--use-installed"
(\fI\-\-prepare\fR mode only)
.Sp
If packages are already installed, use the contents (from the local
filesystem) instead of downloading them.
.Sp
Note that this can cause malformed appliances if local files have been
changed from what was originally in the package.  This is particularly
a problem for configuration files.
.Sp
However this option is useful in some controlled situations: for
example when using supermin inside a freshly installed chroot, or if
you have no network access during the build.
.IP "\fB\-\-size\fR SIZE" 4
.IX Item "--size SIZE"
(\fI\-\-build\fR mode only)
.Sp
Select the size of the output ext2 filesystem, where the size can be
specified using common names such as \f(CW\*(C`32G\*(C'\fR (32 gigabytes) etc.
.Sp
If the size is not specified, a default size of 4 GB is used.
.Sp
To specify size in bytes, the number must be followed by the lowercase
letter \fIb\fR, eg: \f(CW\*(C`\-\-size\ 10737418240b\*(C'\fR.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
Enable verbose messages.
.Sp
You can give this option multiple times to enable even more messages:
.RS 4
.IP \fI\-v\fR 4
.IX Item "-v"
Debugging of overall stages.
.IP "\fI\-v \-v\fR" 4
.IX Item "-v -v"
Detailed information within each stage.
.IP "\fI\-v \-v \-v\fR" 4
.IX Item "-v -v -v"
Massive amounts of debugging (far too much for normal use, but good
if you are trying to diagnose a bug in supermin).
.RE
.RS 4
.RE
.IP \fB\-V\fR 4
.IX Item "-V"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
Print the package name and version number, and exit.
.SH "SUPERMIN APPLIANCES"
.IX Header "SUPERMIN APPLIANCES"
Supermin appliances consist of just enough information to be able to
build an appliance containing the same operating system (Linux
version, distro, release etc) as the host OS.  Since the host and
appliance share many common files such as \fI/bin/bash\fR and
\&\fI/lib/libc.so\fR there is no reason to ship these files in the
appliance.  They can simply be read from the host on demand when the
appliance is launched.  Therefore to save space we just store the
names of the packages we want from the host, and copy those in (plus
dependencies) at build time.
.PP
There are some files which cannot just be copied from the host in this
way.  These include configuration files which the host admin might
have edited.  So along with the list of host files, we also store a
skeleton base image which contains these files and the outline
directory structure.
.PP
Therefore the supermin appliance normally consists of at least two
control files (\fIpackages\fR and \fIbase.tar.gz\fR).
.IP \fIpackages\fR 4
.IX Item "packages"
The list of packages to be copied from the host.  Dependencies are
resolved automatically.
.Sp
The file is plain text, one package name per line.
.IP \fIbase.tar\fR 4
.IX Item "base.tar"
.PD 0
.IP \fIbase.tar.gz\fR 4
.IX Item "base.tar.gz"
.PD
This tar file (which may be compressed) contains the skeleton
filesystem.  Mostly it contains directories and a few configuration
files.
.Sp
All paths in the tar file should be relative to the root directory of
the appliance.
.IP \fIhostfiles\fR 4
.IX Item "hostfiles"
Any other files that are to be copied from the host.  This is a plain
text file with one pathname per line.
.Sp
Paths can contain wildcards, which are expanded when the appliance
is created, eg:
.Sp
.Vb 1
\& /etc/yum.repos.d/*.repo
.Ve
.Sp
would copy all of the \fI*.repo\fR files into the appliance.
.Sp
Each pathname in the file should start with a \f(CW\*(C`/\*(C'\fR character.
.Sp
Supermin itself does not create hostfiles (although before version\ 5, this was the main mechanism used to create the full appliance).
However you may drop one or more of these files into the supermin
appliance directory if you want to copy random unpackaged files into
the full appliance.
.IP \fIexcludefiles\fR 4
.IX Item "excludefiles"
A list of filenames, directory names, or wildcards prefixed by \f(CW\*(C`\-\*(C'\fR
which are excluded from the final appliance.
.Sp
This is rather brutal since it just removes things, potentially
breaking packages.  However it can be used as a convenient way to
minimize the size of the final appliance.
.Sp
Supermin itself does not create excludefiles.  However you may drop
one of more of these files into the supermin appliance directory to
stop packaged files from being copied into the full appliance.
.PP
Note that the names above are just suggestions.  You can use any names
you want, as supermin detects the contents of each file when it
reconstructs the appliance.  You can also have multiple of each type
of file.
.SS "RECONSTRUCTING THE APPLIANCE"
.IX Subsection "RECONSTRUCTING THE APPLIANCE"
The separate mode \f(CW\*(C`supermin \-\-build\*(C'\fR is used to reconstruct an
appliance from the supermin appliance files.
.PP
This program in fact iterates recursively over the files and
directories passed to it.  A common layout could look like this:
.PP
.Vb 5
\& supermin.d/
\& supermin.d/base.tar.gz
\& supermin.d/extra.tar.gz
\& supermin.d/packages
\& supermin.d/zz\-hostfiles
.Ve
.PP
In this way extra files can be added to the appliance just by creating
another tar file (\fIextra.tar.gz\fR in the example above) and dropping
it into the directory, and additional host files can be added
(\fIzz-hostfiles\fR in the example above).  When the appliance is
constructed, the extra files will appear in the appliance.
.SS "MINIMIZING THE SUPERMIN APPLIANCE"
.IX Subsection "MINIMIZING THE SUPERMIN APPLIANCE"
You may want to "minimize" the supermin appliance in order to save
time and space when it is instantiated.  Typically you might want to
remove documentation, info files, man pages and locales.
.PP
You can do this by creating an excludefiles that lists files,
directories or wildcards that you don't want to include.  They are
skipped when the full appliance is built.
.PP
.Vb 5
\& \-/boot/*
\& \-/lib/modules/*
\& \-/usr/share/doc/*
\& \-/usr/share/info/*
\& \-/usr/share/man/*
.Ve
.PP
Be careful what you remove because files may be necessary for correct
operation of the appliance.
.SS "KERNEL AND KERNEL MODULES"
.IX Subsection "KERNEL AND KERNEL MODULES"
Usually the kernel and kernel modules are \fInot\fR included in the
supermin appliance.
.PP
When the full appliance is built, the kernel modules from the host are
copied in, and it is booted using the host kernel.
.PP
\fIUSING A CUSTOM KERNEL AND KERNEL MODULES\fR
.IX Subsection "USING A CUSTOM KERNEL AND KERNEL MODULES"
.PP
Supermin is able to choose the best host kernel available to boot the
appliance.  However you can override this by setting environment
variables (see "ENVIRONMENT VARIABLES" below).
.PP
If you build a custom kernel (eg. by compiling Linux from source),
then you should do something like this:
.PP
.Vb 4
\& mkdir /tmp/kmods
\& make bzImage
\& make modules
\& make modules_install INSTALL_MOD_PATH=/tmp/kmods
\& 
\& export SUPERMIN_KERNEL=/path/to/linux.git/arch/x86/boot/bzImage
\& export SUPERMIN_MODULES=/tmp/kmods/lib/modules/3.xx.yy
\& 
\& supermin \-\-build \-f ext2 [etc]
.Ve
.SS "ENFORCING AVAILABILITY OF PACKAGES"
.IX Subsection "ENFORCING AVAILABILITY OF PACKAGES"
Supermin builds the appliance by copying in the packages listed in
\&\fIpackages\fR.  For this to work those packages must be available.  We
usually enforce this by adding requirements (eg. RPM \f(CW\*(C`Requires:\*(C'\fR
lines) on the package that uses the supermin appliance, so that
package cannot be installed without pulling in the dependent packages
and thus making sure the packages are installed for supermin to use.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.IP SUPERMIN_KERNEL 4
.IX Item "SUPERMIN_KERNEL"
If this environment variable is set, then automatic selection of the
kernel is bypassed and this kernel is used.
.Sp
The environment variable should point to a kernel file,
eg. \fI/boot/vmlinuz\-3.0.x86_64\fR
.IP SUPERMIN_MODULES 4
.IX Item "SUPERMIN_MODULES"
This specifies the kernel modules directory to use.
.Sp
The environment variable should point to a module directory,
eg. \fI/lib/modules/3.0.x86_64/\fR
.IP SUPERMIN_KERNEL_VERSION 4
.IX Item "SUPERMIN_KERNEL_VERSION"
On non\-x86 architectures, you may need to set this environment
variable if supermin cannot determine the kernel version of
\&\f(CW\*(C`SUPERMIN_KERNEL\*(C'\fR just by looking at the file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://people.redhat.com/~rjones/supermin/>,
\&\fBguestfs\fR\|(3),
<http://libguestfs.org/>.
.SH AUTHORS
.IX Header "AUTHORS"
.IP \(bu 4
Richard W.M. Jones <http://people.redhat.com/~rjones/>
.IP \(bu 4
Matthew Booth
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2016 Red Hat Inc.
.PP
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.
.PP
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.
.PP
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., 675 Mass Ave, Cambridge, MA 02139, USA.