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.4</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               <itemizedlist>
  92                 <listitem><para><command>file (default)</command> - use a ._
  93                 AppleDouble file compatible with OS X and
  94                 Netatalk</para></listitem>
  95
  96                 <listitem><para><command>xattr</command> - use a
  97                 xattr, requires a filesystem with large xattr support
  98                 and a file IO API compatible with xattrs, this boils
  99                 down to Solaris and derived platforms and
 100                 ZFS</para></listitem>
 101
 102                 <listitem><para><command>stream</command> - pass the
 103                 stream on to the next module in the VFS
 104                 stack</para></listitem>
 105               </itemizedlist>
 106
 107             </listitem>
 108           </varlistentry>
 109
 110           <varlistentry>
 111             <term>fruit:metadata = [ stream | netatalk ]</term>
 112             <listitem>
 113               <para>Controls where the OS X metadata stream is stored:</para>
 114
 115               <itemizedlist>
 116                 <listitem><para><command>netatalk (default)</command> - use
 117                 Netatalk compatible xattr</para></listitem>
 118
 119                 <listitem><para><command>stream</command> - pass the
 120                 stream on to the next module in the VFS
 121                 stack</para></listitem>
 122               </itemizedlist>
 123
 124             </listitem>
 125           </varlistentry>
 126
 127           <varlistentry>
 128             <term>fruit:locking = [ netatalk | none ]</term>
 129             <listitem>
 130               <para></para>
 131               <itemizedlist>
 132                 <listitem><para><command>none (default)</command> - no
 133                 cross protocol locking</para></listitem>
 134
 135                 <listitem><para><command>netatalk</command> - use
 136                 cross protocol locking with Netatalk</para></listitem>
 137
 138               </itemizedlist>
 139             </listitem>
 140           </varlistentry>
 141
 142           <varlistentry>
 143             <term>fruit:encoding = [ native | private ]</term>
 144             <listitem>
 145
 146               <para>Controls how the set of illegal NTFS ASCII
 147               character, commonly used by OS X clients, are stored in
 148               the filesystem:</para>
 149
 150               <itemizedlist>
 151
 152                 <listitem><para><command>private (default)</command> -
 153                 store characters as encoded by the OS X client: mapped
 154                 to the Unicode private range</para></listitem>
 155
 156                 <listitem><para><command>native</command> - store
 157                 characters with their native ASCII
 158                 value</para></listitem>
 159
 160               </itemizedlist>
 161             </listitem>
 162           </varlistentry>
 163
 164           <varlistentry>
 165             <term>fruit:aapl = yes | no</term>
 166             <listitem>
 167               <para>A global option whether to enable Apple's SMB2+
 168               extension codenamed AAPL. Default
 169               <emphasis>yes</emphasis>. This extension enhances
 170               several deficiencies when connecting from Macs:</para>
 171
 172               <itemizedlist>
 173                 <listitem><para>directory enumeration is enriched with
 174                 Mac relevant filesystem metadata (UNIX mode,
 175                 FinderInfo, resource fork size and effective
 176                 permission), as a result the Mac client doesn't need
 177                 to fetch this metadata individuallly per directory
 178                 entry resulting in an often tremendous performance
 179                 increase.</para></listitem>
 180
 181                 <listitem><para>The ability to query and modify the
 182                 UNIX mode of directory entries.</para></listitem>
 183               </itemizedlist>
 184
 185               <para>There's a set of per share options that can be
 186               used to disable the computation of specific Mac metadata
 187               in the directory enumeration context, all are enabled by
 188               default:</para>
 189
 190               <itemizedlist>
 191                 <listitem><para>readdir_attr:aapl_rsize = true | false</para></listitem>
 192                 <listitem><para>readdir_attr:aapl_finder_info = true | false</para></listitem>
 193                 <listitem><para>readdir_attr:aapl_max_access = true | false</para></listitem>
 194               </itemizedlist>
 195
 196             </listitem>
 197           </varlistentry>
 198
 199           <varlistentry>
 200             <term>fruit:nfs_aces = yes | no</term>
 201             <listitem>
 202               <para>Whether support for querying and modifying the
 203               UNIX mode of directory entries via NFS ACEs is enabled,
 204               default <emphasis>yes</emphasis>.</para>
 205             </listitem>
 206           </varlistentry>
 207
 208           <varlistentry>
 209             <term>fruit:veto_appledouble = yes | no</term>
 210             <listitem>
 211               <para>Whether ._ AppleDouble files are vetoed which
 212               prevents the client from seing and accessing internal
 213               AppleDouble files created by vfs_fruit itself for the
 214               purpose of storing a Mac resource fork.</para>
 215               <para>Vetoing ._ files may break some applications, eg
 216               extracting Mac ZIP archives from Mac clients failes,
 217               because they contain ._ files. Setting this option to
 218               false will fix this, but the abstraction leak of
 219               exposing the internally created ._ files may have other
 220               unknown side effects.</para>
 221               <para>The default is <emphasis>yes</emphasis>.</para>
 222             </listitem>
 223           </varlistentry>
 224
 225           <varlistentry>
 226             <term>fruit:copyfile = yes | no</term>
 227             <listitem>
 228               <para>Whether to enable OS X specific copychunk ioctl
 229               that requests a copy of a whole file along with all
 230               attached metadata.</para>
 231               <para>WARNING: the copyfile request is blocking the
 232               client while the server does the copy.</para>.
 233               <para>The default is <emphasis>no</emphasis>.</para>
 234             </listitem>
 235           </varlistentry>
 236
 237           <varlistentry>
 238             <term>fruit:posix_rename = yes | no</term>
 239             <listitem>
 240               <para>Whether to enable POSIX directory rename behaviour
 241               for OS X clients. Without this, directories can't be
 242               renamed if any client has any file inside it
 243               (recursive!) open.</para>
 244               <para>The default is <emphasis>yes</emphasis>.</para>
 245             </listitem>
 246           </varlistentry>
 247
 248         </variablelist>
 249 </refsect1>
 250
 251 <refsect1>
 252         <title>EXAMPLES</title>
 253
 254 <programlisting>
 255         <smbconfsection name="[share]"/>
 256         <smbconfoption name="ea support">yes</smbconfoption>
 257         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 258         <smbconfoption name="fruit:resource">file</smbconfoption>
 259         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 260         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 261         <smbconfoption name="fruit:encoding">native</smbconfoption>
 262 </programlisting>
 263
 264 </refsect1>
 265
 266 <refsect1>
 267         <title>AUTHOR</title>
 268
 269         <para>The original Samba software and related utilities
 270         were created by Andrew Tridgell. Samba is now developed
 271         by the Samba Team as an Open Source project similar
 272         to the way the Linux kernel is developed.</para>
 273
 274 </refsect1>
 275
 276 </refentry>