1BINDFS(1) General Commands Manual BINDFS(1)
2
6 bindfs ‐ mount --bind in user-space
7
11 bindfs [options] dir mountpoint
12
16 A FUSE filesystem for mirroring the contents of a directory to another
17 directory, with changes to permissions and other features.
18
21 -u, --force-user, -o force-user=...
22 Makes all files owned by the specified user. Also causes chown
23 on the mounted filesystem to always fail.
24 -g, --force-group=group, -o force-group=...
27 Makes all files owned by the specified group. Also causes chgrp
28 on the mounted filesystem to always fail.
29 -p, --perms=permissions, -o perms=...
32 Takes a comma- or colon-separated list of chmod-like permission
33 specifications to be applied to the permission bits in order.
34 See PERMISSION SPECIFICATION below for details.
35 This only affects how the permission bits of existing files are
37 altered when shown in the mounted directory. You can use --cre‐
38 ate-with-perms to change the permissions that newly created
39 files get in the source directory.
40 Note that, as usual, the root user isn't bound by the permis‐
42 sions set here. You can get a truly read-only mount by using
43 -r.
44 -m, --mirror=user1:user2:..., -o mirror=...
47 Takes a comma- or colon-separated list of users who will see
48 themselves as the owners of all files. Users who are not listed
49 here will still be able to access the mount if the permissions
50 otherwise allow them to.
51 You can also give a group name prefixed with an '@' to mirror
53 all members of a group. This will not change which group the
54 files are shown to have.
55 -M, --mirror-only=user1:user2:..., -o mirror-only=...
58 Like --mirror but disallows access for all other users (except
59 root).
60 --map=user1/user2:@group1/@group2:..., -o map=...
63 Given a mapping user1/user2, all files owned by user1 are shown
64 as owned by user2. When user2 creates files, they are chowned to
65 user1 in the underlying directory. When files are chowned to
66 user2, they are chowned to user1 in the underlying directory.
67 Works similarly for groups.
68 A single user or group may appear no more than once on the left
70 and once on the right of a slash in the list of mappings. Cur‐
71 rently, the options --force-user, --force-group, --mirror,
72 --create-for-*, --chown-* and --chgrp-* override the correspond‐
73 ing behavior of this option.
74 Requires mounting as root.
76 --map-passwd=<passwdfile>, -o map-passwd=<passwdfile>
79 --map-group=<groupfile>, -o map-group=<groupfile>
80 Like --map=..., but reads the UID (GID) mapping from passwd
81 (group) file (like /etc/passwd and /etc/group). Maps UID (GID)
82 provided in the <passwdfile> (<groupfile>) to its corresponding
83 user (group) name. Helpful to restore system backups where UIDs
84 and GIDs differ.
85 Example usage:
87 bindfs --map-passwd=/mnt/orig/etc/passwd \
89 --map-group=/mnt/orig/etc/group \
90 /mnt/orig /mnt/mapped
91 Requires mounting as root.
93 --map-passwd-rev=<passwdfile>, -o map-passwd-rev=<passwdfile>
95 --map-group-rev=<groupfile>, -o map-group-rev=<groupfile>
96 Reversed variant of --map-passwd and --map-group. Like
97 --map=..., but reads the UID (GID) mapping from passwd (group)
98 files (like /etc/passwd and /etc/group). Maps user (group) name
99 provided in the <passwdfile> (<groupfile>) to its corresponding
100 UID (GID). Helpful to create compatible chroot environments
101 where UIDs and GIDs differ.
102 Example usage:
104 bindfs --map-passwd-rev=/mnt/mapped/etc/passwd \
106 --map-group-rev=/mnt/mapped/etc/group \
107 /mnt/orig /mnt/mapped
108 Requires mounting as root.
110 --uid-offset=..., -o uid-offset=...
112 Works like --map, but adds the given number to all file owner
113 user IDs. For instance, --uid-offset=100000 causes a file owned
114 by user 123 to be shown as owned by user 100123.
115 For now, this option cannot be used together with --map. Please
117 file an issue with the desired semantics if you have a case for
118 using them together.
119 Requires mounting as root.
121 --gid-offset=..., -o gid-offset=...
123 Works exactly like --uid-offset but for groups.
124
127 New files and directories are created so they are owned by the mounter.
128 bindfs can let this happen (the default for normal users), or it can
129 try to change the owner to the uid/gid of the process that wants to
130 create the file (the default for root). It is also possible to have
131 bindfs try to change the owner to a particular user or group.
132 --create-as-user, -o create-as-user
134 Tries to change the owner and group of new files and directories
135 to the uid and gid of the caller. This can work only if the
136 mounter is root. It is also the default behavior (mimicing
137 mount --bind) if the mounter is root.
138 --create-as-mounter, -o create-as-mounter
140 All new files and directories will be owned by the mounter.
141 This is the default behavior for non-root mounters.
142 --create-for-user=user, -o create-for-user=...
144 Tries to change the owner of new files and directories to the
145 user specified here. This can work only if the mounter is root.
146 This option overrides the --create-as-user and --cre‐
147 ate-as-mounter options.
148 --create-for-group=group, -o create-for-group=...
150 Tries to change the owning group of new files and directories to
151 the group specified here. This can work only if the mounter is
152 root. This option overrides the --create-as-user and --cre‐
153 ate-as-mounter options.
154 --create-with-perms=permissions, -o create-with-perms=...
156 Works like --perms but is applied to the permission bits of new
157 files get in the source directory. Normally the permissions of
158 new files depend on the creating process's preferences and
159 umask. This option can be used to modify those permissions or
160 override them completely. See PERMISSION SPECIFICATION below
161 for details.
162
165 The behaviour on chown/chgrp calls can be changed. By default they are
166 passed through to the source directory even if bindfs is set to show a
167 fake owner/group. A chown/chgrp call will only succeed if the user has
168 enough mirrored permissions to chmod the mirrored file AND the mounter
169 has enough permissions to chmod the real file.
170 --chown-normal, -o chown-normal
172 Tries to chown the underlying file. This is the default.
173 --chown-ignore, -o chown-ignore
175 Lets chown succeed (if the user has enough mirrored permissions)
176 but actually does nothing. A combined chown/chgrp is effectively
177 turned into a chgrp-only request.
178 --chown-deny, -o chown-deny
180 Makes chown always fail with a 'permission denied' error. A
181 combined chown/chgrp request will fail as well.
182 --chgrp-normal, -o chgrp-normal
184 Tries to chgrp the underlying file. This is the default.
185 --chgrp-ignore, -o chgrp-ignore
187 Lets chgrp succeed (if the user has enough mirrored permissions)
188 but actually does nothing. A combined chown/chgrp is effectively
189 turned into a chown-only request.
190 --chgrp-deny, -o chgrp-deny
192 Makes chgrp always fail with a 'permission denied' error. A
193 combined chown/chgrp request will fail as well.
194
197 Chmod calls are forwarded to the source directory by default. This may
198 cause unexpected behaviour if bindfs is altering permission bits.
199 --chmod-normal, -o chmod-normal
201 Tries to chmod the underlying file. This will succeed if the
202 user has the appropriate mirrored permissions to chmod the mir‐
203 rored file AND the mounter has enough permissions to chmod the
204 real file. This is the default (in order to behave like mount
205 --bind by default).
206 --chmod-ignore, -o chmod-ignore
208 Lets chmod succeed (if the user has enough mirrored permissions)
209 but actually does nothing.
210 --chmod-deny, -o chmod-deny
212 Makes chmod always fail with a 'permission denied' error.
213 --chmod-filter=permissions, -o chmod-filter=...
215 Changes the permission bits of a chmod request before it is ap‐
216 plied to the original file. Accepts the same permission syntax
217 as --perms. See PERMISSION SPECIFICATION below for details.
218 --chmod-allow-x, -o chmod-allow-x
220 Allows setting and clearing the executable attribute on files
221 (but not directories). When used with --chmod-ignore, chmods
222 will only affect execute bits on files and changes to other bits
223 are discarded. With --chmod-deny, all chmods that would change
224 any bits except excecute bits on files will still fail with a
225 'permission denied'. This option does nothing with --chmod-nor‐
226 mal.
227
230 Extended attributes are mirrored by default, though not all underlying
231 file systems support xattrs.
232 --xattr-none, -o xattr-none
234 Disable extended attributes altogether. All operations will re‐
235 turn 'Operation not supported'.
236 --xattr-ro, -o xattr-ro
238 Let extended attributes be read-only.
239 --xattr-rw, -o xattr-rw
241 Let extended attributes be read-write (the default). The
242 read/write permissions are checked against the (possibly modi‐
243 fied) file permissions inside the mount.
244
247 --delete-deny, -o delete-deny
248 Makes all file delete operations fail with a 'permission de‐
249 nied'. By default, files can still be modified if they have
250 write permission, and renamed if the directory has write permis‐
251 sion.
252 --rename-deny, -o rename-deny
254 Makes all file rename/move operations within the mountpoint fail
255 with a 'permission denied'. Programs that move files out of a
256 mountpoint do so by copying and deleting the original.
257
259 Reads and writes through the mount point can be throttled. Throttling
260 works by sleeping the required amount of time on each read or write re‐
261 quest. Throttling imposes one global limit on all readers/writers as
262 opposed to a per-process or per-user limit.
263 Currently, the implementation is not entirely fair. See BUGS below.
265 --read-rate=N, -o read-rate=N
267 Allow at most N bytes per second to be read. N may have one of
268 the following (1024-based) suffixes: k, M, G, T.
269 --write-rate=N, -o write-rate=N
271 Same as above, but for writes.
272
274 --hide-hard-links, -o hide-hard-links
275 Shows the hard link count of all files as 1.
276 --resolve-symlinks, -o resolve-symlinks
278 Transparently resolves symbolic links. Disables creation of new
279 symbolic links.
280 With the following exceptions, operations will operate directly
282 on the target file instead of the symlink. Renaming/moving a re‐
283 solved symlink (inside the same mount point) will move the sym‐
284 link instead of the underlying file. Deleting a resolved symlink
285 will delete the underlying symlink but not the destination file.
286 This can be configured with --resolved-symlink-deletion.
287 Note that when some programs, such as vim, save files, they ac‐
289 tually move the old file out of the way, create a new file in
290 its place, and finally delete the old file. Doing these opera‐
291 tions on a resolved symlink will replace it with a regular file.
292 Symlinks pointing outside the source directory are supported
294 with the following exception: accessing the mountpoint recur‐
295 sively through a resolved symlink is not supported and will re‐
296 turn an error. This is because a FUSE filesystem cannot reliably
297 call itself recursively without deadlocking, especially in sin‐
298 gle-threaded mode.
299 --resolved-symlink-deletion=policy, -o resolved-symlink-deletion=policy
301 If --resolve-symlinks is enabled, decides what happens when a
302 resolved symlink is deleted. The options are: deny (resolved
303 symlinks cannot be deleted), symlink-only (the underlying sym‐
304 link is deleted, its target is not), symlink-first (the symlink
305 is deleted, and if that succeeds, the target is deleted but no
306 error is reported if that fails) or target-first (the target is
307 deleted first, and the symlink is deleted only if deleting the
308 target succeeded). The default is symlink-only.
309 Note that deleting files inside symlinked directories is always
311 possible with all settings, including deny, unless something
312 else protects those files.
313
316 -h, --help
317 Displays a help message and exits.
318 -V, --version
320 Displays version information and exits.
321 --fuse-version Displays the version of the FUSE library inter‐
323 face that was seen at compile-time, as well as the version that
324 bindfs currently runs with.
325 --no-allow-other, -o no-allow-other
327 Does not add -o allow_other to FUSE options. This causes the
328 mount to be accessible only by the current user.
329 (The deprecated shorthand -n is also still accepted.)
331 --realistic-permissions, -o realistic-permissions
333 Hides read/write/execute permissions for a mirrored file when
334 the mounter doesn't have read/write/execute access to the under‐
335 lying file. Useless when mounting as root, since root will al‐
336 ways have full access.
337 (Prior to version 1.10 this option was the default behavior. I
339 felt it violated the principle of least surprise badly enough to
340 warrant a small break in backwards-compatibility.)
341 --ctime-from-mtime, -o ctime-from-mtime
343 Recall that a unix file has three standard timestamps: atime
344 (last access i.e. read time), mtime (last content modification
345 time) ctime (last content or metadata (inode) change time)
346 With this option, the ctime of each file and directory is read
348 from its mtime. In other words, only content modifications (as
349 opposed to metadata changes) will be reflected in a mirrored
350 file's ctime. The underlying file's ctime will still be updated
351 normally.
352 --enable-lock-forwarding, -o enable-lock-forwarding
354 Forwards flock and fcntl locking requests to the source direc‐
355 tory. This way, locking a file in the bindfs mount will also
356 lock the file in the source directory.
357 This option must be used with --multithreaded because otherwise
359 bindfs will deadlock as soon as there is lock contention. How‐
360 ever, see BUGS below for caveats about --multithreaded with the
361 current implementation.
362 --disable-lock-forwarding, -o disable-lock-forwarding
364 Currently does nothing, but a future release may default to en‐
365 abling lock forwarding. If you depend on this behaviour, it's
366 recommended to set this flag explicitly.
367 --enable-ioctl, -o enable-ioctl
369 Enables forwarding of ioctl, which is needed for some advanced
370 features such as append-only files (chattr +a). Note that the
371 ioctl action will be performed as the mounter, not the calling
372 user. No efforts are made to check whether the calling user
373 would ordinarily have the permissions to make the ioctl. This
374 may be a security concern, especially when mounting as root.
375 --block-devices-as-files, -o block-devices-as-files
377 Shows block devices as regular files.
378 --multithreaded, -o multithreaded
380 Run bindfs in multithreaded mode. While bindfs is designed to be
381 otherwise thread-safe, there is currently a race condition that
382 may pose a security risk for some use cases. See BUGS below.
383 --direct-io, -o direct-io
385 Forwards each read/write operation 1:1 to the underlying FS,
387 disabling batching and caching by the kernel. Some applications
388 may require this, however it may be incompatible with other ap‐
389 plications, as currently it has issues with mmap(2) calls, at
390 least.
391 --no-direct-io, -o no-direct-io
393 This option is provided in case the default changes in the fu‐
395 ture.
396 --forward-odirect=alignment, -o forward-odirect=alignment
398 Enable experimental O_DIRECT forwarding, with all read/write re‐
399 quests rounded to the given alignment (in bytes). By default,
400 the O_DIRECT flag is not forwarded to the underlying FS. See
401 open(2) for details about O_DIRECT.
402 Only works on Linux. Ignored on other platforms.
404
407 See fuse(8) for the full list of FUSE options. Some of the more common
408 ones are mentioned below.
409 -r, -o ro
411 Make the mount strictly read-only. This even prevents root from
412 writing to it. If this is all you need, then (since Linux
413 2.6.26) you can get a more efficent mount with mount --bind and
414 then mount -o remount,ro.
415 -d, -o debug
417 Enable debug output (implies -f).
418 -o fsname=name
420 Sets the source directory name in /proc/mounts (returned by
421 mount). This is automatically set as long as the source path
422 has no special characters.
423 -f Foreground operation.
425
428 The -p option takes a comma- or colon-separated list of either octal
429 numeric permission bits or symbolic representations of permission bit
430 operations. The symbolic representation is based on that of the
431 chmod(1) command. setuid, setgid and sticky bits are ignored.
432 This program extends the chmod symbolic representation with the follow‐
434 ing operands:
435 `D' (right hand side)
437 Works like X but applies only to directories (not to executables).
438 `d' and `f' (left hand side)
440 Makes this directive only apply to directories (d) or files (f).
441 e.g. gd-w would remove the group write bit from all directories.
442 `u', `g', `o' (right hand side)
444 Uses the user (u), group (g) or others (o) permission bits of
445 the original file.
446 e.g. g=u would copy the user's permission bits to the group.
447 ug+o would add the others' permissions to the owner and group.
448 Examples
451 o-rwx Removes all permission bits from others.
452 g=rD Allows group to read all files and enter all directories, but
454 nothing else.
455 0644,a+X
457 Sets permission bits to 0644 and adds the execute bit for every‐
458 one to all directories and executables.
459 og-x:og+rD:u=rwX:g+rw
461 Removes execute bit for others and group, adds read and direc‐
462 tory execute for others and group, sets user permissions to
463 read, write and execute directory/executable, adds read and
464 write for group.
465
468 bindfs -u www -g nogroup -p 0000,u=rD ~/mywebsite ~/public_html/mysite
470 Publishes a website in public_html so that only the 'www' user
472 can read the site.
473 bindfs -M foo,bar,1007,@mygroup -p 0600,u+X dir mnt
475 Gives access to 'foo', 'bar', the user with the UID 1007 as well
477 as everyone in the group 'mygroup'. Sets the permission bits to
478 0600, thus giving the specified users read/write access, and
479 adds the user execute bit for directories and executables.
480 bindfs -ono-allow-other,perms=a-w somedir somedir
482 Makes a directory read-only and accessable only by the current
484 user.
485 /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD 0 0
487 An example /etc/fstab entry. Note that the colon must be used to
489 separate arguments to perms, because the comma is an option sep‐
490 arator in /etc/fstab.
491 bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD 0 0
493 Older systems may require this deprecated fstab syntax.
495
498 Setuid and setgid bits have no effect inside the mount. This is a nec‐
499 essary security feature of FUSE.
500 Access to device files is denied by default by FUSE as a security pre‐
502 caution. Use -o dev to enable access (requires mounting as root). This
503 may not be supported on all operating systems.
504 MacFuse caches file contents by default. This means that changes in
506 source files are not always immediately visible under the mount point.
507 -o nolocalcaches can be used to disable the cache.
508 When using --mirror[-only] @somegroup, bindfs won't see changes to the
510 group's member list. Sending bindfs a SIGUSR1 signal will make it
511 reread the user database.
512 The following extra options may be useful under osxfuse: -o local,al‐
514 low_other,extended_security,noappledouble See https://github.com/osx‐
515 fuse/osxfuse/wiki/Mount-options for details.
516
518 If bindfs is run in multithreaded mode (with the --multithreaded op‐
519 tion) then it's possible for another process to briefly see a file with
520 an incorrect owner, group or permissions. This may constitute a secu‐
521 rity risk if you rely on bindfs to reduce permissions on new files. For
522 this reason, as of version 1.11 bindfs runs in single-threaded mode by
523 default.
524 Rate limiting favors the process with the larger block size. If two
526 processes compete for read/write access, the one whose read()/write()
527 calls specify the larger block size gets to read/write faster. The to‐
528 tal rate limit is maintained though, and clients with equal block sizes
529 and a similar rate of requests are treated fairly as long as the kernel
530 orders their requests fairly.
531 Some features relying on xattrs might not work properly on OS X
533 (https://github.com/mpartel/bindfs/issues/21). For instance, Finder
534 tags seem to work but comments might not.
535 Please report bugs and/or send pull requests to
537 https://github.com/mpartel/bindfs/issues.
538
541 The option names --user and --group were deprecated and replaced with
542 --force-user and --force-group in version 1.12. The former names
543 clashed with standard option names. They are still available but their
544 use is discouraged and prints a warning. The synonym --owner is also
545 deprecated for consistency.
546
549 Martin Pärtel <martin dot partel at gmail dot com>
550
553 chmod(1), fusermount(1), fuse(8), http://bindfs.org/
554 BINDFS(1)