[[!meta copyright="Copyright © 2008, 2009, 2010, 2013, 2014 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]]."]]"""]]
[[!tag stable_URL]]
# `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|fsysopts]] 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 proposals:
[2010-09-20](http://thread.gmane.org/gmane.linux.kernel/1038413),
[2013-03-12](http://lkml.indiana.edu/hypermail/linux/kernel/1303.1/02231.html).
How is this different?