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.
Be careful when mixing shares with and without vfs_fruit. OS X
clients negotiate SMB2 AAPL protocol extensions on the first tcon, so mixing
shares with and without fruit will globally disable AAPL if the first tcon
is without 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 than 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.
fruit:aapl = yes | no
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 individually 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 options, 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.
fruit:nfs_aces = yes | no
A global option whether support for querying and
modifying the UNIX mode of directory entries via NFS ACEs is enabled, default
yes.
fruit:copyfile = yes | no
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.
fruit:model = MacSamba
This option defines the model string inside the AAPL
extension and will determine the appearance of the icon representing the Samba
server in the Finder window.
The default is MacSamba.
The following options can be set either in the global smb.conf
section or per share.
fruit:resource = [ file | xattr | stream ]
Controls where the OS X resource fork is stored.
Due to a spelling bug in all Samba versions older than 4.6.0, this
option can also be given as fruit:ressource, ie with two s.
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 filesystems.
fruit:time machine = [ yes | no ]
Controls if Time Machine support via the FULLSYNC volume
capability is advertised to clients.
•yes - Enables Time Machine support for this
share. Also registers the share with mDNS in case Samba is built with mDNS
support.
•no (default) Disables advertising Time Machine
support.
This option enforces the following settings per share (or for all shares if
enabled globally):
•durable handles = yes
•kernel oplocks = no
•kernel share modes = no
•posix locking = no
fruit:time machine max size = SIZE [K|M|G|T|P]
Useful for Time Machine: limits the reported disksize,
thus preventing Time Machine from using the whole real disk space for backup.
The option takes a number plus an optional unit.
IMPORTANT: This is an approximated calculation that only
takes into account the contents of Time Machine sparsebundle images.
Therefore you MUST NOT use this volume to store other content when
using this option, because it would NOT be accounted.
The calculation works by reading the band size from the Info.plist
XML file of the sparsebundle, reading the bands/ directory counting the
number of band files, and then multiplying one with the other.
fruit:metadata = [ stream | netatalk ]
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
fruit:locking = [ netatalk | none ]
•none (default) - no cross protocol locking
•netatalk - use cross protocol locking with
Netatalk
fruit:encoding = [ native | private ]
Controls how the set of illegal NTFS ASCII character,
commonly used by OS X clients, are stored in the filesystem.
Important: this is known to not fully work with
fruit:metadata=stream or fruit:resource=stream.
•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. Important: this option requires the use of vfs_catia in
the VFS module stack as shown in the examples section.
fruit:veto_appledouble = yes | no
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, e.g. extracting Mac
ZIP archives from Mac clients fails, because they contain ._ files. rsync
will also be unable to sync files beginning with underscores, as the
temporary files it uses for these will start with ._ and so cannot be
created.
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.
readdir_attr:aapl_rsize = yes | no
Return resource fork size in SMB2 FIND responses.
The default is yes.
readdir_attr:aapl_finder_info = yes | no
Return FinderInfo in SMB2 FIND responses.
The default is yes.
readdir_attr:aapl_max_access = yes | no
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.
fruit:wipe_intentionally_left_blank_rfork = yes | no
Whether to wipe Resource Fork data that matches the
special 286 bytes sized placeholder blob that macOS client create on occasion.
The blob contains a string “This resource fork intentionally left
blank”, the remaining bytes being mostly zero. There being no one use
of this data, it is probably safe to discard it. When this option is enabled,
this module truncates the Resource Fork stream to 0 bytes.
The default is no.
fruit:delete_empty_adfiles = yes | no
Whether to delete empty AppleDouble files. Empty means
that the resource fork entry in the AppleDouble files is of size 0, or the
size is exactly 286 bytes and the content matches a special boilerplate
resource fork created my macOS.
The default is no.
fruit:zero_file_id = yes | no
Whether to return zero to queries of on-disk file
identifier if the client has negotiated AAPL.
Mac applications and / or the Mac SMB client code expect the
on-disk file identifier to have the semantics of HFS+ Catalog Node
Identifier (CNID). Samba provides File-IDs based on a file's inode number
which gets recycled across file creation and deletion and can therefore not
be used for Mac client. Returning a file identifier of zero causes the Mac
client to stop using and trusting the file id returned from the server.
The default is yes.
fruit:convert_adouble = yes | no
Whether an attempt shall be made to convert ._
AppleDouble sidecar files to native streams (xattrs when using
vfs_streams_xattr). The main use case for this conversion is transparent
migration from a server config without streams support where the macOS client
created those AppleDouble sidecar files.
The default is yes.
fruit:validate_afpinfo = yes | no
Apple clients use the AFP_AfpInfo stream to store
structured file metadata. As part of the marshaled data stored in the stream
the first eight bytes contain some header information. Apple's SMB server as
well as Samba will validate this header bytes processing a client write
request on this stream, and, if the validation fails, fail the write. While
this validation is generally correct, in some data migration scenarios clients
may try to migrate data from 3rd-party SMB servers to Samba servers where the
header information is broken for whatever reason. To allow migration and
header fix-up in these scenarios, the validation can be temporarily disabled
by setting this option to
no.
The default is yes.
fruit:posix_opens = yes | no
When
fruit:posix_opens is set to
yes,
vfs_fruit will internally translate all filesystem semantics to use POSIX
behaviour instead of Windows behaviour. As Macs are closer to POSIX than
Windows with regard to filesystem semantics, this improves access semantics
for a lot of corner cases.
The default is yes.
fruit:ignore_zero_aces = yes | no
When
fruit:ignore_zero_aces is enabled, attempts
to modify filesystem permissions fail if the ACL sent over the wire contains
no ACEs. This is completely valid client behaviour, but it means subsequently
no further access is possible to the file, unless permissions get fixed by an
administrator.
This problematic behaviour has been reported for latest macOS
versions and this new option allows to work around it.
The default is yes.