Merge branch 'master' into external_pager_mechanism

Conflicts:
	microkernel/mach/external_pager_mechanism.mdwn

1 files changed, 160 insertions, 0 deletions

diff --git a/hurd/translator/unionfs.mdwn b/hurd/translator/unionfs.mdwn
new file mode 100644
index 00000000..2b692cf9
--- /dev/null
+++ b/hurd/translator/unionfs.mdwn
@@ -0,0 +1,160 @@
+[[!meta copyright="Copyright © 2008, 2009, 2010 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+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`
+
+*Unionfs allows you to simply union one directory or translator into another one, so you see the files of both of them side by side.*
+
+Source repository: <http://git.savannah.gnu.org/cgit/hurd/unionfs.git/>
+
+Right now there are some problems with syncing, so please be aware
+that it might not work as expected.
+
+<a name="unionmount"></a>
+# `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.
+
+[[Sergiu Ivanov|scolobb]] has been working on this as a [[Google Summer of Code
+2009 project|community/gsoc/2009]].
+
+## 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`.
+
+# External Links
+
+  * [*Unioning file systems for Linux*](http://valerieaurora.org/union/)
+
+  * [FUSE page about
+    `unionfs`](http://sourceforge.net/apps/mediawiki/fuse/index.php?title=UnionFileSystems)
+
+  * [Linux' overlay file system proposal,
+    2010-09-20](http://thread.gmane.org/gmane.linux.kernel/1038413)
+
+    How is this different?