unionfs-fuse(8)unionfs-fuse(8)NAMEunionfs-fuse - A userspace unionfs implementation
SYNOPSISunionfs-fuse [-o option1 -o option2 ... -o optionN ]
top_branch:lower_branch:...:lowest_branch
mount_point
DESCRIPTIONunionfs-fuse 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-fuse options
-o chroot=path
Path to chroot into. By using this option unionfs-fuse 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-fuse-
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-fuse servs "/"
applications like KDE or GNOME might have much more open files,
which will make the unionfs-fuse process to exceed this limit.
Suggested for "/" is >16000 or even >32000 files. If this limit
exceeds unionfs-fuse will not be able to open further files.
-o noinitgroups
Since version 0.23 without any effect, just left over for com‐
patibility. Might be removed in future versions.
-o relaxed_permissions
Usually we automatically add the libfuse option "-odefault_per‐
missions" so that libfuse takes over permission checks. However,
if running not as root (so as uid =! 0 and gid != 0), permis‐
sions 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.
-o stats
Show statistics in the file 'stats' under the mountpoint.
Options to libfuse
There are several further options available, which don't directly apply
to unionfs, but to libfuse. Please run "unionfs-fuse --help" to see
these. We already set the "-o default-permissions" options on our own.
EXAMPLESunionfs-fuse-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-fuse 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-fuse 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 cre‐
ated. 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.
AUTHORSunionfs-fuse Original implemention by Radek Podgorny <radek@pod‐
gorny.cz>
COPYRIGHT
Radek Podgorny <radek@podgorny.cz>, Bernd Schubert <bernd-schu‐
bert@gmx.de>
THANKS
Many thanks to the author of the FUSE filesystem Miklos Szeredi.
unionfs-fuse 0.21 June 2008 unionfs-fuse(8)
