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:metadata = [ stream | netatalk ]</term>
 246             <listitem>
 247               <para>Controls where the OS X metadata stream is stored:</para>
 248
 249               <itemizedlist>
 250                 <listitem><para><command>netatalk (default)</command> - use
 251                 Netatalk compatible xattr</para></listitem>
 252
 253                 <listitem><para><command>stream</command> - pass the
 254                 stream on to the next module in the VFS
 255                 stack</para></listitem>
 256               </itemizedlist>
 257
 258             </listitem>
 259           </varlistentry>
 260
 261           <varlistentry>
 262             <term>fruit:locking = [ netatalk | none ]</term>
 263             <listitem>
 264               <para></para>
 265               <itemizedlist>
 266                 <listitem><para><command>none (default)</command> - no
 267                 cross protocol locking</para></listitem>
 268
 269                 <listitem><para><command>netatalk</command> - use
 270                 cross protocol locking with Netatalk</para></listitem>
 271
 272               </itemizedlist>
 273             </listitem>
 274           </varlistentry>
 275
 276           <varlistentry>
 277             <term>fruit:encoding = [ native | private ]</term>
 278             <listitem>
 279
 280               <para>Controls how the set of illegal NTFS ASCII
 281               character, commonly used by OS X clients, are stored in
 282               the filesystem.</para>
 283
 284               <para><emphasis>Important:</emphasis> this is known to not fully
 285               work with <emphasis>fruit:metadata=stream</emphasis> or
 286               <emphasis>fruit:resource=stream</emphasis>.</para>
 287
 288               <itemizedlist>
 289
 290                 <listitem><para><command>private (default)</command> -
 291                 store characters as encoded by the OS X client: mapped
 292                 to the Unicode private range</para></listitem>
 293
 294                 <listitem><para><command>native</command> - store
 295                 characters with their native ASCII
 296                 value. <emphasis>Important</emphasis>: this option
 297                 requires the use of <emphasis>vfs_catia</emphasis> in
 298                 the VFS module stack as shown in the examples
 299                 section.</para></listitem>
 300
 301               </itemizedlist>
 302             </listitem>
 303           </varlistentry>
 304
 305           <varlistentry>
 306             <term>fruit:veto_appledouble = yes | no</term>
 307             <listitem>
 308               <para><emphasis>Note:</emphasis> this option only applies when
 309               <parameter>fruit:resource</parameter> is set to
 310               <parameter>file</parameter> (the default).</para>
 311
 312               <para>When <parameter>fruit:resource</parameter> is set to
 313               <parameter>file</parameter>, vfs_fruit may create ._ AppleDouble
 314               files. This options controls whether these ._ AppleDouble files
 315               are vetoed which prevents the client from accessing them.</para>
 316               <para>Vetoing ._ files may break some applications, eg
 317               extracting Mac ZIP archives from Mac clients failes,
 318               because they contain ._ files. Setting this option to
 319               false will fix this, but the abstraction leak of
 320               exposing the internally created ._ files may have other
 321               unknown side effects.</para>
 322               <para>The default is <emphasis>yes</emphasis>.</para>
 323             </listitem>
 324           </varlistentry>
 325
 326           <varlistentry>
 327             <term>fruit:posix_rename = yes | no</term>
 328             <listitem>
 329               <para>Whether to enable POSIX directory rename behaviour
 330               for OS X clients. Without this, directories can't be
 331               renamed if any client has any file inside it
 332               (recursive!) open.</para>
 333               <para>The default is <emphasis>yes</emphasis>.</para>
 334             </listitem>
 335           </varlistentry>
 336
 337           <varlistentry>
 338             <term>readdir_attr:aapl_rsize = yes | no</term>
 339             <listitem>
 340               <para>Return resource fork size in SMB2 FIND responses.</para>
 341               <para>The default is <emphasis>yes</emphasis>.</para>
 342             </listitem>
 343           </varlistentry>
 344
 345           <varlistentry>
 346             <term>readdir_attr:aapl_finder_info = yes | no</term>
 347             <listitem>
 348               <para>Return FinderInfo in SMB2 FIND responses.</para>
 349               <para>The default is <emphasis>yes</emphasis>.</para>
 350             </listitem>
 351           </varlistentry>
 352
 353           <varlistentry>
 354             <term>readdir_attr:aapl_max_access = yes | no</term>
 355             <listitem>
 356               <para>Return the user's effective maximum permissions in SMB2 FIND
 357               responses. This is an expensive computation, setting this to off
 358               pretends the use has maximum effective permissions.</para>
 359               <para>The default is <emphasis>yes</emphasis>.</para>
 360             </listitem>
 361           </varlistentry>
 362
 363         </variablelist>
 364 </refsect1>
 365
 366 <refsect1>
 367         <title>EXAMPLES</title>
 368
 369 <programlisting>
 370         <smbconfsection name="[share]"/>
 371         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 372         <smbconfoption name="fruit:resource">file</smbconfoption>
 373         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 374         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 375         <smbconfoption name="fruit:encoding">native</smbconfoption>
 376 </programlisting>
 377
 378 </refsect1>
 379
 380 <refsect1>
 381         <title>AUTHOR</title>
 382
 383         <para>The original Samba software and related utilities
 384         were created by Andrew Tridgell. Samba is now developed
 385         by the Samba Team as an Open Source project similar
 386         to the way the Linux kernel is developed.</para>
 387
 388 </refsect1>
 389
 390 </refentry>