helper/febootstrap-supermin-helper.pod

   1 =head1 NAME
   2
   3 febootstrap-supermin-helper - Reconstruct initramfs from supermin appliance.
   4
   5 =head1 SYNOPSIS
   6
   7  febootstrap-supermin-helper supermin.img hostfiles.txt host_cpu kernel initrd
   8  febootstrap-supermin-helper input [...] host_cpu kernel initrd
   9
  10  febootstrap-supermin-helper -f ext2 input [...] host_cpu kernel initrd appliance
  11
  12  febootstrap-supermin-helper -f checksum input [...] host_cpu
  13
  14 =head1 DESCRIPTION
  15
  16 I<febootstrap-supermin-helper> reconstructs a bootable kernel and
  17 initramfs from a supermin appliance.  First you should be familiar
  18 with L<febootstrap(8)>.
  19
  20 =head1 PARAMETERS
  21
  22 Of the required parameters, the first few are I<input> files, and the
  23 last two or three are I<output> files.
  24
  25 C<supermin.img> and C<hostfiles.txt> are the input files which
  26 describe the supermin appliance.  (You can also use a directory name
  27 here which is searched for files).
  28
  29 C<host_cpu> should be the host CPU, eg. C<x86_64> or C<i686>.
  30
  31 C<kernel>, C<initrd> and C<appliance> are the temporary output files
  32 that this script produces.  These output files are meant to be used
  33 just for booting the appliance, and should be deleted straight
  34 afterwards.  The extra C<appliance> parameter is only required when
  35 the format is C<ext2>.  None of these parameters are needed for
  36 the checksum output C<-f checksum>.
  37
  38 =head1 OPTIONS
  39
  40 =over 4
  41
  42 =item B<-f fmt>
  43
  44 =item B<--format fmt>
  45
  46 Select the output format for the appliance.  Possible formats are:
  47
  48 =over 4
  49
  50 =item cpio
  51
  52 A Linux initramfs.  This is the default.
  53
  54 In this case you have to supply names for the C<kernel>
  55 and C<initrd>, where the C<initrd> is the appliance.
  56
  57 =item ext2
  58
  59 An ext2 filesystem.
  60
  61 In this case you have to supply names for the C<kernel>, a small
  62 C<initrd> which is used just to locate the appliance, and the
  63 C<appliance> (the ext2 filesystem).
  64
  65 =item checksum
  66
  67 Output a checksum.
  68
  69 This prints a checksum which only changes when one of the input files
  70 changes.
  71
  72 You can use this in order to cache the output of a previous run of
  73 this program: computing the checksum is much quicker than building an
  74 appliance, and you only need to invalidate the cache (and consequently
  75 rebuild the appliance) when the checksum changes.  Note that the
  76 host_cpu and the UID of the current user are included in the checksum.
  77
  78 =back
  79
  80 =item B<-k file>
  81
  82 =item B<--kmods file>
  83
  84 If this option is specified, then C<file> should be a list of
  85 wildcards matching kernel module names, eg:
  86
  87  virtio*.ko
  88  scsi*.ko
  89  piix.ko
  90
  91 In this case, only kernel modules matching those wildcards will be
  92 included in the output appliance.  Note: You must resolve any
  93 dependencies yourself as this does not pull in dependent modules
  94 automatically.
  95
  96 If this option is not specified, then every kernel module from the
  97 host will be included.  This is safer, but can produce rather large
  98 appliances which need a lot more memory to boot.
  99
 100 =item B<-u user>
 101
 102 =item B<--user user>
 103
 104 =item B<-g group>
 105
 106 =item B<--group group>
 107
 108 Run febootstrap-supermin-helper as an alternate user and/or group.
 109 C<user> and C<group> can be specified as either a name, which will
 110 be resolved using the system name service, or a uid/gid.  Use of these
 111 options requires root privileges.
 112
 113 Use of these options is required if running febootstrap-supermin-helper
 114 as root with the effective uid/gid set to non-root.  Bash will reset
 115 the effective uid/gid to the real uid/gid when invoked.  As
 116 febootstrap-supermin-helper uses bash in parts, this will result in the
 117 creation of an appliance with a mixture of ownerships.
 118
 119 =back
 120
 121 =head1 SPEED
 122
 123 In libguestfs, on a mid-range Intel-based PC, we reconstruct the
 124 initramfs using this script in around 1/5th of a second (assuming a
 125 "hot cache" - it's rather slower when run the first time on a cold
 126 cache).
 127
 128 Some tips to improve performance:
 129
 130 =over 4
 131
 132 =item *
 133
 134 Use a kernel module whitelist (the C<--kmods> option), and only
 135 list the kernel modules you really need.
 136
 137 =item *
 138
 139 Minimize the appliance, removing as much extraneous junk as possible.
 140
 141 =back
 142
 143 =head1 ENVIRONMENT VARIABLES
 144
 145 =over 4
 146
 147 =item FEBOOTSTRAP_KERNEL
 148
 149 If this environment variable is set, then automatic selection of the
 150 kernel is bypassed and this kernel is used.
 151
 152 The environment variable should point to a kernel file,
 153 eg. C</boot/vmlinuz-3.0.x86_64>
 154
 155 The corresponding module path is guessed from the kernel name, but you
 156 can override that by setting C<FEBOOTSTRAP_MODULES>.
 157
 158 =item FEBOOTSTRAP_MODULES
 159
 160 If C<FEBOOTSTRAP_KERNEL> and C<FEBOOTSTRAP_MODULES> are both set, then
 161 automatic selection of the kernel is bypassed and the kernel and
 162 module path are set to these values.
 163
 164 The environment variable should point to a module directory,
 165 eg. C</lib/modules/3.0.x86_64/>
 166
 167 This has no effect if C<FEBOOTSTRAP_KERNEL> is not set.
 168
 169 =back
 170
 171 =head1 SEE ALSO
 172
 173 L<febootstrap(8)>.
 174
 175 =head1 AUTHORS
 176
 177 Richard W.M. Jones <rjones @ redhat . com>
 178
 179 =head1 COPYRIGHT
 180
 181 (C) Copyright 2009-2011 Red Hat Inc.,
 182 L<http://people.redhat.com/~rjones/febootstrap>.
 183
 184 This program is free software; you can redistribute it and/or modify
 185 it under the terms of the GNU General Public License as published by
 186 the Free Software Foundation; either version 2 of the License, or
 187 (at your option) any later version.
 188
 189 This program is distributed in the hope that it will be useful,
 190 but WITHOUT ANY WARRANTY; without even the implied warranty of
 191 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 192 GNU General Public License for more details.
 193
 194 You should have received a copy of the GNU General Public License
 195 along with this program; if not, write to the Free Software
 196 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.