Mount Options - macfuse/macfuse GitHub Wiki
allow_other
By default, macFUSE limits volume access to the user that mounted the volume. Nobody, not even the user root, can access another user's volume. This blanket denial is a first line of defense against misbehaving (whether inadvertently or otherwise) user space file systems that could "hang" system programs. If you do trust a file system or are otherwise confident, you can use allow_other to turn the blanket denial off. For example, if you wish to use Spotlight on a macFUSE volume, you'll need to use allow_other.
With allow_other, the volume will be accessible normally to all users, but usual permission checks will of course apply. Note that allow_other is a privileged option in that it can only be used by either the user root or by a user belonging to the macFUSE admin group. When the macFUSE kernel extension is loaded, loader sets this group's ID to be that of the admin group on macOS. The user root can change this ID through the sysctl interface (note that macFUSE allows you to set any group ID you specify, even those that do not exist):
Get admin group ID:
% sudo sysctl vfs.generic.macfuse.tunables.admin_group
vfs.generic.macfuse.tunables.admin_group: 80
Set admin group ID:
% sudo sysctl -w vfs.generic.macfuse.tunables.admin_group=81
vfs.generic.macfuse.tunables.admin_group: 80 -> 81
allow_recursion
By default, macFUSE does not allow you to mount a macFUSE volume on a directory that itself resides on a macFUSE volume. Such recursion can create unmount-time issues in some cases. Unlike most other macFUSE restrictions, this is a "soft" check that is done only by the mount tool. allow_recursion disables this restriction.
allow_root
Please read the description for allow_other first. allow_root is similar, except that the set of "other" users contains only the user root. You need to be a member of the macFUSE admin group to use allow_root.
auto_cache
By default, if macFUSE detects a change in a file's size during getattr(), it will purge that file's buffer cache. When auto_cache is enabled, macFUSE will additionally detect modification time changes during getattr() and open() and will automatically purge the buffer cache and/or attributes of the file if necessary. It will also generate the relevant kqueue messages. auto_cache is not enabled by default, it's opt-in. Use the unsolicited notification API instead of auto_cache to actively inform the kernel extension about remote changes.
auto_xattr
By default, macFUSE provides a flexible and adaptive mechanism to handle extended attributes (including things such as Finder Info, Resource Forks, and ACLs). It will initially forward extended attributes calls up to the user space file system. If the latter does not implement extended attribute functions, macFUSE will remember this and will not forward subsequent calls. It will store extended attributes as Apple Double (._) files. If the user space file system does implement extended attribute functions, it can choose to handle all or only some extended attributes. If there are certain extended attributes that the user space file system wants macFUSE (the kernel) to handle through ._ files, it should return ENOTSUP for such attributes. The auto_xattr option tells macFUSE to not bother with sending any extended attributes calls up to user space, regardless of whether the user space file system implements the relevant functions or not. With auto_xattr, the kernel will always use ._ files.
daemon_timeout
daemon_timeout=N, where N specifies the timeout in seconds.
When the kernel sends calls to a user space file system, the latter must reply within some reasonably short time limit, otherwise those calls, and in turn the application that made those calls, will "hang". User programs cannot be completely trusted as they could inadvertently or maliciously fail to respond forever. A typical example is when the file system has a bug that has caused it to crash. In this case, the file system will never respond. Another typical example is that of a network operation performed by the file system taking too long. The kernel can't tell what is really going on, but it does have to guard against hangs.
If you need more control, you can tweak things on a per-mount basis. The daemon_timeout option lets you specify the aforementioned time limit in seconds. The default timeout is 60 seconds. In case there is a timeout, the volume will be automatically ejected (data in any open files may be lost).
debug
The debug (or simply -d) option causes the user space file system daemon to print debugging messages for requests and response. The daemon will also run in foregrounded mode with this option.
default_permissions and defer_permissions
As with extended attributes, macFUSE provides a flexible and adaptive mechanism for dealing with permission checks. By default, macFUSE will involve the user space file system in permission checks by sending it access messages (see access(2)). If the file system doesn't implement the access function, macFUSE will perform permission checks entirely itself based on the attributes of file system objects. The default_permissions option also enables this behavior, wherein the kernel will attempt to do the "right thing" based on what it can "see" (the permission bits as reported by the file system). The file system may not always do the right thing itself though--for example, if the file system retrieves file information from another computer and reports user/group IDs as is, the kernel will not see any alien IDs as belonging to the user that mounted the volume. (This can happen if user ID translation is not enabled or sometimes doesn't work with sshfs.) The defer_permissions option is useful in such cases. It causes macFUSE to assume that all accesses are allowed, it will forward all operations to the file system, and it is up to somebody else to eventually allow or deny the operations. In the case of sshfs, it would be the SFTP server eventually making the decision about what to allow or disallow.
direct_io
Some file systems may not know the sizes of files that they provide. This could be because a file's content is being streamed so it's difficult or impossible to know the "size" of the file. The content could be dynamically changing so it may not make sense to advertise a size at getattr time only to find that the size has changed at read or write time. What these file systems would like is to be able to allow reads and writes without the file size mattering. This is not possible in the normal I/O paths in the kernel. The direct_io option causes macFUSE to use an alternative "direct" I/O path between the kernel and the user space file system. This path makes the file size irrelevant and reads will go on until the file system stops returning data. In particular, as an implementation side effect, the I/O path bypasses the unified buffer cache altogether. As a result mmap(2) is not available. This in turn will cause compatibility issues with many high-level applications. direct_io is a nonstandard mode of operation. Unless your file system requires this mode, don't use this option.
extended_security
macFUSE supports access control lists (ACLs). The extended_security option enables the feature for a file system. To properly support ACLs, a user space file system must correctly handle the com.apple.system.Security extended attribute. It is possible to get by with storing ACLs in Apple Double (._) files, although that wouldn't be a very secure implementation of ACLs because such files can be manipulated directly. Still, it would work for experimental purposes.
-f
The -f option causes a user space file system to run in foreground mode.
fair_locking
By default, macFUSE uses an unfair locking mechanism to ensure file system consistency. This can lead to issues when the file system is processing an extreme amount of operations in parallel. In this case, some file system operations might be delayed too long for real-time tasks. The "fair_locking" option ensures that file system operations are processed fairly. Fair locking comes a little performance overhead compared to unfair locking, but it might be the better option when dealing with high pressure situations.
fsid
fsid=N, where N is a 24-bit integer (0 and 0xFFFFFF not valid).
By default, macFUSE will use a newly generated file system ID for every mount. This is fine except in a case where you do want the volume, when mounted again, to have a persistent file system ID (think aliases, for example). Since macFUSE volumes do not have "real" devices backing them, this isn't possible without extra help. The fsid option is that extra help: you use it to specify a 24-bit number that will be used to generate the file system ID.
fsname
fsname=NAME, where NAME is a string.
This option can be used to specify the "file system name", analogous to the device in the case of a disk-backed "real" file system. For example, the fsname in the following mount information is sshfs#[email protected].
% mount
...
sshfs#[email protected]:/tmp/dir on /private/tmp/ssh (macfuse, nodev, nosuid, synchronous, mounted by singh)
...
Note:
- The file system daemon can choose to specify its own
fsnameand can override a user-providedfsname. - If you implement support for renaming disk-backed file systems,
fsnameneeds to specify the backing device, otherwise the volume can not be unmounted programmatically.
fssubtype
fssubtype=N, where N is an integer.
You can use this option to specify the file system subtype identifier for macFUSE volume being mounted. The Finder uses this subtype to retrieve the string description (if any) for the file system. The description is what you see next to the Format: label in window that you get when you perform a "Get Info" Finder operation on the volume. This only works for subtype-string pairs that are already present in the macFUSE file system bundle (macfuse.fs) that's installed as part of macFUSE.
fstypename
fstypename=NAME, where NAME is a string.
You can use this option to specify the file system's type name. NAME can be at most 6 character (and if specified, must be at least one character). This would cause the in-kernel file system type to be macfuse_NAME. That is, the macfuse_ prefix will be implied and automatically added by the kernel. Thereafter, a user space file system that uses this option must name its on-disk file system bundle macfuse_NAME.fs. The Finder and other programs/libraries that look into file system bundles will now look inside this bundle (instead of the usual macfuse.fs) for things such as subtypes and description strings. The fssubtype=N option will continue to exist and work. A file system that does not need or use fssubtypename=NAME will work as in the past. Please note that this option is doing something the side effects of which cannot be entirely predicted because arbitrary programs can depend on the true file system type--therefore, the use of this option is subject to a general "this might break things you don't know about" warning.
iosize
iosize=N, where N is the I/O size in bytes.
You can use this option to specify the I/O size macFUSE should use while accessing the hypothetical storage device corresponding to a macFUSE volume. The minimum possible I/O size is 16,384 bytes on Apple Silicon and 4,096 bytes on Intel hardware, whereas the largest is 32 MiB. The size must also be a power of 2.
jail_symlinks
This option can be used to "jail" symbolic links within the macFUSE volume itself. If an absolute symbolic link is encountered, macFUSE will prefix the mount path to it.
local
This option marks the volume as local. By default, macFUSE volumes are marked as "non-local", which technically isn't necessarily the same as a "server" or "network" volume, but is treated as such by the Finder in many cases. If you use this option, you can get around this "limitation". However, macOS will be more aggressive in dealing with "local" volumes, e.g. a .Trashes. directory will be created. You might run into mysterious problems with Disk Arbitration and other system components. The effects of this option are largely unknown. Therefore, treat this option as experimental and use it with caution.
modules
modules=M1[:M2...], where Mi is the name of a module to be pushed onto the file system stack.
The macFUSE user space library supports stackable modules. Modules are entire file systems or file system shims that can be stacked atop other file systems or shims. For example, filename character set conversion can be handled through such a module. Custom volume icon support in macFUSE is handled through the volicon module. In fact, the volicon=PATH option is a shortcut for modules=volicon,iconpath=PATH option combination. Note that each module can have one or more of its own arguments (volicon has one option: iconpath).
negative_vncache
This option enables negative vnode name caching in the kernel. That is, when a file system object name does not exist, macFUSE will remember this upon the first lookup of that name. Thereafter, macFUSE will not call the user space file system upon subsequent lookups for that name, until an object of that name does get created. The negative cache is LRU managed by the kernel. This is an optimization. If you have a case where file system objects can appear "outside of macFUSE's knowledge" (say, on a remote server in the case of a macFUSE-based network file system), then you should not enable this option.
noappledouble
This option makes macFUSE deny all types of access to Apple Double (._) files and .DS_Store files. Any existing files will become apparently non-existent. New files that match the criteria will be disallowed from being created.
noapplexattr
This option makes macFUSE deny all types of access to extended attributes that begin with the com.apple. prefix. This is the preferred option if you wish to disallow entities such as resource forks and Finder information.
nobrowse
This marks a volume as non-browsable in that it indicates that the file system is not an appropriate path to user data. The Finder wouldn't automatically browse into such a volume.
nolocalcaches
The nolocalcaches option disables the unified buffer cache (UBC), vnode name caching, attribute caching, and readaheads. This means the kernel will have to call the user space file system upon every operation. The "benefit" is that the kernel might be able to detect remote file changes sooner.
For example, in the case of sshfs, if a file was changed remotely on the server, macFUSE has no way of knowing about it. With nolocalcaches, macFUSE will have no cached information and will have to call sshfs upon every operation. The sshfs program has its own cache, which you can also disable using the cache=no option. If all caching is thus disabled, all operations would end up going to go to the SFTP server, resulting in an apparently up-to-date view of the remote file system. There are major caveats, however. nolocalcaches creates significant overhead. File operations could end up being much slower. Besides, since SFTP provides no synchronization or locking, there are no consistency or ordering guarantees if multiple clients write to the same file concurrently. SFTP is merely a utility to access remote data and not a means of distributed file sharing.
norm_insensitive
When using the norm_insensitive option with a high-level file system, file names are normalized before performing a lookup. File names using different normalization forms will be treated as equal.
noubc
This turns off the unified buffer cache (UBC) for the entire macFUSE volume.
novncache
This turns off vnode name caching in the kernel.
quiet
The macFUSE user space library ensures at runtime that it is talking to a compatible version of the macFUSE kernel extension. If there is a mismatch, macFUSE will show an alert and will also send a notification to the Distributed Notification Center. The quiet option will suppress any such alert.
rdonly
The rdonly (or simply, -r) option can be used to mount a macFUSE file system in read-only mode.
-s
By default, the macFUSE user space library runs a file system in multithreaded mode. You can use the -s option to make a user space file system run in single-threaded mode.
slow_statfs
By default statfs() is assumed to be fast enough so that the returned information (e.g. free/used space on a volume) does not need to be cached by macOS. This option is intended for file systems that must always read from disk or always perform network transactions when receiving a statfs() call. Using the slow_statfs option will result in fewer statfs() calls. However, Finder and other system components might present stale information. In most cases, using this option is not recommended.
volicon
volicon=PATH, where PATH is a path to an icon (.icns) file.
You can use the volicon option to specify an icon file that should be used as the Desktop icon for the mounted macFUSE volume. macFUSE will then do the needful (simulating Finder information for the root folder, simulating a /.VolumeIcon.icns file) to make the custom volume icon work. Note that macFUSE uses library-level stacking for this. It generates a shim file system atop the regular user space file system, with the shim's only purpose being to simulate what's necessary for the icon to work. Please note that volicon=PATH is a convenience shortcut for loading the volicon module (see modules options above) and using the iconpath=PATH option.
volname
volname=NAME, where NAME is a string.
You can use the volname option to specify a name for the macFUSE volume being mounted. This is the name that will show up in Finder and on the Desktop. In the absence of this option, macFUSE will automatically generate a name that would incorporate the macFUSE device index and the user space file system being used. For example, an sshfs mount might have an automatically assigned name "macFUSE Volume 0 (sshfs)".