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 options, 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, e.g.
 335               extracting Mac ZIP archives from Mac clients fails,
 336               because they contain ._ files. <command>rsync</command> will
 337               also be unable to sync files beginning with underscores, as
 338               the temporary files it uses for these will start with ._ and
 339               so cannot be created.</para>
 340               <para>Setting this option to
 341               false will fix this, but the abstraction leak of
 342               exposing the internally created ._ files may have other
 343               unknown side effects.</para>
 344               <para>The default is <emphasis>yes</emphasis>.</para>
 345             </listitem>
 346           </varlistentry>
 347
 348           <varlistentry>
 349             <term>fruit:posix_rename = yes | no</term>
 350             <listitem>
 351               <para>Whether to enable POSIX directory rename behaviour
 352               for OS X clients. Without this, directories can't be
 353               renamed if any client has any file inside it
 354               (recursive!) open.</para>
 355               <para>The default is <emphasis>yes</emphasis>.</para>
 356             </listitem>
 357           </varlistentry>
 358
 359           <varlistentry>
 360             <term>readdir_attr:aapl_rsize = yes | no</term>
 361             <listitem>
 362               <para>Return resource fork size in SMB2 FIND responses.</para>
 363               <para>The default is <emphasis>yes</emphasis>.</para>
 364             </listitem>
 365           </varlistentry>
 366
 367           <varlistentry>
 368             <term>readdir_attr:aapl_finder_info = yes | no</term>
 369             <listitem>
 370               <para>Return FinderInfo in SMB2 FIND responses.</para>
 371               <para>The default is <emphasis>yes</emphasis>.</para>
 372             </listitem>
 373           </varlistentry>
 374
 375           <varlistentry>
 376             <term>readdir_attr:aapl_max_access = yes | no</term>
 377             <listitem>
 378               <para>Return the user's effective maximum permissions in SMB2 FIND
 379               responses. This is an expensive computation, setting this to off
 380               pretends the use has maximum effective permissions.</para>
 381               <para>The default is <emphasis>yes</emphasis>.</para>
 382             </listitem>
 383           </varlistentry>
 384
 385           <varlistentry>
 386             <term>fruit:wipe_intentionally_left_blank_rfork = yes | no</term>
 387             <listitem>
 388               <para>Whether to wipe Resource Fork data that matches the special
 389               286 bytes sized placeholder blob that macOS client create on
 390               occasion. The blob contains a string <quote>This resource fork
 391               intentionally left blank</quote>, the remaining bytes being mostly
 392               zero. There being no one use of this data, it is probably safe to
 393               discard it. When this option is enabled, this module truncates the
 394               Resource Fork stream to 0 bytes.</para>
 395               <para>The default is <emphasis>no</emphasis>.</para>
 396             </listitem>
 397           </varlistentry>
 398
 399           <varlistentry>
 400             <term>fruit:delete_empty_adfiles = yes | no</term>
 401             <listitem>
 402               <para>Whether to delete empty AppleDouble files. Empty means that
 403               the resource fork entry in the AppleDouble files is of size 0, or
 404               the size is exactly 286 bytes and the content matches a special
 405               boilerplate resource fork created my macOS.</para>
 406               <para>The default is <emphasis>no</emphasis>.</para>
 407             </listitem>
 408           </varlistentry>
 409
 410         </variablelist>
 411 </refsect1>
 412
 413 <refsect1>
 414         <title>EXAMPLES</title>
 415
 416 <programlisting>
 417         <smbconfsection name="[share]"/>
 418         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 419         <smbconfoption name="fruit:resource">file</smbconfoption>
 420         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 421         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 422         <smbconfoption name="fruit:encoding">native</smbconfoption>
 423 </programlisting>
 424
 425 </refsect1>
 426
 427 <refsect1>
 428         <title>AUTHOR</title>
 429
 430         <para>The original Samba software and related utilities
 431         were created by Andrew Tridgell. Samba is now developed
 432         by the Samba Team as an Open Source project similar
 433         to the way the Linux kernel is developed.</para>
 434
 435 </refsect1>
 436
 437 </refentry>