1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="vfs_fruit.8">
6 <refentrytitle>vfs_fruit</refentrytitle>
7 <manvolnum>8</manvolnum>
8 <refmiscinfo class="source">Samba</refmiscinfo>
9 <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10 <refmiscinfo class="version">&doc.version;</refmiscinfo>
15 <refname>vfs_fruit</refname>
16 <refpurpose>Enhanced OS X and Netatalk interoperability</refpurpose>
21 <command>vfs objects = fruit</command>
26 <title>DESCRIPTION</title>
28 <para>This VFS module is part of the
29 <citerefentry><refentrytitle>samba</refentrytitle>
30 <manvolnum>7</manvolnum></citerefentry> suite.</para>
32 <para>The <command>vfs_fruit</command> module provides
33 enhanced compatibility with Apple SMB clients and
34 interoperability with a Netatalk 3 AFP fileserver.</para>
36 <para>The module should be stacked with
37 <command>vfs_catia</command> if enabling character conversion and
38 must be stacked with <command>vfs_streams_xattr</command>, see the
39 example section for the correct config.</para>
41 <para>The module enables alternate data streams (ADS) support
42 for a share, intercepts the OS X special streams "AFP_AfpInfo"
43 and "AFP_Resource" and handles them in a special way. All
44 other named streams are deferred to
45 <command>vfs_streams_xattr</command> which must be loaded
46 together with <command>vfs_fruit</command>.</para>
48 <para>Be careful when mixing shares with and without
49 vfs_fruit. OS X clients negotiate SMB2 AAPL protocol
50 extensions on the first tcon, so mixing shares with and
51 without fruit will globally disable AAPL if the first tcon is
54 <para>Having shares with ADS support enabled for OS X client
55 is worthwhile because it resembles the behaviour of Apple's
56 own SMB server implementation and it avoids certain severe
57 performance degradations caused by Samba's case sensitivity
60 <para>The OS X metadata and resource fork stream can be stored
61 in a way compatible with Netatalk 3 by setting
62 <command>fruit:resource = file</command> and
63 <command>fruit:metadata = netatalk</command>.</para>
65 <para>OS X maps NTFS illegal characters to the Unicode private
66 range in SMB requests. By setting <command>fruit:encoding =
67 native</command>, all mapped characters are converted to
68 native ASCII characters.</para>
70 <para>Finally, share access modes are optionally checked
71 against Netatalk AFP sharing modes by setting
72 <command>fruit:locking = netatalk</command>.</para>
74 <para>This module is not stackable other than described in
80 <title>GLOBAL OPTIONS</title>
82 <para>The following options must be set in the global smb.conf section
83 and won't take effect when set per share.</para>
88 <term>fruit:aapl = yes | no</term>
90 <para>A <emphasis>global</emphasis> option whether to enable Apple's SMB2+
91 extension codenamed AAPL. Default
92 <emphasis>yes</emphasis>. This extension enhances
93 several deficiencies when connecting from Macs:</para>
96 <listitem><para>directory enumeration is enriched with
97 Mac relevant filesystem metadata (UNIX mode,
98 FinderInfo, resource fork size and effective
99 permission), as a result the Mac client doesn't need
100 to fetch this metadata individually per directory
101 entry resulting in an often tremendous performance
102 increase.</para></listitem>
104 <listitem><para>The ability to query and modify the
105 UNIX mode of directory entries.</para></listitem>
108 <para>There's a set of per share options that come into play when
109 <emphasis>fruit:aapl</emphasis> is enabled. These options, listed
110 below, can be used to disable the computation of specific Mac
111 metadata in the directory enumeration context, all are enabled by
115 <listitem><para>readdir_attr:aapl_rsize = yes | no</para></listitem>
116 <listitem><para>readdir_attr:aapl_finder_info = yes | no</para></listitem>
117 <listitem><para>readdir_attr:aapl_max_access = yes | no</para></listitem>
120 <para>See below for a description of these options.</para>
126 <term>fruit:nfs_aces = yes | no</term>
128 <para>A <emphasis>global</emphasis> option whether support for
129 querying and modifying the UNIX mode of directory entries via NFS
130 ACEs is enabled, default <emphasis>yes</emphasis>.</para>
135 <term>fruit:copyfile = yes | no</term>
137 <para>A <emphasis>global</emphasis> option whether to enable OS X
138 specific copychunk ioctl that requests a copy of a whole file
139 along with all attached metadata.</para>
140 <para>WARNING: the copyfile request is blocking the
141 client while the server does the copy.</para>
142 <para>The default is <emphasis>no</emphasis>.</para>
147 <term>fruit:zero_file_id = yes | no</term>
149 <para>A <emphasis>global</emphasis> option whether to return
150 zero to queries of on-disk file identifier, if the client
151 has negotiated AAPL.</para>
152 <para>Mac applications and / or the Mac SMB
153 client code expect the on-disk file identifier to have the
154 semantics of HFS+ Catalog Node Identifier (CNID). Samba
155 doesn't provide those semantics, and that occasionally cause
156 usability issues or even data loss. Returning a file identifier
157 of zero causes the Mac client to stop using and trusting the
158 file id returned from the server.</para>
159 <para>The default is <emphasis>yes</emphasis>.</para>
164 <term>fruit:model = MacSamba</term>
166 <para>This option defines the model string inside the AAPL
167 extension and will determine the appearance of the icon representing the
168 Samba server in the Finder window.</para>
169 <para>The default is <emphasis>MacSamba</emphasis>.</para>
176 <title>OPTIONS</title>
178 <para>The following options can be set either in the global smb.conf section
184 <term>fruit:resource = [ file | xattr | stream ]</term>
186 <para>Controls where the OS X resource fork is stored.</para>
188 <para>Due to a spelling bug in all Samba versions older then
189 4.6.0, this option can also be given as
190 <emphasis>fruit:ressource</emphasis>, ie with two s.</para>
192 <para>Settings:</para>
195 <listitem><para><command>file (default)</command> - use a ._
196 AppleDouble file compatible with OS X and
197 Netatalk</para></listitem>
199 <listitem><para><command>xattr</command> - use a
200 xattr, requires a filesystem with large xattr support
201 and a file IO API compatible with xattrs, this boils
202 down to Solaris and derived platforms and
203 ZFS</para></listitem>
205 <listitem><para><command>stream (experimental)</command> - pass
206 the stream on to the next module in the VFS stack.
207 <emphasis>Warning: </emphasis> this option should not be used
208 with the <emphasis>streams_xattr</emphasis> module due to the
209 extended attributes size limitations of most
210 filesytems.</para></listitem>
217 <term>fruit:time machine = [ yes | no ]</term>
219 <para>Controls if Time Machine support via the FULLSYNC volume
220 capability is advertised to clients.</para>
223 <listitem><para><command>yes</command> - Enables Time Machine
224 support for this share. Also registers the share with mDNS in
225 case Samba is built with mDNS support.</para></listitem>
227 <listitem><para><command>no (default)</command> Disables
228 advertising Time Machine support.</para></listitem>
232 <para>This option enforces the following settings per share (or
233 for all shares if enabled globally):</para>
235 <listitem><para><command>durable handles = yes</command></para></listitem>
236 <listitem><para><command>kernel oplocks = no</command></para></listitem>
237 <listitem><para><command>kernel share modes = no</command></para></listitem>
238 <listitem><para><command>posix locking = no</command></para></listitem>
245 <term>fruit:time machine max size = SIZE [K|M|G|T|P]</term>
247 <para>Useful for Time Machine: limits the reported disksize, thus
248 preventing Time Machine from using the whole real disk space for
249 backup. The option takes a number plus an optional unit.</para>
250 <para><emphasis>IMPORTANT</emphasis>: This is an approximated
251 calculation that only takes into account the contents of Time
252 Machine sparsebundle images. Therefor you <emphasis>MUST
253 NOT</emphasis> use this volume to store other content when using
254 this option, because it would NOT be accounted.</para>
255 <para>The calculation works by reading the band size from the
256 Info.plist XML file of the sparsebundle, reading the bands/
257 directory counting the number of band files, and then multiplying
258 one with the other.</para>
263 <term>fruit:metadata = [ stream | netatalk ]</term>
265 <para>Controls where the OS X metadata stream is stored:</para>
268 <listitem><para><command>netatalk (default)</command> - use
269 Netatalk compatible xattr</para></listitem>
271 <listitem><para><command>stream</command> - pass the
272 stream on to the next module in the VFS
273 stack</para></listitem>
280 <term>fruit:locking = [ netatalk | none ]</term>
284 <listitem><para><command>none (default)</command> - no
285 cross protocol locking</para></listitem>
287 <listitem><para><command>netatalk</command> - use
288 cross protocol locking with Netatalk</para></listitem>
295 <term>fruit:encoding = [ native | private ]</term>
298 <para>Controls how the set of illegal NTFS ASCII
299 character, commonly used by OS X clients, are stored in
300 the filesystem.</para>
302 <para><emphasis>Important:</emphasis> this is known to not fully
303 work with <emphasis>fruit:metadata=stream</emphasis> or
304 <emphasis>fruit:resource=stream</emphasis>.</para>
308 <listitem><para><command>private (default)</command> -
309 store characters as encoded by the OS X client: mapped
310 to the Unicode private range</para></listitem>
312 <listitem><para><command>native</command> - store
313 characters with their native ASCII
314 value. <emphasis>Important</emphasis>: this option
315 requires the use of <emphasis>vfs_catia</emphasis> in
316 the VFS module stack as shown in the examples
317 section.</para></listitem>
324 <term>fruit:veto_appledouble = yes | no</term>
326 <para><emphasis>Note:</emphasis> this option only applies when
327 <parameter>fruit:resource</parameter> is set to
328 <parameter>file</parameter> (the default).</para>
330 <para>When <parameter>fruit:resource</parameter> is set to
331 <parameter>file</parameter>, vfs_fruit may create ._ AppleDouble
332 files. This options controls whether these ._ AppleDouble files
333 are vetoed which prevents the client from accessing them.</para>
334 <para>Vetoing ._ files may break some applications, e.g.
335 extracting Mac ZIP archives from Mac clients fails,
336 because they contain ._ files. <command>rsync</command> will
337 also be unable to sync files beginning with underscores, as
338 the temporary files it uses for these will start with ._ and
339 so cannot be created.</para>
340 <para>Setting this option to
341 false will fix this, but the abstraction leak of
342 exposing the internally created ._ files may have other
343 unknown side effects.</para>
344 <para>The default is <emphasis>yes</emphasis>.</para>
349 <term>fruit:posix_rename = yes | no</term>
351 <para>Whether to enable POSIX directory rename behaviour
352 for OS X clients. Without this, directories can't be
353 renamed if any client has any file inside it
354 (recursive!) open.</para>
355 <para>The default is <emphasis>yes</emphasis>.</para>
360 <term>readdir_attr:aapl_rsize = yes | no</term>
362 <para>Return resource fork size in SMB2 FIND responses.</para>
363 <para>The default is <emphasis>yes</emphasis>.</para>
368 <term>readdir_attr:aapl_finder_info = yes | no</term>
370 <para>Return FinderInfo in SMB2 FIND responses.</para>
371 <para>The default is <emphasis>yes</emphasis>.</para>
376 <term>readdir_attr:aapl_max_access = yes | no</term>
378 <para>Return the user's effective maximum permissions in SMB2 FIND
379 responses. This is an expensive computation, setting this to off
380 pretends the use has maximum effective permissions.</para>
381 <para>The default is <emphasis>yes</emphasis>.</para>
386 <term>fruit:wipe_intentionally_left_blank_rfork = yes | no</term>
388 <para>Whether to wipe Resource Fork data that matches the special
389 286 bytes sized placeholder blob that macOS client create on
390 occasion. The blob contains a string <quote>This resource fork
391 intentionally left blank</quote>, the remaining bytes being mostly
392 zero. There being no one use of this data, it is probably safe to
393 discard it. When this option is enabled, this module truncates the
394 Resource Fork stream to 0 bytes.</para>
395 <para>The default is <emphasis>no</emphasis>.</para>
400 <term>fruit:delete_empty_adfiles = yes | no</term>
402 <para>Whether to delete empty AppleDouble files. Empty means that
403 the resource fork entry in the AppleDouble files is of size 0, or
404 the size is exactly 286 bytes and the content matches a special
405 boilerplate resource fork created my macOS.</para>
406 <para>The default is <emphasis>no</emphasis>.</para>
414 <title>EXAMPLES</title>
417 <smbconfsection name="[share]"/>
418 <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
419 <smbconfoption name="fruit:resource">file</smbconfoption>
420 <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
421 <smbconfoption name="fruit:locking">netatalk</smbconfoption>
422 <smbconfoption name="fruit:encoding">native</smbconfoption>
428 <title>AUTHOR</title>
430 <para>The original Samba software and related utilities
431 were created by Andrew Tridgell. Samba is now developed
432 by the Samba Team as an Open Source project similar
433 to the way the Linux kernel is developed.</para>