NAME¶

SYNOPSIS¶

 supermin --prepare -o OUTPUTDIR PACKAGE [PACKAGE ...]

 supermin --build -o OUTPUTDIR -f chroot|ext2 INPUT [INPUT ...]

EXAMPLE¶

 supermin --prepare bash util-linux -o /tmp/supermin.d
 
 cat > init <<EOF
 #!/bin/sh
 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-kvm -nodefaults -nographic \
          -kernel /tmp/appliance.d/kernel \
          -initrd /tmp/appliance.d/initrd \
          -hda /tmp/appliance.d/root \
          -serial stdio -append "console=ttyS0 root=/dev/sda"
 ...
 Welcome to supermin
 bash-4.3#

DESCRIPTION¶

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.

 supermin --prepare bash coreutils -o supermin.d

 supermin --build --format ext2 supermin.d -o appliance.d

 supermin --build \
   --if-newer --lock /run/user/`id -u`/supermin.lock \
   --format ext2 supermin.d -o appliance.d

OPTIONS¶

--help

Display brief command line usage, and exit.

--build

Build the full appliance from the supermin appliance. This used to be a separate program called "supermin-helper".

--copy-kernel

(--build mode only)

Copy the kernel (and device tree, if created) instead of symlinking to the kernel in /boot.

This is fractionally slower, but is necessary if you want to change the permissions or SELinux label on the kernel or device tree.

-f FORMAT

--format FORMAT

(--build mode only)

Select the output format for the full appliance.

There is no default. When using --build you must specify the --format option.

Possible formats are:

--host-cpu CPU

(--build mode only)

Specify the host CPU (eg. "i686", "x86_64"). 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.

--if-newer

(--build mode only)

The output directory is checked and it is not rebuilt unless it needs to be.

This is done by consulting the dates of the host package database (/var/lib/rpm 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.

See also --lock below.

--include-packagelist

(--build mode only)

Add a /packagelist file inside the generated chroot or ext2 filesystem, containing a sorted list of all the packages used to build the appliance.

Mostly useful for debugging, as it makes it easier to find out e.g. which version of a package was copied in the appliance.

--list-drivers

List the package manager drivers compiled into supermin, and whether the corresponding package manager is detected on the current system.

--lock LOCKFILE

(--build mode only)

If multiple parallel runs of supermin need to build a full appliance, then you can use the --lock option to ensure they do not stomp on each other.

The lock file is used to provide mutual exclusion so only one instance of supermin will run at a time.

Note that the lock file must not be stored inside the output directory.

-o OUTPUTDIR

Select the output directory.

When using --prepare, this is the directory where the supermin appliance will be written. When using --build, this is the directory where the full appliance, kernel etc will be written.

Any previous contents of the output directory are deleted, and a new output directory is created.

The output directory is created (nearly) atomically by constructing a temporary directory called something like OUTPUTDIR.abc543, then renaming the old output directory (if present) and deleting it, and then renaming the temporary directory to OUTPUTDIR. By combining this option with --lock you can ensure that multiple parallel runs of supermin do not conflict with each other.

--packager-config CONFIGFILE

(--prepare mode only)

Set the configuration file for the package manager. This allows you to specify alternate software repositories.

For ArchLinux, this sets the pacman configuration file (default /etc/pacman.conf). See pacman.conf(5).

For Yum/RPM distributions, this sets the yum configuration file (default /etc/yum.conf). See yum.conf(5).

--prepare

Prepare the supermin appliance.

--use-installed

(--prepare mode only)

If packages are already installed, use the contents (from the local filesystem) instead of downloading them.

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.

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.

--size SIZE

(--build mode only)

Select the size of the output ext2 filesystem, where the size can be specified using common names such as "32G" (32 gigabytes) etc.

If the size is not specified, a default size of 4 GB is used.

To specify size in bytes, the number must be followed by the lowercase letter b, eg: "--size 10737418240b".

-v

--verbose

Enable verbose messages.

You can give this option multiple times to enable even more messages:

-V

--version

Print the package name and version number, and exit.

SUPERMIN APPLIANCES¶

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.

Therefore the supermin appliance normally consists of at least two control files (packages and base.tar.gz).

packages

The list of packages to be copied from the host. Dependencies are resolved automatically.

The file is plain text, one package name per line.

base.tar

base.tar.gz

This tar file (which may be compressed) contains the skeleton filesystem. Mostly it contains directories and a few configuration files.

All paths in the tar file should be relative to the root directory of the appliance.

hostfiles

Any other files that are to be copied from the host. This is a plain text file with one pathname per line.

Paths can contain wildcards, which are expanded when the appliance is created, eg:

 /etc/yum.repos.d/*.repo
    

would copy all of the *.repo files into the appliance.

Each pathname in the file should start with a "/" character.

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.

excludefiles

A list of filenames, directory names, or wildcards prefixed by "-" which are excluded from the final appliance.

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.

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.

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.

 supermin.d/
 supermin.d/base.tar.gz
 supermin.d/extra.tar.gz
 supermin.d/packages
 supermin.d/zz-hostfiles

 -/boot/*
 -/lib/modules/*
 -/usr/share/doc/*
 -/usr/share/info/*
 -/usr/share/man/*

 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]

ENVIRONMENT VARIABLES¶

SUPERMIN_KERNEL

If this environment variable is set, then automatic selection of the kernel is bypassed and this kernel is used.

The environment variable should point to a kernel file, eg. /boot/vmlinuz-3.0.x86_64

SUPERMIN_MODULES

This specifies the kernel modules directory to use.

The environment variable should point to a module directory, eg. /lib/modules/3.0.x86_64/

SUPERMIN_KERNEL_VERSION

On non-x86 architectures, you may need to set this environment variable if supermin cannot determine the kernel version of "SUPERMIN_KERNEL" just by looking at the file.

SEE ALSO¶

AUTHORS¶

• Richard W.M. Jones <http://people.redhat.com/~rjones/>
• Matthew Booth

COPYRIGHT¶

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., 675 Mass Ave, Cambridge, MA 02139, USA.