unionfs-fuse(8) 														   unionfs-fuse(8)

NAME

       unionfs-fuse - A userspace unionfs implementation

SYNOPSIS

       unionfs-fuse [-o option1 -o option2 ... -o optionN ]
		    top_branch:lower_branch:...:lowest_branch
		    mount_point

DESCRIPTION

       unionfs-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 cow Enable copy-on-write

       -o stats
	      Show statistics in the file 'stats' under the mountpoint.

       -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 noinitgroups
	      Since version 0.23 without any effect, just left over for compatibility.	Might be removed in future versions.

       -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 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.  Sug-
	      gested for "/" is >16000 or even >32000 files.  If this limit exceeds unionfs-fuse will not be able to open further files.

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.

EXAMPLES

	unionfs-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 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 implemention 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.

unionfs-fuse 0.21						     June 2008							   unionfs-fuse(8)