[PATCH] initramfs: unprivileged image creation

This patch makes several tweaks so that an initramfs image can be
completely created by an unprivileged user.  It should maintain
compatibility with previous initramfs early userspace cpio/image creation
and it updates documentation.

There are a few very important tweaks:

CONFIG_INITRAMFS_SOURCE is now either a single cpio archive that is
directly used or a list of directories and files for building a cpio
archive for the initramfs image.  Making the cpio archive listable in
CONFIG_INITRAMFS_SOURCE makes the cpio step more official and automated so
that it doesn't have to be copied by hand to usr/initramfs_data.cpio (I
think this was broken anyway and would be overwritten).  The alternative
list of directories *and* files means that files can be install in a "root"
directory and device-special files can be listed in a file list.

CONFIG_ROOT_UID and CONFIG_ROOT_GID are now available for doing simple
user/group ID translation.  That means that user ID 500, group ID 500 can
create all the files in the "root" directory, but that they can all be
owned by user ID 0, group ID 0 in the cpio image.

Various documentation updates to pull it all together.

Removal of old cruft that was unused/misleading.

Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

1 files changed, 57 insertions, 14 deletions

diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README
index 77eaa58368d125..270a88e22fb931 100644
--- a/Documentation/early-userspace/README
+++ b/Documentation/early-userspace/README
@@ -1,7 +1,7 @@
 Early userspace support
 =======================
 
-Last update: 2004-11-12
+Last update: 2004-12-20 tlh
 
 
 "Early userspace" is a set of libraries and programs that provide
@@ -21,19 +21,62 @@ It consists of several major infrastructure components:
 
 The cpio file format used by initramfs is the "newc" (aka "cpio -c")
 format, and is documented in the file "buffer-format.txt".  There are
-three ways to add an early userspace filesystem:
-
-1) Put your gzip'ed cpio in usr/initramfs_data.cpio.gz.
-
-2) Set CONFIG_INITRAMFS_SOURCE to the filename of a gen_init_cpio
-input file.  This provides the most flexibility and allows creation of
-archives with files not owned by the build user.  This means that an
-unprivileged user can create an early userspace with files owned by
-root.
-
-3) Set CONFIG_INITRAMFS_SOURCE to point to a directory containing the
-files for your filesystem.
-
+two ways to add an early userspace image: specify an existing cpio
+archive to be used as the image or have the kernel build process build
+the image from specifications.
+
+CPIO ARCHIVE method
+
+You can create a cpio archive that contains the early userspace image.
+Youre cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it
+will be used directly.  Only a single cpio file may be specified in
+CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in
+combination with a cpio archive.
+
+IMAGE BUILDING method
+
+The kernel build process can also build an early userspace image from
+source parts rather than supplying a cpio archive.  This method provides
+a way to create images with root-owned files even though the image was
+built by an unprivileged user.
+
+The image is specified as one or more sources in
+CONFIG_INITRAMFS_SOURCE.  Sources can be either directories or files -
+cpio archives are *not* allowed when building from sources.
+
+A source directory will have it and all of it's contents packaged.  The
+specified directory name will be mapped to '/'.  When packaging a
+directory, limited user and group ID translation can be performed.
+INITRAMFS_ROOT_UID can be set to a user ID that needs to be mapped to
+user root (0).  INITRAMFS_ROOT_GID can be set to a group ID that needs
+to be mapped to group root (0).
+
+A source file must be directives in the format required by the
+usr/gen_init_cpio utility (run 'usr/gen_init_cpio --help' to get the
+file format).  The directives in the file will be passed directly to
+usr/gen_init_cpio.
+
+When a combination of directories and files are specified then the
+initramfs image will be an aggregate of all of them.  In this way a user
+can create a 'root-image' directory and install all files into it.
+Because device-special files cannot be created by a unprivileged user,
+special files can be listed in a 'root-files' file.  Both 'root-image'
+and 'root-files' can be listed in CONFIG_INITRAMFS_SOURCE and a complete
+early userspace image can be built by an unprivileged user.
+
+As a technical note, when directories and files are specified, the
+entire CONFIG_INITRAMFS_SOURCE is passed to
+scripts/gen_initramfs_list.sh.  This means that CONFIG_INITRAMFS_SOURCE
+can really be interpreted as any legal argument to
+gen_initramfs_list.sh.  If a directory is specified as an argument then
+the contents are scanned, uid/gid translation is performed, and
+usr/gen_init_cpio file directives are output.  If a directory is
+specified as an arugemnt to scripts/gen_initramfs_list.sh then the
+contents of the file are simply copied to the output.  All of the output
+directives from directory scanning and file contents copying are
+processed by usr/gen_init_cpio.
+
+See also 'scripts/gen_initramfs_list.sh -h'.
 
 Where's this all leading?
 =========================