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 --fuse-version Displays the version of the FUSE library inter‐
326 face that was seen at compile-time, as well as the version that
327 bindfs currently runs with.
328 --no-allow-other, -o no-allow-other
331 Does not add -o allow_other to FUSE options. This causes the
332 mount to be accessible only by the current user.
333 (The deprecated shorthand -n is also still accepted.)
335 --realistic-permissions, -o realistic-permissions
338 Hides read/write/execute permissions for a mirrored file when
339 the mounter doesn't have read/write/execute access to the under‐
340 lying file. Useless when mounting as root, since root will
341 always have full access.
342 (Prior to version 1.10 this option was the default behavior. I
344 felt it violated the principle of least surprise badly enough to
345 warrant a small break in backwards-compatibility.)
346 --ctime-from-mtime, -o ctime-from-mtime
349 Recall that a unix file has three standard timestamps: atime
350 (last access i.e. read time), mtime (last content modification
351 time) ctime (last content or metadata (inode) change time)
352 With this option, the ctime of each file and directory is read
354 from its mtime. In other words, only content modifications (as
355 opposed to metadata changes) will be reflected in a mirrored
356 file's ctime. The underlying file's ctime will still be updated
357 normally.
358 --enable-lock-forwarding, -o enable-lock-forwarding
361 Forwards flock and fcntl locking requests to the source direc‐
362 tory. This way, locking a file in the bindfs mount will also
363 lock the file in the source directory.
364 This option must be used with --multithreaded because otherwise
366 bindfs will deadlock as soon as there is lock contention. How‐
367 ever, see BUGS below for caveats about --multithreaded with the
368 current implementation.
369 --disable-lock-forwarding, -o disable-lock-forwarding
372 Currently does nothing, but a future release may default to
373 enabling lock forwarding. If you depend on this behaviour, it's
374 recommended to set this flag explicitly.
375 --enable-ioctl, -o enable-ioctl
378 Enables forwarding of ioctl, which is needed for some advanced
379 features such as append-only files (chattr +a). Note that the
380 ioctl action will be performed as the mounter, not the calling
381 user. No efforts are made to check whether the calling user
382 would ordinarily have the permissions to make the ioctl. This
383 may be a security concern, especially when mounting as root.
384 --block-devices-as-files, -o block-devices-as-files
387 Shows block devices as regular files.
388 --multithreaded, -o multithreaded
391 Run bindfs in multithreaded mode. While bindfs is designed to be
392 otherwise thread-safe, there is currently a race condition that
393 may pose a security risk for some use cases. See BUGS below.
394 --forward-odirect=alignment, -o forward-odirect=alignment
397 Enable experimental O_DIRECT forwarding, with all read/write
398 requests rounded to the given alignment (in bytes). By default,
399 the O_DIRECT flag is not forwarded to the underlying FS. See
400 open(2) for details about O_DIRECT.
401 Only works on Linux. Ignored on other platforms.
403
406 -o options
407 Fuse options.
408 -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
418 Enable debug output (implies -f).
419 -f Foreground operation.
422
426 The -p option takes a comma- or colon-separated list of either octal
427 numeric permission bits or symbolic representations of permission bit
428 operations. The symbolic representation is based on that of the
429 chmod(1) command. setuid, setgid and sticky bits are ignored.
430 This program extends the chmod symbolic representation with the follow‐
432 ing operands:
433 `D' (right hand side)
435 Works like X but applies only to directories (not to executables).
436 `d' and `f' (left hand side)
438 Makes this directive only apply to directories (d) or files (f).
439 e.g. gd-w would remove the group write bit from all directories.
440 `u', `g', `o' (right hand side)
442 Uses the user (u), group (g) or others (o) permission bits of
443 the original file.
444 e.g. g=u would copy the user's permission bits to the group.
445 ug+o would add the others' permissions to the owner and group.
446 Examples
449 o-rwx Removes all permission bits from others.
451 g=rD Allows group to read all files and enter all directories, but
454 nothing else.
455 0644,a+X
458 Sets permission bits to 0644 and adds the execute bit for every‐
459 one to all directories and executables.
460 og-x:og+rD:u=rwX:g+rw
463 Removes execute bit for others and group, adds read and direc‐
464 tory execute for others and group, sets user permissions to
465 read, write and execute directory/executable, adds read and
466 write for group.
467
471 bindfs -u www -g nogroup -p 0000,u=rD ~/mywebsite ~/public_html/mysite
474 Publishes a website in public_html so that only the 'www' user
476 can read the site.
477 bindfs -M foo,bar,1007,@mygroup -p 0600,u+X dir mnt
480 Gives access to 'foo', 'bar', the user with the UID 1007 as well
482 as everyone in the group 'mygroup'. Sets the permission bits to
483 0600, thus giving the specified users read/write access, and
484 adds the user execute bit for directories and executables.
485 bindfs -ono-allow-other,perms=a-w somedir somedir
488 Makes a directory read-only and accessable only by the current
490 user.
491 /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD 0 0
494 An example /etc/fstab entry. Note that the colon must be used to
496 separate arguments to perms, because the comma is an option sep‐
497 arator in /etc/fstab.
498 bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD 0 0
501 Older systems may require this deprecated fstab syntax.
503
507 Setuid and setgid bits have no effect inside the mount. This is a nec‐
508 essary security feature of FUSE.
509 Access to device files is denied by default by FUSE as a security pre‐
511 caution. Use -o dev to enable access (requires mounting as root). This
512 may not be supported on all operating systems.
513 MacFuse caches file contents by default. This means that changes in
515 source files are not always immediately visible under the mount point.
516 -o nolocalcaches can be used to disable the cache.
517 When using --mirror[-only] @somegroup, bindfs won't see changes to the
519 group's member list. Sending bindfs a SIGUSR1 signal will make it
520 reread the user database.
521 The following extra options may be useful under osxfuse: -o
523 local,allow_other,extended_security,noappledouble See
524 https://github.com/osxfuse/osxfuse/wiki/Mount-options for details.
525
528 If bindfs is run in multithreaded mode (with the --multithreaded
529 option) then it's possible for another process to briefly see a file
530 with an incorrect owner, group or permissions. This may constitute a
531 security risk if you rely on bindfs to reduce permissions on new files.
532 For this reason, as of version 1.11 bindfs runs in single-threaded mode
533 by default.
534 Rate limiting favors the process with the larger block size. If two
536 processes compete for read/write access, the one whose read()/write()
537 calls specify the larger block size gets to read/write faster. The
538 total rate limit is maintained though, and clients with equal block
539 sizes and a similar rate of requests are treated fairly as long as the
540 kernel orders their requests fairly.
541 Some features relying on xattrs might not work properly on OS X
543 (https://github.com/mpartel/bindfs/issues/21). For instance, Finder
544 tags seem to work but comments might not.
545 Please report bugs and/or send pull requests to
547 https://github.com/mpartel/bindfs/issues.
548
552 The option names --user and --group were deprecated and replaced with
553 --force-user and --force-group in version 1.12. The former names
554 clashed with standard option names. They are still available but their
555 use is discouraged and prints a warning. The synonym --owner is also
556 deprecated for consistency.
557
561 Martin Pärtel <martin dot partel at gmail dot com>
562
566 chmod(1), fusermount(1), http://bindfs.org/
567 BINDFS(1)