Provided by: bindfs_1.14.7-1.1build2_amd64 bug

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 --create-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 permissions  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.   Currently,  the  options  --force-user,
              --force-group,  --mirror,  --create-for-*,  --chown-*  and  --chgrp-*  override the
              corresponding 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  restore 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 --create-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 --create-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 mirrored 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 applied 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-normal.

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 return  '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 modified) file permissions inside the mount.

OTHER FILE OPERATIONS

       --delete-deny, -o delete-deny
              Makes all file delete operations fail with  a  'permission  denied'.   By  default,
              files  can  still  be  modified  if  they have write permission, and renamed if the
              directory has write permission.

       --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 request.  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 resolved symlink (inside the  same  mount
              point)  will  move  the symlink 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 actually move the old
              file out of the way, create a new file in its place, and  finally  delete  the  old
              file.  Doing  these operations 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 recursively through a resolved symlink is not
              supported and will return an error.  This  is  because  a  FUSE  filesystem  cannot
              reliably call itself recursively without deadlocking, especially in single-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 symlink 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 interface 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 underlying file.  Useless when mounting as
              root, since root will always 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 directory.  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. However, 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  enabling  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  requests  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 following 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 everyone to all
              directories and executables.

       og-x:og+rD:u=rwX:g+rw
              Removes execute bit for others and group,  adds  read  and  directory  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 separator 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 necessary security
       feature of FUSE.

       Access to device files is denied by default by FUSE as a security precaution.  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,allow_other,extended_security,noappledouble                                      See
       https://github.com/osxfuse/osxfuse/wiki/Mount-options for details.

BUGS

       If  bindfs  is  run  in  multithreaded  mode  (with  the --multithreaded option) then it's
       possible for another process to briefly see a file  with  an  incorrect  owner,  group  or
       permissions.   This  may  constitute  a  security  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 total 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 Pärtel <martin dot partel at gmail dot com>

SEE ALSO

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

                                                                                        BINDFS(1)