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" rawhide /tmp/rawhide
  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 not need to be run as root.  If for some reason you
  25 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)> and
  29 C<livecd-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<--install="list of packages separated by commas">
  39
  40 =item B<--groupinstall="list of groups separated by commas">
  41
  42 Specify the list of packages or groups to install.  These are passed
  43 directly to C<yum install> or C<yum groupinstall> commands, and thus
  44 any dependencies are also resolved by yum.  You can also use shell
  45 globs and filenames here, as with ordinary yum.
  46
  47 If no packages or groups are given, then we install the C<Core> group
  48 which is the smallest working Fedora installation.  Use C<yum
  49 groupinfo Core> to list the packages currently in the C<Core> group.
  50
  51 =back
  52
  53 =head1 FAKEROOT LOGFILE
  54
  55 When febootstrap is run as non-root (the normal case) we use fakeroot
  56 so that yum thinks it is running as root.  Fakeroot keeps track of
  57 "real" file permissions in a log file which is saved into the target
  58 directory as C<I<TARGET>/fakeroot.log>.
  59
  60 You can use the fakeroot logfile in a number of ways:
  61
  62 =over 4
  63
  64 =item *
  65
  66 Run C<fakeroot -i fakeroot.log I<command>> in order to run a
  67 command with the faked file permissions.
  68
  69 =item *
  70
  71 Generate an initrd (cpio) file containing the correct permissions
  72 using the tool C<febootstrap-to-initrd>.
  73
  74 =item *
  75
  76 Apply the permissions to the target directory using the tool
  77 C<febootstrap-fix-root> (requires root).
  78
  79 =back
  80
  81 =head1 COMPARISON TO debootstrap
  82
  83 febootstrap cannot do cross-architecture installs (C<debootstrap
  84 --foreign>).  The reason is that C<%pre> and C<%post> scripts cannot
  85 run.  It may be possible to defer running of scriptlets (which is
  86 basically how debootstrap works), and patches to do this are welcomed.
  87
  88 febootstrap cannot do 32-on-64 bit installs.  The reason is that
  89 fakeroot and fakechroot do not load the correct preload library.  This
  90 is really a bug in fakeroot/fakechroot, which we think would be easy
  91 to fix.  (debootstrap deals with this case the same as for
  92 C<--foreign> installs - see previous point).
  93
  94 =head1 OTHER RESTRICTIONS AND BUGS
  95
  96 Some C<%post> scripts do not run correctly.  The most common case is
  97 C</sbin/ldconfig>.  Since this binary is statically linked, fakeroot
  98 and fakechroot's LD_PRELOAD hack does not work, so effectively
  99 ldconfig tries to update the system cache.  You will see the following
 100 error:
 101
 102  /sbin/ldconfig: Can't create temporary cache file /etc/ld.so.cache~: Permission denied
 103
 104 This error is mostly harmless.  Just run C</sbin/ldconfig> the first
 105 time you boot into the newly created Fedora system.
 106
 107 Another error you will see is with C</usr/sbin/glibc_post_upgrade>
 108 which is caused for the same reason - this binary is statically
 109 linked.  We have examined what this binary does, and it is not really
 110 necessary for installs.  If it makes you happier, you can run it the
 111 first time you boot the new system.
 112
 113 =head1 HOME PAGE
 114
 115 L<http://et.redhat.com/~rjones/febootstrap>
 116
 117 =head1 SEE ALSO
 118
 119 L<febootstrap-to-initrd(8)>,
 120 L<febootstrap-fix-root(8)>,
 121 L<fakeroot(1)>,
 122 L<fakechroot(1)>,
 123 L<yum(8)>,
 124 L<rpm(8)>.
 125
 126 =head1 ALTERNATIVES
 127
 128 L<mock(1)>,
 129 L<http://fedoraproject.org/wiki/FedoraLiveCD/LiveCDHowTo>,
 130 L<debootstrap(8)>.
 131
 132 =head1 AUTHORS
 133
 134 Richard W.M. Jones <rjones @ redhat . com>
 135
 136 =head1 COPYRIGHT
 137
 138 (C) Copyright 2009 Red Hat Inc.,
 139 L<http://et.redhat.com/~rjones/febootstrap>.
 140
 141 This program is free software; you can redistribute it and/or modify
 142 it under the terms of the GNU General Public License as published by
 143 the Free Software Foundation; either version 2 of the License, or
 144 (at your option) any later version.
 145
 146 This program is distributed in the hope that it will be useful,
 147 but WITHOUT ANY WARRANTY; without even the implied warranty of
 148 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 149 GNU General Public License for more details.
 150
 151 You should have received a copy of the GNU General Public License
 152 along with this program; if not, write to the Free Software
 153 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.