GNU Hurd/ hurd/ translator/ unionfs

Welcome to... ... the GNU Hurd!

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: https://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.

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 has been working on this as a Google Summer of Code 2009 project.

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.

stowfs

... is a special mode of unionfs.

External Links