[ostree] doc/adapting-existing: Describe /lib/passwd

[Colin Walters <walters src gnome org>]

commit bd5eb72e109243f35b019582fab36a42a7b12682
Author: Colin Walters <walters verbum org>
Date:   Sun Aug 25 16:12:14 2013 -0400

    doc/adapting-existing: Describe /lib/passwd

 doc/adapting-existing.xml |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)
---
diff --git a/doc/adapting-existing.xml b/doc/adapting-existing.xml
index c21f6f3..b8295f0 100644
--- a/doc/adapting-existing.xml
+++ b/doc/adapting-existing.xml
@@ -162,6 +162,31 @@ d /run/media 0755 root root -
     </para>
   </chapter>
 
+  <chapter id="lib-passwd">
+    <title>/lib/passwd</title>
+    <para>
+      In order to ship an OS that contains both system users and users
+      dynamically created on client machines, you will need to choose
+      a solution for <filename>/etc/passwd</filename>.  The core
+      problem is that if you add a user to the system for a daemon,
+      the OSTree upgrade process for <filename
+      class='directory'>/etc</filename> will simply notice that
+      because <filename>/etc/passwd</filename> differs from the
+      previous default, it will keep the modified config file, and
+      your new OS user will not be visible.
+    </para>
+    <para>
+      The solution chosen for the <ulink
+      url="https://wiki.gnome.org/GnomeOSTree";>gnome-ostree</ulink>
+      operating system is to create <filename>/lib/passwd</filename>,
+      and to include a NSS module <ulink
+      url="https://github.com/aperezdc/nss-altfiles";>nss-altfiles</ulink>
+      which instructs glibc to read from it.  Then, the build system places
+      all system users there, freeing up <filename>/etc/passwd</filename>
+      to be purely a database of local users.
+    </para>
+  </chapter>
+
   <chapter id="adapting-package-manager">
     <title>Adapting existing package managers</title>
     <para>