fakechroot 2.9 now includes the patches.

[febootstrap.git] / febootstrap.pod

diff --git a/febootstrap.pod b/febootstrap.pod
index da97766..b2d7470 100644 (file)
--- a/febootstrap.pod
+++ b/febootstrap.pod
@@ -25,8 +25,8 @@ febootstrap does I<not> need to be run as root.  If for some reason
 you do run it as root, then it works slightly differently and may have
 side effects such as stopping or starting system daemons.
 
-For more advanced needs, take a look at L<mock(1)> and
-C<livecd-creator>.
+For more advanced needs, take a look at L<mock(1)>, C<livecd-creator>
+and I<thincrust.net>'s C<appliance-creator>.
 
 The normal output is a root directory located at I<TARGET> and
 a fakeroot logfile at C<I<TARGET>/fakeroot.log>.
@@ -52,8 +52,9 @@ commands, and thus any dependencies are also resolved by yum.  You can
 also use shell globs and filenames here, as with ordinary yum.
 
 If no packages or groups are given, then we install the C<Core> group
-which is the smallest working Fedora installation.  Use C<yum
-groupinfo Core> to list the packages currently in the C<Core> group.
+which is a small working Fedora installation (but by no means
+minimal).  Use C<yum groupinfo Core> to list the packages currently in
+the C<Core> group.
 
 =item B<--no-clean>
 
@@ -74,21 +75,46 @@ L<http://mirrors.fedoraproject.org/mirrorlist?repo=help&arch=i386>
 (If necessary replace C<i386> with your architecture, but it seems
 unlikely that this list will change based on architecture).
 
-=head1 FAKEROOT LOGFILE
+=head1 RUNNING EXTRA COMMANDS IN THE ROOT FILESYSTEM
+
+If you want to run further commands inside the root filesystem, for
+example additional C<yum> installs, then use C<febootstrap-run>.  See
+the L<febootstrap-run(8)> manual page for more details.
+
+You have to be careful about modifying files in the root filesystem
+directly (without using C<febootstrap-run>).  It's easy to confuse
+fakeroot and end up with the wrong permissions on files (see FAKEROOT
+LOGFILE below).
+
+C<febootstrap-run> runs the command inside the root filesystem, which
+means it won't normally have access to files outside the root.  You
+can use C<FAKECHROOT_EXCLUDE_PATH> environment variable (see
+L<fakechroot(1)>) or copy files into the root first.
+
+=head2 FAKEROOT LOGFILE
 
 When febootstrap is run as non-root (the normal case) we use fakeroot
 so that yum thinks it is running as root.  Fakeroot keeps track of
 "real" file permissions in a log file which is saved into the target
 directory as C<I<TARGET>/fakeroot.log>.
 
+This logfile is indexed by inode number, which makes certain
+operations safe and other operations unsafe.  For example, deleting
+files is usually safe.  Files should be replaced only by doing:
+
+ echo updated-content > old-file
+
+(since that preserves the original inode).  In most cases it's usually
+safest to use C<febootstrap-run>.
+
 You can use the fakeroot logfile in a number of ways:
 
 =over 4
 
 =item *
 
-Run C<fakeroot -i fakeroot.log I<command>> in order to run a
-command with the faked file permissions.
+Use L<febootstrap-run(8)> to run a command with the faked file
+permissions.
 
 =item *
 
@@ -102,7 +128,12 @@ tool C<febootstrap-fix-root> (requires root).
 
 =back
 
-=head1 COMPARISON TO debootstrap
+=head1 RUNNING FEBOOTSTRAP AS ROOT
+
+There is some rudimentary support for running C<febootstrap> as root.
+However it is not well-tested and generally not recommended.
+
+=head1 COMPARISON TO DEBOOTSTRAP
 
 febootstrap cannot do cross-architecture installs (C<debootstrap
 --foreign>).  The reason is that C<%pre> and C<%post> scripts cannot
@@ -146,6 +177,7 @@ L<http://et.redhat.com/~rjones/febootstrap>
 
 L<febootstrap-to-initramfs(8)>,
 L<febootstrap-minimize(8)>,
+L<febootstrap-run(8)>,
 L<fakeroot(1)>,
 L<fakechroot(1)>,
 L<yum(8)>,
@@ -155,7 +187,9 @@ L<rpm(8)>.
 
 L<mock(1)>,
 L<http://fedoraproject.org/wiki/FedoraLiveCD/LiveCDHowTo>,
-L<debootstrap(8)>.
+L<http://thincrust.net/>,
+L<debootstrap(8)>,
+C<ubuntu-vm-builder>.
 
 =head1 AUTHORS