1VFS_FRUIT(8) System Administration tools VFS_FRUIT(8)
2
6 vfs_fruit - Enhanced OS X and Netatalk interoperability
7
9 vfs objects = fruit
10
12 This VFS module is part of the samba(7) suite.
13 The vfs_fruit module provides enhanced compatibility with Apple SMB
15 clients and interoperability with a Netatalk 3 AFP fileserver.
16 The module should be stacked with vfs_catia if enabling character
18 conversion and must be stacked with vfs_streams_xattr, see the example
19 section for the correct config.
20 The module enables alternate data streams (ADS) support for a share,
22 intercepts the OS X special streams "AFP_AfpInfo" and "AFP_Resource"
23 and handles them in a special way. All other named streams are deferred
24 to vfs_streams_xattr which must be loaded together with vfs_fruit.
25 Be careful when mixing shares with and without vfs_fruit. OS X clients
27 negotiate SMB2 AAPL protocol extensions on the first tcon, so mixing
28 shares with and without fruit will globally disable AAPL if the first
29 tcon is without fruit.
30 Having shares with ADS support enabled for OS X client is worthwhile
32 because it resembles the behaviour of Apple's own SMB server
33 implementation and it avoids certain severe performance degradations
34 caused by Samba's case sensitivity semantics.
35 The OS X metadata and resource fork stream can be stored in a way
37 compatible with Netatalk 3 by setting fruit:resource = file and
38 fruit:metadata = netatalk.
39 OS X maps NTFS illegal characters to the Unicode private range in SMB
41 requests. By setting fruit:encoding = native, all mapped characters are
42 converted to native ASCII characters.
43 Finally, share access modes are optionally checked against Netatalk AFP
45 sharing modes by setting fruit:locking = netatalk.
46 This module is not stackable other than described in this manpage.
48
50 The following options must be set in the global smb.conf section and
51 won't take effect when set per share.
52 fruit:aapl = yes | no
54 A global option whether to enable Apple's SMB2+ extension codenamed
55 AAPL. Default yes. This extension enhances several deficiencies
56 when connecting from Macs:
57 • directory enumeration is enriched with Mac relevant
59 filesystem metadata (UNIX mode, FinderInfo, resource
60 fork size and effective permission), as a result the Mac
61 client doesn't need to fetch this metadata individually
62 per directory entry resulting in an often tremendous
63 performance increase.
64 • The ability to query and modify the UNIX mode of
66 directory entries.
67 There's a set of per share options that come into play when
69 fruit:aapl is enabled. These options, listed below, can be used to
70 disable the computation of specific Mac metadata in the directory
71 enumeration context, all are enabled by default:
72 • readdir_attr:aapl_rsize = yes | no
74 • readdir_attr:aapl_finder_info = yes | no
76 • readdir_attr:aapl_max_access = yes | no
78 See below for a description of these options.
80 fruit:nfs_aces = yes | no
82 A global option whether support for querying and modifying the UNIX
83 mode of directory entries via NFS ACEs is enabled, default yes.
84 fruit:copyfile = yes | no
86 A global option whether to enable OS X specific copychunk ioctl
87 that requests a copy of a whole file along with all attached
88 metadata.
89 WARNING: the copyfile request is blocking the client while the
91 server does the copy.
92 The default is no.
94 fruit:model = MacSamba
96 This option defines the model string inside the AAPL extension and
97 will determine the appearance of the icon representing the Samba
98 server in the Finder window.
99 The default is MacSamba.
101
103 The following options can be set either in the global smb.conf section
104 or per share.
105 fruit:resource = [ file | xattr | stream ]
107 Controls where the OS X resource fork is stored.
108 Due to a spelling bug in all Samba versions older then 4.6.0, this
110 option can also be given as fruit:ressource, ie with two s.
111 Settings:
113 • file (default) - use a ._ AppleDouble file compatible
115 with OS X and Netatalk
116 • xattr - use a xattr, requires a filesystem with large
118 xattr support and a file IO API compatible with xattrs,
119 this boils down to Solaris and derived platforms and ZFS
120 • stream (experimental) - pass the stream on to the next
122 module in the VFS stack. Warning: this option should
123 not be used with the streams_xattr module due to the
124 extended attributes size limitations of most
125 filesystems.
126 fruit:time machine = [ yes | no ]
129 Controls if Time Machine support via the FULLSYNC volume capability
130 is advertised to clients.
131 • yes - Enables Time Machine support for this share. Also
133 registers the share with mDNS in case Samba is built
134 with mDNS support.
135 • no (default) Disables advertising Time Machine support.
137 This option enforces the following settings per share (or for all
139 shares if enabled globally):
140 • durable handles = yes
142 • kernel oplocks = no
144 • kernel share modes = no
146 • posix locking = no
148 fruit:time machine max size = SIZE [K|M|G|T|P]
151 Useful for Time Machine: limits the reported disksize, thus
152 preventing Time Machine from using the whole real disk space for
153 backup. The option takes a number plus an optional unit.
154 IMPORTANT: This is an approximated calculation that only takes into
156 account the contents of Time Machine sparsebundle images. Therefore
157 you MUST NOT use this volume to store other content when using this
158 option, because it would NOT be accounted.
159 The calculation works by reading the band size from the Info.plist
161 XML file of the sparsebundle, reading the bands/ directory counting
162 the number of band files, and then multiplying one with the other.
163 fruit:metadata = [ stream | netatalk ]
165 Controls where the OS X metadata stream is stored:
166 • netatalk (default) - use Netatalk compatible xattr
168 • stream - pass the stream on to the next module in the
170 VFS stack
171 fruit:locking = [ netatalk | none ]
174 • none (default) - no cross protocol locking
177 • netatalk - use cross protocol locking with Netatalk
179 fruit:encoding = [ native | private ]
182 Controls how the set of illegal NTFS ASCII character, commonly used
183 by OS X clients, are stored in the filesystem.
184 Important: this is known to not fully work with
186 fruit:metadata=stream or fruit:resource=stream.
187 • private (default) - store characters as encoded by the
189 OS X client: mapped to the Unicode private range
190 • native - store characters with their native ASCII value.
192 Important: this option requires the use of vfs_catia in
193 the VFS module stack as shown in the examples section.
194 fruit:veto_appledouble = yes | no
197 Note: this option only applies when fruit:resource is set to file
198 (the default).
199 When fruit:resource is set to file, vfs_fruit may create ._
201 AppleDouble files. This options controls whether these ._
202 AppleDouble files are vetoed which prevents the client from
203 accessing them.
204 Vetoing ._ files may break some applications, e.g. extracting Mac
206 ZIP archives from Mac clients fails, because they contain ._ files.
207 rsync will also be unable to sync files beginning with underscores,
208 as the temporary files it uses for these will start with ._ and so
209 cannot be created.
210 Setting this option to false will fix this, but the abstraction
212 leak of exposing the internally created ._ files may have other
213 unknown side effects.
214 The default is yes.
216 fruit:posix_rename = yes | no
218 Whether to enable POSIX directory rename behaviour for OS X
219 clients. Without this, directories can't be renamed if any client
220 has any file inside it (recursive!) open.
221 The default is yes.
223 readdir_attr:aapl_rsize = yes | no
225 Return resource fork size in SMB2 FIND responses.
226 The default is yes.
228 readdir_attr:aapl_finder_info = yes | no
230 Return FinderInfo in SMB2 FIND responses.
231 The default is yes.
233 readdir_attr:aapl_max_access = yes | no
235 Return the user's effective maximum permissions in SMB2 FIND
236 responses. This is an expensive computation, setting this to off
237 pretends the use has maximum effective permissions.
238 The default is yes.
240 fruit:wipe_intentionally_left_blank_rfork = yes | no
242 Whether to wipe Resource Fork data that matches the special 286
243 bytes sized placeholder blob that macOS client create on occasion.
244 The blob contains a string “This resource fork intentionally left
245 blank”, the remaining bytes being mostly zero. There being no one
246 use of this data, it is probably safe to discard it. When this
247 option is enabled, this module truncates the Resource Fork stream
248 to 0 bytes.
249 The default is no.
251 fruit:delete_empty_adfiles = yes | no
253 Whether to delete empty AppleDouble files. Empty means that the
254 resource fork entry in the AppleDouble files is of size 0, or the
255 size is exactly 286 bytes and the content matches a special
256 boilerplate resource fork created my macOS.
257 The default is no.
259 fruit:zero_file_id = yes | no
261 Whether to return zero to queries of on-disk file identifier if the
262 client has negotiated AAPL.
263 Mac applications and / or the Mac SMB client code expect the
265 on-disk file identifier to have the semantics of HFS+ Catalog Node
266 Identifier (CNID). Samba provides File-IDs based on a file's inode
267 number which gets recycled across file creation and deletion and
268 can therefore not be used for Mac client. Returning a file
269 identifier of zero causes the Mac client to stop using and trusting
270 the file id returned from the server.
271 The default is yes.
273 fruit:convert_adouble = yes | no
275 Whether an attempt shall be made to convert ._ AppleDouble sidecar
276 files to native streams (xattrs when using vfs_streams_xattr). The
277 main use case for this conversion is transparent migration from a
278 server config without streams support where the macOS client
279 created those AppleDouble sidecar files.
280 The default is yes.
282
284 [share]
285 vfs objects = catia fruit streams_xattr
286 fruit:resource = file
287 fruit:metadata = netatalk
288 fruit:locking = netatalk
289 fruit:encoding = native
290
292 The original Samba software and related utilities were created by
293 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
294 Source project similar to the way the Linux kernel is developed.
295Samba 4.18.9 11/30/2023 VFS_FRUIT(8)