Table of Contents
bindfs - mount --bind in user-space
bindfs [options] dir mountpoint
A FUSE filesystem for mirroring the contents of a directory
to another directory, with changes to permissions and other features.
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.
- -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,
- Makes all files owned by the specified group. Also causes
chgrp on the mounted filesystem to always fail.
- -p, --perms=permissions, -o
- 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:...,
- 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.
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.
--mirror-only=user1:user2:..., -o mirror-only=...
- Like --mirror but disallows access
for all other users (except root).
- --map=user1/user2:@group1/@group2:..., -o
- 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.
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-group=<groupfile>, -o map-group=<groupfile>
- Like --map=...,
but reads the UID (GID) mapping from passwd (group) file (like /etc/passwd
and /etc/group). Maps UID (GID) provided in the <passwdfile> (<groupfile>) to
its corresponding user (group) name. Helpful to restore system backups where
UIDs and GIDs differ.
Requires mounting as root.
- --map-group-rev=<groupfile>, -o map-group-rev=<groupfile>
- Reversed variant of --map-passwd and --map-group. Like --map=..., but reads the UID
(GID) mapping from passwd (group) files (like /etc/passwd and /etc/group).
Maps user (group) name provided in the <passwdfile> (<groupfile>) to its corresponding
UID (GID). Helpful to create compatible chroot environments where UIDs and
Requires mounting as root.
- --uid-offset=..., -o
- 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.
- Works exactly like --uid-offset but for groups.
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.
- --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
- --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.
Chmod calls are forwarded
to the source directory by default. This may cause unexpected behaviour
if bindfs is altering permission bits.
- Tries to chown the underlying file. This is the default.
- 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
- --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.
- Makes chgrp always fail with a ’permission denied’ error. A combined
chown/chgrp request will fail as well.
Extended attributes are mirrored by default,
though not all underlying file systems support xattrs.
- --chmod-normal, -o chmod-normal
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’
- --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
- --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
- --xattr-none, -o xattr-none
- Disable extended attributes altogether. All operations will return ’Operation
- --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.
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.
- --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.
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.
- --hide-hard-links, -o hide-hard-links
- Shows the
hard link count of all files as 1.
- --resolve-symlinks, -o resolve-symlinks
resolves symbolic links. Disables creation of new symbolic links.
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.
- 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
- -h, --help
- Displays a help message and exits.
- -V, --version
- Displays version information and exits.
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
- 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
- --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.
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.
- 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
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.
- Shows block devices as regular files.
- 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.
- --no-direct-io, -o no-direct-io
By default, each read/write operation is forwarded 1:1 to the underlying
FS, disabling batching and caching by the kernel. Specify this option for
default FUSE behaviour, which may be more performant with some applications
but incompatible with others.
- --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.
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.
- -o 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).
- -o fsname=name
- Sets the source
directory name in /proc/mounts (returned by mount). This is automatically
set as long as the source path has no special characters.
program extends the chmod symbolic representation with the following operands:
‘D’ (right hand side) Works like X but applies only to directories (not
‘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.
- Removes all permission bits from others.
- Allows group
to read all files and enter all directories, but nothing else.
- Sets permission bits to 0644 and adds the execute bit for everyone to all
directories and executables.
- 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.
- bindfs -u www -g nogroup -p 0000,u=rD
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
Makes a directory read-only and accessable only by the current
- /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD
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
- bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD
Older systems may require this deprecated fstab syntax.
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.
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.
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.
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.
bugs and/or send pull requests to https://github.com/mpartel/bindfs/issues.
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.
Martin P[:a]rtel <martin dot partel at gmail dot com>
Table of Contents