1VFS_FRUIT(8)              System Administration tools             VFS_FRUIT(8)
2
3
4

NAME

6       vfs_fruit - Enhanced OS X and Netatalk interoperability
7

SYNOPSIS

9       vfs objects = fruit
10

DESCRIPTION

12       This VFS module is part of the samba(7) suite.
13
14       The vfs_fruit module provides enhanced compatibility with Apple SMB
15       clients and interoperability with a Netatalk 3 AFP fileserver.
16
17       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
21       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
26       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
31       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
36       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
40       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
44       Finally, share access modes are optionally checked against Netatalk AFP
45       sharing modes by setting fruit:locking = netatalk.
46
47       This module is not stackable other than described in this manpage.
48

GLOBAL OPTIONS

50       The following options must be set in the global smb.conf section and
51       won't take effect when set per share.
52
53       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
58                  ·   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
65                  ·   The ability to query and modify the UNIX mode of
66                      directory entries.
67
68           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
73                  ·   readdir_attr:aapl_rsize = yes | no
74
75                  ·   readdir_attr:aapl_finder_info = yes | no
76
77                  ·   readdir_attr:aapl_max_access = yes | no
78
79           See below for a description of these options.
80
81       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
85       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
90           WARNING: the copyfile request is blocking the client while the
91           server does the copy.
92
93           The default is no.
94
95       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
100           The default is MacSamba.
101

OPTIONS

103       The following options can be set either in the global smb.conf section
104       or per share.
105
106       fruit:resource = [ file | xattr | stream ]
107           Controls where the OS X resource fork is stored.
108
109           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
112           Settings:
113
114                  ·   file (default) - use a ._ AppleDouble file compatible
115                      with OS X and Netatalk
116
117                  ·   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
121                  ·   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 filesytems.
125
126
127       fruit:time machine = [ yes | no ]
128           Controls if Time Machine support via the FULLSYNC volume capability
129           is advertised to clients.
130
131                  ·   yes - Enables Time Machine support for this share. Also
132                      registers the share with mDNS in case Samba is built
133                      with mDNS support.
134
135                  ·   no (default) Disables advertising Time Machine support.
136
137           This option enforces the following settings per share (or for all
138           shares if enabled globally):
139
140                  ·   durable handles = yes
141
142                  ·   kernel oplocks = no
143
144                  ·   kernel share modes = no
145
146                  ·   posix locking = no
147
148
149       fruit:time machine max size = SIZE [K|M|G|T|P]
150           Useful for Time Machine: limits the reported disksize, thus
151           preventing Time Machine from using the whole real disk space for
152           backup. The option takes a number plus an optional unit.
153
154           IMPORTANT: This is an approximated calculation that only takes into
155           account the contents of Time Machine sparsebundle images. Therefor
156           you MUST NOT use this volume to store other content when using this
157           option, because it would NOT be accounted.
158
159           The calculation works by reading the band size from the Info.plist
160           XML file of the sparsebundle, reading the bands/ directory counting
161           the number of band files, and then multiplying one with the other.
162
163       fruit:metadata = [ stream | netatalk ]
164           Controls where the OS X metadata stream is stored:
165
166                  ·   netatalk (default) - use Netatalk compatible xattr
167
168                  ·   stream - pass the stream on to the next module in the
169                      VFS stack
170
171
172       fruit:locking = [ netatalk | none ]
173
174
175                  ·   none (default) - no cross protocol locking
176
177                  ·   netatalk - use cross protocol locking with Netatalk
178
179
180       fruit:encoding = [ native | private ]
181           Controls how the set of illegal NTFS ASCII character, commonly used
182           by OS X clients, are stored in the filesystem.
183
184           Important: this is known to not fully work with
185           fruit:metadata=stream or fruit:resource=stream.
186
187                  ·   private (default) - store characters as encoded by the
188                      OS X client: mapped to the Unicode private range
189
190                  ·   native - store characters with their native ASCII value.
191                      Important: this option requires the use of vfs_catia in
192                      the VFS module stack as shown in the examples section.
193
194
195       fruit:veto_appledouble = yes | no
196           Note: this option only applies when fruit:resource is set to file
197           (the default).
198
199           When fruit:resource is set to file, vfs_fruit may create ._
200           AppleDouble files. This options controls whether these ._
201           AppleDouble files are vetoed which prevents the client from
202           accessing them.
203
204           Vetoing ._ files may break some applications, e.g. extracting Mac
205           ZIP archives from Mac clients fails, because they contain ._ files.
206           rsync will also be unable to sync files beginning with underscores,
207           as the temporary files it uses for these will start with ._ and so
208           cannot be created.
209
210           Setting this option to false will fix this, but the abstraction
211           leak of exposing the internally created ._ files may have other
212           unknown side effects.
213
214           The default is yes.
215
216       fruit:posix_rename = yes | no
217           Whether to enable POSIX directory rename behaviour for OS X
218           clients. Without this, directories can't be renamed if any client
219           has any file inside it (recursive!) open.
220
221           The default is yes.
222
223       readdir_attr:aapl_rsize = yes | no
224           Return resource fork size in SMB2 FIND responses.
225
226           The default is yes.
227
228       readdir_attr:aapl_finder_info = yes | no
229           Return FinderInfo in SMB2 FIND responses.
230
231           The default is yes.
232
233       readdir_attr:aapl_max_access = yes | no
234           Return the user's effective maximum permissions in SMB2 FIND
235           responses. This is an expensive computation, setting this to off
236           pretends the use has maximum effective permissions.
237
238           The default is yes.
239
240       fruit:wipe_intentionally_left_blank_rfork = yes | no
241           Whether to wipe Resource Fork data that matches the special 286
242           bytes sized placeholder blob that macOS client create on occasion.
243           The blob contains a string “This resource fork intentionally left
244           blank”, the remaining bytes being mostly zero. There being no one
245           use of this data, it is probably safe to discard it. When this
246           option is enabled, this module truncates the Resource Fork stream
247           to 0 bytes.
248
249           The default is no.
250
251       fruit:delete_empty_adfiles = yes | no
252           Whether to delete empty AppleDouble files. Empty means that the
253           resource fork entry in the AppleDouble files is of size 0, or the
254           size is exactly 286 bytes and the content matches a special
255           boilerplate resource fork created my macOS.
256
257           The default is no.
258
259       fruit:zero_file_id = yes | no
260           Whether to return zero to queries of on-disk file identifier if the
261           client has negotiated AAPL.
262
263           Mac applications and / or the Mac SMB client code expect the
264           on-disk file identifier to have the semantics of HFS+ Catalog Node
265           Identifier (CNID). Samba provides File-IDs based on a file's
266           initial creation date if the option store dos attributes is
267           enabled. Returning a file identifier of zero causes the Mac client
268           to stop using and trusting the file id returned from the server.
269
270           The default is yes.
271

EXAMPLES

273                   [share]
274                vfs objects = catia fruit streams_xattr
275                fruit:resource = file
276                fruit:metadata = netatalk
277                fruit:locking = netatalk
278                fruit:encoding = native
279

AUTHOR

281       The original Samba software and related utilities were created by
282       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
283       Source project similar to the way the Linux kernel is developed.
284
285
286
287Samba 4.11.4                      12/16/2019                      VFS_FRUIT(8)
Impressum