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. Additionally, one can change the permissions of files in the
18       mirrored directory.
19
20
21

FILE OWNERSHIP

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

FILE CREATION POLICY

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

CHOWN/CHGRP POLICY

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

CHMOD POLICY

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

XATTR POLICY

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

OTHER FILE OPERATIONS

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

RATE LIMITS

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

MISCELLANEOUS OPTIONS

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

FUSE OPTIONS

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

PERMISSION SPECIFICATION

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

EXAMPLES

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

NOTES

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

BUGS

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

DEPRECATIONS

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

AUTHOR

517       Martin Pärtel <martin dot partel at gmail dot com>
518
519

SEE ALSO

521       chmod(1), fusermount(1), http://bindfs.org/
522
523
524
525
526                                                                     BINDFS(1)
Impressum