vfs_fruit: add manpage

Signed-off-by: Ralph Boehme <rb@sernet.de>
Reviewed-by: Jeremy Allison <jra@samba.org>
Reviewed-by: Volker Lendecke <vl@samba.org>

diff --git a/docs-xml/manpages/vfs_fruit.8.xml b/docs-xml/manpages/vfs_fruit.8.xml
new file mode 100644 (file)
index 0000000..500fbec
--- /dev/null
+++ b/docs-xml/manpages/vfs_fruit.8.xml
@@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="vfs_fruit.8">
+
+<refmeta>
+       <refentrytitle>vfs_fruit</refentrytitle>
+       <manvolnum>8</manvolnum>
+       <refmiscinfo class="source">Samba</refmiscinfo>
+       <refmiscinfo class="manual">System Administration tools</refmiscinfo>
+       <refmiscinfo class="version">4.1</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+       <refname>vfs_fruit</refname>
+       <refpurpose>Enhanced OS X and Netatalk interoperability</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+       <cmdsynopsis>
+               <command>vfs objects = fruit</command>
+       </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+       <title>DESCRIPTION</title>
+
+       <para>This VFS module is part of the
+       <citerefentry><refentrytitle>samba</refentrytitle>
+       <manvolnum>7</manvolnum></citerefentry> suite.</para>
+
+       <para>The <command>vfs_fruit</command> module provides
+       enhanced compatibility with Apple SMB clients and
+       interoperability with a Netatalk 3 AFP fileserver.</para>
+
+       <para>The module should be stacked with
+       <command>vfs_catia</command> if enabling character conversion and
+       must be stacked with <command>vfs_streams_xattr</command>, see the
+       example section for the correct config.</para>
+
+       <para>The module enables alternate data streams (ADS) support
+       for a share, intercepts the OS X special streams "AFP_AfpInfo"
+       and "AFP_Resource" and handles them in a special way. All
+       other named streams are deferred to
+       <command>vfs_streams_xattr</command> which must be loaded
+       together with <command>vfs_fruit</command>.</para>
+
+       <para>Having shares with ADS support enabled for OS X client
+       is worthwhile because it resembles the behaviour of Apple's
+       own SMB server implementation and it avoids certain severe
+       performance degradations caused by Samba's case sensitivity
+       semantics.</para>
+
+       <para>The OS X metadata and resource fork stream can be stored
+       in a way compatible with Netatalk 3 by setting
+       <command>fruit:resource = file</command> and
+       <command>fruit:metadata = netatalk</command>.</para>
+
+       <para>OS X maps NTFS illegal characters to the Unicode private
+       range in SMB requests. By setting <command>fruit:encoding =
+       native</command>, all mapped characters are converted to
+       native ASCII characters.</para>
+
+       <para>Finally, share access modes are optionally checked
+       against Netatalk AFP sharing modes by setting
+       <command>fruit:locking = netatalk</command>.</para>
+
+       <para>This module is not stackable other then described in
+       this manpage.</para>
+
+</refsect1>
+
+<refsect1>
+       <title>OPTIONS</title>
+
+       <variablelist>
+
+         <varlistentry>
+           <term>fruit:resource = [ file | xattr | stream ]</term>
+           <listitem>
+             <para>Controls where the OS X resource fork is stored:</para>
+
+             <itemizedlist>
+               <listitem><para><command>file (default)</command> - use a ._
+               AppleDouble file compatible with OS X and
+               Netatalk</para></listitem>
+
+               <listitem><para><command>xattr</command> - use a
+               xattr, requires a filesystem with large xattr support
+               and a file IO API compatible with xattrs, this boils
+               down to Solaris and derived platforms and
+               ZFS</para></listitem>
+
+               <listitem><para><command>stream</command> - pass the
+               stream on to the next module in the VFS
+               stack</para></listitem>
+             </itemizedlist>
+
+           </listitem>
+         </varlistentry>
+
+         <varlistentry>
+           <term>fruit:metadata = [ stream | netatalk ]</term>
+           <listitem>
+             <para>Controls where the OS X metadata stream is stored:</para>
+
+             <itemizedlist>
+               <listitem><para><command>netatalk (default)</command> - use
+               Netatalk compatible xattr</para></listitem>
+
+               <listitem><para><command>stream</command> - pass the
+               stream on to the next module in the VFS
+               stack</para></listitem>
+             </itemizedlist>
+
+           </listitem>
+         </varlistentry>
+
+         <varlistentry>
+           <term>fruit:locking = [ netatalk | none ]</term>
+           <listitem>
+             <para></para>
+             <itemizedlist>
+               <listitem><para><command>none (default)</command> - no
+               cross protocol locking</para></listitem>
+
+               <listitem><para><command>netatalk</command> - use
+               cross protocol locking with Netatalk</para></listitem>
+
+             </itemizedlist>
+           </listitem>
+         </varlistentry>
+
+         <varlistentry>
+           <term>fruit:encoding = [ native | private ]</term>
+           <listitem>
+
+             <para>Controls how the set of illegal NTFS ASCII
+             character, commonly used by OS X clients, are stored in
+             the filesystem:</para>
+
+             <itemizedlist>
+
+               <listitem><para><command>private (default)</command> -
+               store characters as encoded by the OS X client: mapped
+               to the Unicode private range</para></listitem>
+
+               <listitem><para><command>native</command> - store
+               characters with their native ASCII
+               value</para></listitem>
+
+             </itemizedlist>
+           </listitem>
+         </varlistentry>
+
+       </variablelist>
+</refsect1>
+
+<refsect1>
+       <title>EXAMPLES</title>
+
+<programlisting>
+        <smbconfsection name="[share]"/>
+       <smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
+       <smbconfoption name="fruit:resource">file</smbconfoption>
+       <smbconfoption name="fruit:metadata">netatalk</smbconfoption>
+       <smbconfoption name="fruit:locking">netatalk</smbconfoption>
+       <smbconfoption name="fruit:encoding">native</smbconfoption>
+</programlisting>
+
+</refsect1>
+
+<refsect1>
+       <title>AUTHOR</title>
+
+       <para>The original Samba software and related utilities
+       were created by Andrew Tridgell. Samba is now developed
+       by the Samba Team as an Open Source project similar
+       to the way the Linux kernel is developed.</para>
+
+</refsect1>
+
+</refentry>

diff --git a/docs-xml/wscript_build b/docs-xml/wscript_build
index 42c9a85696a94d5cf17ba061fb8d39ec7263a61b..e7c8931ddad5d210f3b62842b04118dd5924f062 100644 (file)
--- a/docs-xml/wscript_build
+++ b/docs-xml/wscript_build
@@ -60,6 +60,7 @@ manpages='''
          manpages/vfs_extd_audit.8
          manpages/vfs_fake_perms.8
          manpages/vfs_fileid.8
+         manpages/vfs_fruit.8
          manpages/vfs_full_audit.8
          manpages/vfs_gpfs.8
          manpages/vfs_linux_xfs_sgid.8