'\" t .\" Title: vfs_fruit .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 04/07/2024 .\" Manual: System Administration tools .\" Source: Samba 4.20.0 .\" Language: English .\" .TH "VFS_FRUIT" "8" "04/07/2024" "Samba 4\&.20\&.0" "System Administration tools" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" vfs_fruit \- Enhanced OS X and Netatalk interoperability .SH "SYNOPSIS" .HP \w'\ 'u vfs objects = fruit .SH "DESCRIPTION" .PP This VFS module is part of the \fBsamba\fR(7) suite\&. .PP The vfs_fruit module provides enhanced compatibility with Apple SMB clients and interoperability with a Netatalk 3 AFP fileserver\&. .PP 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\&. .PP 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\&. .PP 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\&. .PP Having shares with ADS support enabled for OS X client is worthwhile because it resembles the behaviour of Apple\*(Aqs own SMB server implementation and it avoids certain severe performance degradations caused by Samba\*(Aqs case sensitivity semantics\&. .PP 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\&. .PP 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\&. .PP Finally, share access modes are optionally checked against Netatalk AFP sharing modes by setting fruit:locking = netatalk\&. .PP This module is not stackable other than described in this manpage\&. .SH "GLOBAL OPTIONS" .PP The following options must be set in the global smb\&.conf section and won\*(Aqt take effect when set per share\&. .PP fruit:aapl = yes | no .RS 4 A \fIglobal\fR option whether to enable Apple\*(Aqs SMB2+ extension codenamed AAPL\&. Default \fIyes\fR\&. This extension enhances several deficiencies when connecting from Macs: .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 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\*(Aqt need to fetch this metadata individually per directory entry resulting in an often tremendous performance increase\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The ability to query and modify the UNIX mode of directory entries\&. .RE .sp .RE There\*(Aqs a set of per share options that come into play when \fIfruit:aapl\fR 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: .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} readdir_attr:aapl_rsize = yes | no .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} readdir_attr:aapl_finder_info = yes | no .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} readdir_attr:aapl_max_access = yes | no .RE .sp .RE See below for a description of these options\&. .RE .PP fruit:nfs_aces = yes | no .RS 4 A \fIglobal\fR option whether support for querying and modifying the UNIX mode of directory entries via NFS ACEs is enabled, default \fIyes\fR\&. .RE .PP fruit:copyfile = yes | no .RS 4 A \fIglobal\fR option whether to enable OS X specific copychunk ioctl that requests a copy of a whole file along with all attached metadata\&. .sp WARNING: the copyfile request is blocking the client while the server does the copy\&. .sp The default is \fIno\fR\&. .RE .PP fruit:model = MacSamba .RS 4 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\&. .sp The default is \fIMacSamba\fR\&. .RE .SH "OPTIONS" .PP The following options can be set either in the global smb\&.conf section or per share\&. .PP fruit:resource = [ file | xattr | stream ] .RS 4 Controls where the OS X resource fork is stored\&. .sp Due to a spelling bug in all Samba versions older than 4\&.6\&.0, this option can also be given as \fIfruit:ressource\fR, ie with two s\&. .sp Settings: .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} file (default) \- use a \&._ AppleDouble file compatible with OS X and Netatalk .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 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 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} stream (experimental) \- pass the stream on to the next module in the VFS stack\&. \fIWarning: \fR this option should not be used with the \fIstreams_xattr\fR module due to the extended attributes size limitations of most filesystems\&. .RE .sp .RE .RE .PP fruit:time machine = [ yes | no ] .RS 4 Controls if Time Machine support via the FULLSYNC volume capability is advertised to clients\&. .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} yes \- Enables Time Machine support for this share\&. Also registers the share with mDNS in case Samba is built with mDNS support\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} no (default) Disables advertising Time Machine support\&. .RE .sp .RE This option enforces the following settings per share (or for all shares if enabled globally): .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} durable handles = yes .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} kernel oplocks = no .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} kernel share modes = no .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} posix locking = no .RE .sp .RE .RE .PP fruit:time machine max size = SIZE [K|M|G|T|P] .RS 4 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\&. .sp \fIIMPORTANT\fR: This is an approximated calculation that only takes into account the contents of Time Machine sparsebundle images\&. Therefore you \fIMUST NOT\fR use this volume to store other content when using this option, because it would NOT be accounted\&. .sp 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\&. .RE .PP fruit:metadata = [ stream | netatalk ] .RS 4 Controls where the OS X metadata stream is stored: .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} netatalk (default) \- use Netatalk compatible xattr .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} stream \- pass the stream on to the next module in the VFS stack .RE .sp .RE .RE .PP fruit:locking = [ netatalk | none ] .RS 4 .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} none (default) \- no cross protocol locking .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} netatalk \- use cross protocol locking with Netatalk .RE .sp .RE .RE .PP fruit:encoding = [ native | private ] .RS 4 Controls how the set of illegal NTFS ASCII character, commonly used by OS X clients, are stored in the filesystem\&. .sp \fIImportant:\fR this is known to not fully work with \fIfruit:metadata=stream\fR or \fIfruit:resource=stream\fR\&. .RS .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} private (default) \- store characters as encoded by the OS X client: mapped to the Unicode private range .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} native \- store characters with their native ASCII value\&. \fIImportant\fR: this option requires the use of \fIvfs_catia\fR in the VFS module stack as shown in the examples section\&. .RE .sp .RE .RE .PP fruit:veto_appledouble = yes | no .RS 4 \fINote:\fR this option only applies when \fIfruit:resource\fR is set to \fIfile\fR (the default)\&. .sp When \fIfruit:resource\fR is set to \fIfile\fR, vfs_fruit may create \&._ AppleDouble files\&. This options controls whether these \&._ AppleDouble files are vetoed which prevents the client from accessing them\&. .sp 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\&. .sp Setting this option to false will fix this, but the abstraction leak of exposing the internally created \&._ files may have other unknown side effects\&. .sp The default is \fIyes\fR\&. .RE .PP fruit:posix_rename = yes | no .RS 4 Whether to enable POSIX directory rename behaviour for OS X clients\&. Without this, directories can\*(Aqt be renamed if any client has any file inside it (recursive!) open\&. .sp The default is \fIyes\fR\&. .RE .PP readdir_attr:aapl_rsize = yes | no .RS 4 Return resource fork size in SMB2 FIND responses\&. .sp The default is \fIyes\fR\&. .RE .PP readdir_attr:aapl_finder_info = yes | no .RS 4 Return FinderInfo in SMB2 FIND responses\&. .sp The default is \fIyes\fR\&. .RE .PP readdir_attr:aapl_max_access = yes | no .RS 4 Return the user\*(Aqs effective maximum permissions in SMB2 FIND responses\&. This is an expensive computation, setting this to off pretends the use has maximum effective permissions\&. .sp The default is \fIyes\fR\&. .RE .PP fruit:wipe_intentionally_left_blank_rfork = yes | no .RS 4 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 \(lqThis resource fork intentionally left blank\(rq, 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\&. .sp The default is \fIno\fR\&. .RE .PP fruit:delete_empty_adfiles = yes | no .RS 4 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\&. .sp The default is \fIno\fR\&. .RE .PP fruit:zero_file_id = yes | no .RS 4 Whether to return zero to queries of on\-disk file identifier if the client has negotiated AAPL\&. .sp 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\*(Aqs 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\&. .sp The default is \fIyes\fR\&. .RE .PP fruit:convert_adouble = yes | no .RS 4 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\&. .sp The default is \fIyes\fR\&. .RE .PP fruit:validate_afpinfo = yes | no .RS 4 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\*(Aqs 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 \fIno\fR\&. .sp The default is \fIyes\fR\&. .RE .SH "EXAMPLES" .sp .if n \{\ .RS 4 .\} .nf \fI[share]\fR \m[blue]\fBvfs objects = catia fruit streams_xattr\fR\m[] \m[blue]\fBfruit:resource = file\fR\m[] \m[blue]\fBfruit:metadata = netatalk\fR\m[] \m[blue]\fBfruit:locking = netatalk\fR\m[] \m[blue]\fBfruit:encoding = native\fR\m[] .fi .if n \{\ .RE .\} .SH "AUTHOR" .PP The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.