1BINDFS(1)                   General Commands Manual                  BINDFS(1)
2
3
4

NAME

6       bindfs ‐ mount --bind in user-space
7
8
9

SYNOPSIS

11       bindfs [options] dir mountpoint
12
13
14

DESCRIPTION

16       A  FUSE filesystem for mirroring the contents of a directory to another
17       directory, with changes to permissions and other features.
18
19

FILE OWNERSHIP

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
25
26       -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
30
31       -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
36              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
41              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
45
46       -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
52              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
56
57       -M, --mirror-only=user1:user2:..., -o mirror-only=...
58              Like --mirror but disallows access for all other  users  (except
59              root).
60
61
62       --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
69              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
75              Requires mounting as root.
76
77
78       --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
86              Example usage:
87
88                  bindfs --map-passwd=/mnt/orig/etc/passwd \
89                      --map-group=/mnt/orig/etc/group \
90                      /mnt/orig /mnt/mapped
91
92              Requires mounting as root.
93
94       --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
103              Example usage:
104
105                  bindfs --map-passwd-rev=/mnt/mapped/etc/passwd \
106                      --map-group-rev=/mnt/mapped/etc/group \
107                      /mnt/orig /mnt/mapped
108
109              Requires mounting as root.
110
111       --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
116              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
120              Requires mounting as root.
121
122       --gid-offset=..., -o gid-offset=...
123              Works exactly like --uid-offset but for groups.
124
125

FILE CREATION POLICY

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
133       --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
139       --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
143       --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
149       --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
155       --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
163

CHOWN/CHGRP POLICY

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
171       --chown-normal, -o chown-normal
172              Tries to chown the underlying file. This is the default.
173
174       --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
179       --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
183       --chgrp-normal, -o chgrp-normal
184              Tries to chgrp the underlying file. This is the default.
185
186       --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
191       --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
195

CHMOD POLICY

197       Chmod calls are forwarded to the source directory by default.  This may
198       cause unexpected behaviour if bindfs is altering permission bits.
199
200       --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
207       --chmod-ignore, -o chmod-ignore
208              Lets chmod succeed (if the user has enough mirrored permissions)
209              but actually does nothing.
210
211       --chmod-deny, -o chmod-deny
212              Makes chmod always fail with a 'permission denied' error.
213
214       --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
219       --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
228

XATTR POLICY

230       Extended  attributes are mirrored by default, though not all underlying
231       file systems support xattrs.
232
233       --xattr-none, -o xattr-none
234              Disable extended attributes altogether. All operations will  re‐
235              turn 'Operation not supported'.
236
237       --xattr-ro, -o xattr-ro
238              Let extended attributes be read-only.
239
240       --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
245

OTHER FILE OPERATIONS

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
253       --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

RATE LIMITS

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
264       Currently, the implementation is not entirely fair. See BUGS below.
265
266       --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
270       --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
277       --resolve-symlinks, -o resolve-symlinks
278              Transparently resolves symbolic links.  Disables creation of new
279              symbolic links.
280
281              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
288              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
293              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
300       --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
310              Note  that deleting files inside symlinked directories is always
311              possible with all settings,  including  deny,  unless  something
312              else protects those files.
313
314

MISCELLANEOUS OPTIONS

316       -h, --help
317              Displays a help message and exits.
318
319       -V, --version
320              Displays version information and exits.
321
322              --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
326       --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
330              (The deprecated shorthand -n is also still accepted.)
331
332       --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
338              (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
342       --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
347              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
353       --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
358              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
363       --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
368       --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
376       --block-devices-as-files, -o block-devices-as-files
377              Shows block devices as regular files.
378
379       --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
384       --direct-io, -o direct-io
385
386              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
392       --no-direct-io, -o no-direct-io
393
394              This  option  is provided in case the default changes in the fu‐
395              ture.
396
397       --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
403              Only works on Linux. Ignored on other platforms.
404

FUSE OPTIONS

406       -o options
407              Fuse options.
408
409       -r, -o ro
410              Make the mount strictly read-only.  This even prevents root from
411              writing to it.  If this is  all  you  need,  then  (since  Linux
412              2.6.26)  you can get a more efficent mount with mount --bind and
413              then mount -o remount,ro.
414
415       -d, -o debug
416              Enable debug output (implies -f).
417
418       -o fsname=name
419              Sets the source directory  name  in  /proc/mounts  (returned  by
420              mount).   This  is  automatically set as long as the source path
421              has no special characters.
422
423       -f     Foreground operation.
424
425

PERMISSION SPECIFICATION

427       The -p option takes a comma- or colon-separated list  of  either  octal
428       numeric  permission  bits or symbolic representations of permission bit
429       operations.  The symbolic  representation  is  based  on  that  of  the
430       chmod(1) command.  setuid, setgid and sticky bits are ignored.
431
432       This program extends the chmod symbolic representation with the follow‐
433       ing operands:
434
435       `D' (right hand side)
436           Works like X but applies only to directories (not to executables).
437
438       `d' and `f' (left hand side)
439           Makes this directive only apply to directories (d) or files (f).
440           e.g. gd-w would remove the group write bit from all directories.
441
442       `u', `g', `o' (right hand side)
443           Uses the user (u), group (g) or others (o) permission bits of
444           the original file.
445           e.g. g=u would copy the user's permission bits to the group.
446                ug+o would add the others' permissions to the owner and group.
447
448
449       Examples
450       o-rwx  Removes all permission bits from others.
451
452       g=rD   Allows group to read all files and enter  all  directories,  but
453              nothing else.
454
455       0644,a+X
456              Sets permission bits to 0644 and adds the execute bit for every‐
457              one to all directories and executables.
458
459       og-x:og+rD:u=rwX:g+rw
460              Removes execute bit for others and group, adds read  and  direc‐
461              tory  execute  for  others  and  group, sets user permissions to
462              read, write and  execute  directory/executable,  adds  read  and
463              write for group.
464
465

EXAMPLES

467
468       bindfs -u www -g nogroup -p 0000,u=rD ~/mywebsite ~/public_html/mysite
469
470              Publishes  a  website in public_html so that only the 'www' user
471              can read the site.
472
473       bindfs -M foo,bar,1007,@mygroup -p 0600,u+X dir mnt
474
475              Gives access to 'foo', 'bar', the user with the UID 1007 as well
476              as  everyone in the group 'mygroup'. Sets the permission bits to
477              0600, thus giving the specified  users  read/write  access,  and
478              adds the user execute bit for directories and executables.
479
480       bindfs -ono-allow-other,perms=a-w somedir somedir
481
482              Makes  a  directory read-only and accessable only by the current
483              user.
484
485       /home/bob/shared /var/www/shared/bob fuse.bindfs perms=0000:u+rD 0 0
486
487              An example /etc/fstab entry. Note that the colon must be used to
488              separate arguments to perms, because the comma is an option sep‐
489              arator in /etc/fstab.
490
491       bindfs#/home/bob/shared /var/www/shared/bob fuse perms=0000:u+rD 0 0
492
493              Older systems may require this deprecated fstab syntax.
494
495

NOTES

497       Setuid and setgid bits have no effect inside the mount.  This is a nec‐
498       essary security feature of FUSE.
499
500       Access  to device files is denied by default by FUSE as a security pre‐
501       caution.  Use -o dev to enable access (requires mounting as root). This
502       may not be supported on all operating systems.
503
504       MacFuse  caches  file  contents by default.  This means that changes in
505       source files are not always immediately visible under the mount  point.
506       -o nolocalcaches can be used to disable the cache.
507
508       When  using --mirror[-only] @somegroup, bindfs won't see changes to the
509       group's member list.  Sending bindfs a  SIGUSR1  signal  will  make  it
510       reread the user database.
511
512       The  following  extra options may be useful under osxfuse: -o local,al‐
513       low_other,extended_security,noappledouble  See  https://github.com/osx
514       fuse/osxfuse/wiki/Mount-options for details.
515

BUGS

517       If  bindfs  is  run in multithreaded mode (with the --multithreaded op‐
518       tion) then it's possible for another process to briefly see a file with
519       an  incorrect owner, group or permissions.  This may constitute a secu‐
520       rity risk if you rely on bindfs to reduce permissions on new files. For
521       this  reason, as of version 1.11 bindfs runs in single-threaded mode by
522       default.
523
524       Rate limiting favors the process with the larger block  size.   If  two
525       processes  compete  for read/write access, the one whose read()/write()
526       calls specify the larger block size gets to read/write faster.  The to‐
527       tal rate limit is maintained though, and clients with equal block sizes
528       and a similar rate of requests are treated fairly as long as the kernel
529       orders their requests fairly.
530
531       Some  features  relying  on  xattrs  might  not  work  properly on OS X
532       (https://github.com/mpartel/bindfs/issues/21).   For  instance,  Finder
533       tags seem to work but comments might not.
534
535       Please     report     bugs     and/or    send    pull    requests    to
536       https://github.com/mpartel/bindfs/issues.
537
538

DEPRECATIONS

540       The option names --user and --group were deprecated and  replaced  with
541       --force-user  and  --force-group  in  version  1.12.   The former names
542       clashed with standard option names.  They are still available but their
543       use  is  discouraged  and prints a warning. The synonym --owner is also
544       deprecated for consistency.
545
546

AUTHOR

548       Martin Pärtel <martin dot partel at gmail dot com>
549
550

SEE ALSO

552       chmod(1), fusermount(1), http://bindfs.org/
553
554
555
556
557                                                                     BINDFS(1)
Impressum