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
|
<?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.2</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>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>
<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</command> - pass the
stream on to the next module in the VFS
stack</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>
<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</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>
</variablelist>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<programlisting>
<smbconfsection name="[share]"/>
<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>
|
