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         </variablelist>
 157 </refsect1>
 158
 159 <refsect1>
 160         <title>EXAMPLES</title>
 161
 162 <programlisting>
 163         <smbconfsection name="[share]"/>
 164         <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
 165         <smbconfoption name="fruit:resource">file</smbconfoption>
 166         <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
 167         <smbconfoption name="fruit:locking">netatalk</smbconfoption>
 168         <smbconfoption name="fruit:encoding">native</smbconfoption>
 169 </programlisting>
 170
 171 </refsect1>
 172
 173 <refsect1>
 174         <title>AUTHOR</title>
 175
 176         <para>The original Samba software and related utilities
 177         were created by Andrew Tridgell. Samba is now developed
 178         by the Samba Team as an Open Source project similar
 179         to the way the Linux kernel is developed.</para>
 180
 181 </refsect1>
 182
 183 </refentry>