1SUPERMIN(1) Virtualization Support SUPERMIN(1)
2
6 supermin - Tool for creating and building supermin appliances
7
9 supermin --prepare -o OUTPUTDIR PACKAGE [PACKAGE ...]
10 supermin --build -o OUTPUTDIR -f chroot|ext2 INPUT [INPUT ...]
12
14 supermin --prepare bash -o /tmp/supermin.d
15 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 chmod +x init
25 tar zcf /tmp/supermin.d/init.tar.gz ./init
26 supermin --build /tmp/supermin.d -f ext2 -o /tmp/appliance.d
28 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
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 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 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 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 PREPARE MODE
60 --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 For example:
67 supermin --prepare bash coreutils -o supermin.d
69 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 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 BUILD MODE
80 --build (previously a separate program called "supermin-helper") builds
82 the full appliance from the supermin appliance:
83 supermin --build --format ext2 supermin.d -o appliance.d
85 This will create files called appliance.d/kernel, appliance.d/root etc,
87 which is the full sized bootable appliance.
88 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 Build and cache
95 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 supermin --build \
100 --if-newer --lock /run/user/`id -u`/supermin.lock \
101 --format ext2 supermin.d -o appliance.d
102 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 Note that the lock file must not be stored inside the -o directory.
109 PACKAGES
111 By "package" we mean the RPM, Debian, (etc.) package, eg. "coreutils",
113 "perl".
114 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
120 --help
121 Display brief command line usage, and exit.
122 --build
124 Build the full appliance from the supermin appliance. This used to
125 be a separate program called "supermin-helper".
126 --copy-kernel
128 (--build mode only)
129 Copy the kernel (and device tree, if created) instead of symlinking
131 to the kernel in /boot.
132 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 -f FORMAT
137 --format FORMAT
138 (--build mode only)
139 Select the output format for the full appliance.
141 There is no default. When using --build you must specify the
143 --format option.
144 Possible formats are:
146 chroot
148 A directory tree in the host filesystem.
149 The filesystem tree is written to OUTPUTDIR (ie. the -o
151 option).
152 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 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 ext2
162 An ext2 filesystem disk image.
163 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 The filesystem (OUTPUTDIR/root) has a default size of 4 GB (see
170 also the --size option).
171 --host-cpu CPU
173 (--build mode only)
174 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 --if-newer
181 (--build mode only)
182 The output directory is checked and it is not rebuilt unless it
184 needs to be.
185 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 See also --lock below.
193 --include-packagelist
195 (--build mode only)
196 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 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 --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 --lock LOCKFILE
210 (--build mode only)
211 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 The lock file is used to provide mutual exclusion so only one
217 instance of supermin will run at a time.
218 Note that the lock file must not be stored inside the output
220 directory.
221 -o OUTPUTDIR
223 Select the output directory.
224 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 Any previous contents of the output directory are deleted, and a
230 new output directory is created.
231 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 --packager-config CONFIGFILE
240 (--prepare mode only)
241 Set the configuration file for the package manager. This allows
243 you to specify alternate software repositories.
244 For ArchLinux, this sets the pacman configuration file (default
246 /etc/pacman.conf). See pacman.conf(5).
247 For Yum/RPM distributions, this sets the yum configuration file
249 (default /etc/yum.conf). See yum.conf(5).
250 --prepare
252 Prepare the supermin appliance.
253 --use-installed
255 (--prepare mode only)
256 If packages are already installed, use the contents (from the local
258 filesystem) instead of downloading them.
259 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 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 --size SIZE
269 (--build mode only)
270 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 If the size is not specified, a default size of 4 GB is used.
275 To specify size in bytes, the number must be followed by the
277 lowercase letter b, eg: "--size 10737418240b".
278 -v
280 --verbose
281 Enable verbose messages.
282 You can give this option multiple times to enable even more
284 messages:
285 -v Debugging of overall stages.
287 -v -v
289 Detailed information within each stage.
290 -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 -V
296 --version
297 Print the package name and version number, and exit.
298
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 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 Therefore the supermin appliance normally consists of at least two
316 control files (packages and base.tar.gz).
317 packages
319 The list of packages to be copied from the host. Dependencies are
320 resolved automatically.
321 The file is plain text, one package name per line.
323 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 All paths in the tar file should be relative to the root directory
331 of the appliance.
332 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 Paths can contain wildcards, which are expanded when the appliance
338 is created, eg:
339 /etc/yum.repos.d/*.repo
341 would copy all of the *.repo files into the appliance.
343 Each pathname in the file should start with a "/" character.
345 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 excludefiles
353 A list of filenames, directory names, or wildcards prefixed by "-"
354 which are excluded from the final appliance.
355 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 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 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 RECONSTRUCTING THE APPLIANCE
370 The separate mode "supermin --build" is used to reconstruct an
371 appliance from the supermin appliance files.
372 This program in fact iterates recursively over the files and
374 directories passed to it. A common layout could look like this:
375 supermin.d/
377 supermin.d/base.tar.gz
378 supermin.d/extra.tar.gz
379 supermin.d/packages
380 supermin.d/zz-hostfiles
381 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 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 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 -/boot/*
398 -/lib/modules/*
399 -/usr/share/doc/*
400 -/usr/share/info/*
401 -/usr/share/man/*
402 Be careful what you remove because files may be necessary for correct
404 operation of the appliance.
405 KERNEL AND KERNEL MODULES
407 Usually the kernel and kernel modules are not included in the supermin
408 appliance.
409 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 USING A CUSTOM KERNEL AND KERNEL MODULES
414 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 If you build a custom kernel (eg. by compiling Linux from source), then
420 you should do something like this:
421 mkdir /tmp/kmods
423 make bzImage
424 make modules
425 make modules_install INSTALL_MOD_PATH=/tmp/kmods
426 export SUPERMIN_KERNEL=/path/to/linux.git/arch/x86/boot/bzImage
428 export SUPERMIN_MODULES=/tmp/kmods/lib/modules/3.xx.yy
429 supermin --build -f ext2 [etc]
431 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
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 The environment variable should point to a kernel file, eg.
446 /boot/vmlinuz-3.0.x86_64
447 SUPERMIN_MODULES
449 This specifies the kernel modules directory to use.
450 The environment variable should point to a module directory, eg.
452 /lib/modules/3.0.x86_64/
453 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
460 <http://people.redhat.com/~rjones/supermin/>, guestfs(3),
461 <http://libguestfs.org/>.
462
464 · Richard W.M. Jones <http://people.redhat.com/~rjones/>
465 · Matthew Booth
467
469 Copyright (C) 2009-2016 Red Hat Inc.
470 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 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 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.
484supermin-5.1.17 2016-12-07 SUPERMIN(1)