febootstrap.pod

   1 =head1 NAME
   2
   3 febootstrap - Bootstrap a basic Fedora system (like Debian debootstrap)
   4
   5 =head1 SYNOPSIS
   6
   7  febootstrap [--options] REPO TARGET [MIRROR]
   8
   9 =head1 EXAMPLES
  10
  11  febootstrap fedora-10 /tmp/f10
  12  febootstrap rawhide /tmp/rawhide
  13  febootstrap rawhide /tmp/rawhide http://mymirror/rawhide/x86_64/os
  14  febootstrap --groupinstall="Mail Server" fedora-10 /tmp/mailserver
  15
  16 =head1 DESCRIPTION
  17
  18 febootstrap creates a Fedora root filesystem, based on the Fedora
  19 version specified by I<REPO> under the directory specified by
  20 I<TARGET>.  Optionally I<MIRROR> can point to a local mirror
  21 (otherwise the public Fedora mirrors are used).  I<REPO> names are
  22 C<fedora-I<VERSION>> (eg. C<fedora-10>) or C<rawhide>.
  23
  24 febootstrap does I<not> need to be run as root.  If for some reason
  25 you do run it as root, then it works slightly differently and may have
  26 side effects such as stopping or starting system daemons.
  27
  28 For more advanced needs, take a look at L<mock(1)>, C<livecd-creator>
  29 and I<thincrust.net>'s C<appliance-creator>.
  30
  31 The normal output is a root directory located at I<TARGET> and
  32 a fakeroot logfile at C<I<TARGET>/fakeroot.log>.
  33
  34 =head1 OPTIONS
  35
  36 =over 4
  37
  38 =item B<-i package>
  39
  40 =item B<--install=package>
  41
  42 =item B<-g "group">
  43
  44 =item B<--groupinstall="group">
  45
  46 Specify the package or group to install.  To list multiple packages or
  47 groups, you must give multiple C<-i> or C<-g> options.  Group names
  48 can contain spaces, so use quotes where necessary.
  49
  50 These are passed directly to C<yum install> or C<yum groupinstall>
  51 commands, and thus any dependencies are also resolved by yum.  You can
  52 also use shell globs and filenames here, as with ordinary yum.
  53
  54 If no packages or groups are given, then we install the C<Core> group
  55 which is a small working Fedora installation (but by no means
  56 minimal).  Use C<yum groupinfo Core> to list the packages currently in
  57 the C<Core> group.
  58
  59 =item B<--no-clean>
  60
  61 Normally febootstrap will clean up the yum repository
  62 (C</var/cache/yum> inside the image).  This contains the downloaded
  63 RPMs and metadata.  However if you give the C<--no-clean> option, then
  64 the yum repository is left.  This is useful if you want to run further
  65 yum commands inside the filesystem by hand.
  66
  67 =back
  68
  69 =head1 REPOSITORIES
  70
  71 You can list available repositories by visiting this URL:
  72
  73 L<http://mirrors.fedoraproject.org/mirrorlist?repo=help&arch=i386>
  74
  75 (If necessary replace C<i386> with your architecture, but it seems
  76 unlikely that this list will change based on architecture).
  77
  78 =head1 FAKEROOT LOGFILE
  79
  80 When febootstrap is run as non-root (the normal case) we use fakeroot
  81 so that yum thinks it is running as root.  Fakeroot keeps track of
  82 "real" file permissions in a log file which is saved into the target
  83 directory as C<I<TARGET>/fakeroot.log>.
  84
  85 You can use the fakeroot logfile in a number of ways:
  86
  87 =over 4
  88
  89 =item *
  90
  91 Run
  92
  93  fakeroot -i fakeroot.log command
  94
  95 in order to run a command with the faked file permissions.  If the
  96 command will make updates, then do:
  97
  98  fakeroot -i fakeroot.log -s fakeroot.log command
  99
 100 =item *
 101
 102 Generate an initramfs (compressed cpio) file containing the correct
 103 permissions using the tool C<febootstrap-to-initramfs>.
 104
 105 =item *
 106
 107 Apply the permissions to the target directory using the forthcoming
 108 tool C<febootstrap-fix-root> (requires root).
 109
 110 =back
 111
 112 =head1 COMPARISON TO debootstrap
 113
 114 febootstrap cannot do cross-architecture installs (C<debootstrap
 115 --foreign>).  The reason is that C<%pre> and C<%post> scripts cannot
 116 run.  It may be possible to defer running of scriptlets (which is
 117 basically how debootstrap works), and patches to do this are welcomed.
 118
 119 febootstrap cannot do 32-on-64 bit installs.  The reason is that
 120 fakeroot and fakechroot do not load the correct preload library.  This
 121 is really a bug in fakeroot/fakechroot, which we think would be easy
 122 to fix.  (debootstrap deals with this case the same as for
 123 C<--foreign> installs - see previous point).
 124
 125 =head1 OTHER RESTRICTIONS AND BUGS
 126
 127 Some C<%post> scripts do not run correctly.  The most common case is
 128 C</sbin/ldconfig>.  Since this binary is statically linked, fakeroot
 129 and fakechroot's LD_PRELOAD hack does not work, so effectively
 130 ldconfig tries to update the system cache.  You will see the following
 131 error:
 132
 133  /sbin/ldconfig: Can't create temporary cache file /etc/ld.so.cache~: Permission denied
 134
 135 This error is mostly harmless.  Just run C</sbin/ldconfig> the first
 136 time you boot into the newly created Fedora system.
 137
 138 Another error you will see is with C</usr/sbin/glibc_post_upgrade>
 139 which is caused for the same reason - this binary is statically
 140 linked.  We have examined what this binary does, and it is not really
 141 necessary for installs.  If it makes you happier, you can run it the
 142 first time you boot the new system.
 143
 144 febootstrap recreates the repository anew each time, and this causes
 145 yum to download all the RPMs every time.  This is very wasteful, and
 146 we should provide a way to cache the repository.
 147
 148 =head1 HOME PAGE
 149
 150 L<http://et.redhat.com/~rjones/febootstrap>
 151
 152 =head1 SEE ALSO
 153
 154 L<febootstrap-to-initramfs(8)>,
 155 L<febootstrap-minimize(8)>,
 156 L<fakeroot(1)>,
 157 L<fakechroot(1)>,
 158 L<yum(8)>,
 159 L<rpm(8)>.
 160
 161 =head1 ALTERNATIVES
 162
 163 L<mock(1)>,
 164 L<http://fedoraproject.org/wiki/FedoraLiveCD/LiveCDHowTo>,
 165 L<http://thincrust.net/>,
 166 L<debootstrap(8)>,
 167 C<ubuntu-vm-builder>.
 168
 169 =head1 AUTHORS
 170
 171 Richard W.M. Jones <rjones @ redhat . com>
 172
 173 =head1 COPYRIGHT
 174
 175 (C) Copyright 2009 Red Hat Inc.,
 176 L<http://et.redhat.com/~rjones/febootstrap>.
 177
 178 This program is free software; you can redistribute it and/or modify
 179 it under the terms of the GNU General Public License as published by
 180 the Free Software Foundation; either version 2 of the License, or
 181 (at your option) any later version.
 182
 183 This program is distributed in the hope that it will be useful,
 184 but WITHOUT ANY WARRANTY; without even the implied warranty of
 185 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 186 GNU General Public License for more details.
 187
 188 You should have received a copy of the GNU General Public License
 189 along with this program; if not, write to the Free Software
 190 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.