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