Ubuntu Manpage: bindfs ‐ mount --bind in user-space

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.

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

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.

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

MISCELLANEOUS OPTIONS

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

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

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

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

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>