supermin-helper(8)

1SUPERMIN-HELPER(8)          Virtualization Support          SUPERMIN-HELPER(8)
2
3
4

NAME

6       supermin-helper - Reconstruct initramfs from supermin appliance.
7

SYNOPSIS

9        supermin-helper supermin.img hostfiles.txt host_cpu kernel initrd
10        supermin-helper input [...] host_cpu kernel initrd
11
12        supermin-helper -f ext2 input [...] host_cpu kernel initrd appliance
13
14        supermin-helper -f checksum input [...] host_cpu
15

DESCRIPTION

17       supermin-helper reconstructs a bootable kernel and initramfs from a
18       supermin appliance.  First you should be familiar with supermin(8).
19

PARAMETERS

21       Of the required parameters, the first few are input files, and the last
22       two or three are output files.
23
24       "supermin.img" and "hostfiles.txt" are the input files which describe
25       the supermin appliance.  (You can also use a directory name here which
26       is searched for files).
27
28       "host_cpu" should be the host CPU, eg. "x86_64" or "i686".
29
30       "kernel", "initrd" and "appliance" are the temporary output files that
31       this script produces.  These output files are meant to be used just for
32       booting the appliance, and should be deleted straight afterwards.  The
33       extra "appliance" parameter is only required when the format is "ext2".
34       None of these parameters are needed for the checksum output "-f
35       checksum".
36

OPTIONS

38       --help
39           Display brief command line usage, and exit.
40
41       -f fmt
42       --format fmt
43           Select the output format for the appliance.  Possible formats are:
44
45           cpio
46               A Linux initramfs.  This is the default.
47
48               In this case you have to supply names for the "kernel" and
49               "initrd", where the "initrd" is the appliance.
50
51               Note that cpio(1) might not be able to extract this file fully.
52               The format used by the Linux kernel is not quite a true cpio
53               file.
54
55           ext2
56               An ext2 filesystem.
57
58               In this case you have to supply names for the "kernel", a small
59               "initrd" which is used just to locate the appliance, and the
60               "appliance" (the ext2 filesystem).
61
62           checksum
63               Output a checksum.
64
65               This prints a checksum which only changes when one of the input
66               files changes.
67
68               You can use this in order to cache the output of a previous run
69               of this program: computing the checksum is much quicker than
70               building an appliance, and you only need to invalidate the
71               cache (and consequently rebuild the appliance) when the
72               checksum changes.  Note that the host_cpu and the UID of the
73               current user are included in the checksum.
74
75       --copy-kernel
76           Copy the kernel instead of symlinking to the kernel in "/boot".
77
78           This is fractionally slower, but is necessary if you want to change
79           the permissions or SELinux label on the kernel.
80
81       -k file
82       --kmods file
83           If this option is specified, then "file" should be a list of
84           wildcards matching kernel module names, eg:
85
86            virtio*.ko
87            scsi*.ko
88            piix.ko
89
90           In this case, only kernel modules matching those wildcards will be
91           included in the output appliance.  Note: You must resolve any
92           dependencies yourself as this does not pull in dependent modules
93           automatically.
94
95           If this option is not specified, then every kernel module from the
96           host will be included.  This is safer, but can produce rather large
97           appliances which need a lot more memory to boot.
98
99       -u user
100       --user user
101       -g group
102       --group group
103           Run supermin-helper as an alternate user and/or group.  "user" and
104           "group" can be specified as either a name, which will be resolved
105           using the system name service, or a uid/gid.  Use of these options
106           requires root privileges.
107
108           Use of these options is required if running supermin-helper as root
109           with the effective uid/gid set to non-root.  Bash will reset the
110           effective uid/gid to the real uid/gid when invoked.  As supermin-
111           helper uses bash in parts, this will result in the creation of an
112           appliance with a mixture of ownerships.
113
114       -v
115       --verbose
116           Enable verbose messages (give multiple times for more verbosity).
117
118       -V
119       --version
120           Display version number and exit.
121

COMPRESSED INPUT FILES

123       supermin-helper ≥ 4.1.4 supports gzip-compressed input cpio image
124       files.  "hostfiles" cannot be compressed.
125
126       Compressing input files saves space, but can make supermin-helper run
127       fractionally slower.
128

SPEED

130       In libguestfs, on a mid-range Intel-based PC, we reconstruct the
131       initramfs using this script in around 1/5th of a second (assuming a
132       "hot cache" - it's rather slower when run the first time on a cold
133       cache).
134
135       Some tips to improve performance:
136
137       ·   Use a kernel module whitelist (the "--kmods" option), and only list
138           the kernel modules you really need.
139
140       ·   Minimize the appliance, removing as much extraneous junk as
141           possible.
142

ENVIRONMENT VARIABLES

144       SUPERMIN_KERNEL
145           If this environment variable is set, then automatic selection of
146           the kernel is bypassed and this kernel is used.
147
148           The environment variable should point to a kernel file, eg.
149           "/boot/vmlinuz-3.0.x86_64"
150
151           The corresponding module path is guessed from the kernel name, but
152           you can override that by setting "SUPERMIN_MODULES".
153
154       SUPERMIN_MODULES
155           If "SUPERMIN_KERNEL" and "SUPERMIN_MODULES" are both set, then
156           automatic selection of the kernel is bypassed and the kernel and
157           module path are set to these values.
158
159           The environment variable should point to a module directory, eg.
160           "/lib/modules/3.0.x86_64/"
161
162           This has no effect if "SUPERMIN_KERNEL" is not set.
163

AUTHORS

168       Richard W.M. Jones <rjones @ redhat . com>
169

COPYRIGHT

171       (C) Copyright 2009-2013 Red Hat Inc.,
172       <http://people.redhat.com/~rjones/supermin>.
173
174       This program is free software; you can redistribute it and/or modify it
175       under the terms of the GNU General Public License as published by the
176       Free Software Foundation; either version 2 of the License, or (at your
177       option) any later version.
178
179       This program is distributed in the hope that it will be useful, but
180       WITHOUT ANY WARRANTY; without even the implied warranty of
181       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
182       General Public License for more details.
183
184       You should have received a copy of the GNU General Public License along
185       with this program; if not, write to the Free Software Foundation, Inc.,
186       675 Mass Ave, Cambridge, MA 02139, USA.
187
188
189
190supermin-4.1.3                    2013-08-28                SUPERMIN-HELPER(8)