Man Linux: Main Page and Category List


       unionfs-fuse - A userspace unionfs implementation


       unionfs-fuse [-o option1 -o option2 ... -o optionN ]


       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.


       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-
     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.
              Suggested 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.


        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 \

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.


       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.


       unionfs-fuse     Original     implemention     by     Radek    Podgorny


       Radek      Podgorny      <>,      Bernd       Schubert


       Many thanks to the author of the FUSE filesystem Miklos Szeredi.