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 opions, 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:zero_file_id = yes | no
96           A global option whether to return zero to queries of on-disk file
97           identifier, if the client has negotiated AAPL.
98
99           Mac applications and / or the Mac SMB client code expect the
100           on-disk file identifier to have the semantics of HFS+ Catalog Node
101           Identifier (CNID). Samba doesn't provide those semantics, and that
102           occasionally cause usability issues or even data loss. Returning a
103           file identifier of zero causes the Mac client to stop using and
104           trusting the file id returned from the server.
105
106           The default is yes.
107
108       fruit:model = MacSamba
109           This option defines the model string inside the AAPL extension and
110           will determine the appearance of the icon representing the Samba
111           server in the Finder window.
112
113           The default is MacSamba.
114

OPTIONS

116       The following options can be set either in the global smb.conf section
117       or per share.
118
119       fruit:resource = [ file | xattr | stream ]
120           Controls where the OS X resource fork is stored.
121
122           Due to a spelling bug in all Samba versions older then 4.6.0, this
123           option can also be given as fruit:ressource, ie with two s.
124
125           Settings:
126
127                  ·   file (default) - use a ._ AppleDouble file compatible
128                      with OS X and Netatalk
129
130                  ·   xattr - use a xattr, requires a filesystem with large
131                      xattr support and a file IO API compatible with xattrs,
132                      this boils down to Solaris and derived platforms and ZFS
133
134                  ·   stream (experimental) - pass the stream on to the next
135                      module in the VFS stack.  Warning: this option should
136                      not be used with the streams_xattr module due to the
137                      extended attributes size limitations of most filesytems.
138
139
140       fruit:time machine = [ yes | no ]
141           Controls if Time Machine support via the FULLSYNC volume capability
142           is advertised to clients.
143
144                  ·   yes - Enables Time Machine support for this share. Also
145                      registers the share with mDNS in case Samba is built
146                      with mDNS support.
147
148                  ·   no (default) Disables advertising Time Machine support.
149
150           This option enforces the following settings per share (or for all
151           shares if enabled globally):
152
153                  ·   durable handles = yes
154
155                  ·   kernel oplocks = no
156
157                  ·   kernel share modes = no
158
159                  ·   posix locking = no
160
161
162       fruit:time machine max size = SIZE [K|M|G|T|P]
163           Useful for Time Machine: limits the reported disksize, thus
164           preventing Time Machine from using the whole real disk space for
165           backup. The option takes a number plus an optional unit.
166
167           IMPORTANT: This is an approximated calculation that only takes into
168           account the contents of Time Machine sparsebundle images. Therefor
169           you MUST NOT use this volume to store other content when using this
170           option, because it would NOT be accounted.
171
172           The calculation works by reading the band size from the Info.plist
173           XML file of the sparsebundle, reading the bands/ directory counting
174           the number of band files, and then multiplying one with the other.
175
176       fruit:metadata = [ stream | netatalk ]
177           Controls where the OS X metadata stream is stored:
178
179                  ·   netatalk (default) - use Netatalk compatible xattr
180
181                  ·   stream - pass the stream on to the next module in the
182                      VFS stack
183
184
185       fruit:locking = [ netatalk | none ]
186
187
188                  ·   none (default) - no cross protocol locking
189
190                  ·   netatalk - use cross protocol locking with Netatalk
191
192
193       fruit:encoding = [ native | private ]
194           Controls how the set of illegal NTFS ASCII character, commonly used
195           by OS X clients, are stored in the filesystem.
196
197           Important: this is known to not fully work with
198           fruit:metadata=stream or fruit:resource=stream.
199
200                  ·   private (default) - store characters as encoded by the
201                      OS X client: mapped to the Unicode private range
202
203                  ·   native - store characters with their native ASCII value.
204                      Important: this option requires the use of vfs_catia in
205                      the VFS module stack as shown in the examples section.
206
207
208       fruit:veto_appledouble = yes | no
209           Note: this option only applies when fruit:resource is set to file
210           (the default).
211
212           When fruit:resource is set to file, vfs_fruit may create ._
213           AppleDouble files. This options controls whether these ._
214           AppleDouble files are vetoed which prevents the client from
215           accessing them.
216
217           Vetoing ._ files may break some applications, eg extracting Mac ZIP
218           archives from Mac clients failes, because they contain ._ files.
219           Setting this option to false will fix this, but the abstraction
220           leak of exposing the internally created ._ files may have other
221           unknown side effects.
222
223           The default is yes.
224
225       fruit:posix_rename = yes | no
226           Whether to enable POSIX directory rename behaviour for OS X
227           clients. Without this, directories can't be renamed if any client
228           has any file inside it (recursive!) open.
229
230           The default is yes.
231
232       readdir_attr:aapl_rsize = yes | no
233           Return resource fork size in SMB2 FIND responses.
234
235           The default is yes.
236
237       readdir_attr:aapl_finder_info = yes | no
238           Return FinderInfo in SMB2 FIND responses.
239
240           The default is yes.
241
242       readdir_attr:aapl_max_access = yes | no
243           Return the user's effective maximum permissions in SMB2 FIND
244           responses. This is an expensive computation, setting this to off
245           pretends the use has maximum effective permissions.
246
247           The default is yes.
248

EXAMPLES

250                   [share]
251                vfs objects = catia fruit streams_xattr
252                fruit:resource = file
253                fruit:metadata = netatalk
254                fruit:locking = netatalk
255                fruit:encoding = native
256

AUTHOR

258       The original Samba software and related utilities were created by
259       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
260       Source project similar to the way the Linux kernel is developed.
261
262
263
264Samba 4.8.3                       10/30/2018                      VFS_FRUIT(8)
Impressum