1SUPERMIN(1)                 Virtualization Support                 SUPERMIN(1)
2
3
4

NAME

6       supermin - Tool for creating and building supermin appliances
7

SYNOPSIS

9        supermin --prepare -o OUTPUTDIR PACKAGE [PACKAGE ...]
10
11        supermin --build -o OUTPUTDIR -f chroot|ext2 INPUT [INPUT ...]
12

EXAMPLE

14        supermin --prepare bash -o /tmp/supermin.d
15
16        cat > init <<EOF
17        #!/bin/sh
18        mount -t proc /proc /proc
19        mount -t sysfs /sys /sys
20        echo Welcome to supermin
21        bash -i
22        EOF
23
24        chmod +x init
25        tar zcf /tmp/supermin.d/init.tar.gz ./init
26
27        supermin --build /tmp/supermin.d -f ext2 -o /tmp/appliance.d
28
29        qemu-kvm -nodefaults -nographic \
30                 -kernel /tmp/appliance.d/kernel \
31                 -initrd /tmp/appliance.d/initrd \
32                 -hda /tmp/appliance.d/root \
33                 -serial stdio -append "console=ttyS0"
34        ...
35        Welcome to supermin
36        bash-4.3#
37

DESCRIPTION

39       Supermin is a tool for building supermin appliances.  These are tiny
40       appliances (similar to virtual machines), usually around 100KB in size,
41       which get fully instantiated on-the-fly in a fraction of a second when
42       you need to boot one of them.
43
44       This program used to be called febootstrap.  This manual page documents
45       supermin 5.x which is a complete rewrite and quite different from
46       febootstrap 2.x.  If you are looking for the febootstrap 2.x tools,
47       then this is not the right place.
48
49   BASIC OPERATION
50       The supermin tool can be used in two modes, preparing a tiny supermin
51       appliance, which is done on a build system.  And building, which takes
52       the supermin appliance and constructs a full, bootable appliance, which
53       is done on the end user's system.
54
55       Supermin does not need to be run as root, and generally should not be
56       run as root.  It does not affect the host system or the packages
57       installed on the host system.
58
59       PREPARE MODE
60
61       --prepare creates the tiny supermin appliance in the given output
62       directory.  You give it a list of packages that you want installed, and
63       supermin will automatically find the dependencies.  The list of
64       packages has to be installed on the host machine.
65
66       For example:
67
68        supermin --prepare bash coreutils -o supermin.d
69
70       creates a supermin appliance containing the packages "bash" and
71       "coreutils".  Specifically, it creates some files in directory
72       supermin.d.  This directory is the supermin appliance.  (See "SUPERMIN
73       APPLIANCES" below).
74
75       It is intended that the --prepare step is done on a central build
76       machine, and the supermin appliance is distributed to end users (which
77       is easy because supermin appliances are so small).
78
79       BUILD MODE
80
81       --build (previously a separate program called "supermin-helper") builds
82       the full appliance from the supermin appliance:
83
84        supermin --build --format ext2 supermin.d -o appliance.d
85
86       This will create files called appliance.d/kernel, appliance.d/root etc,
87       which is the full sized bootable appliance.
88
89       It is intended that the --build step is done on the end user's machine
90       at the last second before the appliance is needed.  The packages in the
91       supermin appliance (those specified when the supermin appliance was
92       prepared) must be installed on the end user's machine.
93
94       Build and cache
95
96       Typically you want to rebuild the appliance on the end user machine
97       only on demand.  Supermin has some extra options to make this easy:
98
99        supermin --build \
100          --if-newer --lock /run/user/`id -u`/supermin.lock \
101          --format ext2 supermin.d -o appliance.d
102
103       If multiple programs run this command in parallel, the instances will
104       wait on the lock file.  The full appliance only gets rebuilt if it
105       doesn't exist or if it is older than the input files and host package
106       database.
107
108       Note that the lock file must not be stored inside the -o directory.
109
110       PACKAGES
111
112       By "package" we mean the RPM, Debian, (etc.) package, eg. "coreutils",
113       "perl".
114
115       In all cases supermin can only build a supermin appliance which is
116       identical in distro, version and architecture to the host.  It does not
117       do cross-builds.
118

OPTIONS

120       --help
121           Display brief command line usage, and exit.
122
123       --build
124           Build the full appliance from the supermin appliance.  This used to
125           be a separate program called "supermin-helper".
126
127       --copy-kernel
128           (--build mode only)
129
130           Copy the kernel (and device tree, if created) instead of symlinking
131           to the kernel in /boot.
132
133           This is fractionally slower, but is necessary if you want to change
134           the permissions or SELinux label on the kernel or device tree.
135
136       -f FORMAT
137       --format FORMAT
138           (--build mode only)
139
140           Select the output format for the full appliance.
141
142           There is no default.  When using --build you must specify the
143           --format option.
144
145           Possible formats are:
146
147           chroot
148               A directory tree in the host filesystem.
149
150               The filesystem tree is written to OUTPUTDIR (ie. the -o
151               option).
152
153               This is called a "chroot" because you could literally chroot(1)
154               into this directory afterwards, although it's a better idea to
155               use a container technology (LXC, etc.).
156
157               No kernel or initrd is generated in this mode because it is
158               assumed that you will be running the appliance using the host
159               kernel.
160
161           ext2
162               An ext2 filesystem disk image.
163
164               The output kernel is written to OUTPUTDIR/kernel, a small
165               initramfs which can mount the appliance to OUTPUTDIR/initrd,
166               and the ext2 filesystem image to OUTPUTDIR/root.  (Where
167               OUTPUTDIR is specified by the -o option).
168
169               The filesystem (OUTPUTDIR/root) has a default size of 4 GB (see
170               also the --size option).
171
172       --host-cpu CPU
173           (--build mode only)
174
175           Specify the host CPU (eg. "i686", "x86_64").  This is used as a
176           substring match when searching for compatible kernels.  If not
177           specified, it defaults to the host CPU that supermin was compiled
178           on.
179
180       --if-newer
181           (--build mode only)
182
183           The output directory is checked and it is not rebuilt unless it
184           needs to be.
185
186           This is done by consulting the dates of the host package database
187           (/var/lib/rpm etc), the input supermin files, and the output
188           directory.  The operation is only carried out if either the host
189           package database or the input supermin files are newer than the
190           output directory.
191
192           See also --lock below.
193
194       --include-packagelist
195           (--build mode only)
196
197           Add a /packagelist file inside the generated chroot or ext2
198           filesystem, containing a sorted list of all the packages used to
199           build the appliance.
200
201           Mostly useful for debugging, as it makes it easier to find out e.g.
202           which version of a package was copied in the appliance.
203
204       --list-drivers
205           List the package manager drivers compiled into supermin, and
206           whether the corresponding package manager is detected on the
207           current system.
208
209       --lock LOCKFILE
210           (--build mode only)
211
212           If multiple parallel runs of supermin need to build a full
213           appliance, then you can use the --lock option to ensure they do not
214           stomp on each other.
215
216           The lock file is used to provide mutual exclusion so only one
217           instance of supermin will run at a time.
218
219           Note that the lock file must not be stored inside the output
220           directory.
221
222       -o OUTPUTDIR
223           Select the output directory.
224
225           When using --prepare, this is the directory where the supermin
226           appliance will be written.  When using --build, this is the
227           directory where the full appliance, kernel etc will be written.
228
229           Any previous contents of the output directory are deleted, and a
230           new output directory is created.
231
232           The output directory is created (nearly) atomically by constructing
233           a temporary directory called something like OUTPUTDIR.abc543, then
234           renaming the old output directory (if present) and deleting it, and
235           then renaming the temporary directory to OUTPUTDIR.  By combining
236           this option with --lock you can ensure that multiple parallel runs
237           of supermin do not conflict with each other.
238
239       --packager-config CONFIGFILE
240           (--prepare mode only)
241
242           Set the configuration file for the package manager.  This allows
243           you to specify alternate software repositories.
244
245           For ArchLinux, this sets the pacman configuration file (default
246           /etc/pacman.conf).  See pacman.conf(5).
247
248           For Yum/RPM distributions, this sets the yum configuration file
249           (default /etc/yum.conf).  See yum.conf(5).
250
251       --prepare
252           Prepare the supermin appliance.
253
254       --use-installed
255           (--prepare mode only)
256
257           If packages are already installed, use the contents (from the local
258           filesystem) instead of downloading them.
259
260           Note that this can cause malformed appliances if local files have
261           been changed from what was originally in the package.  This is
262           particularly a problem for configuration files.
263
264           However this option is useful in some controlled situations: for
265           example when using supermin inside a freshly installed chroot, or
266           if you have no network access during the build.
267
268       --size SIZE
269           (--build mode only)
270
271           Select the size of the output ext2 filesystem, where the size can
272           be specified using common names such as "32G" (32 gigabytes) etc.
273
274           If the size is not specified, a default size of 4 GB is used.
275
276           To specify size in bytes, the number must be followed by the
277           lowercase letter b, eg: "--size 10737418240b".
278
279       -v
280       --verbose
281           Enable verbose messages.
282
283           You can give this option multiple times to enable even more
284           messages:
285
286           -v  Debugging of overall stages.
287
288           -v -v
289               Detailed information within each stage.
290
291           -v -v -v
292               Massive amounts of debugging (far too much for normal use, but
293               good if you are trying to diagnose a bug in supermin).
294
295       -V
296       --version
297           Print the package name and version number, and exit.
298

SUPERMIN APPLIANCES

300       Supermin appliances consist of just enough information to be able to
301       build an appliance containing the same operating system (Linux version,
302       distro, release etc) as the host OS.  Since the host and appliance
303       share many common files such as /bin/bash and /lib/libc.so there is no
304       reason to ship these files in the appliance.  They can simply be read
305       from the host on demand when the appliance is launched.  Therefore to
306       save space we just store the names of the packages we want from the
307       host, and copy those in (plus dependencies) at build time.
308
309       There are some files which cannot just be copied from the host in this
310       way.  These include configuration files which the host admin might have
311       edited.  So along with the list of host files, we also store a skeleton
312       base image which contains these files and the outline directory
313       structure.
314
315       Therefore the supermin appliance normally consists of at least two
316       control files (packages and base.tar.gz).
317
318       packages
319           The list of packages to be copied from the host.  Dependencies are
320           resolved automatically.
321
322           The file is plain text, one package name per line.
323
324       base.tar
325       base.tar.gz
326           This tar file (which may be compressed) contains the skeleton
327           filesystem.  Mostly it contains directories and a few configuration
328           files.
329
330           All paths in the tar file should be relative to the root directory
331           of the appliance.
332
333       hostfiles
334           Any other files that are to be copied from the host.  This is a
335           plain text file with one pathname per line.
336
337           Paths can contain wildcards, which are expanded when the appliance
338           is created, eg:
339
340            /etc/yum.repos.d/*.repo
341
342           would copy all of the *.repo files into the appliance.
343
344           Each pathname in the file should start with a "/" character.
345
346           Supermin itself does not create hostfiles (although before
347           version 5, this was the main mechanism used to create the full
348           appliance).  However you may drop one or more of these files into
349           the supermin appliance directory if you want to copy random
350           unpackaged files into the full appliance.
351
352       excludefiles
353           A list of filenames, directory names, or wildcards prefixed by "-"
354           which are excluded from the final appliance.
355
356           This is rather brutal since it just removes things, potentially
357           breaking packages.  However it can be used as a convenient way to
358           minimize the size of the final appliance.
359
360           Supermin itself does not create excludefiles.  However you may drop
361           one of more of these files into the supermin appliance directory to
362           stop packaged files from being copied into the full appliance.
363
364       Note that the names above are just suggestions.  You can use any names
365       you want, as supermin detects the contents of each file when it
366       reconstructs the appliance.  You can also have multiple of each type of
367       file.
368
369   RECONSTRUCTING THE APPLIANCE
370       The separate mode "supermin --build" is used to reconstruct an
371       appliance from the supermin appliance files.
372
373       This program in fact iterates recursively over the files and
374       directories passed to it.  A common layout could look like this:
375
376        supermin.d/
377        supermin.d/base.tar.gz
378        supermin.d/extra.tar.gz
379        supermin.d/packages
380        supermin.d/zz-hostfiles
381
382       In this way extra files can be added to the appliance just by creating
383       another tar file (extra.tar.gz in the example above) and dropping it
384       into the directory, and additional host files can be added (zz-
385       hostfiles in the example above).  When the appliance is constructed,
386       the extra files will appear in the appliance.
387
388   MINIMIZING THE SUPERMIN APPLIANCE
389       You may want to "minimize" the supermin appliance in order to save time
390       and space when it is instantiated.  Typically you might want to remove
391       documentation, info files, man pages and locales.
392
393       You can do this by creating an excludefiles that lists files,
394       directories or wildcards that you don't want to include.  They are
395       skipped when the full appliance is built.
396
397        -/boot/*
398        -/lib/modules/*
399        -/usr/share/doc/*
400        -/usr/share/info/*
401        -/usr/share/man/*
402
403       Be careful what you remove because files may be necessary for correct
404       operation of the appliance.
405
406   KERNEL AND KERNEL MODULES
407       Usually the kernel and kernel modules are not included in the supermin
408       appliance.
409
410       When the full appliance is built, the kernel modules from the host are
411       copied in, and it is booted using the host kernel.
412
413       USING A CUSTOM KERNEL AND KERNEL MODULES
414
415       Supermin is able to choose the best host kernel available to boot the
416       appliance.  However you can override this by setting environment
417       variables (see "ENVIRONMENT VARIABLES" below).
418
419       If you build a custom kernel (eg. by compiling Linux from source), then
420       you should do something like this:
421
422        mkdir /tmp/kmods
423        make bzImage
424        make modules
425        make modules_install INSTALL_MOD_PATH=/tmp/kmods
426
427        export SUPERMIN_KERNEL=/path/to/linux.git/arch/x86/boot/bzImage
428        export SUPERMIN_MODULES=/tmp/kmods/lib/modules/3.xx.yy
429
430        supermin --build -f ext2 [etc]
431
432   ENFORCING AVAILABILITY OF PACKAGES
433       Supermin builds the appliance by copying in the packages listed in
434       packages.  For this to work those packages must be available.  We
435       usually enforce this by adding requirements (eg. RPM "Requires:" lines)
436       on the package that uses the supermin appliance, so that package cannot
437       be installed without pulling in the dependent packages and thus making
438       sure the packages are installed for supermin to use.
439

ENVIRONMENT VARIABLES

441       SUPERMIN_KERNEL
442           If this environment variable is set, then automatic selection of
443           the kernel is bypassed and this kernel is used.
444
445           The environment variable should point to a kernel file, eg.
446           /boot/vmlinuz-3.0.x86_64
447
448       SUPERMIN_MODULES
449           This specifies the kernel modules directory to use.
450
451           The environment variable should point to a module directory, eg.
452           /lib/modules/3.0.x86_64/
453
454       SUPERMIN_KERNEL_VERSION
455           On non-x86 architectures, you may need to set this environment
456           variable if supermin cannot determine the kernel version of
457           "SUPERMIN_KERNEL" just by looking at the file.
458

SEE ALSO

460       <http://people.redhat.com/~rjones/supermin/>, guestfs(3),
461       <http://libguestfs.org/>.
462

AUTHORS

464       ·   Richard W.M. Jones <http://people.redhat.com/~rjones/>
465
466       ·   Matthew Booth
467
469       Copyright (C) 2009-2016 Red Hat Inc.
470
471       This program is free software; you can redistribute it and/or modify it
472       under the terms of the GNU General Public License as published by the
473       Free Software Foundation; either version 2 of the License, or (at your
474       option) any later version.
475
476       This program is distributed in the hope that it will be useful, but
477       WITHOUT ANY WARRANTY; without even the implied warranty of
478       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
479       General Public License for more details.
480
481       You should have received a copy of the GNU General Public License along
482       with this program; if not, write to the Free Software Foundation, Inc.,
483       675 Mass Ave, Cambridge, MA 02139, USA.
484
485
486
487supermin-5.1.17                   2016-12-07                       SUPERMIN(1)
Impressum