Implement ext2 output module.

[febootstrap.git] / febootstrap.pod

diff --git a/febootstrap.pod b/febootstrap.pod
index dfc93fc..b1e512b 100644 (file)
--- a/febootstrap.pod
+++ b/febootstrap.pod
@@ -64,6 +64,36 @@ RPMs and metadata.  However if you give the C<--no-clean> option, then
 the yum repository is left.  This is useful if you want to run further
 yum commands inside the filesystem by hand.
 
 the yum repository is left.  This is useful if you want to run further
 yum commands inside the filesystem by hand.
 

+=item B<-p "proxyurl">
+
+=item B<--proxy="proxyurl">
+
+URL to the proxy server that yum should use.
+
+=item B<-u source>
+
+=item B<--updates=source>
+
+Pull in updates from an additional updates repository.  The possible
+sources are:
+
+=over 4
+
+=item -u C<http://...> (a URL)
+
+Get updates from the specific URL.
+
+=item -u C<updates-released-fN> (an updates repository name)
+
+Get updates from the public mirrors of the named repository
+(eg. C<updates-released-f10>).  See REPOSITORIES below.
+
+=item -u C<none> (default)
+
+Don't add an updates repository.  This is the default.
+
+=back
+

 =back
 
 =head1 REPOSITORIES
 =back
 
 =head1 REPOSITORIES


@@ -75,27 +105,62 @@ 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).
 
 (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>.
 
 
 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.
+Files should be replaced only by doing:
+
+ echo updated-content > old-file
+
+(since that preserves the original inode).
+
+Deleting files and then creating new ones (even with a different name)
+is usually unsafe, because the new files might reuse inodes claimed by
+the old files, and so appear with peculiar permissions
+(eg. unreadable, or as a symbolic link).
+
+Deleting files is also usually unsafe, although the reasons are more
+subtle.  If you just use C<rm> then the inode number is not deleted
+from C<fakeroot.log> which means it can be reused by another file
+later on.
+
+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 *
 
 You can use the fakeroot logfile in a number of ways:
 
 =over 4
 
 =item *
 

-Run
-
- fakeroot -i fakeroot.log command
+Use L<febootstrap-run(8)> to run a command with the faked file
+permissions.

 
 

-in order to run a command with the faked file permissions.  If the
-command will make updates, then do:
+=item *

 
 

- fakeroot -i fakeroot.log -s fakeroot.log command
+Use L<febootstrap-install(8)> to install a file with permissions
+in the root filesystem.

 
 =item *
 
 
 =item *
 


@@ -104,12 +169,22 @@ permissions using the tool C<febootstrap-to-initramfs>.
 
 =item *
 
 
 =item *
 

+Generate a supermin appliance using the tool
+C<febootstrap-to-supermin>.
+
+=item *
+

 Apply the permissions to the target directory using the forthcoming
 tool C<febootstrap-fix-root> (requires root).
 
 =back
 
 Apply the permissions to the target directory using the forthcoming
 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
 
 febootstrap cannot do cross-architecture installs (C<debootstrap
 --foreign>).  The reason is that C<%pre> and C<%post> scripts cannot


@@ -124,22 +199,24 @@ C<--foreign> installs - see previous point).
 
 =head1 OTHER RESTRICTIONS AND BUGS
 
 
 =head1 OTHER RESTRICTIONS AND BUGS
 

-Some C<%post> scripts do not run correctly.  The most common case is
-C</sbin/ldconfig>.  Since this binary is statically linked, fakeroot
-and fakechroot's LD_PRELOAD hack does not work, so effectively
-ldconfig tries to update the system cache.  You will see the following
-error:
+The following programs are not run during C<%post> scriptlets (because
+they are all statically linked, and fakechroot cannot run statically
+linked programs).
+
+=over 4

 
 

- /sbin/ldconfig: Can't create temporary cache file /etc/ld.so.cache~: Permission denied
+=item C</sbin/ldconfig> (from many packages)

 
 

-This error is mostly harmless.  Just run C</sbin/ldconfig> the first
-time you boot into the newly created Fedora system.
+=item C</usr/sbin/glibc_post_upgrade> (from C<glibc>)
+
+=item C</usr/sbin/build-locale-archive> (from C<glibc-common>)
+
+=item C</usr/sbin/libgcc_post_upgrade> (from C<libgcc>)
+
+=back

 
 

-Another error you will see is with C</usr/sbin/glibc_post_upgrade>
-which is caused for the same reason - this binary is statically
-linked.  We have examined what this binary does, and it is not really
-necessary for installs.  If it makes you happier, you can run it the
-first time you boot the new system.
+If you wish, you can run them the first time you boot into the new
+machine.

 
 febootstrap recreates the repository anew each time, and this causes
 yum to download all the RPMs every time.  This is very wasteful, and
 
 febootstrap recreates the repository anew each time, and this causes
 yum to download all the RPMs every time.  This is very wasteful, and


@@ -147,12 +224,15 @@ we should provide a way to cache the repository.
 
 =head1 HOME PAGE
 
 
 =head1 HOME PAGE
 

-L<http://et.redhat.com/~rjones/febootstrap>
+L<http://people.redhat.com/~rjones/febootstrap>

 
 =head1 SEE ALSO
 
 L<febootstrap-to-initramfs(8)>,
 L<febootstrap-minimize(8)>,
 
 =head1 SEE ALSO
 
 L<febootstrap-to-initramfs(8)>,
 L<febootstrap-minimize(8)>,

+L<febootstrap-run(8)>,
+L<febootstrap-install(8)>,
+L<febootstrap-to-supermin(8)>,

 L<fakeroot(1)>,
 L<fakechroot(1)>,
 L<yum(8)>,
 L<fakeroot(1)>,
 L<fakechroot(1)>,
 L<yum(8)>,


@@ -173,7 +253,7 @@ Richard W.M. Jones <rjones @ redhat . com>
 =head1 COPYRIGHT
 
 (C) Copyright 2009 Red Hat Inc.,
 =head1 COPYRIGHT
 
 (C) Copyright 2009 Red Hat Inc.,

-L<http://et.redhat.com/~rjones/febootstrap>.
+L<http://people.redhat.com/~rjones/febootstrap>.

 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by