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 =back
  98
  99 =head1 SPEED
 100
 101 In libguestfs, on a mid-range Intel-based PC, we reconstruct the
 102 initramfs using this script in around 1/5th of a second (assuming a
 103 "hot cache" - it's rather slower when run the first time on a cold
 104 cache).
 105
 106 Some tips to improve performance:
 107
 108 =over 4
 109
 110 =item *
 111
 112 Use a kernel module whitelist (the C<--kmods> option), and only
 113 list the kernel modules you really need.
 114
 115 =item *
 116
 117 Minimize the appliance, removing as much extraneous junk as possible.
 118
 119 As well as using L<febootstrap-minimize(8)> it is worth checking for
 120 anything that is not necessary for your particular application and
 121 removing it by hand.
 122
 123 =back
 124
 125 =head1 SEE ALSO
 126
 127 L<febootstrap(8)>,
 128 L<febootstrap-to-initramfs(8)>,
 129 L<febootstrap-to-supermin(8)>.
 130
 131 =head1 AUTHORS
 132
 133 Richard W.M. Jones <rjones @ redhat . com>
 134
 135 =head1 COPYRIGHT
 136
 137 (C) Copyright 2009-2010 Red Hat Inc.,
 138 L<http://people.redhat.com/~rjones/febootstrap>.
 139
 140 This program is free software; you can redistribute it and/or modify
 141 it under the terms of the GNU General Public License as published by
 142 the Free Software Foundation; either version 2 of the License, or
 143 (at your option) any later version.
 144
 145 This program is distributed in the hope that it will be useful,
 146 but WITHOUT ANY WARRANTY; without even the implied warranty of
 147 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 148 GNU General Public License for more details.
 149
 150 You should have received a copy of the GNU General Public License
 151 along with this program; if not, write to the Free Software
 152 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.