[SCM] wiki-content branch, master, updated. 98802c06a211461d9e5a437688ec07c102e4d895

[Tails developers]

The following commit has been merged in the master branch:
commit cf6277e51d2ab7a12860a5ae7ed14af252ff39c9
Author: Tails developers <amnesia at boum.org>
Date:   Thu Mar 1 13:36:56 2012 +0100

    Finalise the live.persist syntax and update the example.

diff --git a/devel/rfc/persistence.mdwn b/devel/rfc/persistence.mdwn
index 9e73254..4868aec 100644
--- a/devel/rfc/persistence.mdwn
+++ b/devel/rfc/persistence.mdwn
@@ -104,6 +104,55 @@ We use different labels for full persistence and custom mounts:
 Full and custom persistence are not mutually exclusive but will work
 just like when using live-rw and home-rw at the same time previously.
 
+### live.persist syntax
+
+Each line in live.persist are either a comment (line starts with `#`)
+or of the following form (using sh's IFS as separators):
+
+    SOURCE [DEST [OPTIONS...]]
+
+which roughly translates to "mount SOURCE on DEST in the way described
+by OPTIONS".
+
+SOURCE is an absolute path w.r.t. the persistent media's root that
+cannot contain "`.`" or "`..`". It specifies where the persistent data
+is stored on the persistent media.
+
+DEST is an absolute path w.r.t. the live system's filesystem root
+that cannot contain "`.`" or "`..`". It specifies where SOURCE will be
+"mounted" in the live system's filesystem. If DEST isn't specified
+it's the same as specifying DEST which is the same as SOURCE.
+
+We will always make the "mounts" in an order so that no DEST1 ever
+hides another DEST2 since DEST1 is a parent directory of DEST2. For
+instance, if we have the two DEST:s `/a` and `/a/b` we'd always mount
+`/a` first, then `/a/b`. The ordering in live.persist doesn't matter,
+and it doesn't matter if we're dealing with several live.persist:s on
+different storage media either.
+
+OPTIONS is a coma-separated list that determines in what way we
+"mount" SOURCE on DEST and can be any of the following:
+
+* Default: Bind-mount SOURCE on DEST.
+
+* `linkfiles`: Create the directory structure of the SOURCE directory
+  in the DEST directory and create symbolic links (overwriting
+  existing files or directories with the same name) from the
+  corresponding place in DEST to each file in SOURCE. Note that
+  deleting the links in DEST will only remove the link, not the
+  corresponding file in SOURCE; removed links will reappear after a
+  reboot.
+
+  Effectively `linkfiles` will make *only* the files already in SOURCE
+  persistent, not files created in DEST. This option is useful when
+  one only need certain files to be persistent and not the whole
+  directory they're in, e.g. some dot-files in $HOME's root.
+
+* `union`: Let the SOURCE be the rw branch of a union with DEST from
+  the image's read-only filesystem so only the *changes* are stored
+  persistently. This can potentially reduce disk usage, and will not
+  hide files added to the read-only media. This is not supported with
+  `union=unionmount`.
 
 ### In-depth example
 
@@ -113,37 +162,42 @@ we need but are not installed on the image. So, inside our persistent
 media $dev (either a file called custom-ov or a partition with label
 custom-ov), we put a live.persist containing:
 
-    /home/user
     /var/cache/apt
-  
+    /config-files /home/user linkfiles
+	/etc /etc union
+
 When live-boot has identified $dev as persistent media, $dev is
-mounted on some $mnt. It then checks for the existence of
-$mnt/live.persist, and since it's there we do the following:
-
-    mount ${mnt}/home/user ${root}/home/user mount
-    ${mnt}/var/cache/apt ${root}/var/cache/apt
-
-where $root is what will become the filesystem root after
-initramfs. (We leave out the exact details, but the above mount
-command of course has to be adapted depending on whether we use union
-mounts or bind-mounts.)
-
-Say that we also have another persistent media that contains the
-following live.persist:
-
-    /etc
-    /var
-    /home/user
-
-* /etc would be mounted as above without any second thoughts since
-  there's no possible mount hiding.
-* /var would have to be mounted before /var/cache/apt in order to
-  avoid getting one mount hiding the other. Note: if the same device
-  would've listed both, we'd ignore /var/cache/apt and only mount
-  /var, i.e we ignore all sub-directories.
-* /home/user is problematic, since hiding is unavoidable. Hence this
-  will cause undefined behaviour. A single device will be selected and
-  mounted on it, but we don't give any guarantees to which.
+mounted on some `${mnt}`. It then checks for the existence of
+$mnt/live.persist, and since it's there we proceed. For the first line
+we simply do:
+
+    mount --bind ${mnt}/var/cache/apt /var/cache/apt
+
+For the second line, let's say `${mnt}/config-files` contains the
+files `.emacs` and `.ssh/config`. We first create
+`/home/user/.ssh` and make sure it has the same ownership and
+permissions as `${mnt}/config-files/.ssh`. Then we do:
+
+    ln -s ${mnt}/config-files/.emacs /home/user/.emacs
+	ln -s ${mnt}/config-files/.ssh /home/user/.ssh/config
+
+The third line depends on live-boot's `union` option, but if we assume
+it's `aufs` it translates into something like:
+
+    mount -t aufs -o dirs=${mnt}/etc=rw,${rofs}=rr aufs /etc
+
+where `${rofs}` is `/etc` from the read-only filesystem (e.g. the
+`/etc` in `/live/filesystem.squashfs`). If that directory doesn't
+exist exist there's no read-only branch of the union so it essentially
+becomes a bind-mount.
+
+Say that we add the following line to live.persist (or have it in a
+live.persist on another persistent media):
+
+    /etc/ssh
+
+Then we'd always deal with this mount *after* the `/etc` mount so that
+no mount is hid by another mount.
 
 ### Snapshots
 
@@ -190,30 +244,6 @@ completely transparent.
 "global" /etc/live-snapshot.list, but then the precedence problem
 mentioned in the "Snapshots" section needs to be resolved.
 
-### Options
-
-Options may be passed as a coma separated list in the second column
-(or the third in case of the "extended syntax") for any live.persist
-entry and have the following effects:
-
-* `linkfiles`: Instead of mounting the source on the destination,
-  create the directory structure of the source in the destination
-  directory and create symbolic links (overwriting existing files or
-  directories with the same name) from the corresponding place in the
-  destination to each file in the source. Note that deleting the links
-  in the destination will only remove the link, not the corresponding
-  file in the source; removed links will reappear after a reboot.
-
-  Effectively `linkfiles` will make *only* the files already in the
-  source persistent, not files created in the destination. This option
-  is useful when one only need certain files to be persistent and not
-  the whole directory they're in, e.g. some dot-files in $HOME's root.
-
-* `union`: Let the source on the persistent media be an rw branch of a
-  union so only the *changes* are stored persistently. This can
-  potentially reduce disk usage, and will not hide files added to the
-  read-only media. This is not supported with `union=unionmount`.
-
 ### Missing sources and destinations
 
 An interesting issue is what to do if the mount source on the

-- 
wiki-content