Add the short documentation of unionmount.

2 files changed, 122 insertions, 54 deletions

diff --git a/hurd/translator/unionfs.mdwn b/hurd/translator/unionfs.mdwn
index b177b874..93a3a385 100644
--- a/hurd/translator/unionfs.mdwn
+++ b/hurd/translator/unionfs.mdwn
@@ -8,18 +8,135 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
+# `unionfs`
+
 Source repository: <http://git.savannah.gnu.org/cgit/hurd/unionfs.git/>
 
+# `unionmount`
+
+... is a special mode of `unionfs`.
+
+## Project Idea
+
+When setting a translator on Hurd -- similar to mounting a file system on UNIX
+-- the new node(s) exported by the translator are obscuring the original node
+where the translator is set, and any nodes below it in the directory tree. The
+translator itself can access the underlying node (which is a very nice feature,
+as it allows translators presenting the contents of the node in a different
+format); but it's no longer accessible from the "outside".
+
+Plan9 has a feature where a file system can be mounted in union mode: the new
+file system doesn't obscure the mount point in this case, but instead the
+contents are combined. (This feature has also been under discussion in Linux
+for a couple of years now, under the label "VFS-based union mounts".)
+
+This kind of union mounts is generally useful, as it's sometimes more
+convenient than unioning existing filesystem locations with unionfs -- it's not
+necessary to mount a file system that is to be unioned at some external
+location first: just union-mount it directly at the target location.
+
+But union mounts also allow creating passive translator hierarchies: If there
+is a passive translator on a parent node, and further passive translators on
+child nodes, the union mount allows the child nodes with the further translator
+settings still to be visible after the parent translator has started.
+
+This could be useful for device nodes for example: let's say we have an
+ethernet multiplexer at /dev/veth. Now the virtual subnodes could all be
+directly under /dev, i.e. /dev/veth0, /dev/veth1 etc., and explicitely refer to
+the main /dev/veth node in the translator command line. It would be more
+elegant however to store the virtual nodes direcly below the main multiplexer
+node -- /dev/veth/0, /dev/veth/1 etc.
+
+There are two possible approaches how union mounts could be implemented in the
+Hurd. The first one is to let the various translators handle union mounts
+internally, i.e. let them present the underlying nodes to the clients in
+addition to the actual nodes they export themselfs. This probably can be
+implemented as some kind of extension to the existing netfs and diskfs
+libraries.
+
+The other possible apporach is less efficient and probably more tricky, but
+probably also more generic: create a special unionmount translator, which
+serves as a kind of proxy: setting the union-mounted translator on some
+internal node; and at the actual mount location, presenting a union of the
+nodes exported by this translator, and the nodes from the underlying file
+system.
+
+The goal of this project is implementing union mounts using either of the
+approaches described above. (Though it might be useful initially to prototype
+both for comparision.) The ethernet multiplexer shall serve as an example use
+case -- any changes necessary to allow using it with the union mount
+functionality are also to be considered part of the task.
+
+## Implementation
+
+### Source
+
+Union mounts are currently implemented as two additional command line
+options of the `unionfs` translator.  This implementation resides in
+the master-unionmount branch of the unionfs git repository.  To
+checkout the code, do the following:
+
+    $ git clone git://git.sv.gnu.org/hurd/unionfs.git
+    $ cd unionfs
+    $ git checkout -b master-unionmount
+    $ git pull origin master-unionmount
+
+You can skip the checkout step if you don't mind that the
+`master-unionmount` branch gets merged into the `master` branch.
+
+### Short Documentation
+
+The `unionmount` project adds options "--mount" and "--no-mount" to
+`unionfs` (short versions: "-t" and "-n" correspondingly).  Both
+options are used to implement union-mounting, but the first option
+will create a *transparent* union mount, while the second option will
+create a *nontransparent* union mount.
+
+One can create a transparent union mount with the following command:
+
+    $ settrans -a <node> unionfs --underlying --mount=<translator>
+
+When running
+
+    $ fsysopts <node>
+
+one will see the information about the `<translator>`, not the
+`unionfs` translator.  Although this might seem the only natural way
+to do union mounts, one must keep in mind that such transparency
+deprives one of the possibility to modify the unioned virtual
+filesystem exported by `unionfs` at run-time (via `fsysopts`).
+
+One can create a nontransparent union mount with the following command:
+
+    $ settrans -a <node> unionfs --underlying --no-mount=<translator>
+
+When running
+
+    $ fsysopts <node>
+
+one will see the information about the `unionfs` translator.  Although
+this way allows modifying the contents of the unioned filesystem
+exported by `unionfs` at runtime, the access to `<translator>` is
+blocked.
+
+The filesystem exported by the *mountee* (`<translator>`) is actually
+treated like a normal filesystem within `unionfs`, which means that
+one can assign priorities to the *mountee* to achieve the desired
+order of layering of the unioned directories.  The following will make
+`unionfs` query the underlying filesystem first and then the
+*mountee*:
+
+    $ settrans -a <node> unionfs --priority=2 --underlying --priority=1 --mount=<translator>
+
+Note that the same functionality can also be achieved by assigning
+priority 1 to the underlying filesystem and keeping the priority of
+the *mountee* at 0.
 
 <a name="stowfs"></a>
 # `stowfs`
 
 ... is a special mode of `unionfs`.
 
-# See Also
-
-  * [[unionmount]]
-
 # External Links
 
   * [*Unioning file systems for Linux*](http://valerieaurora.org/union/)
diff --git a/hurd/translator/unionmount.mdwn b/hurd/translator/unionmount.mdwn
index 47a3d85d..65f09719 100644
--- a/hurd/translator/unionmount.mdwn
+++ b/hurd/translator/unionmount.mdwn
@@ -8,53 +8,4 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-[[!meta title="Union Mounts"]]
-
-When setting a translator on Hurd -- similar to mounting a file system on UNIX
--- the new node(s) exported by the translator are obscuring the original node
-where the translator is set, and any nodes below it in the directory tree. The
-translator itself can access the underlying node (which is a very nice feature,
-as it allows translators presenting the contents of the node in a different
-format); but it's no longer accessible from the "outside".
-
-Plan9 has a feature where a file system can be mounted in union mode: the new
-file system doesn't obscure the mount point in this case, but instead the
-contents are combined. (This feature has also been under discussion in Linux
-for a couple of years now, under the label "VFS-based union mounts".)
-
-This kind of union mounts is generally useful, as it's sometimes more
-convenient than unioning existing filesystem locations with unionfs -- it's not
-necessary to mount a file system that is to be unioned at some external
-location first: just union-mount it directly at the target location.
-
-But union mounts also allow creating passive translator hierarchies: If there
-is a passive translator on a parent node, and further passive translators on
-child nodes, the union mount allows the child nodes with the further translator
-settings still to be visible after the parent translator has started.
-
-This could be useful for device nodes for example: let's say we have an
-ethernet multiplexer at /dev/veth. Now the virtual subnodes could all be
-directly under /dev, i.e. /dev/veth0, /dev/veth1 etc., and explicitely refer to
-the main /dev/veth node in the translator command line. It would be more
-elegant however to store the virtual nodes direcly below the main multiplexer
-node -- /dev/veth/0, /dev/veth/1 etc.
-
-There are two possible approaches how union mounts could be implemented in the
-Hurd. The first one is to let the various translators handle union mounts
-internally, i.e. let them present the underlying nodes to the clients in
-addition to the actual nodes they export themselfs. This probably can be
-implemented as some kind of extension to the existing netfs and diskfs
-libraries.
-
-The other possible apporach is less efficient and probably more tricky, but
-probably also more generic: create a special unionmount translator, which
-serves as a kind of proxy: setting the union-mounted translator on some
-internal node; and at the actual mount location, presenting a union of the
-nodes exported by this translator, and the nodes from the underlying file
-system.
-
-The goal of this project is implementing union mounts using either of the
-approaches described above. (Though it might be useful initially to prototype
-both for comparision.) The ethernet multiplexer shall serve as an example use
-case -- any changes necessary to allow using it with the union mount
-functionality are also to be considered part of the task.
+[[!meta redir=unionfs]]