diff --git a/doc/adapting-existing.xml b/doc/adapting-existing.xml
index c21f6f32..b8295f04 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>