1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<refentry id="vfs_fruit.8">
<refmeta>
<refentrytitle>vfs_fruit</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="source">Samba</refmiscinfo>
<refmiscinfo class="manual">System Administration tools</refmiscinfo>
<refmiscinfo class="version">4.7</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vfs_fruit</refname>
<refpurpose>Enhanced OS X and Netatalk interoperability</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>vfs objects = fruit</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>This VFS module is part of the
<citerefentry><refentrytitle>samba</refentrytitle>
<manvolnum>7</manvolnum></citerefentry> suite.</para>
<para>The <command>vfs_fruit</command> module provides
enhanced compatibility with Apple SMB clients and
interoperability with a Netatalk 3 AFP fileserver.</para>
<para>The module should be stacked with
<command>vfs_catia</command> if enabling character conversion and
must be stacked with <command>vfs_streams_xattr</command>, see the
example section for the correct config.</para>
<para>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
<command>vfs_streams_xattr</command> which must be loaded
together with <command>vfs_fruit</command>.</para>
<para>vfs_fruit requires "ea support = yes".</para>
<para>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.</para>
<para>Having shares with ADS support enabled for OS X client
is worthwhile because it resembles the behaviour of Apple's
own SMB server implementation and it avoids certain severe
performance degradations caused by Samba's case sensitivity
semantics.</para>
<para>The OS X metadata and resource fork stream can be stored
in a way compatible with Netatalk 3 by setting
<command>fruit:resource = file</command> and
<command>fruit:metadata = netatalk</command>.</para>
<para>OS X maps NTFS illegal characters to the Unicode private
range in SMB requests. By setting <command>fruit:encoding =
native</command>, all mapped characters are converted to
native ASCII characters.</para>
<para>Finally, share access modes are optionally checked
against Netatalk AFP sharing modes by setting
<command>fruit:locking = netatalk</command>.</para>
<para>This module is not stackable other then described in
this manpage.</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>fruit:resource = [ file | xattr | stream ]</term>
<listitem>
<para>Controls where the OS X resource fork is stored.</para>
<para>Due to a spelling bug in all Samba versions older then
4.6.0, this option can also be given as
<emphasis>fruit:ressource</emphasis>, ie with two s.</para>
<para>Settings:</para>
<itemizedlist>
<listitem><para><command>file (default)</command> - use a ._
AppleDouble file compatible with OS X and
Netatalk</para></listitem>
<listitem><para><command>xattr</command> - 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</para></listitem>
<listitem><para><command>stream (experimental)</command> - pass
the stream on to the next module in the VFS stack.
<emphasis>Warning: </emphasis> this option should not be used
with the <emphasis>streams_xattr</emphasis> module due to the
extended attributes size limitations of most
filesytems.</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:metadata = [ stream | netatalk ]</term>
<listitem>
<para>Controls where the OS X metadata stream is stored:</para>
<itemizedlist>
<listitem><para><command>netatalk (default)</command> - use
Netatalk compatible xattr</para></listitem>
<listitem><para><command>stream</command> - pass the
stream on to the next module in the VFS
stack</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:locking = [ netatalk | none ]</term>
<listitem>
<para></para>
<itemizedlist>
<listitem><para><command>none (default)</command> - no
cross protocol locking</para></listitem>
<listitem><para><command>netatalk</command> - use
cross protocol locking with Netatalk</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:encoding = [ native | private ]</term>
<listitem>
<para>Controls how the set of illegal NTFS ASCII
character, commonly used by OS X clients, are stored in
the filesystem.</para>
<para><emphasis>Important:</emphasis> this is known to not fully
work with <emphasis>fruit:metadata=stream</emphasis> or
<emphasis>fruit:resource=stream</emphasis>.</para>
<itemizedlist>
<listitem><para><command>private (default)</command> -
store characters as encoded by the OS X client: mapped
to the Unicode private range</para></listitem>
<listitem><para><command>native</command> - store
characters with their native ASCII
value. <emphasis>Important</emphasis>: this option
requires the use of <emphasis>vfs_catia</emphasis> in
the VFS module stack as shown in the examples
section.</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:aapl = yes | no</term>
<listitem>
<para>A global option whether to enable Apple's SMB2+
extension codenamed AAPL. Default
<emphasis>yes</emphasis>. This extension enhances
several deficiencies when connecting from Macs:</para>
<itemizedlist>
<listitem><para>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't need
to fetch this metadata individuallly per directory
entry resulting in an often tremendous performance
increase.</para></listitem>
<listitem><para>The ability to query and modify the
UNIX mode of directory entries.</para></listitem>
</itemizedlist>
<para>There's a set of per share options that can be
used to disable the computation of specific Mac metadata
in the directory enumeration context, all are enabled by
default:</para>
<itemizedlist>
<listitem><para>readdir_attr:aapl_rsize = true | false</para></listitem>
<listitem><para>readdir_attr:aapl_finder_info = true | false</para></listitem>
<listitem><para>readdir_attr:aapl_max_access = true | false</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:nfs_aces = yes | no</term>
<listitem>
<para>Whether support for querying and modifying the
UNIX mode of directory entries via NFS ACEs is enabled,
default <emphasis>yes</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:veto_appledouble = yes | no</term>
<listitem>
<para>Whether ._ AppleDouble files are vetoed which
prevents the client from seing and accessing internal
AppleDouble files created by vfs_fruit itself for the
purpose of storing a Mac resource fork.</para>
<para>Vetoing ._ files may break some applications, eg
extracting Mac ZIP archives from Mac clients failes,
because they contain ._ files. Setting this option to
false will fix this, but the abstraction leak of
exposing the internally created ._ files may have other
unknown side effects.</para>
<para>The default is <emphasis>yes</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:copyfile = yes | no</term>
<listitem>
<para>Whether to enable OS X specific copychunk ioctl
that requests a copy of a whole file along with all
attached metadata.</para>
<para>WARNING: the copyfile request is blocking the
client while the server does the copy.</para>.
<para>The default is <emphasis>no</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fruit:posix_rename = yes | no</term>
<listitem>
<para>Whether to enable POSIX directory rename behaviour
for OS X clients. Without this, directories can't be
renamed if any client has any file inside it
(recursive!) open.</para>
<para>The default is <emphasis>yes</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<programlisting>
<smbconfsection name="[share]"/>
<smbconfoption name="ea support">yes</smbconfoption>
<smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
<smbconfoption name="fruit:resource">file</smbconfoption>
<smbconfoption name="fruit:metadata">netatalk</smbconfoption>
<smbconfoption name="fruit:locking">netatalk</smbconfoption>
<smbconfoption name="fruit:encoding">native</smbconfoption>
</programlisting>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>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.</para>
</refsect1>
</refentry>
|