Provided by: unionfs-fuse_1.0-1ubuntu2_amd64 
NAME
unionfs-fuse - A userspace unionfs implementation
SYNOPSIS
unionfs [-o option1 -o option2 ... -o optionN ]
top_branch:lower_branch:...:lowest_branch
mount_point
DESCRIPTION
unionfs overlays several directory into one single mount point.
It first tries to access the file on the top branch and if the file does not exist there,
it continues on lower level branches. If the user tries to modify a file on a lower level
read-only branch the file is copied to to a higher level read-write branch if the
copy-on-write (cow) mode was enabled.
OPTIONS
Below is a summary of unionfs options
-o chroot=path
Path to chroot into. By using this option unionfs may be used for live CDs or live
USB sticks, etc. So it can serve "/" as filesystem. If you do not specify this
option and try to use it for "/" it will deadlock on calling 'pivot_root'. If you
do set this option, you also need to specify the branches relativly to the given
chroot directory. See examples/S01a-unionfs-live-cd.sh for an example.
-o cow Enable copy-on-write
-o hide_meta_files
In our unionfs root path we have a .unionfs directory that includes metadata, such
as hidden (deleted) files. This options make this directory invisible from
readdir(), so for example "ls -la /union_root/" will not show it. However, this
directory is still there and "cd .unionfs" or "ls -l .unionfs" still work. Also,
libfuse will create .fuse_hidden* files, if a file is open, but will be deleted.
Those fuse meta files also will be invisble. This option is especially usufull for
package builders.
-d Enable debugging for unionfs and libfuse. Useful for developers if the code if the
code does not behave as expected. Debug information will be written to stderr and a
debug file (./unionfs_debug.log by default).
-o debug_file=file
Write unionfs debug information into that file.
-o max_files=number
Maximum number of open files. Most system have a default of 1024 open files per
process. For example if unionfs serves "/" applications like KDE or GNOME might
have much more open files, which will make the unionfs process to exceed this
limit. Suggested for "/" is >16000 or even >32000 files. If this limit exceeds
unionfs will not be able to open further files.
-o noinitgroups
Since version 0.23 without any effect, just left over for compatibility. Might be
removed in future versions.
-o relaxed_permissions
Usually we automatically add the libfuse option "-odefault_permissions" so that
libfuse takes over permission checks. However, if running not as root (so as uid =!
0 and gid != 0), permissions of the underlying filesystem are already sufficient.
In order to prevent from severe security issues, this option is not allowed if
running as root.
-o statfs_omit_ro
By default blocks of all branches are counted in statfs() calls (e.g. by 'df'). On
setting this option read-only branches will be omitted for the summary of blocks.
This may sound weird but it actually fixes "wrong" percentage of free space.
Options to libfuse
There are several further options available, which don't directly apply to unionfs,
but to libfuse. Please run "unionfs --help" to see these. We already set the "-o
default-permissions" options on our own.
EXAMPLES
unionfs -o cow,max_files=32768 \
-o allow_other,use_ino,suid,dev,nonempty \
/u/host/etc=RW:/u/group/etc=RO:/u/common/etc=RO \
/u/union/etc
Meta data
Like other filesystems unionfs also needs to store meta data. Well, presently only
information about deleted files and directories need to be stored, but in future releases
more information might be required, e.g. inode-numbers for persistent inode information.
Meta data information are saved and looked for in the .unionfs/ directories of each
branch-root. So in the example above, these are /u/host/etc/.unionfs,
/u/group/etc/.unionfs and /u/common/etc/.unionfs. Within these directories a complete
directory structure may be found. Example: If the admin decides to delete the file
/etc/test/testfile, which only exists in /u/unionfs/etc/test/testfile, unionfs can't
delete this file, since it is on a read-only branch. So instead the whiteout file
/u/host/etc/.unionfs/test/testfile_HIDDEN~ will be created. So on accessing the union
filesystem, test/testfile will not be visible. Please also note that whiteout
files/directories will only hide the files in lower level branches. So for example
whiteouts in the group directory (/u/group/etc/.unionfs of the example above) will only
hide file of the common branch (/u/common/etc), but not these of the group and host
branches. Especially for diskless-booted environments it is rather useful for the admin
to create whiteout files him/her-self. For example one should blacklist network re-
initializations, /etc/mtab, /etc/nologin of the server and several cron-scripts. This can
be easily achieved by creating whiteout files for these scripts in the group meta
directory.
KNOWN ISSUES
1) Another issue is that presently there is no support for read-only branches
when copy-on-write is disabled, thus, -ocow is NOT specified! Support for
that might be added in later releases.
AUTHORS
unionfs-fuse Original implementation by Radek Podgorny <radek@podgorny.cz>
COPYRIGHT
Radek Podgorny <radek@podgorny.cz>, Bernd Schubert <bernd-schubert@gmx.de>
THANKS
Many thanks to the author of the FUSE filesystem Miklos Szeredi.