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