path: root/src/bindfs.1

.TH BINDFS 1


.SH NAME
bindfs \(hy mount \-\-bind in user\-space


.SH SYNOPSIS
\fBbindfs\fP [\fIoptions\fP]\fI dir mountpoint


.SH DESCRIPTION
A FUSE filesystem for mirroring the contents of a directory to another
directory, with changes to permissions and other features.

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

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

.TP
.B \-p, \-\-perms=\fIpermissions\fP, \-o perms=...
Takes a comma\- or colon\-separated list of chmod\-like permission
specifications to be applied to the permission bits in order.
See \fB\%PERMISSION \%SPECIFICATION\fP 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 \fB-r\fP.

.TP
.B \-m, \-\-mirror=\fIuser1:user2:...\fP, \-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.

.TP
.B \-M, \-\-mirror\-only=\fIuser1:user2:...\fP, \-o mirror\-only=...
Like \fB\-\-mirror\fP but disallows access for all other users (except root).

.TP
.B \-\-map=\fIuser1/user2:@group1/@group2:...\fP, \-o map=...
Given a mapping \fIuser1/user2\fP, 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 \fB--force-user\fP, \fB--force-group\fP, \fB--mirror\fP,
\fB--create-for-*\fP, \fB--chown-*\fP and \fB--chgrp-*\fP override
the corresponding behavior of this option.

Requires mounting as root.

.TP
.B \-\-map-passwd=\fI<passwdfile>\fP, \-o map-passwd=\fI<passwdfile>\fP
.PD 0
.TP
.B \-\-map-group=\fI<groupfile>\fP, \-o map-group=\fI<groupfile>\fP
Like \fB--map=...\fP, but reads the UID (GID) mapping from passwd (group) file
(like \fI/etc/passwd\fP and \fI/etc/group\fP). Maps UID (GID) provided in the
\fI<passwdfile>\fP (\fI<groupfile>\fP) to its corresponding user (group) name.
Helpful to restore system backups where UIDs and GIDs differ.

Example usage:

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

Requires mounting as root.

.TP
.B \-\-map-passwd-rev=\fI<passwdfile>\fP, \-o map-passwd-rev=\fI<passwdfile>\fP
.PD 0
.TP
.B \-\-map-group-rev=\fI<groupfile>\fP, \-o map-group-rev=\fI<groupfile>\fP
Reversed variant of \fB--map-passwd\fP and \fB--map-group\fP. Like
\fB--map=...\fP, but reads the UID (GID) mapping from passwd (group) files
(like \fI/etc/passwd\fP and \fI/etc/group\fP). Maps user (group) name provided
in the \fI<passwdfile>\fP (\fI<groupfile>\fP) to its corresponding UID (GID).
Helpful to create compatible chroot environments where UIDs and GIDs differ.

Example usage:

\&    bindfs --map-passwd-rev=/mnt/mapped/etc/passwd \\
.br
\&        \--map-group-rev=/mnt/mapped/etc/group \\
.br
\&        /mnt/orig /mnt/mapped

Requires mounting as root.

.TP
.B \-\-uid\-offset=..., \-o uid\-offset=...
Works like \-\-map, but adds the given number to all file owner user IDs.
For instance, \fB--uid-offset=100000\fP causes a file owned by user \fI123\fP
to be shown as owned by user \fI100123\fP.

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.

.TP
.B \-\-gid\-offset=..., \-o gid\-offset=...
Works exactly like \fB--uid-offset\fP but for groups.


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

.TP
.B \-\-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 (mimicking mount \-\-bind) if the mounter is root.

.TP
.B \-\-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.

.TP
.B \-\-create\-for\-user=\fIuser\fP, \-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.

.TP
.B \-\-create\-for\-group=\fIgroup\fP, \-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.

.TP
.B \-\-create\-with\-perms=\fIpermissions\fP, \-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 \fB\%PERMISSION \%SPECIFICATION\fP below for details.


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

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

.TP
.B \-\-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.

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

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

.TP
.B \-\-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.

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


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

.TP
.B \-\-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).

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

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

.TP
.B \-\-chmod\-filter=\fIpermissions\fP, \-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 \fB\%PERMISSION \%SPECIFICATION\fP below for details.

.TP
.B \-\-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
execute bits on files will still fail with a 'permission denied'.
This option does nothing with \-\-chmod\-normal.


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

.TP
.B \-\-xattr\-none, \-o xattr\-none
Disable extended attributes altogether. All operations will
return 'Operation not supported'.

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

.TP
.B \-\-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.


.SH OTHER FILE OPERATIONS

.TP
.B \-\-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.

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

.SH 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 \fB\%BUGS\fP below.

.TP
.B \-\-read\-rate=\fIN\fP, \-o read\-rate=\fIN\fP
Allow at most \fIN\fP bytes per second to be read. \fIN\fP may have one of the
following (1024-based) suffixes: \fBk\fP, \fBM\fP, \fBG\fP, \fBT\fP.

.TP
.B \-\-write\-rate=\fIN\fP, \-o write\-rate=\fIN\fP
Same as above, but for writes.

.SH LINK HANDLING

.TP
.B \-\-hide\-hard\-links, \-o hide\-hard\-links
Shows the hard link count of all files as 1.

.TP
.B \-\-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 \fB\-\-resolved-symlink-deletion\fP.

Note that when some programs, such as \fBvim\fP, 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.

.TP
.B \-\-resolved\-symlink\-deletion=\fIpolicy\fP, \-o resolved\-symlink\-deletion=\fIpolicy\fP
If \fB\-\-resolve\-symlinks\fP is enabled, decides what happens when a resolved
symlink is deleted.  The options are: \fBdeny\fP (resolved symlinks cannot be
deleted), \fBsymlink-only\fP (the underlying symlink is deleted, its target is
not), \fBsymlink-first\fP (the symlink is deleted, and if that succeeds,
the target is deleted but no error is reported if that fails) or
\fBtarget-first\fP (the target is deleted first, and the symlink is deleted
only if deleting the target succeeded).  The default is \fBsymlink-only\fP.

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


.SH MISCELLANEOUS OPTIONS

.TP
.B \-h, \-\-help
Displays a help message and exits.

.TP
.B \-V, \-\-version
Displays version information and exits.

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

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

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

.TP
.B \-\-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.)

.TP
.B \-\-ctime\-from-mtime, \-o ctime\-from\-mtime
Recall that a unix file has three standard timestamps:
\fBatime\fP (last access i.e. read time),
\fBmtime\fP (last content modification time)
\fBctime\fP (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.

.TP
.B \-\-enable\-lock\-forwarding, \-o enable\-lock\-forwarding
Forwards \fBflock\fP and \fBfcntl\fP 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 \fBmust\fP be used with \fB\-\-multithreaded\fP because otherwise
bindfs will deadlock as soon as there is lock contention. However, see
\fB\%BUGS\fP below for caveats about \fB\-\-multithreaded\fP with the current
implementation.

.TP
.B \-\-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.

.TP
.B \-\-enable\-ioctl, \-o enable\-ioctl
Enables forwarding of ioctl, which is needed for some advanced features such as
append-only files (\fBchattr +a\fP). 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.

.TP
.B \-\-block\-devices\-as\-files, \-o block\-devices\-as\-files
Shows block devices as regular files.

.TP
.B \-\-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 \fB\%BUGS\fP below.

.TP
.B \-\-direct\-io, \-o direct\-io

Forwards each read/write operation 1:1 to the underlying FS,
disabling batching and caching by the kernel. Some applications may
require this, however it may be incompatible with other applications,
as currently it has issues with \fBmmap\fP(2) calls, at least.

.TP
.B \-\-no\-direct\-io, \-o no\-direct\-io

This option is provided in case the default changes in the future.

.TP
.B \-\-forward\-odirect=\fIalignment\fP, \-o forward\-odirect=\fIalignment\fP
Enable experimental \fBO_DIRECT\fP forwarding, with all read/write requests rounded
to the given alignment (in bytes). By default, the \fBO_DIRECT\fP flag is
not forwarded to the underlying FS.
See \fBopen\fP(2) for details about \fBO_DIRECT\fP.

Only works on Linux. Ignored on other platforms.


.SH FUSE OPTIONS

.TP
See \fBfuse\fP(8) for the full list of FUSE options. Some of the more common ones are mentioned below.

.TP
.B \-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 efficient mount with \fBmount \-\-bind\fP and then \fBmount \-o remount,ro\fP.

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

.TP
.B \-o fsname=\fIname\fP
Sets the source directory name in /proc/mounts (returned by \fBmount\fP).
This is automatically set as long as the source path has no special characters.

.TP
.B \-f
Foreground operation.


.SH PERMISSION SPECIFICATION
The \fB\-p\fP 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  \fBchmod\fP(1) command.
setuid, setgid and sticky bits are ignored.

This program extends the chmod symbolic representation with the following
operands:

`\fBD\fP' (right hand side)
    Works like \fBX\fP but applies only to directories (not to executables).

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

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


.I Examples
.TP
.B o\-rwx
Removes all permission bits from others.

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

.TP
.B 0644,a+X
Sets permission bits to 0644 and adds the execute bit for everyone
to all directories and executables.

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


.SH EXAMPLES
.BR
.TP
.B 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.

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

.TP
.B bindfs \-ono\-allow\-other,perms=a\-w somedir somedir

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

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

An example \fI/etc/fstab\fP entry. Note that the colon must be used to
separate arguments to perms, because the comma is an option separator in
\fI/etc/fstab\fP.

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

Older systems may require this deprecated fstab syntax.


.SH 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 \fB\-o dev\fP 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.
\fB\-o nolocalcaches\fP can be used to disable the cache.

With fuse-t, \fB\-o noattrcache\fP is recommended.

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

The following extra options may be useful under osxfuse:
\fB-o local,allow_other,extended_security,noappledouble\fP
See \fBhttps://github.com/osxfuse/osxfuse/wiki/Mount-options\fP for details.

.SH BUGS

If bindfs is run in multithreaded mode (with the
\fB\-\-multithreaded\fP 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
(\fBhttps://github.com/mpartel/bindfs/issues/21\fP).
For instance, Finder tags seem to work but comments might not.

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


.SH DEPRECATIONS

The option names \fB\-\-user\fP and \fB\-\-group\fP
were deprecated and replaced with \fB\-\-force\-user\fP
and \fB\-\-force\-group\fP 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 \fB\-\-owner\fP is also deprecated
for consistency.


.SH AUTHOR
Martin P\[:a]rtel <martin dot partel at gmail dot com>


.SH SEE ALSO
\fBchmod\fP(1), \fBfusermount\fP(1), \fBfuse\fP(8), \fBhttp://bindfs.org/\fP