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>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           <varlistentry>
 192             <term>fruit:nfs_aces = yes | no</term>
 193             <listitem>
 194               <para>Whether support for querying and modifying the
 195               UNIX mode of directory entries via NFS ACEs is enabled,
 196               default <emphasis>yes</emphasis>.</para>
 197             </listitem>
 198           </varlistentry>
 199
 200           <varlistentry>
 201             <term>fruit:veto_appledouble = yes | no</term>
 202             <listitem>
 203               <para>Whether ._ AppleDouble files are vetoed which
 204               prevents the client from seing and accessing internal
 205               AppleDouble files created by vfs_fruit itself for the
 206               purpose of storing a Mac resource fork.</para>
 207               <para>Vetoing ._ files may break some applications, eg
 208               extracting Mac ZIP archives from Mac clients failes,
 209               because they contain ._ files. Setting this option to
 210               false will fix this, but the abstraction leak of
 211               exposing the internally created ._ files may have other
 212               unknown side effects.</para>
 213               <para>The default is <emphasis>yes</emphasis>.</para>
 214             </listitem>
 215           </varlistentry>
 216
 217           <varlistentry>
 218             <term>fruit:copyfile = yes | no</term>
 219             <listitem>
 220               <para>Whether to enable OS X specific copychunk ioctl
 221               that requests a copy of a whole file along with all
 222               attached metadata.</para>
 223               <para>WARNING: the copyfile request is blocking the
 224               client while the server does the copy.</para>.
 225               <para>The default is <emphasis>no</emphasis>.</para>
 226             </listitem>
 227           </varlistentry>
 228
 229         </variablelist>
 230 </refsect1>
 231
 232 <refsect1>
 233         <title>EXAMPLES</title>
 234
 235 <programlisting>
 236         <smbconfsection name="[share]"/>
 237         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 238         <smbconfoption name="fruit:resource">file</smbconfoption>
 239         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 240         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 241         <smbconfoption name="fruit:encoding">native</smbconfoption>
 242 </programlisting>
 243
 244 </refsect1>
 245
 246 <refsect1>
 247         <title>AUTHOR</title>
 248
 249         <para>The original Samba software and related utilities
 250         were created by Andrew Tridgell. Samba is now developed
 251         by the Samba Team as an Open Source project similar
 252         to the way the Linux kernel is developed.</para>
 253
 254 </refsect1>
 255
 256 </refentry>