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>vfs_fruit requires "ea support = yes".</para>
  49
  50         <para>Be careful when mixing shares with and without
  51         vfs_fruit. OS X clients negotiate SMB2 AAPL protocol
  52         extensions on the first tcon, so mixing shares with and
  53         without fruit will globally disable AAPL if the first tcon is
  54         without fruit.</para>
  55
  56         <para>Having shares with ADS support enabled for OS X client
  57         is worthwhile because it resembles the behaviour of Apple's
  58         own SMB server implementation and it avoids certain severe
  59         performance degradations caused by Samba's case sensitivity
  60         semantics.</para>
  61
  62         <para>The OS X metadata and resource fork stream can be stored
  63         in a way compatible with Netatalk 3 by setting
  64         <command>fruit:resource = file</command> and
  65         <command>fruit:metadata = netatalk</command>.</para>
  66
  67         <para>OS X maps NTFS illegal characters to the Unicode private
  68         range in SMB requests. By setting <command>fruit:encoding =
  69         native</command>, all mapped characters are converted to
  70         native ASCII characters.</para>
  71
  72         <para>Finally, share access modes are optionally checked
  73         against Netatalk AFP sharing modes by setting
  74         <command>fruit:locking = netatalk</command>.</para>
  75
  76         <para>This module is not stackable other then described in
  77         this manpage.</para>
  78
  79 </refsect1>
  80
  81 <refsect1>
  82         <title>OPTIONS</title>
  83
  84         <variablelist>
  85
  86           <varlistentry>
  87             <term>fruit:resource = [ file | xattr | stream ]</term>
  88             <listitem>
  89               <para>Controls where the OS X resource fork is stored.</para>
  90
  91               <para>Due to a spelling bug in all Samba versions older then
  92               4.6.0, this option can also be given as
  93               <emphasis>fruit:ressource</emphasis>, ie with two s.</para>
  94
  95               <para>Settings:</para>
  96
  97               <itemizedlist>
  98                 <listitem><para><command>file (default)</command> - use a ._
  99                 AppleDouble file compatible with OS X and
 100                 Netatalk</para></listitem>
 101
 102                 <listitem><para><command>xattr</command> - use a
 103                 xattr, requires a filesystem with large xattr support
 104                 and a file IO API compatible with xattrs, this boils
 105                 down to Solaris and derived platforms and
 106                 ZFS</para></listitem>
 107
 108                 <listitem><para><command>stream (experimental)</command> - pass
 109                 the stream on to the next module in the VFS stack.
 110                 <emphasis>Warning: </emphasis> this option should not be used
 111                 with the <emphasis>streams_xattr</emphasis> module due to the
 112                 extended attributes size limitations of most
 113                 filesytems.</para></listitem>
 114               </itemizedlist>
 115
 116             </listitem>
 117           </varlistentry>
 118
 119           <varlistentry>
 120             <term>fruit:metadata = [ stream | netatalk ]</term>
 121             <listitem>
 122               <para>Controls where the OS X metadata stream is stored:</para>
 123
 124               <itemizedlist>
 125                 <listitem><para><command>netatalk (default)</command> - use
 126                 Netatalk compatible xattr</para></listitem>
 127
 128                 <listitem><para><command>stream</command> - pass the
 129                 stream on to the next module in the VFS
 130                 stack</para></listitem>
 131               </itemizedlist>
 132
 133             </listitem>
 134           </varlistentry>
 135
 136           <varlistentry>
 137             <term>fruit:locking = [ netatalk | none ]</term>
 138             <listitem>
 139               <para></para>
 140               <itemizedlist>
 141                 <listitem><para><command>none (default)</command> - no
 142                 cross protocol locking</para></listitem>
 143
 144                 <listitem><para><command>netatalk</command> - use
 145                 cross protocol locking with Netatalk</para></listitem>
 146
 147               </itemizedlist>
 148             </listitem>
 149           </varlistentry>
 150
 151           <varlistentry>
 152             <term>fruit:encoding = [ native | private ]</term>
 153             <listitem>
 154
 155               <para>Controls how the set of illegal NTFS ASCII
 156               character, commonly used by OS X clients, are stored in
 157               the filesystem:</para>
 158
 159               <itemizedlist>
 160
 161                 <listitem><para><command>private (default)</command> -
 162                 store characters as encoded by the OS X client: mapped
 163                 to the Unicode private range</para></listitem>
 164
 165                 <listitem><para><command>native</command> - store
 166                 characters with their native ASCII
 167                 value. <emphasis>Important</emphasis>: this option
 168                 requires the use of <emphasis>vfs_catia</emphasis> in
 169                 the VFS module stack as shown in the examples
 170                 section.</para></listitem>
 171
 172               </itemizedlist>
 173             </listitem>
 174           </varlistentry>
 175
 176           <varlistentry>
 177             <term>fruit:aapl = yes | no</term>
 178             <listitem>
 179               <para>A global option whether to enable Apple's SMB2+
 180               extension codenamed AAPL. Default
 181               <emphasis>yes</emphasis>. This extension enhances
 182               several deficiencies when connecting from Macs:</para>
 183
 184               <itemizedlist>
 185                 <listitem><para>directory enumeration is enriched with
 186                 Mac relevant filesystem metadata (UNIX mode,
 187                 FinderInfo, resource fork size and effective
 188                 permission), as a result the Mac client doesn't need
 189                 to fetch this metadata individuallly per directory
 190                 entry resulting in an often tremendous performance
 191                 increase.</para></listitem>
 192
 193                 <listitem><para>The ability to query and modify the
 194                 UNIX mode of directory entries.</para></listitem>
 195               </itemizedlist>
 196
 197               <para>There's a set of per share options that can be
 198               used to disable the computation of specific Mac metadata
 199               in the directory enumeration context, all are enabled by
 200               default:</para>
 201
 202               <itemizedlist>
 203                 <listitem><para>readdir_attr:aapl_rsize = true | false</para></listitem>
 204                 <listitem><para>readdir_attr:aapl_finder_info = true | false</para></listitem>
 205                 <listitem><para>readdir_attr:aapl_max_access = true | false</para></listitem>
 206               </itemizedlist>
 207
 208             </listitem>
 209           </varlistentry>
 210
 211           <varlistentry>
 212             <term>fruit:nfs_aces = yes | no</term>
 213             <listitem>
 214               <para>Whether support for querying and modifying the
 215               UNIX mode of directory entries via NFS ACEs is enabled,
 216               default <emphasis>yes</emphasis>.</para>
 217             </listitem>
 218           </varlistentry>
 219
 220           <varlistentry>
 221             <term>fruit:veto_appledouble = yes | no</term>
 222             <listitem>
 223               <para>Whether ._ AppleDouble files are vetoed which
 224               prevents the client from seing and accessing internal
 225               AppleDouble files created by vfs_fruit itself for the
 226               purpose of storing a Mac resource fork.</para>
 227               <para>Vetoing ._ files may break some applications, eg
 228               extracting Mac ZIP archives from Mac clients failes,
 229               because they contain ._ files. Setting this option to
 230               false will fix this, but the abstraction leak of
 231               exposing the internally created ._ files may have other
 232               unknown side effects.</para>
 233               <para>The default is <emphasis>yes</emphasis>.</para>
 234             </listitem>
 235           </varlistentry>
 236
 237           <varlistentry>
 238             <term>fruit:copyfile = yes | no</term>
 239             <listitem>
 240               <para>Whether to enable OS X specific copychunk ioctl
 241               that requests a copy of a whole file along with all
 242               attached metadata.</para>
 243               <para>WARNING: the copyfile request is blocking the
 244               client while the server does the copy.</para>.
 245               <para>The default is <emphasis>no</emphasis>.</para>
 246             </listitem>
 247           </varlistentry>
 248
 249           <varlistentry>
 250             <term>fruit:posix_rename = yes | no</term>
 251             <listitem>
 252               <para>Whether to enable POSIX directory rename behaviour
 253               for OS X clients. Without this, directories can't be
 254               renamed if any client has any file inside it
 255               (recursive!) open.</para>
 256               <para>The default is <emphasis>yes</emphasis>.</para>
 257             </listitem>
 258           </varlistentry>
 259
 260         </variablelist>
 261 </refsect1>
 262
 263 <refsect1>
 264         <title>EXAMPLES</title>
 265
 266 <programlisting>
 267         <smbconfsection name="[share]"/>
 268         <smbconfoption name="ea support">yes</smbconfoption>
 269         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 270         <smbconfoption name="fruit:resource">file</smbconfoption>
 271         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 272         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 273         <smbconfoption name="fruit:encoding">native</smbconfoption>
 274 </programlisting>
 275
 276 </refsect1>
 277
 278 <refsect1>
 279         <title>AUTHOR</title>
 280
 281         <para>The original Samba software and related utilities
 282         were created by Andrew Tridgell. Samba is now developed
 283         by the Samba Team as an Open Source project similar
 284         to the way the Linux kernel is developed.</para>
 285
 286 </refsect1>
 287
 288 </refentry>