[[!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: 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|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 unionfs --underlying --mount= When running $ fsysopts one will see the information about the ``, 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 unionfs --underlying --no-mount= When running $ fsysopts 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 `` is blocked. The filesystem exported by the *mountee* (``) 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 unionfs --priority=2 --underlying --priority=1 --mount= 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 * [*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?