vfs_fruit — Enhanced OS X and Netatalk interoperability
vfs objects = fruit
This VFS module is part of the samba(7) suite.
The vfs_fruit module provides
enhanced compatibility with Apple SMB clients and
interoperability with a Netatalk 3 AFP fileserver.
The module should be stacked with
vfs_catia if enabling character conversion and
must be stacked with vfs_streams_xattr, see the
example section for the correct config.
The module enables alternate data streams (ADS) support
for a share, intercepts the OS X special streams "AFP_AfpInfo"
and "AFP_Resource" and handles them in a special way. All
other named streams are deferred to
vfs_streams_xattr which must be loaded
together with vfs_fruit.
Having shares with ADS support enabled for OS X client is worthwhile because it resembles the behaviour of Apple's own SMB server implementation and it avoids certain severe performance degradations caused by Samba's case sensitivity semantics.
The OS X metadata and resource fork stream can be stored
in a way compatible with Netatalk 3 by setting
fruit:resource = file and
fruit:metadata = netatalk.
OS X maps NTFS illegal characters to the Unicode private
range in SMB requests. By setting fruit:encoding =
native, all mapped characters are converted to
native ASCII characters.
Finally, share access modes are optionally checked
against Netatalk AFP sharing modes by setting
fruit:locking = netatalk.
This module is not stackable other then described in this manpage.
The following options must be set in the global smb.conf section and won't take effect when set per share.
A global option whether to enable Apple's SMB2+ extension codenamed AAPL. Default yes. This extension enhances several deficiencies when connecting from Macs:
directory enumeration is enriched with Mac relevant filesystem metadata (UNIX mode, FinderInfo, resource fork size and effective permission), as a result the Mac client doesn't need to fetch this metadata individuallly per directory entry resulting in an often tremendous performance increase.
The ability to query and modify the UNIX mode of directory entries.
There's a set of per share options that come into play when fruit:aapl is enabled. These opions, listed below, can be used to disable the computation of specific Mac metadata in the directory enumeration context, all are enabled by default:
readdir_attr:aapl_rsize = yes | no
readdir_attr:aapl_finder_info = yes | no
readdir_attr:aapl_max_access = yes | no
See below for a description of these options.
A global option whether support for querying and modifying the UNIX mode of directory entries via NFS ACEs is enabled, default yes.
A global option whether to enable OS X specific copychunk ioctl that requests a copy of a whole file along with all attached metadata.
WARNING: the copyfile request is blocking the client while the server does the copy.
.The default is no.
The following options can be set either in the global smb.conf section or per share.
Controls where the OS X resource fork is stored.
Important: Due to a misspelling in the option parser in all Samba versions 4.5 and earlier, this options must be given as fruit:ressource, ie with two s.
Users who set this opion to any non-default setting were still using the default setting of file and are advised to adjust their smb.conf to reflect the effective setting and set fruit:ressource=file in their smb.conf. Removing the option line altogether works as well.
Samba 4.6 will accept both the correct and the wrong spelling, from Samba 4.7 onwards only the correct spelling will be accepted.
Settings:
file (default) - use a ._
AppleDouble file compatible with OS X and
Netatalk
xattr - use a
xattr, requires a filesystem with large xattr support
and a file IO API compatible with xattrs, this boils
down to Solaris and derived platforms and
ZFS
stream (experimental) - pass
the stream on to the next module in the VFS stack.
Warning: this option should not be used
with the streams_xattr module due to the
extended attributes size limitations of most
filesytems.
Controls where the OS X metadata stream is stored:
netatalk (default) - use
Netatalk compatible xattr
stream - pass the
stream on to the next module in the VFS
stack
none (default) - no
cross protocol locking
netatalk - use
cross protocol locking with Netatalk
Controls how the set of illegal NTFS ASCII character, commonly used by OS X clients, are stored in the filesystem:
private (default) -
store characters as encoded by the OS X client: mapped
to the Unicode private range
native - store
characters with their native ASCII
value
Note: this option only applies when
fruit:resource is set to
file (the default).
When fruit:resource is set to
file, vfs_fruit may create ._ AppleDouble
files. This options controls whether these ._ AppleDouble files
are vetoed which prevents the client from accessing them.
Vetoing ._ files may break some applications, eg extracting Mac ZIP archives from Mac clients failes, because they contain ._ files. Setting this option to false will fix this, but the abstraction leak of exposing the internally created ._ files may have other unknown side effects.
The default is yes.
Whether to enable POSIX directory rename behaviour for OS X clients. Without this, directories can't be renamed if any client has any file inside it (recursive!) open.
The default is yes.
Return resource fork size in SMB2 FIND responses.
The default is yes.
Return FinderInfo in SMB2 FIND responses.
The default is yes.
Return the user's effective maximum permissions in SMB2 FIND responses. This is an expensive computation, setting this to off pretends the use has maximum effective permissions.
The default is yes.