--- name: "bindfs" section: "1" platform: "linux" package: "bindfs" version: "1.14.7-1.1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/bindfs" --- # bindfs(1) 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.* - **--map-passwd=*\*, -o map-passwd=*\*** - **--map-group=*\*, -o map-group=*\*** *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 \* ## SEE ALSO **chmod***(1),* **fusermount***(1),* **http://bindfs.org/**