---
name: "unionfs"
section: "4"
platform: "linux"
package: "unionfs-tools"
version: "1.4+debian-4"
release: "Debian 4.0 (Etch)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/unionfs/4"
---

# unionfs(4)

a unification file system for Linux

## 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)](/unionimap/8.md) 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)](/unionctl/8.md),** **[unionimap(8)](/unionimap/8.md),** **[uniondbg(8)](/uniondbg/8.md),** **http://www.fsl.cs.sunysb.edu/**