diff options
authorPeter Seebach <seebs@eee12.(none)>2010-04-06 14:19:16 -0500
committerPeter Seebach <peter.seebach@windriver.com>2010-04-26 17:13:44 -0700
commit390c8ad100345356ddcbcad89011474d4d54b244 (patch)
parentd686759bcfe87a08336470666283c4b2ab6ad510 (diff)
Update documentation for chroot, passwd functionality.
4 files changed, 63 insertions, 3 deletions
diff --git a/ChangeLog.txt b/ChangeLog.txt
index d3ced17..0154454 100644
--- a/ChangeLog.txt
+++ b/ChangeLog.txt
@@ -1,3 +1,7 @@
+ * (seebs) implement various passwd-related utilities, various
+ bugfixes.
* (seebs) fix return values.
diff --git a/README b/README
index 6a25e08..3f04d47 100644
--- a/README
+++ b/README
@@ -37,9 +37,7 @@ some documentation on internals is provided in the doc/ directory.
-* We intend to add functionality to support user name/uid lookups from
- an alternative password file.
-* The chroot() functionality may need improvement.
+* The chroot() functionality is incomplete.
* We have no immediate plans to make pseudo work on other targets, but
are not opposed to accepting patches to do so. (It isn't even CLOSE
on OS X, largely because of the Linux-specific _STAT_VER stuff.)
diff --git a/doc/chroot b/doc/chroot
new file mode 100644
index 0000000..a0d1758
--- /dev/null
+++ b/doc/chroot
@@ -0,0 +1,31 @@
+Pseudo incorporates functionality similar to that of fakechroot.
+The implementation is basically as follows: When incoming arguments
+are known to be paths, they are automatically converted to absolute,
+fully canonicalized, paths. When the chroot(2) call is used, pseudo
+intercepts it and stashes the path to the new root directory internally
+in the client. This path is then silently prepended to absolute
+paths. The internal tracking of file paths uses absolute paths
+including the path to the chroot directory. So, all underlying calls
+are invoked with absolute, canonical, paths.
+A few calls are then modified. For instance, when readlink() returns
+a link, it strips a leading prefix looking like the chroot directory;
+when symlink() creates a link, if the link path is absolute, the chroot
+directory is prepended to it.
+This behavior, which may seem surprising, is an attempt to produce
+path resolution equivalent to what would normally happen when
+canonicalizing a path using real chroot; if you create a link to /tmp
+while in a chroot environment, following that link should yield
+<chroot>/tmp. Arguably, now that we are intercepting nearly every
+incoming path, we should just prepend the chroot path when following
+absolute symlinks -- this may get revisited.
+Similarly, when glob() is called, the path to be globbed has the
+chroot directory prepended, and then the results have any leading
+chroot directory stripped from them.
+This implementation is far from complete or perfect; the intent is
+that it provide enough functionality to allow RPM and similar tools
+to run file system installs using chroot().
diff --git a/doc/passwd b/doc/passwd
new file mode 100644
index 0000000..42d41c6
--- /dev/null
+++ b/doc/passwd
@@ -0,0 +1,27 @@
+Pseudo provides limited support for faking up password file access.
+Routines such as setpwent(), getpwent(), and so on, are modified to
+possibly pick a password file other than /etc/passwd, and likewise
+for setgrent() and /etc/group. The logic is as follows:
+* If a chroot directory is set, <chroot>/etc is tried first.
+* If PSEUDO_PASSWD is set, PSEUDO_PASSWD/etc is tried next.
+* Otherwise, fall back on /etc.
+In each case, failure to find a passwd or group file results in
+going on to trying the next case.
+The behavior of lckpwdf()/ulckpwdf() is a special case. In this
+case, the same order of directories is tried, but pseudo attempts
+to create the files, rather than attempting to open existing files.
+The underlying implementation directs nearly everything to
+fgetpwent_r() and fgetgrent_r(), which are extensions available in
+glibc. This allows pseudo to avoid having to actually implement yet
+another horrible passwd file parser which would inevitably have
+bugs that have already been fixed dozens of times in other
+Note that both the chroot directory and PSEUDO_PASSWD are assumed
+to be the parent directory of etc, not the directory containing the
+passwd and group files.