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.2</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>Having shares with ADS support enabled for OS X client
  49         is worthwhile because it resembles the behaviour of Apple's
  50         own SMB server implementation and it avoids certain severe
  51         performance degradations caused by Samba's case sensitivity
  52         semantics.</para>
  53
  54         <para>The OS X metadata and resource fork stream can be stored
  55         in a way compatible with Netatalk 3 by setting
  56         <command>fruit:resource = file</command> and
  57         <command>fruit:metadata = netatalk</command>.</para>
  58
  59         <para>OS X maps NTFS illegal characters to the Unicode private
  60         range in SMB requests. By setting <command>fruit:encoding =
  61         native</command>, all mapped characters are converted to
  62         native ASCII characters.</para>
  63
  64         <para>Finally, share access modes are optionally checked
  65         against Netatalk AFP sharing modes by setting
  66         <command>fruit:locking = netatalk</command>.</para>
  67
  68         <para>This module is not stackable other then described in
  69         this manpage.</para>
  70
  71 </refsect1>
  72
  73 <refsect1>
  74         <title>OPTIONS</title>
  75
  76         <variablelist>
  77
  78           <varlistentry>
  79             <term>fruit:resource = [ file | xattr | stream ]</term>
  80             <listitem>
  81               <para>Controls where the OS X resource fork is stored:</para>
  82
  83               <itemizedlist>
  84                 <listitem><para><command>file (default)</command> - use a ._
  85                 AppleDouble file compatible with OS X and
  86                 Netatalk</para></listitem>
  87
  88                 <listitem><para><command>xattr</command> - use a
  89                 xattr, requires a filesystem with large xattr support
  90                 and a file IO API compatible with xattrs, this boils
  91                 down to Solaris and derived platforms and
  92                 ZFS</para></listitem>
  93
  94                 <listitem><para><command>stream</command> - pass the
  95                 stream on to the next module in the VFS
  96                 stack</para></listitem>
  97               </itemizedlist>
  98
  99             </listitem>
 100           </varlistentry>
 101
 102           <varlistentry>
 103             <term>fruit:metadata = [ stream | netatalk ]</term>
 104             <listitem>
 105               <para>Controls where the OS X metadata stream is stored:</para>
 106
 107               <itemizedlist>
 108                 <listitem><para><command>netatalk (default)</command> - use
 109                 Netatalk compatible xattr</para></listitem>
 110
 111                 <listitem><para><command>stream</command> - pass the
 112                 stream on to the next module in the VFS
 113                 stack</para></listitem>
 114               </itemizedlist>
 115
 116             </listitem>
 117           </varlistentry>
 118
 119           <varlistentry>
 120             <term>fruit:locking = [ netatalk | none ]</term>
 121             <listitem>
 122               <para></para>
 123               <itemizedlist>
 124                 <listitem><para><command>none (default)</command> - no
 125                 cross protocol locking</para></listitem>
 126
 127                 <listitem><para><command>netatalk</command> - use
 128                 cross protocol locking with Netatalk</para></listitem>
 129
 130               </itemizedlist>
 131             </listitem>
 132           </varlistentry>
 133
 134           <varlistentry>
 135             <term>fruit:encoding = [ native | private ]</term>
 136             <listitem>
 137
 138               <para>Controls how the set of illegal NTFS ASCII
 139               character, commonly used by OS X clients, are stored in
 140               the filesystem:</para>
 141
 142               <itemizedlist>
 143
 144                 <listitem><para><command>private (default)</command> -
 145                 store characters as encoded by the OS X client: mapped
 146                 to the Unicode private range</para></listitem>
 147
 148                 <listitem><para><command>native</command> - store
 149                 characters with their native ASCII
 150                 value</para></listitem>
 151
 152               </itemizedlist>
 153             </listitem>
 154           </varlistentry>
 155
 156           <varlistentry>
 157             <term>fruit:aapl = yes | no</term>
 158             <listitem>
 159               <para>A global option whether to enable Apple's SMB2+
 160               extension codenamed AAPL. Default
 161               <emphasis>yes</emphasis>. This extension enhances
 162               several deficiencies when connecting from Macs:</para>
 163
 164               <itemizedlist>
 165                 <listitem><para>directory enumeration is enriched with
 166                 Mac relevant filesystem metadata (UNIX mode,
 167                 FinderInfo, resource fork size and effective
 168                 permission), as a result the Mac client doesn't need
 169                 to fetch this metadata individuallly per directory
 170                 entry resulting in an often tremendous performance
 171                 increase.</para></listitem>
 172
 173                 <listitem><para>The ability to query and modify the
 174                 UNIX mode of directory entries.</para></listitem>
 175               </itemizedlist>
 176
 177               <para>There's a set of per share options that can be
 178               used to disable the computation of specific Mac metadata
 179               in the directory enumeration context, all are enabled by
 180               default:</para>
 181
 182               <itemizedlist>
 183                 <listitem><para>readdir_attr:aapl_rsize = true | false</para></listitem>
 184                 <listitem><para>readdir_attr:aapl_finder_info = true | false</para></listitem>
 185                 <listitem><para>readdir_attr:aapl_max_access = true | false</para></listitem>
 186               </itemizedlist>
 187
 188             </listitem>
 189           </varlistentry>
 190
 191         </variablelist>
 192 </refsect1>
 193
 194 <refsect1>
 195         <title>EXAMPLES</title>
 196
 197 <programlisting>
 198         <smbconfsection name="[share]"/>
 199         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 200         <smbconfoption name="fruit:resource">file</smbconfoption>
 201         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 202         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 203         <smbconfoption name="fruit:encoding">native</smbconfoption>
 204 </programlisting>
 205
 206 </refsect1>
 207
 208 <refsect1>
 209         <title>AUTHOR</title>
 210
 211         <para>The original Samba software and related utilities
 212         were created by Andrew Tridgell. Samba is now developed
 213         by the Samba Team as an Open Source project similar
 214         to the way the Linux kernel is developed.</para>
 215
 216 </refsect1>
 217
 218 </refentry>