Provided by: unionfs-tools_1.4+debian-7_i386 bug

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/