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

FreeBSD Manual Pages

  
 
  

home | help
BINDFS(1)		    General Commands Manual		     BINDFS(1)

NAME
       bindfs -	mount --bind in	user-space

SYNOPSIS
       bindfs [options]	dir mountpoint

DESCRIPTION
       A  FUSE filesystem for mirroring	the contents of	a directory to another
       directory. Additionally,	one can	change the permissions of files	in the
       mirrored	directory.

FILE OWNERSHIP
       -u, --force-user, -o force-user=...
	      Makes  all files owned by	the specified user.  Also causes chown
	      on the mounted filesystem	to always fail.

       -g, --force-group=group,	-o force-group=...
	      Makes all	files owned by the specified group.  Also causes chgrp
	      on the mounted filesystem	to always fail.

       -p, --perms=permissions,	-o perms=...
	      Takes  a comma- or colon-separated list of chmod-like permission
	      specifications to	be applied to the permission  bits  in	order.
	      See PERMISSION SPECIFICATION below for details.

	      This  only affects how the permission bits of existing files are
	      altered when shown in the	mounted	directory. You can use	--cre-
	      ate-with-perms  to  change  the  permissions  that newly created
	      files get	in the source directory.

	      Note that, as usual, the root user isn't bound  by  the  permis-
	      sions  set  here.	  You can get a	truly read-only	mount by using
	      -r.

       -m, --mirror=user1:user2:..., -o	mirror=...
	      Takes a comma- or	colon-separated	list of	 users	who  will  see
	      themselves  as the owners	of all files. Users who	are not	listed
	      here will	still be able to access	the mount if  the  permissions
	      otherwise	allow them to.

	      You  can	also  give a group name	prefixed with an '@' to	mirror
	      all members of a group. This will	not  change  which  group  the
	      files are	shown to have.

       -M, --mirror-only=user1:user2:..., -o mirror-only=...
	      Like  --mirror  but disallows access for all other users (except
	      root).

       --map=user1/user2:@group1/@group2:..., -o map=...
	      Given a mapping user1/user2, all files owned by user1 are	 shown
	      as owned by user2. When user2 creates files, they	are chowned to
	      user1 in the underlying directory. When  files  are  chowned  to
	      user2,  they  are	 chowned to user1 in the underlying directory.
	      Works similarly for groups.

	      A	single user or group may appear	no more	than once on the  left
	      and  once	on the right of	a slash	in the list of mappings.  Cur-
	      rently,  the  options  --force-user,  --force-group,   --mirror,
	      --create-for-*, --chown-*	and --chgrp-* override the correspond-
	      ing behavior of this option.

	      Requires mounting	as root.

       --map-passwd=_passwdfile_, -o map-passwd=_passwdfile_
       --map-group=_groupfile_,	-o map-group=_groupfile_
	      Like --map=..., but reads	the UID/GID mapping  from  passwd  and
	      group  files  (like  /etc/passwd and /etc/group).	Helpful	to re-
	      store system backups where UIDs/GIDs differ.

	      Example usage:

		  bindfs --map-passwd=/mnt/orig/etc/passwd \
		      --map-passwd=/mnt/orig/etc/group \
		      /mnt/orig	/mnt/mapped

	      Requires mounting	as root.

       --uid-offset=..., -o uid-offset=...
	      Works like --map,	but adds the given number to  all  file	 owner
	      user IDs.	 For instance, --uid-offset=100000 causes a file owned
	      by user 123 to be	shown as owned by user 100123.

	      For now, this option cannot be used together with	--map.	Please
	      file  an issue with the desired semantics	if you have a case for
	      using them together.

	      Requires mounting	as root.

       --gid-offset=..., -o gid-offset=...
	      Works exactly like --uid-offset but for groups.

FILE CREATION POLICY
       New files and directories are created so	they are owned by the mounter.
       bindfs  can  let	 this happen (the default for normal users), or	it can
       try to change the owner to the uid/gid of the  process  that  wants  to
       create  the  file  (the default for root).  It is also possible to have
       bindfs try to change the	owner to a particular user or group.

       --create-as-user, -o create-as-user
	      Tries to change the owner	and group of new files and directories
	      to  the  uid  and	 gid  of the caller. This can work only	if the
	      mounter is root.	It is  also  the  default  behavior  (mimicing
	      mount --bind) if the mounter is root.

       --create-as-mounter, -o create-as-mounter
	      All  new	files  and  directories	 will be owned by the mounter.
	      This is the default behavior for non-root	mounters.

       --create-for-user=user, -o create-for-user=...
	      Tries to change the owner	of new files and  directories  to  the
	      user specified here.  This can work only if the mounter is root.
	      This  option   overrides	 the   --create-as-user	  and	--cre-
	      ate-as-mounter options.

       --create-for-group=group, -o create-for-group=...
	      Tries to change the owning group of new files and	directories to
	      the group	specified here.	 This can work only if the mounter  is
	      root.   This  option  overrides  the --create-as-user and	--cre-
	      ate-as-mounter options.

       --create-with-perms=permissions,	-o create-with-perms=...
	      Works like --perms but is	applied	to the permission bits of  new
	      files  get in the	source directory.  Normally the	permissions of
	      new files	depend	on  the	 creating  process's  preferences  and
	      umask.   This  option can	be used	to modify those	permissions or
	      override them completely.	 See  PERMISSION  SPECIFICATION	 below
	      for details.

CHOWN/CHGRP POLICY
       The  behaviour on chown/chgrp calls can be changed. By default they are
       passed through to the source directory even if bindfs is	set to show  a
       fake  owner/group. A chown/chgrp	call will only succeed if the user has
       enough mirrored permissions to chmod the	mirrored file AND the  mounter
       has enough permissions to chmod the real	file.

       --chown-normal, -o chown-normal
	      Tries to chown the underlying file. This is the default.

       --chown-ignore, -o chown-ignore
	      Lets chown succeed (if the user has enough mirrored permissions)
	      but actually does	nothing. A combined chown/chgrp	is effectively
	      turned into a chgrp-only request.

       --chown-deny, -o	chown-deny
	      Makes  chown  always  fail  with a 'permission denied' error.  A
	      combined chown/chgrp request will	fail as	well.

       --chgrp-normal, -o chgrp-normal
	      Tries to chgrp the underlying file. This is the default.

       --chgrp-ignore, -o chgrp-ignore
	      Lets chgrp succeed (if the user has enough mirrored permissions)
	      but actually does	nothing. A combined chown/chgrp	is effectively
	      turned into a chown-only request.

       --chgrp-deny, -o	chgrp-deny
	      Makes chgrp always fail with a  'permission  denied'  error.   A
	      combined chown/chgrp request will	fail as	well.

CHMOD POLICY
       Chmod calls are forwarded to the	source directory by default.  This may
       cause unexpected	behaviour if bindfs is altering	permission bits.

       --chmod-normal, -o chmod-normal
	      Tries to chmod the underlying file. This	will  succeed  if  the
	      user  has	the appropriate	mirrored permissions to	chmod the mir-
	      rored file AND the mounter has enough permissions	to  chmod  the
	      real  file.   This is the	default	(in order to behave like mount
	      --bind by	default).

       --chmod-ignore, -o chmod-ignore
	      Lets chmod succeed (if the user has enough mirrored permissions)
	      but actually does	nothing.

       --chmod-deny, -o	chmod-deny
	      Makes chmod always fail with a 'permission denied' error.

       --chmod-filter=permissions, -o chmod-filter=...
	      Changes  the permission bits of a	chmod request before it	is ap-
	      plied to the original file. Accepts the same  permission	syntax
	      as --perms.  See PERMISSION SPECIFICATION	below for details.

       --chmod-allow-x,	-o chmod-allow-x
	      Allows  setting  and  clearing the executable attribute on files
	      (but not directories). When  used	 with  --chmod-ignore,	chmods
	      will only	affect execute bits on files and changes to other bits
	      are discarded.  With --chmod-deny, all chmods that would	change
	      any  bits	 except	 excecute bits on files	will still fail	with a
	      'permission denied'.  This option	does nothing with --chmod-nor-
	      mal.

XATTR POLICY
       Extended	 attributes are	mirrored by default, though not	all underlying
       file systems support xattrs.

       --xattr-none, -o	xattr-none
	      Disable extended attributes altogether. All operations will  re-
	      turn 'Operation not supported'.

       --xattr-ro, -o xattr-ro
	      Let extended attributes be read-only.

       --xattr-rw, -o xattr-rw
	      Let  extended  attributes	 be  read-write	 (the  default).   The
	      read/write permissions are checked against the  (possibly	 modi-
	      fied) file permissions inside the	mount.

OTHER FILE OPERATIONS
       --delete-deny, -o delete-deny
	      Makes  all  file	delete	operations fail	with a 'permission de-
	      nied'.  By default, files	can still be  modified	if  they  have
	      write permission,	and renamed if the directory has write permis-
	      sion.

       --rename-deny, -o rename-deny
	      Makes all	file rename/move operations within the mountpoint fail
	      with  a  'permission  denied'. Programs that move	files out of a
	      mountpoint do so by copying and deleting the original.

RATE LIMITS
       Reads and writes	through	the mount point	can be	throttled.  Throttling
       works by	sleeping the required amount of	time on	each read or write re-
       quest.  Throttling imposes one global limit on all  readers/writers  as
       opposed to a per-process	or per-user limit.

       Currently, the implementation is	not entirely fair. See BUGS below.

       --read-rate=N, -o read-rate=N
	      Allow  at	 most N	bytes per second to be read. N may have	one of
	      the following (1024-based) suffixes: k, M, G, T.

       --write-rate=N, -o write-rate=N
	      Same as above, but for writes.

LINK HANDLING
       --hide-hard-links, -o hide-hard-links
	      Shows the	hard link count	of all files as	1.

       --resolve-symlinks, -o resolve-symlinks
	      Transparently resolves symbolic links.  Disables creation	of new
	      symbolic links.

	      With  the	following exceptions, operations will operate directly
	      on the target file instead of the	symlink. Renaming/moving a re-
	      solved  symlink (inside the same mount point) will move the sym-
	      link instead of the underlying file. Deleting a resolved symlink
	      will delete the underlying symlink but not the destination file.
	      This can be configured with --resolved-symlink-deletion.

	      Note that	when some programs, such as vim, save files, they  ac-
	      tually  move  the	 old file out of the way, create a new file in
	      its place, and finally delete the	old file. Doing	 these	opera-
	      tions on a resolved symlink will replace it with a regular file.

	      Symlinks	pointing  outside  the	source directory are supported
	      with the following exception: accessing  the  mountpoint	recur-
	      sively  through a	resolved symlink is not	supported and will re-
	      turn an error. This is because a FUSE filesystem cannot reliably
	      call  itself recursively without deadlocking, especially in sin-
	      gle-threaded mode.

       --resolved-symlink-deletion=policy, -o resolved-symlink-deletion=policy
	      If --resolve-symlinks is enabled,	decides	what  happens  when  a
	      resolved	symlink	 is  deleted.  The options are:	deny (resolved
	      symlinks cannot be deleted), symlink-only	(the  underlying  sym-
	      link  is deleted,	its target is not), symlink-first (the symlink
	      is deleted, and if that succeeds,	the target is deleted  but  no
	      error  is	reported if that fails)	or target-first	(the target is
	      deleted first, and the symlink is	deleted	only if	 deleting  the
	      target succeeded).  The default is symlink-only.

	      Note  that deleting files	inside symlinked directories is	always
	      possible with all	settings,  including  deny,  unless  something
	      else protects those files.

MISCELLANEOUS OPTIONS
       -h, --help
	      Displays a help message and exits.

       -V, --version
	      Displays version information and exits.

	      --fuse-version  Displays	the version of the FUSE	library	inter-
	      face that	was seen at compile-time, as well as the version  that
	      bindfs currently runs with.

       --no-allow-other, -o no-allow-other
	      Does  not	 add  -o allow_other to	FUSE options.  This causes the
	      mount to be accessible only by the current user.

	      (The deprecated shorthand	-n is also still accepted.)

       --realistic-permissions,	-o realistic-permissions
	      Hides read/write/execute permissions for a  mirrored  file  when
	      the mounter doesn't have read/write/execute access to the	under-
	      lying file.  Useless when	mounting as root, since	root will  al-
	      ways have	full access.

	      (Prior  to version 1.10 this option was the default behavior.  I
	      felt it violated the principle of	least surprise badly enough to
	      warrant a	small break in backwards-compatibility.)

       --ctime-from-mtime, -o ctime-from-mtime
	      Recall  that  a  unix  file has three standard timestamps: atime
	      (last access i.e.	read time), mtime (last	 content  modification
	      time) ctime (last	content	or metadata (inode) change time)

	      With  this  option, the ctime of each file and directory is read
	      from its mtime.  In other	words, only content modifications  (as
	      opposed  to  metadata  changes)  will be reflected in a mirrored
	      file's ctime.  The underlying file's ctime will still be updated
	      normally.

       --enable-lock-forwarding, -o enable-lock-forwarding
	      Forwards	flock  and fcntl locking requests to the source	direc-
	      tory.  This way, locking a file in the bindfs  mount  will  also
	      lock the file in the source directory.

	      This  option must	be used	with --multithreaded because otherwise
	      bindfs will deadlock as soon as there is lock  contention.  How-
	      ever,  see BUGS below for	caveats	about --multithreaded with the
	      current implementation.

       --disable-lock-forwarding, -o disable-lock-forwarding
	      Currently	does nothing, but a future release may default to  en-
	      abling  lock  forwarding.	 If you	depend on this behaviour, it's
	      recommended to set this flag explicitly.

       --enable-ioctl, -o enable-ioctl
	      Enables forwarding of ioctl, which is needed for	some  advanced
	      features	such  as  append-only files (chattr +a). Note that the
	      ioctl action will	be performed as	the mounter, not  the  calling
	      user.  No	 efforts  are  made  to	check whether the calling user
	      would ordinarily have the	permissions to make  the  ioctl.  This
	      may be a security	concern, especially when mounting as root.

       --block-devices-as-files, -o block-devices-as-files
	      Shows block devices as regular files.

       --multithreaded,	-o multithreaded
	      Run bindfs in multithreaded mode.	While bindfs is	designed to be
	      otherwise	thread-safe, there is currently	a race condition  that
	      may pose a security risk for some	use cases. See BUGS below.

       --forward-odirect=alignment, -o forward-odirect=alignment
	      Enable experimental O_DIRECT forwarding, with all	read/write re-
	      quests rounded to	the given alignment (in	 bytes).  By  default,
	      the  O_DIRECT  flag  is not forwarded to the underlying FS.  See
	      open(2) for details about	O_DIRECT.

	      Only works on Linux. Ignored on other platforms.

FUSE OPTIONS
       -o options
	      Fuse options.

       -r, -o ro
	      Make the mount strictly read-only.  This even prevents root from
	      writing  to  it.	 If  this  is  all you need, then (since Linux
	      2.6.26) you can get a more efficent mount	with mount --bind  and
	      then mount -o remount,ro.

       -d, -o debug
	      Enable debug output (implies -f).

       -f     Foreground operation.

PERMISSION SPECIFICATION
       The  -p	option	takes a	comma- or colon-separated list of either octal
       numeric permission bits or symbolic representations of  permission  bit
       operations.   The  symbolic  representation  is	based  on  that	of the
       chmod(1)	command.  setuid, setgid and sticky bits are ignored.

       This program extends the	chmod symbolic representation with the follow-
       ing operands:

       `D' (right hand side)
	   Works like X	but applies only to directories	(not to	executables).

       `d' and `f' (left hand side)
	   Makes this directive	only apply to directories (d) or files (f).
	   e.g.	gd-w would remove the group write bit from all directories.

       `u', `g', `o' (right hand side)
	   Uses	the user (u), group (g)	or others (o) permission bits of
	   the original	file.
	   e.g.	g=u would copy the user's permission bits to the group.
		ug+o would add the others' permissions to the owner and	group.

       Examples
       o-rwx  Removes all permission bits from others.

       g=rD   Allows  group  to	 read all files	and enter all directories, but
	      nothing else.

       0644,a+X
	      Sets permission bits to 0644 and adds the	execute	bit for	every-
	      one to all directories and executables.

       og-x:og+rD:u=rwX:g+rw
	      Removes  execute	bit for	others and group, adds read and	direc-
	      tory execute for others and  group,  sets	 user  permissions  to
	      read,  write  and	 execute  directory/executable,	 adds read and
	      write for	group.

EXAMPLES

       bindfs -u www -g	nogroup	-p 0000,u=rD ~/mywebsite ~/public_html/mysite

	      Publishes	a website in public_html so that only the  'www'  user
	      can read the site.

       bindfs -M foo,bar,1007,@mygroup -p 0600,u+X dir mnt

	      Gives access to 'foo', 'bar', the	user with the UID 1007 as well
	      as everyone in the group 'mygroup'. Sets the permission bits  to
	      0600,  thus  giving  the	specified users	read/write access, and
	      adds the user execute bit	for directories	and executables.

       bindfs -ono-allow-other,perms=a-w somedir somedir

	      Makes a directory	read-only and accessable only by  the  current
	      user.

       /home/bob/shared	/var/www/shared/bob fuse.bindfs	perms=0000:u+rD	0 0

	      An example /etc/fstab entry. Note	that the colon must be used to
	      separate arguments to perms, because the comma is	an option sep-
	      arator in	/etc/fstab.

       bindfs#/home/bob/shared /var/www/shared/bob fuse	perms=0000:u+rD	0 0

	      Older systems may	require	this deprecated	fstab syntax.

NOTES
       Setuid and setgid bits have no effect inside the	mount.	This is	a nec-
       essary security feature of FUSE.

       Access to device	files is denied	by default by FUSE as a	security  pre-
       caution.	 Use -o	dev to enable access (requires mounting	as root). This
       may not be supported on all operating systems.

       MacFuse caches file contents by default.	 This means  that  changes  in
       source  files are not always immediately	visible	under the mount	point.
       -o nolocalcaches	can be used to disable the cache.

       When using --mirror[-only] @somegroup, bindfs won't see changes to  the
       group's	member	list.	Sending	 bindfs	 a SIGUSR1 signal will make it
       reread the user database.

       The following extra options may be useful under osxfuse:	 -o  local,al-
       low_other,extended_security,noappledouble  See  https://github.com/osx-
       fuse/osxfuse/wiki/Mount-options for details.

BUGS
       If bindfs is run	in multithreaded mode (with  the  --multithreaded  op-
       tion) then it's possible	for another process to briefly see a file with
       an incorrect owner, group or permissions.  This may constitute a	 secu-
       rity risk if you	rely on	bindfs to reduce permissions on	new files. For
       this reason, as of version 1.11 bindfs runs in single-threaded mode  by
       default.

       Rate  limiting  favors  the process with	the larger block size.	If two
       processes compete for read/write	access,	the one	 whose	read()/write()
       calls specify the larger	block size gets	to read/write faster.  The to-
       tal rate	limit is maintained though, and	clients	with equal block sizes
       and a similar rate of requests are treated fairly as long as the	kernel
       orders their requests fairly.

       Some features relying on	 xattrs	 might	not  work  properly  on	 OS  X
       (https://github.com/mpartel/bindfs/issues/21).	For  instance,	Finder
       tags seem to work but comments might not.

       Please	 report	   bugs	   and/or    send     pull     requests	    to
       https://github.com/mpartel/bindfs/issues.

DEPRECATIONS
       The  option  names --user and --group were deprecated and replaced with
       --force-user and	--force-group  in  version  1.12.   The	 former	 names
       clashed with standard option names.  They are still available but their
       use is discouraged and prints a warning.	The synonym  --owner  is  also
       deprecated for consistency.

AUTHOR
       Martin Partel <martin dot partel	at gmail dot com>

SEE ALSO
       chmod(1), fusermount(1),	http://bindfs.org/

								     BINDFS(1)

NAME | SYNOPSIS | DESCRIPTION | FILE OWNERSHIP | FILE CREATION POLICY | CHOWN/CHGRP POLICY | CHMOD POLICY | XATTR POLICY | OTHER FILE OPERATIONS | RATE LIMITS | LINK HANDLING | MISCELLANEOUS OPTIONS | FUSE OPTIONS | PERMISSION SPECIFICATION | EXAMPLES | NOTES | BUGS | DEPRECATIONS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bindfs&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help