From 127340741f01e7984aa48b637946b79e334b78b4 Mon Sep 17 00:00:00 2001 From: Sergiu Ivanov Date: Mon, 28 Sep 2009 18:08:36 +0300 Subject: Add the short documentation of unionmount. --- hurd/translator/unionfs.mdwn | 125 ++++++++++++++++++++++++++++++++++++++-- hurd/translator/unionmount.mdwn | 51 +--------------- 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: +# `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 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`. -# 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]] -- cgit v1.2.3