From b06e10ebf9d24589f10e05c706933b8f2e8665ea Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Sun, 25 Aug 2013 10:23:19 -0400
Subject: [PATCH] doc/adapting-existing: Elaborate a bit more on FS layout and
 links

---
 doc/adapting-existing.xml | 44 ++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/doc/adapting-existing.xml b/doc/adapting-existing.xml
index d02e70b3..c21f6f32 100644
--- a/doc/adapting-existing.xml
+++ b/doc/adapting-existing.xml
@@ -37,11 +37,15 @@
 
     <para>
       Because OSTree only preserves <filename
-      class='directory'>/var</filename> across upgrades, it is very
-      strongly recommended for systems which want to preserve
-      compatibility with the <ulink
+      class='directory'>/var</filename> across upgrades (each
+      deployment's chroot directory will be garbage collected
+      eventually), you will need to choose how to handle other
+      toplevel writable directories specified by the <ulink
       url="http://www.pathname.com/fhs/">Filesystem Hierarchy
-      Standard</ulink> to create the following symbolic links:
+      Standard</ulink>.  Your operating system may of course choose
+      not to support some of these such as <filename
+      class='directory'>/usr/local</filename>, but following is the
+      recommended set:
       <itemizedlist>
 	<listitem>
 	  <para>
@@ -53,6 +57,16 @@
 	    <filename class='directory'>/opt</filename> to <filename class='directory'>/var/opt</filename>
 	  </para>
 	</listitem>
+	<listitem>
+	  <para>
+	    <filename class='directory'>/srv</filename> to <filename class='directory'>/var/srv</filename>
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    <filename class='directory'>/root</filename> to <filename class='directory'>/var/roothome</filename>
+	  </para>
+	</listitem>
 	<listitem>
 	  <para>
 	    <filename class='directory'>/usr/local</filename> to <filename class='directory'>/var/local</filename>
@@ -74,9 +88,10 @@
     <para>
       Furthermore, since <filename class='directory'>/var</filename>
       is empty by default, your operating system will need to
-      dynamically create these directories at boot.  A good way to do
-      this is using <command>systemd-tmpfiles</command>, if your OS
-      uses systemd.  For example:
+      dynamically create the <emphasis>targets</emphasis> of these at
+      boot.  A good way to do this is using
+      <command>systemd-tmpfiles</command>, if your OS uses systemd.
+      For example:
     </para>
 
     <programlisting>
@@ -100,6 +115,21 @@ d /var/mnt 0755 root root -
 d /run/media 0755 root root -
       ]]>
 </programlisting>
+
+     <para>
+       Particularly note here the double indirection of <filename
+       class='directory'>/home</filename>.  By default, each
+       deployment will share the global toplevel <filename
+       class='directory'>/home</filename> directory on the physical
+       root filesystem.  It is then up to higher levels of management
+       tools to keep <filename>/etc/passwd</filename> or equivalent
+       synchronized between operating systems.
+     </para>
+     <para>
+       Each deployment can easily be reconfigured to have its own home
+       directory set simply by making <filename
+       class='directory'>/var/home</filename> a real directory.
+     </para>
   </chapter>
 
   <chapter id="booting">