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:model = MacSamba</term>
 148             <listitem>
 149               <para>This option defines the model string inside the AAPL
 150               extension and will determine the appearance of the icon representing the
 151               Samba server in the Finder window.</para>
 152               <para>The default is <emphasis>MacSamba</emphasis>.</para>
 153             </listitem>
 154           </varlistentry>
 155         </variablelist>
 156 </refsect1>
 157
 158 <refsect1>
 159         <title>OPTIONS</title>
 160
 161         <para>The following options can be set either in the global smb.conf section
 162         or per share.</para>
 163
 164         <variablelist>
 165
 166           <varlistentry>
 167             <term>fruit:resource = [ file | xattr | stream ]</term>
 168             <listitem>
 169               <para>Controls where the OS X resource fork is stored.</para>
 170
 171               <para>Due to a spelling bug in all Samba versions older than
 172               4.6.0, this option can also be given as
 173               <emphasis>fruit:ressource</emphasis>, ie with two s.</para>
 174
 175               <para>Settings:</para>
 176
 177               <itemizedlist>
 178                 <listitem><para><command>file (default)</command> - use a ._
 179                 AppleDouble file compatible with OS X and
 180                 Netatalk</para></listitem>
 181
 182                 <listitem><para><command>xattr</command> - use a
 183                 xattr, requires a filesystem with large xattr support
 184                 and a file IO API compatible with xattrs, this boils
 185                 down to Solaris and derived platforms and
 186                 ZFS</para></listitem>
 187
 188                 <listitem><para><command>stream (experimental)</command> - pass
 189                 the stream on to the next module in the VFS stack.
 190                 <emphasis>Warning: </emphasis> this option should not be used
 191                 with the <emphasis>streams_xattr</emphasis> module due to the
 192                 extended attributes size limitations of most
 193                 filesystems.</para></listitem>
 194               </itemizedlist>
 195
 196             </listitem>
 197           </varlistentry>
 198
 199           <varlistentry>
 200             <term>fruit:time machine = [ yes | no ]</term>
 201             <listitem>
 202               <para>Controls if Time Machine support via the FULLSYNC volume
 203               capability is advertised to clients.</para>
 204
 205               <itemizedlist>
 206                 <listitem><para><command>yes</command> - Enables Time Machine
 207                 support for this share. Also registers the share with mDNS in
 208                 case Samba is built with mDNS support.</para></listitem>
 209
 210                 <listitem><para><command>no (default)</command> Disables
 211                 advertising Time Machine support.</para></listitem>
 212
 213               </itemizedlist>
 214
 215               <para>This option enforces the following settings per share (or
 216               for all shares if enabled globally):</para>
 217               <itemizedlist>
 218                 <listitem><para><command>durable handles = yes</command></para></listitem>
 219                 <listitem><para><command>kernel oplocks = no</command></para></listitem>
 220                 <listitem><para><command>kernel share modes = no</command></para></listitem>
 221                 <listitem><para><command>posix locking = no</command></para></listitem>
 222               </itemizedlist>
 223
 224             </listitem>
 225           </varlistentry>
 226
 227           <varlistentry>
 228             <term>fruit:time machine max size = SIZE [K|M|G|T|P]</term>
 229             <listitem>
 230               <para>Useful for Time Machine: limits the reported disksize, thus
 231               preventing Time Machine from using the whole real disk space for
 232               backup. The option takes a number plus an optional unit.</para>
 233               <para><emphasis>IMPORTANT</emphasis>: This is an approximated
 234               calculation that only takes into account the contents of Time
 235               Machine sparsebundle images. Therefore you <emphasis>MUST
 236               NOT</emphasis> use this volume to store other content when using
 237               this option, because it would NOT be accounted.</para>
 238               <para>The calculation works by reading the band size from the
 239               Info.plist XML file of the sparsebundle, reading the bands/
 240               directory counting the number of band files, and then multiplying
 241               one with the other.</para>
 242             </listitem>
 243           </varlistentry>
 244
 245           <varlistentry>
 246             <term>fruit:metadata = [ stream | netatalk ]</term>
 247             <listitem>
 248               <para>Controls where the OS X metadata stream is stored:</para>
 249
 250               <itemizedlist>
 251                 <listitem><para><command>netatalk (default)</command> - use
 252                 Netatalk compatible xattr</para></listitem>
 253
 254                 <listitem><para><command>stream</command> - pass the
 255                 stream on to the next module in the VFS
 256                 stack</para></listitem>
 257               </itemizedlist>
 258
 259             </listitem>
 260           </varlistentry>
 261
 262           <varlistentry>
 263             <term>fruit:locking = [ netatalk | none ]</term>
 264             <listitem>
 265               <para></para>
 266               <itemizedlist>
 267                 <listitem><para><command>none (default)</command> - no
 268                 cross protocol locking</para></listitem>
 269
 270                 <listitem><para><command>netatalk</command> - use
 271                 cross protocol locking with Netatalk</para></listitem>
 272
 273               </itemizedlist>
 274             </listitem>
 275           </varlistentry>
 276
 277           <varlistentry>
 278             <term>fruit:encoding = [ native | private ]</term>
 279             <listitem>
 280
 281               <para>Controls how the set of illegal NTFS ASCII
 282               character, commonly used by OS X clients, are stored in
 283               the filesystem.</para>
 284
 285               <para><emphasis>Important:</emphasis> this is known to not fully
 286               work with <emphasis>fruit:metadata=stream</emphasis> or
 287               <emphasis>fruit:resource=stream</emphasis>.</para>
 288
 289               <itemizedlist>
 290
 291                 <listitem><para><command>private (default)</command> -
 292                 store characters as encoded by the OS X client: mapped
 293                 to the Unicode private range</para></listitem>
 294
 295                 <listitem><para><command>native</command> - store
 296                 characters with their native ASCII
 297                 value. <emphasis>Important</emphasis>: this option
 298                 requires the use of <emphasis>vfs_catia</emphasis> in
 299                 the VFS module stack as shown in the examples
 300                 section.</para></listitem>
 301
 302               </itemizedlist>
 303             </listitem>
 304           </varlistentry>
 305
 306           <varlistentry>
 307             <term>fruit:veto_appledouble = yes | no</term>
 308             <listitem>
 309               <para><emphasis>Note:</emphasis> this option only applies when
 310               <parameter>fruit:resource</parameter> is set to
 311               <parameter>file</parameter> (the default).</para>
 312
 313               <para>When <parameter>fruit:resource</parameter> is set to
 314               <parameter>file</parameter>, vfs_fruit may create ._ AppleDouble
 315               files. This options controls whether these ._ AppleDouble files
 316               are vetoed which prevents the client from accessing them.</para>
 317               <para>Vetoing ._ files may break some applications, e.g.
 318               extracting Mac ZIP archives from Mac clients fails,
 319               because they contain ._ files. <command>rsync</command> will
 320               also be unable to sync files beginning with underscores, as
 321               the temporary files it uses for these will start with ._ and
 322               so cannot be created.</para>
 323               <para>Setting this option to
 324               false will fix this, but the abstraction leak of
 325               exposing the internally created ._ files may have other
 326               unknown side effects.</para>
 327               <para>The default is <emphasis>yes</emphasis>.</para>
 328             </listitem>
 329           </varlistentry>
 330
 331           <varlistentry>
 332             <term>readdir_attr:aapl_rsize = yes | no</term>
 333             <listitem>
 334               <para>Return resource fork size in SMB2 FIND responses.</para>
 335               <para>The default is <emphasis>yes</emphasis>.</para>
 336             </listitem>
 337           </varlistentry>
 338
 339           <varlistentry>
 340             <term>readdir_attr:aapl_finder_info = yes | no</term>
 341             <listitem>
 342               <para>Return FinderInfo in SMB2 FIND responses.</para>
 343               <para>The default is <emphasis>yes</emphasis>.</para>
 344             </listitem>
 345           </varlistentry>
 346
 347           <varlistentry>
 348             <term>readdir_attr:aapl_max_access = yes | no</term>
 349             <listitem>
 350               <para>Return the user's effective maximum permissions in SMB2 FIND
 351               responses. This is an expensive computation, setting this to off
 352               pretends the use has maximum effective permissions.</para>
 353               <para>The default is <emphasis>yes</emphasis>.</para>
 354             </listitem>
 355           </varlistentry>
 356
 357           <varlistentry>
 358             <term>fruit:wipe_intentionally_left_blank_rfork = yes | no</term>
 359             <listitem>
 360               <para>Whether to wipe Resource Fork data that matches the special
 361               286 bytes sized placeholder blob that macOS client create on
 362               occasion. The blob contains a string <quote>This resource fork
 363               intentionally left blank</quote>, the remaining bytes being mostly
 364               zero. There being no one use of this data, it is probably safe to
 365               discard it. When this option is enabled, this module truncates the
 366               Resource Fork stream to 0 bytes.</para>
 367               <para>The default is <emphasis>no</emphasis>.</para>
 368             </listitem>
 369           </varlistentry>
 370
 371           <varlistentry>
 372             <term>fruit:delete_empty_adfiles = yes | no</term>
 373             <listitem>
 374               <para>Whether to delete empty AppleDouble files. Empty means that
 375               the resource fork entry in the AppleDouble files is of size 0, or
 376               the size is exactly 286 bytes and the content matches a special
 377               boilerplate resource fork created my macOS.</para>
 378               <para>The default is <emphasis>no</emphasis>.</para>
 379             </listitem>
 380           </varlistentry>
 381
 382           <varlistentry>
 383             <term>fruit:zero_file_id = yes | no</term>
 384             <listitem>
 385               <para>Whether to return zero to queries of on-disk file
 386               identifier if the client has negotiated AAPL.</para>
 387               <para>Mac applications and / or the Mac SMB client code expect the
 388               on-disk file identifier to have the semantics of HFS+ Catalog Node
 389               Identifier (CNID). Samba provides File-IDs based on a file's inode
 390               number which gets recycled across file creation and deletion and
 391               can therefore not be used for Mac client. Returning a file identifier of
 392               zero causes the Mac client to stop using and trusting the file id
 393               returned from the server.</para>
 394               <para>The default is <emphasis>yes</emphasis>.</para>
 395             </listitem>
 396           </varlistentry>
 397
 398           <varlistentry>
 399             <term>fruit:convert_adouble = yes | no</term>
 400             <listitem>
 401               <para>Whether an attempt shall be made to convert ._ AppleDouble
 402               sidecar files to native streams (xattrs when using
 403               vfs_streams_xattr). The main use case for this conversion is
 404               transparent migration from a server config without streams support
 405               where the macOS client created those AppleDouble sidecar
 406               files.</para>
 407               <para>The default is <emphasis>yes</emphasis>.</para>
 408             </listitem>
 409           </varlistentry>
 410
 411           <varlistentry>
 412             <term>fruit:validate_afpinfo = yes | no</term>
 413             <listitem>
 414               <para>Apple clients use the AFP_AfpInfo stream to store structured
 415               file metadata. As part of the marshaled data stored in the stream
 416               the first eight bytes contain some header information. Apple's SMB
 417               server as well as Samba will validate this header bytes processing
 418               a client write request on this stream, and, if the validation
 419               fails, fail the write. While this validation is generally correct,
 420               in some data migration scenarios clients may try to migrate data
 421               from 3rd-party SMB servers to Samba servers where the header
 422               information is broken for whatever reason. To allow migration and
 423               header fix-up in these scenarios, the validation can be temporarily
 424               disabled by setting this option to <emphasis>no</emphasis>.</para>
 425               <para>The default is <emphasis>yes</emphasis>.</para>
 426             </listitem>
 427           </varlistentry>
 428
 429         </variablelist>
 430 </refsect1>
 431
 432 <refsect1>
 433         <title>EXAMPLES</title>
 434
 435 <programlisting>
 436         <smbconfsection name="[share]"/>
 437         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 438         <smbconfoption name="fruit:resource">file</smbconfoption>
 439         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 440         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 441         <smbconfoption name="fruit:encoding">native</smbconfoption>
 442 </programlisting>
 443
 444 </refsect1>
 445
 446 <refsect1>
 447         <title>AUTHOR</title>
 448
 449         <para>The original Samba software and related utilities
 450         were created by Andrew Tridgell. Samba is now developed
 451         by the Samba Team as an Open Source project similar
 452         to the way the Linux kernel is developed.</para>
 453
 454 </refsect1>
 455
 456 </refentry>