7f6a0e7c022cd8f81352e30ae5a83d7efdf01f2c
[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">&doc.version;</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>Be careful when mixing shares with and without
49         vfs_fruit. OS X clients negotiate SMB2 AAPL protocol
50         extensions on the first tcon, so mixing shares with and
51         without fruit will globally disable AAPL if the first tcon is
52         without fruit.</para>
53
54         <para>Having shares with ADS support enabled for OS X client
55         is worthwhile because it resembles the behaviour of Apple's
56         own SMB server implementation and it avoids certain severe
57         performance degradations caused by Samba's case sensitivity
58         semantics.</para>
59
60         <para>The OS X metadata and resource fork stream can be stored
61         in a way compatible with Netatalk 3 by setting
62         <command>fruit:resource = file</command> and
63         <command>fruit:metadata = netatalk</command>.</para>
64
65         <para>OS X maps NTFS illegal characters to the Unicode private
66         range in SMB requests. By setting <command>fruit:encoding =
67         native</command>, all mapped characters are converted to
68         native ASCII characters.</para>
69
70         <para>Finally, share access modes are optionally checked
71         against Netatalk AFP sharing modes by setting
72         <command>fruit:locking = netatalk</command>.</para>
73
74         <para>This module is not stackable other than described in
75         this manpage.</para>
76
77 </refsect1>
78
79 <refsect1>
80         <title>GLOBAL OPTIONS</title>
81
82         <para>The following options must be set in the global smb.conf section
83         and won't take effect when set per share.</para>
84
85         <variablelist>
86
87           <varlistentry>
88             <term>fruit:aapl = yes | no</term>
89             <listitem>
90               <para>A <emphasis>global</emphasis> option whether to enable Apple's SMB2+
91               extension codenamed AAPL. Default
92               <emphasis>yes</emphasis>. This extension enhances
93               several deficiencies when connecting from Macs:</para>
94
95               <itemizedlist>
96                 <listitem><para>directory enumeration is enriched with
97                 Mac relevant filesystem metadata (UNIX mode,
98                 FinderInfo, resource fork size and effective
99                 permission), as a result the Mac client doesn't need
100                 to fetch this metadata individually per directory
101                 entry resulting in an often tremendous performance
102                 increase.</para></listitem>
103
104                 <listitem><para>The ability to query and modify the
105                 UNIX mode of directory entries.</para></listitem>
106               </itemizedlist>
107
108               <para>There's a set of per share options that come into play when
109               <emphasis>fruit:aapl</emphasis> is enabled. These opions, listed
110               below, can be used to disable the computation of specific Mac
111               metadata in the directory enumeration context, all are enabled by
112               default:</para>
113
114               <itemizedlist>
115                 <listitem><para>readdir_attr:aapl_rsize = yes | no</para></listitem>
116                 <listitem><para>readdir_attr:aapl_finder_info = yes | no</para></listitem>
117                 <listitem><para>readdir_attr:aapl_max_access = yes | no</para></listitem>
118               </itemizedlist>
119
120               <para>See below for a description of these options.</para>
121
122             </listitem>
123           </varlistentry>
124
125           <varlistentry>
126             <term>fruit:nfs_aces = yes | no</term>
127             <listitem>
128               <para>A <emphasis>global</emphasis> option whether support for
129               querying and modifying the UNIX mode of directory entries via NFS
130               ACEs is enabled, default <emphasis>yes</emphasis>.</para>
131             </listitem>
132           </varlistentry>
133
134           <varlistentry>
135             <term>fruit:copyfile = yes | no</term>
136             <listitem>
137               <para>A <emphasis>global</emphasis> option whether to enable OS X
138               specific copychunk ioctl that requests a copy of a whole file
139               along with all attached metadata.</para>
140               <para>WARNING: the copyfile request is blocking the
141               client while the server does the copy.</para>
142               <para>The default is <emphasis>no</emphasis>.</para>
143             </listitem>
144           </varlistentry>
145
146           <varlistentry>
147             <term>fruit:zero_file_id = yes | no</term>
148             <listitem>
149               <para>A <emphasis>global</emphasis> option whether to return
150               zero to queries of on-disk file identifier, if the client
151               has negotiated AAPL.</para>
152               <para>Mac applications and / or the Mac SMB
153               client code expect the on-disk file identifier to have the
154               semantics of HFS+ Catalog Node Identifier (CNID). Samba
155               doesn't provide those semantics, and that occasionally cause
156               usability issues or even data loss. Returning a file identifier
157               of zero causes the Mac client to stop using and trusting the
158               file id returned from the server.</para>
159               <para>The default is <emphasis>yes</emphasis>.</para>
160             </listitem>
161           </varlistentry>
162
163           <varlistentry>
164             <term>fruit:model = MacSamba</term>
165             <listitem>
166               <para>This option defines the model string inside the AAPL
167               extension and will determine the appearance of the icon representing the
168               Samba server in the Finder window.</para>
169               <para>The default is <emphasis>MacSamba</emphasis>.</para>
170             </listitem>
171           </varlistentry>
172         </variablelist>
173 </refsect1>
174
175 <refsect1>
176         <title>OPTIONS</title>
177
178         <para>The following options can be set either in the global smb.conf section
179         or per share.</para>
180
181         <variablelist>
182
183           <varlistentry>
184             <term>fruit:resource = [ file | xattr | stream ]</term>
185             <listitem>
186               <para>Controls where the OS X resource fork is stored.</para>
187
188               <para>Due to a spelling bug in all Samba versions older then
189               4.6.0, this option can also be given as
190               <emphasis>fruit:ressource</emphasis>, ie with two s.</para>
191
192               <para>Settings:</para>
193
194               <itemizedlist>
195                 <listitem><para><command>file (default)</command> - use a ._
196                 AppleDouble file compatible with OS X and
197                 Netatalk</para></listitem>
198
199                 <listitem><para><command>xattr</command> - use a
200                 xattr, requires a filesystem with large xattr support
201                 and a file IO API compatible with xattrs, this boils
202                 down to Solaris and derived platforms and
203                 ZFS</para></listitem>
204
205                 <listitem><para><command>stream (experimental)</command> - pass
206                 the stream on to the next module in the VFS stack.
207                 <emphasis>Warning: </emphasis> this option should not be used
208                 with the <emphasis>streams_xattr</emphasis> module due to the
209                 extended attributes size limitations of most
210                 filesytems.</para></listitem>
211               </itemizedlist>
212
213             </listitem>
214           </varlistentry>
215
216           <varlistentry>
217             <term>fruit:time machine = [ yes | no ]</term>
218             <listitem>
219               <para>Controls if Time Machine support via the FULLSYNC volume
220               capability is advertised to clients.</para>
221
222               <itemizedlist>
223                 <listitem><para><command>yes</command> - Enables Time Machine
224                 support for this share. Also registers the share with mDNS in
225                 case Samba is built with mDNS support.</para></listitem>
226
227                 <listitem><para><command>no (default)</command> Disables
228                 advertising Time Machine support.</para></listitem>
229
230               </itemizedlist>
231
232               <para>This option enforces the following settings per share (or
233               for all shares if enabled globally):</para>
234               <itemizedlist>
235                 <listitem><para><command>durable handles = yes</command></para></listitem>
236                 <listitem><para><command>kernel oplocks = no</command></para></listitem>
237                 <listitem><para><command>kernel share modes = no</command></para></listitem>
238                 <listitem><para><command>posix locking = no</command></para></listitem>
239               </itemizedlist>
240
241             </listitem>
242           </varlistentry>
243
244           <varlistentry>
245             <term>fruit:time machine max size = SIZE [K|M|G|T|P]</term>
246             <listitem>
247               <para>Useful for Time Machine: limits the reported disksize, thus
248               preventing Time Machine from using the whole real disk space for
249               backup. The option takes a number plus an optional unit.</para>
250               <para><emphasis>IMPORTANT</emphasis>: This is an approximated
251               calculation that only takes into account the contents of Time
252               Machine sparsebundle images. Therefor you <emphasis>MUST
253               NOT</emphasis> use this volume to store other content when using
254               this option, because it would NOT be accounted.</para>
255               <para>The calculation works by reading the band size from the
256               Info.plist XML file of the sparsebundle, reading the bands/
257               directory counting the number of band files, and then multiplying
258               one with the other.</para>
259             </listitem>
260           </varlistentry>
261
262           <varlistentry>
263             <term>fruit:metadata = [ stream | netatalk ]</term>
264             <listitem>
265               <para>Controls where the OS X metadata stream is stored:</para>
266
267               <itemizedlist>
268                 <listitem><para><command>netatalk (default)</command> - use
269                 Netatalk compatible xattr</para></listitem>
270
271                 <listitem><para><command>stream</command> - pass the
272                 stream on to the next module in the VFS
273                 stack</para></listitem>
274               </itemizedlist>
275
276             </listitem>
277           </varlistentry>
278
279           <varlistentry>
280             <term>fruit:locking = [ netatalk | none ]</term>
281             <listitem>
282               <para></para>
283               <itemizedlist>
284                 <listitem><para><command>none (default)</command> - no
285                 cross protocol locking</para></listitem>
286
287                 <listitem><para><command>netatalk</command> - use
288                 cross protocol locking with Netatalk</para></listitem>
289
290               </itemizedlist>
291             </listitem>
292           </varlistentry>
293
294           <varlistentry>
295             <term>fruit:encoding = [ native | private ]</term>
296             <listitem>
297
298               <para>Controls how the set of illegal NTFS ASCII
299               character, commonly used by OS X clients, are stored in
300               the filesystem.</para>
301
302               <para><emphasis>Important:</emphasis> this is known to not fully
303               work with <emphasis>fruit:metadata=stream</emphasis> or
304               <emphasis>fruit:resource=stream</emphasis>.</para>
305
306               <itemizedlist>
307
308                 <listitem><para><command>private (default)</command> -
309                 store characters as encoded by the OS X client: mapped
310                 to the Unicode private range</para></listitem>
311
312                 <listitem><para><command>native</command> - store
313                 characters with their native ASCII
314                 value. <emphasis>Important</emphasis>: this option
315                 requires the use of <emphasis>vfs_catia</emphasis> in
316                 the VFS module stack as shown in the examples
317                 section.</para></listitem>
318
319               </itemizedlist>
320             </listitem>
321           </varlistentry>
322
323           <varlistentry>
324             <term>fruit:veto_appledouble = yes | no</term>
325             <listitem>
326               <para><emphasis>Note:</emphasis> this option only applies when
327               <parameter>fruit:resource</parameter> is set to
328               <parameter>file</parameter> (the default).</para>
329
330               <para>When <parameter>fruit:resource</parameter> is set to
331               <parameter>file</parameter>, vfs_fruit may create ._ AppleDouble
332               files. This options controls whether these ._ AppleDouble files
333               are vetoed which prevents the client from accessing them.</para>
334               <para>Vetoing ._ files may break some applications, eg
335               extracting Mac ZIP archives from Mac clients failes,
336               because they contain ._ files. Setting this option to
337               false will fix this, but the abstraction leak of
338               exposing the internally created ._ files may have other
339               unknown side effects.</para>
340               <para>The default is <emphasis>yes</emphasis>.</para>
341             </listitem>
342           </varlistentry>
343
344           <varlistentry>
345             <term>fruit:posix_rename = yes | no</term>
346             <listitem>
347               <para>Whether to enable POSIX directory rename behaviour
348               for OS X clients. Without this, directories can't be
349               renamed if any client has any file inside it
350               (recursive!) open.</para>
351               <para>The default is <emphasis>yes</emphasis>.</para>
352             </listitem>
353           </varlistentry>
354
355           <varlistentry>
356             <term>readdir_attr:aapl_rsize = yes | no</term>
357             <listitem>
358               <para>Return resource fork size in SMB2 FIND responses.</para>
359               <para>The default is <emphasis>yes</emphasis>.</para>
360             </listitem>
361           </varlistentry>
362
363           <varlistentry>
364             <term>readdir_attr:aapl_finder_info = yes | no</term>
365             <listitem>
366               <para>Return FinderInfo in SMB2 FIND responses.</para>
367               <para>The default is <emphasis>yes</emphasis>.</para>
368             </listitem>
369           </varlistentry>
370
371           <varlistentry>
372             <term>readdir_attr:aapl_max_access = yes | no</term>
373             <listitem>
374               <para>Return the user's effective maximum permissions in SMB2 FIND
375               responses. This is an expensive computation, setting this to off
376               pretends the use has maximum effective permissions.</para>
377               <para>The default is <emphasis>yes</emphasis>.</para>
378             </listitem>
379           </varlistentry>
380
381         </variablelist>
382 </refsect1>
383
384 <refsect1>
385         <title>EXAMPLES</title>
386
387 <programlisting>
388         <smbconfsection name="[share]"/>
389         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
390         <smbconfoption name="fruit:resource">file</smbconfoption>
391         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
392         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
393         <smbconfoption name="fruit:encoding">native</smbconfoption>
394 </programlisting>
395
396 </refsect1>
397
398 <refsect1>
399         <title>AUTHOR</title>
400
401         <para>The original Samba software and related utilities
402         were created by Andrew Tridgell. Samba is now developed
403         by the Samba Team as an Open Source project similar
404         to the way the Linux kernel is developed.</para>
405
406 </refsect1>
407
408 </refentry>