| 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 | <varlistentry>
|
|---|
| 230 | <term>fruit:posix_rename = yes | no</term>
|
|---|
| 231 | <listitem>
|
|---|
| 232 | <para>Whether to enable POSIX directory rename behaviour
|
|---|
| 233 | for OS X clients. Without this, directories can't be
|
|---|
| 234 | renamed if any client has any file inside it
|
|---|
| 235 | (recursive!) open.</para>
|
|---|
| 236 | <para>The default is <emphasis>yes</emphasis>.</para>
|
|---|
| 237 | </listitem>
|
|---|
| 238 | </varlistentry>
|
|---|
| 239 |
|
|---|
| 240 | </variablelist>
|
|---|
| 241 | </refsect1>
|
|---|
| 242 |
|
|---|
| 243 | <refsect1>
|
|---|
| 244 | <title>EXAMPLES</title>
|
|---|
| 245 |
|
|---|
| 246 | <programlisting>
|
|---|
| 247 | <smbconfsection name="[share]"/>
|
|---|
| 248 | <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
|
|---|
| 249 | <smbconfoption name="fruit:resource">file</smbconfoption>
|
|---|
| 250 | <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
|
|---|
| 251 | <smbconfoption name="fruit:locking">netatalk</smbconfoption>
|
|---|
| 252 | <smbconfoption name="fruit:encoding">native</smbconfoption>
|
|---|
| 253 | </programlisting>
|
|---|
| 254 |
|
|---|
| 255 | </refsect1>
|
|---|
| 256 |
|
|---|
| 257 | <refsect1>
|
|---|
| 258 | <title>AUTHOR</title>
|
|---|
| 259 |
|
|---|
| 260 | <para>The original Samba software and related utilities
|
|---|
| 261 | were created by Andrew Tridgell. Samba is now developed
|
|---|
| 262 | by the Samba Team as an Open Source project similar
|
|---|
| 263 | to the way the Linux kernel is developed.</para>
|
|---|
| 264 |
|
|---|
| 265 | </refsect1>
|
|---|
| 266 |
|
|---|
| 267 | </refentry>
|
|---|
