Hello, I'm sending in my attempt to compile a unionfs documentation. It is formatted as a stand-alone Texinfo file for now, so that I am able to build and view .info files from it. However, according to http://preview.tinyurl.com/lfy436, I will be able to add this document to the Hurd documentation using one or two @lowersections. Still, if I will not be able to use @lowersections, I will tailor the document by hand if necessary and will include it in the Hurd documentation anyway.
It took me a long time to think whether I should post the document as an attachment or directly in the message body, and I chose the latter because in this way it would be easier for you to comment. I hope I didn't choose really bad... Also note that I'm not sending a git patch, since it makes little sense to me: it would have been the same document but with some patch headers and +'s added to each line... The document follows: \input texinfo @c %**start of header @setfilename unionfs.info @settitle GNU/Hurd unionfs Documentation @c %**end of header @copying Copyright @copyright{} 2009 Free Software Foundation, Inc. @command{unionfs} is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2. @command{unionfs} is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU make; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. @end copying @titlepage @title GNU/Hurd unionfs Documentation @page @vskip Opt plus 1fill1 @insertcopying @end titlepage @contents @ifnottex @node Top @top GNU/Hurd unionfs Documentation A short GNU/Hurd unionfs translator documentation. @end ifnottex @menu * Introduction:: * Command Line Interface:: * Stowing:: * Basic Internals:: * Caveat:: * Index:: @end menu @node Introduction @chapter Introduction @cindex introduction, example The @command{unionfs} translator is a GNU/Hurd implementation of the union mounting functionality, which basically consists in merging the contents of several file systems together and mounting the result on a single node. An implementation of this functionality exists on platforms other than GNU/Hurd and is known under the name of @samp{UnionFS}. One of the best known use cases for union mounting is met in LiveCDs, where it is often necessary to combine a read-only file system, residing on the CD, with a read/write RAM disk file system. It may happen that the merged file systems will contain files with the same path. @command{unionfs} uses the priority approach to solve such conflicts. @xref{Resolving Conflicts}. To join @file{foo/}, @file{bar/} and @file{baz/} under @file{quux/} do the following: @example @code{settrans -a quux/ unionfs foo/ bar/ baz/} @end example If one would also like to include the directory tree under @file{quux/} in the list of merged file systems, use @code{unionfs -u}. File systems can be added at run-time using @command{fsysopts}. @xref{Run-time Options}. @node Command Line Interface @chapter Command Line Interface @cindex man, manual, command line, interface @section Synopsis @cindex synopsis, usage @example @code{unionfs [ options ] --add @var{file systems} --remove @var{file systems}} @end example @noindent Where @samp{options} may be any option (or options) enumerated in the section below. @samp{file systems} is a list of paths to directory trees (file system) to be merged. @noindent @strong{Note}: Since @command{unionfs} is a translator, the node to mount the merged file systems on should be specified as an argument to @command{settrans}. @section Options @cindex option, start-up, run-time @subsection Start-up Options @table @option @item -c @var{size} @itemx --cache-si...@var{size} Specify the maximal number of nodes in the node cache. @item -u @itemx --underlying Add the underlying file system to the list of union mounted file systems. @item -w @itemx --writable Specify the following file system as writable. This makes it possible to create new nodes in the specified file system. @end table @subsection Start-up and Run-time Options @anchor{Run-time Options} @table @option @item -a @itemx --add Add the following file system. This option is on by default, i.e. all file systems for which neither @option{--add} nor @option{--remove} was specified are added to the list of merged file systems. @item -r @itemx --remove Remove the following file system from the list of merged file systems. @item -p @var{value} @itemx --priori...@var{value} Set the priority for the following file system to @var{value}. @item -s @var{stowdir} @itemx --st...@var{stowdir} Use the given directory as a stow. @xref{Stowing}. @item -m @var{pattern} @itemx --match @var{pattern} Add only the nodes of the stow directory which match @var{pattern}. The pattern must be a valid shell wildcard pattern (suitable for @samp{<fnmatch.h>} functions). @end table @subsection Self-documenting Options @table @option @item -? @itemx --help Print the list of options with short descriptions. @item --usage Print a short usage message. @item -V @itemx --version Print program version. @end table @node Stowing @chapter Stowing @cindex stow @command{unionfs} can watch for changes in a directory specified as stowing directory and automatically adjust the list of merged directory trees to the list of subdirectories of the stowing directory. To use stow do the following: @example @code{settrans -a foo/ unionfs --stow=/stow} @end example Now, when a new directory appears under @file{/stow/}, @command{unionfs} will automatically add the contents of this new directory to the list of merged file systems. Corresponding updates are done when a directory is removed from under @file{/stow/}. To control which nodes from under @file{/stow/} make their way into the list of merged file systems, one can use the @option{--match} option. The pattern specified via this option must be valid shell wildcard. The following is a typical example of using a pattern-controlled stow: @example @code{settrans -a foo/ unionfs -m bar --stow=/stow} @end example Note that this syntax actually means that all file system nodes matching @file{/stow/*/bar} will be included in the merged file system. One can specify multiple patterns, which will be combined by logical @samp{OR} operation. In other words, the following two commands are equivalent: @example @code{settrans -a foo/ unionfs -m bin -m sbin --stow=/stow} @code{settrans -a foo/ unionfs -m [s]bin --stow=/stow} @end example @node Basic Internals @chapter Basic Internals @cindex internals, node, light node, conflict In this chapter a short description of how @command{unionfs} works will be done. This description is intended for people who have at least a vague idea about GNU/Hurd translator programming. Note that what follows is an overview of the basic functionality. @command{unionfs} is a @samp{libnetfs}-based translator. At the base of the file system published by this translator lies the concept of a @samp{libnetfs} node. Like many other @samp{libnetfs}-based translators, @command{unionfs} does not maintain a node for every file that appears in the merged file system it publishes, because it would present the disadvantage of consuming more space and (what is more important) will put @command{unionfs} in the middle of every I/O request coming from the client to the underlying file system. Instead, nodes are maintained only for directories and when non-directory entries are looked up, @command{unionfs} gives off a port to the @emph{real} entry (i.e., not to a @samp{libnetfs} node). Since @samp{libnetfs} does not impose the necessity of keeping the nodes in a truly hierarchical structure and since a @samp{libnetfs} node carries along with it some bits of technical information, @command{unionfs} introduces the concept of a @dfn{light node}. A light node is a custom structure (by no means connected to @samp{libnetfs}) which contains the information about a file system entry and some links to other light nodes. These links are meant to organize the light nodes in a hierarchical structure, corresponding to the virtual file system exposed by @command{unionfs} translator. The light nodes are created in a lazy fashion, i.e. when the first necessity arises. Immediately after start-up there is only one light node, corresponding to the root node of the merged file system. In further look-ups the tree of light nodes is populated. When asked to look up a file, @command{unionfs} creates light nodes per each directory in the path to the file. Correspondingly, a normal @samp{libnetfs} node is created for each light node. Each @samp{libnetfs} node is stored in a node cache, which is actually a list of references to nodes. Once a node stored in the node cache is accessed, it is pushed to the @acronym{MRU, Most Recently Used} end of the list. When, after a series of additions of new nodes the node cache becomes full, the references to the nodes at the @acronym{LRU, Least Recently Used} are dropped. When there are no references pointing to a node, it is destroyed. The same thing concerns light nodes: when the reference count stored in a light node gets to zero, the light node is destroyed. @anchor{Resolving Conflicts} @command{unionfs} associates a list of ports to the underlying file system(s) with each @samp{libnetfs} node. When look-ups are requested under this node, @command{unionfs} iterates the list and attempts to locate the required file in one of the merged file systems. The client gets the port to the file (in case it is a regular file) found in the file system that comes first in the list. File systems are installed into the list according to priorities specified at their addition. @node Caveat @chapter Caveat @cindex caveat, warning, problem, permission While using @command{unionfs}, you could experience some permission errors or difficult or impossible file or directory deletion. The following is a brief list of things that might happen. @section Warnings @itemize @bullet @item If the translator is run by an unpriviledged user, other users will fail to create files or directories, since the translator won't be able to change the ownership of the file. @end itemize @section Problems @itemize @bullet @item If there is a name conflict in underlying file systems between directories and files -- say that @file{foo} is a directory in underlying file system @file{a} while is a file in the underlying file system @file{b}" -- then unionfs will be unable to delete this entry. This is a structural bug (there's no clean way to solve it), and should be fixed. @item If there's a name conflict in underlying file systems between directories (or between files), and the user has no permission to delete all the entries -- e.g. one hidden entry is read-only -- then he will get an @samp{EPERM} even if permissions seems ok. This is a structural bug (there's no clean way to solve it), and should be fixed. @end itemize @node Index @unnumbered Index @printindex cp @bye