Linux Manpages Online - man.cx manual pages

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

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).

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 [AT] cs.edu>, Mohammad Zubair <mzubair [AT] ic.edu>, Erez Zadok <ezk [AT] cs.edu>

Manpages