1BINDFS(1) General Commands Manual BINDFS(1)
2
3
4
6 bindfs ‐ mount --bind in user-space
7
8
9
11 bindfs [options] dir mountpoint
12
13
14
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
20
21
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
27
28 -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
32
33 -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
38 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
43 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
47
48 -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
54 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
58
59 -M, --mirror-only=user1:user2:..., -o mirror-only=...
60 Like --mirror but disallows access for all other users (except
61 root).
62
63
64 --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
71 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
77 Requires mounting as root.
78
79 --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
85 Example usage:
86
87 bindfs --map-passwd=/mnt/orig/etc/passwd \
88 --map-passwd=/mnt/orig/etc/group \
89 /mnt/orig /mnt/mapped
90
91 Requires mounting as root.
92
93 --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
98 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
102 Requires mounting as root.
103
104 --gid-offset=..., -o gid-offset=...
105 Works exactly like --uid-offset but for groups.
106
107
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
115 --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
121 --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
125 --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
131 --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
137 --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
145
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
153 --chown-normal, -o chown-normal
154 Tries to chown the underlying file. This is the default.
155
156 --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
161 --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
165 --chgrp-normal, -o chgrp-normal
166 Tries to chgrp the underlying file. This is the default.
167
168 --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
173 --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
177
179 Chmod calls are forwarded to the source directory by default. This may
180 cause unexpected behaviour if bindfs is altering permission bits.
181
182 --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
189 --chmod-ignore, -o chmod-ignore
190 Lets chmod succeed (if the user has enough mirrored permissions)
191 but actually does nothing.
192
193 --chmod-deny, -o chmod-deny
194 Makes chmod always fail with a 'permission denied' error.
195
196 --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
201 --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
210
212 Extended attributes are mirrored by default, though not all underlying
213 file systems support xattrs.
214
215 --xattr-none, -o xattr-none
216 Disable extended attributes altogether. All operations will
217 return 'Operation not supported'.
218
219 --xattr-ro, -o xattr-ro
220 Let extended attributes be read-only.
221
222 --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
227
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
235 --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
246 Currently, the implementation is not entirely fair. See BUGS below.
247
248 --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
252 --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
259 --resolve-symlinks, -o resolve-symlinks
260 Transparently resolves symbolic links. Disables creation of new
261 symbolic links.
262
263 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
270 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
275 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
282 --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
292 Note that deleting files inside symlinked directories is always
293 possible with all settings, including deny, unless something
294 else protects those files.
295
296
298 -h, --help
299 Displays a help message and exits.
300
301 -V, --version
302 Displays version information and exits.
303
304 --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
308 --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
312 (The deprecated shorthand -n is also still accepted.)
313
314 --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
320 (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
324 --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
329 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
335 --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
340 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
345 --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
350 --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
358 --block-devices-as-files, -o block-devices-as-files
359 Shows block devices as regular files.
360
361 --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
366 --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
372 Only works on Linux. Ignored on other platforms.
373
375 -o options
376 Fuse options.
377
378 -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
384 -d, -o debug
385 Enable debug output (implies -f).
386
387 -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
392 -f Foreground operation.
393
394
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
401 This program extends the chmod symbolic representation with the follow‐
402 ing operands:
403
404 `D' (right hand side)
405 Works like X but applies only to directories (not to executables).
406
407 `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
411 `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
417
418 Examples
419 o-rwx Removes all permission bits from others.
420
421 g=rD Allows group to read all files and enter all directories, but
422 nothing else.
423
424 0644,a+X
425 Sets permission bits to 0644 and adds the execute bit for every‐
426 one to all directories and executables.
427
428 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
434
436
437 bindfs -u www -g nogroup -p 0000,u=rD ~/mywebsite ~/public_html/mysite
438
439 Publishes a website in public_html so that only the 'www' user
440 can read the site.
441
442 bindfs -M foo,bar,1007,@mygroup -p 0600,u+X dir mnt
443
444 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
449 bindfs -ono-allow-other,perms=a-w somedir somedir
450
451 Makes a directory read-only and accessable only by the current
452 user.
453
454 /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD 0 0
455
456 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
460 bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD 0 0
461
462 Older systems may require this deprecated fstab syntax.
463
464
466 Setuid and setgid bits have no effect inside the mount. This is a nec‐
467 essary security feature of FUSE.
468
469 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
473 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
477 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
481 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
493 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
500 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
504 Please report bugs and/or send pull requests to
505 https://github.com/mpartel/bindfs/issues.
506
507
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
515
517 Martin Pärtel <martin dot partel at gmail dot com>
518
519
521 chmod(1), fusermount(1), http://bindfs.org/
522
523
524
525
526 BINDFS(1)