Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
unionfs(8)							    unionfs(8)

       unionfs-fuse - A	userspace unionfs implementation

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

       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 a higher level  read-write	branch	if  the	 copy-on-write
       (cow)  mode was enabled.

       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/
	      for an example.

       -o cow Enable copy-on-write

       -o hide_meta_files
	      In  our  unionfs root path we have a .unionfs directory that in-
	      cludes 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

       -d     Enable  debugging	for unionfs and	libfuse. Useful	for developers
	      if the code if the code does not behave as expected.  Debug  in-
	      formation	  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 "/"	appli-
	      cations 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 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.

       Options to libfuse
	      There are	several	further	options	 available,  which  don't  di-
	      rectly  apply  to	 unionfs,  but to libfuse. Please run "unionfs
	      --help" to see these.  We	already	set  the  "-o  default-permis-
	      sions" options on	our own.

	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 \

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	infor-
       mation  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	direc-
       tories 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  ac-
       cessing	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

       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@pod->

       Radek  Podgorny	<>,   Bernd   Schubert	  <bernd-schu->

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

unionfs-fuse 2.0		     2016			    unionfs(8)


Want to link to this manual page? Use this URL:

home | help