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">
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.1</refmiscinfo>
15 <refname>vfs_fruit</refname>
16 <refpurpose>Enhanced OS X and Netatalk interoperability</refpurpose>
21 <command>vfs objects = fruit</command>
26 <title>DESCRIPTION</title>
28 <para>This VFS module is part of the
29 <citerefentry><refentrytitle>samba</refentrytitle>
30 <manvolnum>7</manvolnum></citerefentry> suite.</para>
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>
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>
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>
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
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>
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>
64 <para>Finally, share access modes are optionally checked
65 against Netatalk AFP sharing modes by setting
66 <command>fruit:locking = netatalk</command>.</para>
68 <para>This module is not stackable other then described in
74 <title>OPTIONS</title>
79 <term>fruit:resource = [ file | xattr | stream ]</term>
81 <para>Controls where the OS X resource fork is stored:</para>
84 <listitem><para><command>file (default)</command> - use a ._
85 AppleDouble file compatible with OS X and
86 Netatalk</para></listitem>
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
94 <listitem><para><command>stream</command> - pass the
95 stream on to the next module in the VFS
96 stack</para></listitem>
103 <term>fruit:metadata = [ stream | netatalk ]</term>
105 <para>Controls where the OS X metadata stream is stored:</para>
108 <listitem><para><command>netatalk (default)</command> - use
109 Netatalk compatible xattr</para></listitem>
111 <listitem><para><command>stream</command> - pass the
112 stream on to the next module in the VFS
113 stack</para></listitem>
120 <term>fruit:locking = [ netatalk | none ]</term>
124 <listitem><para><command>none (default)</command> - no
125 cross protocol locking</para></listitem>
127 <listitem><para><command>netatalk</command> - use
128 cross protocol locking with Netatalk</para></listitem>
135 <term>fruit:encoding = [ native | private ]</term>
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>
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>
148 <listitem><para><command>native</command> - store
149 characters with their native ASCII
150 value</para></listitem>
160 <title>EXAMPLES</title>
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>
174 <title>AUTHOR</title>
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>