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