unionfs(4)

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 elim

ination 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. Additional

ly, 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|=nfs

ro|=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, fol

lowed 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:re

versemap2:...: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, in

stead 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/

Linux January 2006

UNIONFS(4)