1SUPERMIN(8) Virtualization Support SUPERMIN(8)
2
6 supermin - Tool for creating supermin appliances
7
9 supermin [-o OUTPUTDIR] --names LIST OF PKGS ...
10 supermin [-o OUTPUTDIR] PKG FILE NAMES ...
11
13 Supermin is a tool for building supermin appliances. These are tiny
14 appliances (similar to virtual machines), usually around 100KB in size,
15 which get fully instantiated on-the-fly in a fraction of a second when
16 you need to boot one of them.
17 Originally "fe" in "febootstrap" stood for "Fedora", but this tool is
19 now distro-independent and can build supermin appliances for several
20 popular Linux distros, and adding support for others is reasonably
21 easy. For this reason, starting with version 4, we have renamed the
22 tool "supermin".
23 Note that this manual page documents supermin 4.x which is a complete
25 rewrite and quite different from febootstrap 2.x. If you are looking
26 for the febootstrap 2.x tools, then this is not the right place.
27 BASIC OPERATION
29 There are two modes for using supermin. With the --names parameter,
30 supermin takes a list of package names and creates a supermin appliance
31 containing those packages and all dependencies that those packages
32 require. In this mode supermin usually needs network access because it
33 may need to consult package repositories in order to work out
34 dependencies and download packages.
35 Without --names, supermin takes a list of packages (ie. filenames of
37 locally available packages). This package set must be complete and
38 consistent with no dependencies outside the set of packages you
39 provide. In this mode supermin does not require any network access.
40 It works by looking at the package files themselves.
41 By "package" we mean the RPM, DEB, (etc.) package. A package name
43 might be the fully qualified name (eg. "coreutils-8.5-7.fc14.x86_64")
44 or some abbreviation (eg. "coreutils"). The precise format of the name
45 and what abbreviations are allowed depends on the package manager.
46 The supermin appliance that supermin writes consists of two files
48 called "hostfiles" and "base.img" (see "SUPERMIN APPLIANCES" below).
49 By default these are written to the current directory. If you specify
50 the -o OUTPUTDIR option then these files are written to the named
51 directory instead (traditionally this directory is named "supermin.d"
52 but you can call it whatever you want).
53 In all cases supermin can only build a supermin appliance which is
55 identical in distro, version and architecture to the host. It does not
56 do cross-builds.
57
59 --help
60 Display brief command line usage, and exit.
61 --exclude REGEXP
63 After doing dependency resolution, exclude packages which match the
64 regular expression.
65 This option is only used with --names, and it can be given multiple
67 times on the command line.
68 --names
70 Provide a list of package names, instead of providing packages
71 directly. In this mode supermin may require network access. See
72 "BASIC OPERATION" above.
73 --no-warnings
75 Don't print warnings about packaging problems.
76 -o outputdir
78 Select the output directory where the two supermin appliance files
79 are written ("hostfiles" and "base.img"). The default directory is
80 the current directory. Note that if this files exist already in
81 the output directory then they will be overwritten.
82 --packager-config CONFIGFILE
84 Set the configuration file for the package manager. This allows
85 you to specify alternate software repositories.
86 For ArchLinux, this sets the pacman configuration file (default
88 "/etc/pacman.conf"). See pacman.conf(5).
89 For Yum/RPM distributions, this sets the yum configuration file
91 (default "/etc/yum.conf"). See yum.conf(5).
92 --save-temps
94 Don't remove temporary files and directories on exit. This is
95 useful for debugging.
96 --use-installed
98 If packages are already installed, use the contents (from the local
99 filesystem) instead of downloading them.
100 Note that this can cause malformed appliances if local files have
102 been changed from what was originally in the package. This is
103 particularly a problem for configuration files.
104 However this option is useful in some controlled situations: for
106 example when using supermin inside a freshly installed chroot.
107 -v
109 --verbose
110 Enable verbose messages.
111 -V
113 --version
114 Print the package name and version number, and exit.
115 --yum-config CONFIGFILE
117 This is a deprecated alias for --packager-config CONFIGFILE.
118
120 Supermin appliances consist of just enough information to be able to
121 build an appliance containing the same operating system (Linux version,
122 distro, release etc) as the host OS. Since the host and appliance
123 share many common files such as "/bin/bash" and "/lib/libc.so" there is
124 no reason to ship these files in the appliance. They can simply be
125 read from the host on demand when the appliance is launched. Therefore
126 to save space we just store the names of the host files that we want.
127 There are some files which cannot just be copied from the host in this
129 way. These include configuration files which the host admin might have
130 edited. So along with the list of host files, we also store a skeleton
131 base image which contains these files and the outline directory
132 structure.
133 Therefore the supermin appliance normally consists of at least two
135 control files:
136 hostfiles
138 The list of files that are to be copied from the host. This is a
139 plain text file with one pathname per line. Directories are
140 included in this file.
141 Paths can contain wildcards, which are expanded when the appliance
143 is created, eg:
144 /etc/yum.repos.d/*.repo
146 would copy all of the "*.repo" files into the appliance.
148 Each pathname in the file should start with a "/" character. (In
150 older versions of febootstrap, paths started with "./" and were
151 relative to the root directory, but you should not do that in new
152 files).
153 base.img
155 This uncompressed cpio file contains the skeleton filesystem.
156 Mostly it contains directories and a few configuration files.
157 All paths in the cpio file should be relative to the root directory
159 of the appliance.
160 Note that unlike "hostfiles", paths and directories in the base
162 image don't need to have any relationship to the host filesystem.
163 base.img.gz
165 Since supermin ≥ 4.1.4, any cpio image files may be gzip-compressed
166 to save disk space. "hostfiles" cannot be compressed. The
167 supermin program won't create these files. You need to compress
168 the output yourself, eg by doing:
169 gzip -9 supermin.d/*.img
171 RECONSTRUCTING THE APPLIANCE
173 The separate tool supermin-helper(8) is used to reconstruct an
174 appliance from the hostfiles and base image files.
175 This program in fact iterates recursively over the files and
177 directories passed to it. A common layout is:
178 supermin.d/
180 supermin.d/base.img
181 supermin.d/extra.img
182 supermin.d/hostfiles
183 and then invoking supermin-helper with just the "supermin.d" directory
185 path as an argument.
186 In this way extra files can be added to the appliance just by creating
188 another cpio file ("extra.img" in the example above) and dropping it
189 into the directory. When the appliance is constructed, the extra files
190 will appear in the appliance.
191 DIRECTORIES BEFORE FILES
193 In order for supermin-helper to run quickly, it does not know how to
195 create directories automatically. Inside hostfiles and the cpio files,
196 directories must be specified before any files that they contain. For
197 example:
198 /usr
200 /usr/sbin
201 /usr/sbin/serviced
202 It is fine to list the same directory name multiple times.
204 LEXICOGRAPHICAL ORDER
206 supermin-helper visits the supermin control files in lexicographical
208 order. Thus in the example above, in the order "base.img" ->
209 "extra.img" -> "hostfiles".
210 This has an important effect: files contained in later cpio files
212 overwrite earlier files, and directories do not need to be specified if
213 they have already been created in earlier control files.
214 EXAMPLE OF CREATING EXTRA CPIO FILE
216 You can create a file like "extra.img" very easily using a shell
218 snippet similar to this one:
219 cd $tmpdir
221 mkdir -p usr/sbin
222 cp /path/to/serviced usr/sbin/
223 echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
224 cpio --quiet -o -H newc > extra.img
225 rm -rf usr
226 Notice how we instruct cpio to create intermediate directories.
228 MINIMIZING THE SUPERMIN APPLIANCE
230 You may want to "minimize" the supermin appliance in order to save time
231 and space when it is instantiated. Typically you might want to remove
232 documentation, info files, man pages and locales. We used to provide a
233 separate tool called "febootstrap-minimize" for this purpose, but it is
234 no longer provided. Instead you can post-process "hostfiles" yourself
235 to remove any files or directories that you don't want (by removing
236 lines from the file). Be careful what you remove because files may be
237 necessary for correct operation of the appliance.
238 For example:
240 < supermin.d/hostfiles \
242 grep -v '^/usr/share/man/' |
243 grep -v '^/usr/share/doc/' |
244 grep -v '^/usr/share/info/' > supermin.d/hostfiles-t
245 mv supermin.d/hostfiles-t supermin.d/hostfiles
246 KERNEL AND KERNEL MODULES
248 Usually the kernel and kernel modules are not included in the supermin
249 appliance. When the appliance is instantiated, the kernel modules from
250 the host kernel are copied in, and it is booted using the host kernel.
251 supermin-helper is able to choose the best host kernel available to
253 boot the appliance. Users can override this by setting environment
254 variables (see supermin-helper(8)).
255 BOOTING AND CACHING THE SUPERMIN APPLIANCE
257 For fastest boot times you should cache the output of supermin-helper.
258 See the libguestfs source file "src/appliance.c" for an example of how
259 this is done.
260 ENFORCING AVAILABILITY OF HOSTFILES
262 supermin-helper builds the appliance by copying in host files as listed
263 in "hostfiles". For this to work those host files must be available.
264 We usually enforce this by adding requirements (eg. RPM "Requires:"
265 lines) on the package that uses the supermin appliance, so that package
266 cannot be installed without pulling in the dependent packages and thus
267 making sure the host files are available.
268
270 supermin-helper(8), <http://people.redhat.com/~rjones/supermin/>,
271 guestfs(3), <http://libguestfs.org/>.
272
274 · Richard W.M. Jones <http://people.redhat.com/~rjones/>
275 · Matthew Booth mbooth@redhat.com
277
279 Copyright (C) 2009-2011 Red Hat Inc.
280 This program is free software; you can redistribute it and/or modify it
282 under the terms of the GNU General Public License as published by the
283 Free Software Foundation; either version 2 of the License, or (at your
284 option) any later version.
285 This program is distributed in the hope that it will be useful, but
287 WITHOUT ANY WARRANTY; without even the implied warranty of
288 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
289 General Public License for more details.
290 You should have received a copy of the GNU General Public License along
292 with this program; if not, write to the Free Software Foundation, Inc.,
293 675 Mass Ave, Cambridge, MA 02139, USA.
294supermin-4.1.3 2013-08-28 SUPERMIN(8)