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. Additionally, one can change the permissions of files in the
18 mirrored directory.
19
23 -u, --force-user, -o force-user=...
24 Makes all files owned by the specified user. Also causes chown
25 on the mounted filesystem to always fail.
26 -g, --force-group=group, -o force-group=...
29 Makes all files owned by the specified group. Also causes chgrp
30 on the mounted filesystem to always fail.
31 -p, --perms=permissions, -o perms=...
34 Takes a comma- or colon-separated list of chmod-like permission
35 specifications to be applied to the permission bits in order.
36 See PERMISSION SPECIFICATION below for details.
37 This only affects how the permission bits of existing files are
39 altered when shown in the mounted directory. You can use --cre‐
40 ate-with-perms to change the permissions that newly created
41 files get in the source directory.
42 Note that, as usual, the root user isn't bound by the permis‐
44 sions set here. You can get a truly read-only mount by using
45 -r.
46 -m, --mirror=user1:user2:..., -o mirror=...
49 Takes a comma- or colon-separated list of users who will see
50 themselves as the owners of all files. Users who are not listed
51 here will still be able to access the mount if the permissions
52 otherwise allow them to.
53 You can also give a group name prefixed with an '@' to mirror
55 all members of a group. This will not change which group the
56 files are shown to have.
57 -M, --mirror-only=user1:user2:..., -o mirror-only=...
60 Like --mirror but disallows access for all other users (except
61 root).
62 --map=user1/user2:@group1/@group2:..., -o map=...
65 Given a mapping user1/user2, all files owned by user1 are shown
66 as owned by user2. When user2 creates files, they are chowned to
67 user1 in the underlying directory. When files are chowned to
68 user2, they are chowned to user1 in the underlying directory.
69 Works similarly for groups.
70 A single user or group may appear no more than once on the left
72 and once on the right of a slash in the list of mappings. Cur‐
73 rently, the options --force-user, --force-group, --mirror,
74 --create-for-*, --chown-* and --chgrp-* override the correspond‐
75 ing behavior of this option.
76 Requires mounting as root.
78 --uid-offset=..., -o uid-offset=...
81 Works like --map, but adds the given number to all file owner
82 user IDs. For instance, --uid-offset=100000 causes a file owned
83 by user 123 to be shown as owned by user 100123.
84 For now, this option cannot be used together with --map. Please
86 file an issue with the desired semantics if you have a case for
87 using them together.
88 Requires mounting as root.
90 --gid-offset=..., -o gid-offset=...
93 Works exactly like --uid-offset but for groups.
94
98 New files and directories are created so they are owned by the mounter.
99 bindfs can let this happen (the default for normal users), or it can
100 try to change the owner to the uid/gid of the process that wants to
101 create the file (the default for root). It is also possible to have
102 bindfs try to change the owner to a particular user or group.
103 --create-as-user, -o create-as-user
106 Tries to change the owner and group of new files and directories
107 to the uid and gid of the caller. This can work only if the
108 mounter is root. It is also the default behavior (mimicing
109 mount --bind) if the mounter is root.
110 --create-as-mounter, -o create-as-mounter
113 All new files and directories will be owned by the mounter.
114 This is the default behavior for non-root mounters.
115 --create-for-user=user, -o create-for-user=...
118 Tries to change the owner of new files and directories to the
119 user specified here. This can work only if the mounter is root.
120 This option overrides the --create-as-user and --cre‐
121 ate-as-mounter options.
122 --create-for-group=group, -o create-for-group=...
125 Tries to change the owning group of new files and directories to
126 the group specified here. This can work only if the mounter is
127 root. This option overrides the --create-as-user and --cre‐
128 ate-as-mounter options.
129 --create-with-perms=permissions, -o create-with-perms=...
132 Works like --perms but is applied to the permission bits of new
133 files get in the source directory. Normally the permissions of
134 new files depend on the creating process's preferences and
135 umask. This option can be used to modify those permissions or
136 override them completely. See PERMISSION SPECIFICATION below
137 for details.
138
142 The behaviour on chown/chgrp calls can be changed. By default they are
143 passed through to the source directory even if bindfs is set to show a
144 fake owner/group. A chown/chgrp call will only succeed if the user has
145 enough mirrored permissions to chmod the mirrored file AND the mounter
146 has enough permissions to chmod the real file.
147 --chown-normal, -o chown-normal
150 Tries to chown the underlying file. This is the default.
151 --chown-ignore, -o chown-ignore
154 Lets chown succeed (if the user has enough mirrored permissions)
155 but actually does nothing. A combined chown/chgrp is effectively
156 turned into a chgrp-only request.
157 --chown-deny, -o chown-deny
160 Makes chown always fail with a 'permission denied' error. A
161 combined chown/chgrp request will fail as well.
162 --chgrp-normal, -o chgrp-normal
165 Tries to chgrp the underlying file. This is the default.
166 --chgrp-ignore, -o chgrp-ignore
169 Lets chgrp succeed (if the user has enough mirrored permissions)
170 but actually does nothing. A combined chown/chgrp is effectively
171 turned into a chown-only request.
172 --chgrp-deny, -o chgrp-deny
175 Makes chgrp always fail with a 'permission denied' error. A
176 combined chown/chgrp request will fail as well.
177
181 Chmod calls are forwarded to the source directory by default. This may
182 cause unexpected behaviour if bindfs is altering permission bits.
183 --chmod-normal, -o chmod-normal
186 Tries to chmod the underlying file. This will succeed if the
187 user has the appropriate mirrored permissions to chmod the mir‐
188 rored file AND the mounter has enough permissions to chmod the
189 real file. This is the default (in order to behave like mount
190 --bind by default).
191 --chmod-ignore, -o chmod-ignore
194 Lets chmod succeed (if the user has enough mirrored permissions)
195 but actually does nothing.
196 --chmod-deny, -o chmod-deny
199 Makes chmod always fail with a 'permission denied' error.
200 --chmod-filter=permissions, -o chmod-filter=...
203 Changes the permission bits of a chmod request before it is
204 applied to the original file. Accepts the same permission syntax
205 as --perms. See PERMISSION SPECIFICATION below for details.
206 --chmod-allow-x, -o chmod-allow-x
209 Allows setting and clearing the executable attribute on files
210 (but not directories). When used with --chmod-ignore, chmods
211 will only affect execute bits on files and changes to other bits
212 are discarded. With --chmod-deny, all chmods that would change
213 any bits except excecute bits on files will still fail with a
214 'permission denied'. This option does nothing with --chmod-nor‐
215 mal.
216
220 Extended attributes are mirrored by default, though not all underlying
221 file systems support xattrs.
222 --xattr-none, -o xattr-none
225 Disable extended attributes altogether. All operations will
226 return 'Operation not supported'.
227 --xattr-ro, -o xattr-ro
230 Let extended attributes be read-only.
231 --xattr-rw, -o xattr-rw
234 Let extended attributes be read-write (the default). The
235 read/write permissions are checked against the (possibly modi‐
236 fied) file permissions inside the mount.
237
241 --delete-deny, -o delete-deny
242 Makes all file delete operations fail with a 'permission
243 denied'. By default, files can still be modified if they have
244 write permission, and renamed if the directory has write permis‐
245 sion.
246 --rename-deny, -o rename-deny
249 Makes all file rename/move operations within the mountpoint fail
250 with a 'permission denied'. Programs that move files out of a
251 mountpoint do so by copying and deleting the original.
252
255 Reads and writes through the mount point can be throttled. Throttling
256 works by sleeping the required amount of time on each read or write
257 request. Throttling imposes one global limit on all readers/writers as
258 opposed to a per-process or per-user limit.
259 Currently, the implementation is not entirely fair. See BUGS below.
261 --read-rate=N, -o read-rate=N
264 Allow at most N bytes per second to be read. N may have one of
265 the following (1024-based) suffixes: k, M, G, T.
266 --write-rate=N, -o write-rate=N
269 Same as above, but for writes.
270
273 --hide-hard-links, -o hide-hard-links
274 Shows the hard link count of all files as 1.
275 --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
283 resolved symlink (inside the same mount point) will move the
284 symlink instead of the underlying file. Deleting a resolved sym‐
285 link will delete the underlying symlink but not the destination
286 file. This can be configured with --resolved-symlink-deletion.
287 Note that when some programs, such as vim, save files, they
289 actually 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
296 return an error. This is because a FUSE filesystem cannot reli‐
297 ably call itself recursively without deadlocking, especially in
298 single-threaded mode.
299 --resolved-symlink-deletion=policy, -o resolved-symlink-deletion=policy
302 If --resolve-symlinks is enabled, decides what happens when a
303 resolved symlink is deleted. The options are: deny (resolved
304 symlinks cannot be deleted), symlink-only (the underlying sym‐
305 link is deleted, its target is not), symlink-first (the symlink
306 is deleted, and if that succeeds, the target is deleted but no
307 error is reported if that fails) or target-first (the target is
308 deleted first, and the symlink is deleted only if deleting the
309 target succeeded). The default is symlink-only.
310 Note that deleting files inside symlinked directories is always
312 possible with all settings, including deny, unless something
313 else protects those files.
314
318 -h, --help
319 Displays a help message and exits.
320 -V, --version
323 Displays version information and exits.
324 --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
334 Hides read/write/execute permissions for a mirrored file when
335 the mounter doesn't have read/write/execute access to the under‐
336 lying file. Useless when mounting as root, since root will
337 always have full access.
338 (Prior to version 1.10 this option was the default behavior. I
340 felt it violated the principle of least surprise badly enough to
341 warrant a small break in backwards-compatibility.)
342 --ctime-from-mtime, -o ctime-from-mtime
345 Recall that a unix file has three standard timestamps: atime
346 (last access i.e. read time), mtime (last content modification
347 time) ctime (last content or metadata (inode) change time)
348 With this option, the ctime of each file and directory is read
350 from its mtime. In other words, only content modifications (as
351 opposed to metadata changes) will be reflected in a mirrored
352 file's ctime. The underlying file's ctime will still be updated
353 normally.
354 --enable-lock-forwarding, -o enable-lock-forwarding
357 Forwards flock and fcntl locking requests to the source direc‐
358 tory. This way, locking a file in the bindfs mount will also
359 lock the file in the source directory.
360 This option must be used with --multithreaded because otherwise
362 bindfs will deadlock as soon as there is lock contention. How‐
363 ever, see BUGS below for caveats about --multithreaded with the
364 current implementation.
365 --disable-lock-forwarding, -o disable-lock-forwarding
368 Currently does nothing, but a future release may default to
369 enabling lock forwarding. If you depend on this behaviour, it's
370 recommended to set this flag explicitly.
371 --enable-ioctl, -o enable-ioctl
374 Enables forwarding of ioctl, which is needed for some advanced
375 features such as append-only files (chattr +a). Note that the
376 ioctl action will be performed as the mounter, not the calling
377 user. No efforts are made to check whether the calling user
378 would ordinarily have the permissions to make the ioctl. This
379 may be a security concern, especially when mounting as root.
380 --block-devices-as-files, -o block-devices-as-files
383 Shows block devices as regular files.
384 --multithreaded, -o multithreaded
387 Run bindfs in multithreaded mode. While bindfs is designed to be
388 otherwise thread-safe, there is currently a race condition that
389 may pose a security risk for some use cases. See BUGS below.
390 --forward-odirect=alignment, -o forward-odirect=alignment
393 Enable experimental O_DIRECT forwarding, with all read/write
394 requests rounded to the given alignment (in bytes). By default,
395 the O_DIRECT flag is not forwarded to the underlying FS. See
396 open(2) for details about O_DIRECT.
397 Only works on Linux. Ignored on other platforms.
399
402 -o options
403 Fuse options.
404 -r, -o ro
407 Make the mount strictly read-only. This even prevents root from
408 writing to it. If this is all you need, then (since Linux
409 2.6.26) you can get a more efficent mount with mount --bind and
410 then mount -o remount,ro.
411 -d, -o debug
414 Enable debug output (implies -f).
415 -f Foreground operation.
418
422 The -p option takes a comma- or colon-separated list of either octal
423 numeric permission bits or symbolic representations of permission bit
424 operations. The symbolic representation is based on that of the
425 chmod(1) command. setuid, setgid and sticky bits are ignored.
426 This program extends the chmod symbolic representation with the follow‐
428 ing operands:
429 `D' (right hand side)
431 Works like X but applies only to directories (not to executables).
432 `d' and `f' (left hand side)
434 Makes this directive only apply to directories (d) or files (f).
435 e.g. gd-w would remove the group write bit from all directories.
436 `u', `g', `o' (right hand side)
438 Uses the user (u), group (g) or others (o) permission bits of
439 the original file.
440 e.g. g=u would copy the user's permission bits to the group.
441 ug+o would add the others' permissions to the owner and group.
442 Examples
445 o-rwx Removes all permission bits from others.
447 g=rD Allows group to read all files and enter all directories, but
450 nothing else.
451 0644,a+X
454 Sets permission bits to 0644 and adds the execute bit for every‐
455 one to all directories and executables.
456 og-x:og+rD:u=rwX:g+rw
459 Removes execute bit for others and group, adds read and direc‐
460 tory execute for others and group, sets user permissions to
461 read, write and execute directory/executable, adds read and
462 write for group.
463
467 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
476 Gives access to 'foo', 'bar', the user with the UID 1007 as well
478 as everyone in the group 'mygroup'. Sets the permission bits to
479 0600, thus giving the specified users read/write access, and
480 adds the user execute bit for directories and executables.
481 bindfs -ono-allow-other,perms=a-w somedir somedir
484 Makes a directory read-only and accessable only by the current
486 user.
487 /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD 0 0
490 An example /etc/fstab entry. Note that the colon must be used to
492 separate arguments to perms, because the comma is an option sep‐
493 arator in /etc/fstab.
494 bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD 0 0
497 Older systems may require this deprecated fstab syntax.
499
503 Setuid and setgid bits have no effect inside the mount. This is a nec‐
504 essary security feature of FUSE.
505 Access to device files is denied by default by FUSE as a security pre‐
507 caution. Use -o dev to enable access (requires mounting as root). This
508 may not be supported on all operating systems.
509 MacFuse caches file contents by default. This means that changes in
511 source files are not always immediately visible under the mount point.
512 -o nolocalcaches can be used to disable the cache.
513 When using --mirror[-only] @somegroup, bindfs won't see changes to the
515 group's member list. Sending bindfs a SIGUSR1 signal will make it
516 reread the user database.
517 The following extra options may be useful under osxfuse: -o
519 local,allow_other,extended_security,noappledouble See
520 https://github.com/osxfuse/osxfuse/wiki/Mount-options for details.
521
524 If bindfs is run in multithreaded mode (with the --multithreaded
525 option) then it's possible for another process to briefly see a file
526 with an incorrect owner, group or permissions. This may constitute a
527 security risk if you rely on bindfs to reduce permissions on new files.
528 For this reason, as of version 1.11 bindfs runs in single-threaded mode
529 by default.
530 Rate limiting favors the process with the larger block size. If two
532 processes compete for read/write access, the one whose read()/write()
533 calls specify the larger block size gets to read/write faster. The
534 total rate limit is maintained though, and clients with equal block
535 sizes and a similar rate of requests are treated fairly as long as the
536 kernel orders their requests fairly.
537 Some features relying on xattrs might not work properly on OS X
539 (https://github.com/mpartel/bindfs/issues/21). For instance, Finder
540 tags seem to work but comments might not.
541 Please report bugs and/or send pull requests to
543 https://github.com/mpartel/bindfs/issues.
544
548 The option names --user and --group were deprecated and replaced with
549 --force-user and --force-group in version 1.12. The former names
550 clashed with standard option names. They are still available but their
551 use is discouraged and prints a warning. The synonym --owner is also
552 deprecated for consistency.
553
557 Martin Pärtel <martin dot partel at gmail dot com>
558
562 chmod(1), fusermount(1), http://bindfs.org/
563 BINDFS(1)