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 --map-passwd=<passwdfile>, -o map-passwd=<passwdfile>
80 --map-group=<groupfile>, -o map-group=<groupfile>
81 Like --map=..., but reads the UID/GID mapping from passwd and
82 group files (like /etc/passwd and /etc/group). Helpful to
83 restore system backups where UIDs/GIDs differ.
84 Example usage:
86 bindfs --map-passwd=/mnt/orig/etc/passwd \
88 --map-passwd=/mnt/orig/etc/group \
89 /mnt/orig /mnt/mapped
90 Requires mounting as root.
92 --uid-offset=..., -o uid-offset=...
94 Works like --map, but adds the given number to all file owner
95 user IDs. For instance, --uid-offset=100000 causes a file owned
96 by user 123 to be shown as owned by user 100123.
97 For now, this option cannot be used together with --map. Please
99 file an issue with the desired semantics if you have a case for
100 using them together.
101 Requires mounting as root.
103 --gid-offset=..., -o gid-offset=...
105 Works exactly like --uid-offset but for groups.
106
109 New files and directories are created so they are owned by the mounter.
110 bindfs can let this happen (the default for normal users), or it can
111 try to change the owner to the uid/gid of the process that wants to
112 create the file (the default for root). It is also possible to have
113 bindfs try to change the owner to a particular user or group.
114 --create-as-user, -o create-as-user
116 Tries to change the owner and group of new files and directories
117 to the uid and gid of the caller. This can work only if the
118 mounter is root. It is also the default behavior (mimicing
119 mount --bind) if the mounter is root.
120 --create-as-mounter, -o create-as-mounter
122 All new files and directories will be owned by the mounter.
123 This is the default behavior for non-root mounters.
124 --create-for-user=user, -o create-for-user=...
126 Tries to change the owner of new files and directories to the
127 user specified here. This can work only if the mounter is root.
128 This option overrides the --create-as-user and --cre‐
129 ate-as-mounter options.
130 --create-for-group=group, -o create-for-group=...
132 Tries to change the owning group of new files and directories to
133 the group specified here. This can work only if the mounter is
134 root. This option overrides the --create-as-user and --cre‐
135 ate-as-mounter options.
136 --create-with-perms=permissions, -o create-with-perms=...
138 Works like --perms but is applied to the permission bits of new
139 files get in the source directory. Normally the permissions of
140 new files depend on the creating process's preferences and
141 umask. This option can be used to modify those permissions or
142 override them completely. See PERMISSION SPECIFICATION below
143 for details.
144
147 The behaviour on chown/chgrp calls can be changed. By default they are
148 passed through to the source directory even if bindfs is set to show a
149 fake owner/group. A chown/chgrp call will only succeed if the user has
150 enough mirrored permissions to chmod the mirrored file AND the mounter
151 has enough permissions to chmod the real file.
152 --chown-normal, -o chown-normal
154 Tries to chown the underlying file. This is the default.
155 --chown-ignore, -o chown-ignore
157 Lets chown succeed (if the user has enough mirrored permissions)
158 but actually does nothing. A combined chown/chgrp is effectively
159 turned into a chgrp-only request.
160 --chown-deny, -o chown-deny
162 Makes chown always fail with a 'permission denied' error. A
163 combined chown/chgrp request will fail as well.
164 --chgrp-normal, -o chgrp-normal
166 Tries to chgrp the underlying file. This is the default.
167 --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
174 Makes chgrp always fail with a 'permission denied' error. A
175 combined chown/chgrp request will fail as well.
176
179 Chmod calls are forwarded to the source directory by default. This may
180 cause unexpected behaviour if bindfs is altering permission bits.
181 --chmod-normal, -o chmod-normal
183 Tries to chmod the underlying file. This will succeed if the
184 user has the appropriate mirrored permissions to chmod the mir‐
185 rored file AND the mounter has enough permissions to chmod the
186 real file. This is the default (in order to behave like mount
187 --bind by default).
188 --chmod-ignore, -o chmod-ignore
190 Lets chmod succeed (if the user has enough mirrored permissions)
191 but actually does nothing.
192 --chmod-deny, -o chmod-deny
194 Makes chmod always fail with a 'permission denied' error.
195 --chmod-filter=permissions, -o chmod-filter=...
197 Changes the permission bits of a chmod request before it is
198 applied to the original file. Accepts the same permission syntax
199 as --perms. See PERMISSION SPECIFICATION below for details.
200 --chmod-allow-x, -o chmod-allow-x
202 Allows setting and clearing the executable attribute on files
203 (but not directories). When used with --chmod-ignore, chmods
204 will only affect execute bits on files and changes to other bits
205 are discarded. With --chmod-deny, all chmods that would change
206 any bits except excecute bits on files will still fail with a
207 'permission denied'. This option does nothing with --chmod-nor‐
208 mal.
209
212 Extended attributes are mirrored by default, though not all underlying
213 file systems support xattrs.
214 --xattr-none, -o xattr-none
216 Disable extended attributes altogether. All operations will
217 return 'Operation not supported'.
218 --xattr-ro, -o xattr-ro
220 Let extended attributes be read-only.
221 --xattr-rw, -o xattr-rw
223 Let extended attributes be read-write (the default). The
224 read/write permissions are checked against the (possibly modi‐
225 fied) file permissions inside the mount.
226
229 --delete-deny, -o delete-deny
230 Makes all file delete operations fail with a 'permission
231 denied'. By default, files can still be modified if they have
232 write permission, and renamed if the directory has write permis‐
233 sion.
234 --rename-deny, -o rename-deny
236 Makes all file rename/move operations within the mountpoint fail
237 with a 'permission denied'. Programs that move files out of a
238 mountpoint do so by copying and deleting the original.
239
241 Reads and writes through the mount point can be throttled. Throttling
242 works by sleeping the required amount of time on each read or write
243 request. Throttling imposes one global limit on all readers/writers as
244 opposed to a per-process or per-user limit.
245 Currently, the implementation is not entirely fair. See BUGS below.
247 --read-rate=N, -o read-rate=N
249 Allow at most N bytes per second to be read. N may have one of
250 the following (1024-based) suffixes: k, M, G, T.
251 --write-rate=N, -o write-rate=N
253 Same as above, but for writes.
254
256 --hide-hard-links, -o hide-hard-links
257 Shows the hard link count of all files as 1.
258 --resolve-symlinks, -o resolve-symlinks
260 Transparently resolves symbolic links. Disables creation of new
261 symbolic links.
262 With the following exceptions, operations will operate directly
264 on the target file instead of the symlink. Renaming/moving a
265 resolved symlink (inside the same mount point) will move the
266 symlink instead of the underlying file. Deleting a resolved sym‐
267 link will delete the underlying symlink but not the destination
268 file. This can be configured with --resolved-symlink-deletion.
269 Note that when some programs, such as vim, save files, they
271 actually move the old file out of the way, create a new file in
272 its place, and finally delete the old file. Doing these opera‐
273 tions on a resolved symlink will replace it with a regular file.
274 Symlinks pointing outside the source directory are supported
276 with the following exception: accessing the mountpoint recur‐
277 sively through a resolved symlink is not supported and will
278 return an error. This is because a FUSE filesystem cannot reli‐
279 ably call itself recursively without deadlocking, especially in
280 single-threaded mode.
281 --resolved-symlink-deletion=policy, -o resolved-symlink-deletion=policy
283 If --resolve-symlinks is enabled, decides what happens when a
284 resolved symlink is deleted. The options are: deny (resolved
285 symlinks cannot be deleted), symlink-only (the underlying sym‐
286 link is deleted, its target is not), symlink-first (the symlink
287 is deleted, and if that succeeds, the target is deleted but no
288 error is reported if that fails) or target-first (the target is
289 deleted first, and the symlink is deleted only if deleting the
290 target succeeded). The default is symlink-only.
291 Note that deleting files inside symlinked directories is always
293 possible with all settings, including deny, unless something
294 else protects those files.
295
298 -h, --help
299 Displays a help message and exits.
300 -V, --version
302 Displays version information and exits.
303 --fuse-version Displays the version of the FUSE library inter‐
305 face that was seen at compile-time, as well as the version that
306 bindfs currently runs with.
307 --no-allow-other, -o no-allow-other
309 Does not add -o allow_other to FUSE options. This causes the
310 mount to be accessible only by the current user.
311 (The deprecated shorthand -n is also still accepted.)
313 --realistic-permissions, -o realistic-permissions
315 Hides read/write/execute permissions for a mirrored file when
316 the mounter doesn't have read/write/execute access to the under‐
317 lying file. Useless when mounting as root, since root will
318 always have full access.
319 (Prior to version 1.10 this option was the default behavior. I
321 felt it violated the principle of least surprise badly enough to
322 warrant a small break in backwards-compatibility.)
323 --ctime-from-mtime, -o ctime-from-mtime
325 Recall that a unix file has three standard timestamps: atime
326 (last access i.e. read time), mtime (last content modification
327 time) ctime (last content or metadata (inode) change time)
328 With this option, the ctime of each file and directory is read
330 from its mtime. In other words, only content modifications (as
331 opposed to metadata changes) will be reflected in a mirrored
332 file's ctime. The underlying file's ctime will still be updated
333 normally.
334 --enable-lock-forwarding, -o enable-lock-forwarding
336 Forwards flock and fcntl locking requests to the source direc‐
337 tory. This way, locking a file in the bindfs mount will also
338 lock the file in the source directory.
339 This option must be used with --multithreaded because otherwise
341 bindfs will deadlock as soon as there is lock contention. How‐
342 ever, see BUGS below for caveats about --multithreaded with the
343 current implementation.
344 --disable-lock-forwarding, -o disable-lock-forwarding
346 Currently does nothing, but a future release may default to
347 enabling lock forwarding. If you depend on this behaviour, it's
348 recommended to set this flag explicitly.
349 --enable-ioctl, -o enable-ioctl
351 Enables forwarding of ioctl, which is needed for some advanced
352 features such as append-only files (chattr +a). Note that the
353 ioctl action will be performed as the mounter, not the calling
354 user. No efforts are made to check whether the calling user
355 would ordinarily have the permissions to make the ioctl. This
356 may be a security concern, especially when mounting as root.
357 --block-devices-as-files, -o block-devices-as-files
359 Shows block devices as regular files.
360 --multithreaded, -o multithreaded
362 Run bindfs in multithreaded mode. While bindfs is designed to be
363 otherwise thread-safe, there is currently a race condition that
364 may pose a security risk for some use cases. See BUGS below.
365 --forward-odirect=alignment, -o forward-odirect=alignment
367 Enable experimental O_DIRECT forwarding, with all read/write
368 requests rounded to the given alignment (in bytes). By default,
369 the O_DIRECT flag is not forwarded to the underlying FS. See
370 open(2) for details about O_DIRECT.
371 Only works on Linux. Ignored on other platforms.
373
375 -o options
376 Fuse options.
377 -r, -o ro
379 Make the mount strictly read-only. This even prevents root from
380 writing to it. If this is all you need, then (since Linux
381 2.6.26) you can get a more efficent mount with mount --bind and
382 then mount -o remount,ro.
383 -d, -o debug
385 Enable debug output (implies -f).
386 -o fsname=name
388 Sets the source directory name in /proc/mounts (returned by
389 mount). This is automatically set as long as the source path
390 has no special characters.
391 -f Foreground operation.
393
396 The -p option takes a comma- or colon-separated list of either octal
397 numeric permission bits or symbolic representations of permission bit
398 operations. The symbolic representation is based on that of the
399 chmod(1) command. setuid, setgid and sticky bits are ignored.
400 This program extends the chmod symbolic representation with the follow‐
402 ing operands:
403 `D' (right hand side)
405 Works like X but applies only to directories (not to executables).
406 `d' and `f' (left hand side)
408 Makes this directive only apply to directories (d) or files (f).
409 e.g. gd-w would remove the group write bit from all directories.
410 `u', `g', `o' (right hand side)
412 Uses the user (u), group (g) or others (o) permission bits of
413 the original file.
414 e.g. g=u would copy the user's permission bits to the group.
415 ug+o would add the others' permissions to the owner and group.
416 Examples
419 o-rwx Removes all permission bits from others.
420 g=rD Allows group to read all files and enter all directories, but
422 nothing else.
423 0644,a+X
425 Sets permission bits to 0644 and adds the execute bit for every‐
426 one to all directories and executables.
427 og-x:og+rD:u=rwX:g+rw
429 Removes execute bit for others and group, adds read and direc‐
430 tory execute for others and group, sets user permissions to
431 read, write and execute directory/executable, adds read and
432 write for group.
433
436 bindfs -u www -g nogroup -p 0000,u=rD ~/mywebsite ~/public_html/mysite
438 Publishes a website in public_html so that only the 'www' user
440 can read the site.
441 bindfs -M foo,bar,1007,@mygroup -p 0600,u+X dir mnt
443 Gives access to 'foo', 'bar', the user with the UID 1007 as well
445 as everyone in the group 'mygroup'. Sets the permission bits to
446 0600, thus giving the specified users read/write access, and
447 adds the user execute bit for directories and executables.
448 bindfs -ono-allow-other,perms=a-w somedir somedir
450 Makes a directory read-only and accessable only by the current
452 user.
453 /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD 0 0
455 An example /etc/fstab entry. Note that the colon must be used to
457 separate arguments to perms, because the comma is an option sep‐
458 arator in /etc/fstab.
459 bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD 0 0
461 Older systems may require this deprecated fstab syntax.
463
466 Setuid and setgid bits have no effect inside the mount. This is a nec‐
467 essary security feature of FUSE.
468 Access to device files is denied by default by FUSE as a security pre‐
470 caution. Use -o dev to enable access (requires mounting as root). This
471 may not be supported on all operating systems.
472 MacFuse caches file contents by default. This means that changes in
474 source files are not always immediately visible under the mount point.
475 -o nolocalcaches can be used to disable the cache.
476 When using --mirror[-only] @somegroup, bindfs won't see changes to the
478 group's member list. Sending bindfs a SIGUSR1 signal will make it
479 reread the user database.
480 The following extra options may be useful under osxfuse: -o
482 local,allow_other,extended_security,noappledouble See
483 https://github.com/osxfuse/osxfuse/wiki/Mount-options for details.
484
486 If bindfs is run in multithreaded mode (with the --multithreaded
487 option) then it's possible for another process to briefly see a file
488 with an incorrect owner, group or permissions. This may constitute a
489 security risk if you rely on bindfs to reduce permissions on new files.
490 For this reason, as of version 1.11 bindfs runs in single-threaded mode
491 by default.
492 Rate limiting favors the process with the larger block size. If two
494 processes compete for read/write access, the one whose read()/write()
495 calls specify the larger block size gets to read/write faster. The
496 total rate limit is maintained though, and clients with equal block
497 sizes and a similar rate of requests are treated fairly as long as the
498 kernel orders their requests fairly.
499 Some features relying on xattrs might not work properly on OS X
501 (https://github.com/mpartel/bindfs/issues/21). For instance, Finder
502 tags seem to work but comments might not.
503 Please report bugs and/or send pull requests to
505 https://github.com/mpartel/bindfs/issues.
506
509 The option names --user and --group were deprecated and replaced with
510 --force-user and --force-group in version 1.12. The former names
511 clashed with standard option names. They are still available but their
512 use is discouraged and prints a warning. The synonym --owner is also
513 deprecated for consistency.
514
517 Martin Pärtel <martin dot partel at gmail dot com>
518
521 chmod(1), fusermount(1), http://bindfs.org/
522 BINDFS(1)