Provided by:
unionfs-tools_1.4+debian-7_i386 
NAME
Unionfs - a unification file system for Linux
SYNOPSIS
Unionfs is not a command, but rather a file system. This manual page
describes additional mount options that Unionfs supports.
mount -t unionfs -o branch-option[,union-options[,...]] unionfs union-
dir
DESCRIPTION
Unionfs is a stackable unification file system, which can appear to
merge the contents of several directories (branches), while keeping
their physical content separate. Unionfs is useful for unified source
tree management, merged contents of split CD-ROM, merged separate
software package directories, data grids, and more. Unionfs allows any
mix of read-only and read-write branches, as well as insertion and
deletion of branches anywhere in the fan-out. To maintain unix
semantics, Unionfs handles elimination of duplicates, partial-error
conditions, and more.
Unionfs is part of the larger FiST project.
OPTIONS
The available branch-option for the mount command is:
dirs=branch[=ro|=nfsro|=rw][:...]
specifies a separated list of which directories compose the
union. Directories that come earlier in the list have a higher
precedence than those which come later. Additionally, read-only
or read-write permissions of the branch can be specified by
appending =ro or =rw (default) to each directory.
Is the directory a read-only NFS mount and the NFS server
returns -EACCES for read-only exports, instead of -EROFS, append
=nfsro to the desired directory if you want to use copy-on-write
with NFS. If this flag is set, then Unionfs will apply standard
Unix permissions to files on NFS (so NFS ACLs will break).
Syntax:
dirs=/branch1[=ro|=nfsro|=rw]:/branch2[=ro|=nfsro|=rw]:...:/branchN[=ro|=nfsro|=rw]
Example: dirs=/writable_branch=rw:/read-only_branch=ro:/nfs-
mounted_branch=nfsro
separator="token"
specifies the character(s) that you wish to use to separate
directories in the dirs= option. By default a colon is used
however you can specify any string that you wish to use.
Syntax: separator="token"
Example: separator=":"
The available union-options for the mount command are:
debug=n
specifies the FiST debugging level n. 1 through 8 specify
individual log-levels. If debug is set to 11 through 18, the
output will include debug-10 and all lower levels. If you set
this to a non-zero value lots of output will be sent to the
kernel ring buffer, some of which may be sensitive. The default
value for this option is 0 which will produce no output.
delete=value
controls how Unionfs deletes and renames objects. Possible
values are all, and whiteout with the default behavior being
all.
imap=forwardmap:reversemap[:reversemap[:...]]
specifies a colon separated list of files that are used as the
inode map files (see unionimap(8) for how to create inode map
files). You should specify the forward map first, followed by
the reverse maps. The order of the reverse maps does not
matter. The default behavior for the imap option if left blank
is to not use persistent inode mappings.
Syntax: imap=forwardmap:reversemap1:reversemap2:...:reversemapN
Example:
imap=/tmp/foo.forward:/tmp/foo.reverse:/tmp/foo.reverse2
EXAMPLES
mount -t unionfs -o dirs=/branch_rw=rw:/branch_ro=ro unionfs /union
creates a Union in directory ‘/union’ with the branch-
directories ‘/branch_rw’ (writable) and ‘/branch_ro’ (read-
only).
mount -t unionfs -o
dirs=/branch_rw=rw:/branch_ro=ro,debug=1,delete=whiteout unionfs /union
unifies the directories ‘/branch_rw’, ‘/branch_ro’ in ‘/union’,
sets the log-level to ‘1’ and the Unionfs delete and rename
behaviour to ‘whiteout’.
BUGS
The NFS server returns -EACCES for read-only exports, instead of
-EROFS. This means we can’t reliably detect a read-only NFS export.
If you want to use copy-on-write with NFS, set the per-branch option
‘nfsro’. If this flag is set, then Unionfs will apply standard Unix
permissions to files on this nfs-mouted branch.
Modifying a Unionfs branch directly, while the union is mounted is
currently unsupported. Any such change can cause Unionfs to oops,
however it could even RESULT IN DATA LOSS.
The PPC module loading algorithm has an O(N^2) loop, so it takes a
while to load the Unionfs module, because we have lots of symbols.
Older versions of Reiser4 don’t work with Unionfs, because they can’t
handle seeking through directories properly.
To see a somewhat comprehensive list of Unionfs bugs visit
https://bugzilla.filesystems.org
AUTHORS
Charles Wright <cwright@cs.sunysb.edu>, Mohammad Zubair
<mzubair@ic.sunysb.edu>, Erez Zadok <ezk@cs.sunysb.edu>
SEE ALSO
unionctl(8), unionimap(8), uniondbg(8), http://www.fsl.cs.sunysb.edu/