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>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 then 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 individuallly 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         </variablelist>
 164 </refsect1>
 165
 166 <refsect1>
 167         <title>OPTIONS</title>
 168
 169         <para>The following options can be set either in the global smb.conf section
 170         or per share.</para>
 171
 172         <variablelist>
 173
 174           <varlistentry>
 175             <term>fruit:resource = [ file | xattr | stream ]</term>
 176             <listitem>
 177               <para>Controls where the OS X resource fork is stored.</para>
 178
 179               <para>Due to a spelling bug in all Samba versions older then
 180               4.6.0, this option can also be given as
 181               <emphasis>fruit:ressource</emphasis>, ie with two s.</para>
 182
 183               <para>Settings:</para>
 184
 185               <itemizedlist>
 186                 <listitem><para><command>file (default)</command> - use a ._
 187                 AppleDouble file compatible with OS X and
 188                 Netatalk</para></listitem>
 189
 190                 <listitem><para><command>xattr</command> - use a
 191                 xattr, requires a filesystem with large xattr support
 192                 and a file IO API compatible with xattrs, this boils
 193                 down to Solaris and derived platforms and
 194                 ZFS</para></listitem>
 195
 196                 <listitem><para><command>stream (experimental)</command> - pass
 197                 the stream on to the next module in the VFS stack.
 198                 <emphasis>Warning: </emphasis> this option should not be used
 199                 with the <emphasis>streams_xattr</emphasis> module due to the
 200                 extended attributes size limitations of most
 201                 filesytems.</para></listitem>
 202               </itemizedlist>
 203
 204             </listitem>
 205           </varlistentry>
 206
 207           <varlistentry>
 208             <term>fruit:metadata = [ stream | netatalk ]</term>
 209             <listitem>
 210               <para>Controls where the OS X metadata stream is stored:</para>
 211
 212               <itemizedlist>
 213                 <listitem><para><command>netatalk (default)</command> - use
 214                 Netatalk compatible xattr</para></listitem>
 215
 216                 <listitem><para><command>stream</command> - pass the
 217                 stream on to the next module in the VFS
 218                 stack</para></listitem>
 219               </itemizedlist>
 220
 221             </listitem>
 222           </varlistentry>
 223
 224           <varlistentry>
 225             <term>fruit:locking = [ netatalk | none ]</term>
 226             <listitem>
 227               <para></para>
 228               <itemizedlist>
 229                 <listitem><para><command>none (default)</command> - no
 230                 cross protocol locking</para></listitem>
 231
 232                 <listitem><para><command>netatalk</command> - use
 233                 cross protocol locking with Netatalk</para></listitem>
 234
 235               </itemizedlist>
 236             </listitem>
 237           </varlistentry>
 238
 239           <varlistentry>
 240             <term>fruit:encoding = [ native | private ]</term>
 241             <listitem>
 242
 243               <para>Controls how the set of illegal NTFS ASCII
 244               character, commonly used by OS X clients, are stored in
 245               the filesystem.</para>
 246
 247               <para><emphasis>Important:</emphasis> this is known to not fully
 248               work with <emphasis>fruit:metadata=stream</emphasis> or
 249               <emphasis>fruit:resource=stream</emphasis>.</para>
 250
 251               <itemizedlist>
 252
 253                 <listitem><para><command>private (default)</command> -
 254                 store characters as encoded by the OS X client: mapped
 255                 to the Unicode private range</para></listitem>
 256
 257                 <listitem><para><command>native</command> - store
 258                 characters with their native ASCII
 259                 value. <emphasis>Important</emphasis>: this option
 260                 requires the use of <emphasis>vfs_catia</emphasis> in
 261                 the VFS module stack as shown in the examples
 262                 section.</para></listitem>
 263
 264               </itemizedlist>
 265             </listitem>
 266           </varlistentry>
 267
 268           <varlistentry>
 269             <term>fruit:veto_appledouble = yes | no</term>
 270             <listitem>
 271               <para><emphasis>Note:</emphasis> this option only applies when
 272               <parameter>fruit:resource</parameter> is set to
 273               <parameter>file</parameter> (the default).</para>
 274
 275               <para>When <parameter>fruit:resource</parameter> is set to
 276               <parameter>file</parameter>, vfs_fruit may create ._ AppleDouble
 277               files. This options controls whether these ._ AppleDouble files
 278               are vetoed which prevents the client from accessing them.</para>
 279               <para>Vetoing ._ files may break some applications, eg
 280               extracting Mac ZIP archives from Mac clients failes,
 281               because they contain ._ files. Setting this option to
 282               false will fix this, but the abstraction leak of
 283               exposing the internally created ._ files may have other
 284               unknown side effects.</para>
 285               <para>The default is <emphasis>yes</emphasis>.</para>
 286             </listitem>
 287           </varlistentry>
 288
 289           <varlistentry>
 290             <term>fruit:posix_rename = yes | no</term>
 291             <listitem>
 292               <para>Whether to enable POSIX directory rename behaviour
 293               for OS X clients. Without this, directories can't be
 294               renamed if any client has any file inside it
 295               (recursive!) open.</para>
 296               <para>The default is <emphasis>yes</emphasis>.</para>
 297             </listitem>
 298           </varlistentry>
 299
 300           <varlistentry>
 301             <term>readdir_attr:aapl_rsize = yes | no</term>
 302             <listitem>
 303               <para>Return resource fork size in SMB2 FIND responses.</para>
 304               <para>The default is <emphasis>yes</emphasis>.</para>
 305             </listitem>
 306           </varlistentry>
 307
 308           <varlistentry>
 309             <term>readdir_attr:aapl_finder_info = yes | no</term>
 310             <listitem>
 311               <para>Return FinderInfo in SMB2 FIND responses.</para>
 312               <para>The default is <emphasis>yes</emphasis>.</para>
 313             </listitem>
 314           </varlistentry>
 315
 316           <varlistentry>
 317             <term>readdir_attr:aapl_max_access = yes | no</term>
 318             <listitem>
 319               <para>Return the user's effective maximum permissions in SMB2 FIND
 320               responses. This is an expensive computation, setting this to off
 321               pretends the use has maximum effective permissions.</para>
 322               <para>The default is <emphasis>yes</emphasis>.</para>
 323             </listitem>
 324           </varlistentry>
 325
 326         </variablelist>
 327 </refsect1>
 328
 329 <refsect1>
 330         <title>EXAMPLES</title>
 331
 332 <programlisting>
 333         <smbconfsection name="[share]"/>
 334         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 335         <smbconfoption name="fruit:resource">file</smbconfoption>
 336         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 337         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 338         <smbconfoption name="fruit:encoding">native</smbconfoption>
 339 </programlisting>
 340
 341 </refsect1>
 342
 343 <refsect1>
 344         <title>AUTHOR</title>
 345
 346         <para>The original Samba software and related utilities
 347         were created by Andrew Tridgell. Samba is now developed
 348         by the Samba Team as an Open Source project similar
 349         to the way the Linux kernel is developed.</para>
 350
 351 </refsect1>
 352
 353 </refentry>