manpages/vfs_fruit: document global options

Some options MUST be set in the global section, better document that.

Bug: https://bugzilla.samba.org/show_bug.cgi?id=12615

Signed-off-by: Ralph Boehme <slow@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>
(cherry picked from commit 0c212c50b59081583572f807cf5214037d1517c4)

1 files changed, 99 insertions, 56 deletions

diff --git a/docs-xml/manpages/vfs_fruit.8.xml b/docs-xml/manpages/vfs_fruit.8.xml
index 966bf10630b..74cdd5edcac 100644
--- a/docs-xml/manpages/vfs_fruit.8.xml
+++ b/docs-xml/manpages/vfs_fruit.8.xml
@@ -71,8 +71,81 @@
 </refsect1>
 
 <refsect1>
+	<title>GLOBAL OPTIONS</title>
+
+	<para>The following options must be set in the global smb.conf section
+	and won't take effect when set per share.</para>
+
+	<variablelist>
+
+	  <varlistentry>
+	    <term>fruit:aapl = yes | no</term>
+	    <listitem>
+	      <para>A <emphasis>global</emphasis> option whether to enable Apple's SMB2+
+	      extension codenamed AAPL. Default
+	      <emphasis>yes</emphasis>. This extension enhances
+	      several deficiencies when connecting from Macs:</para>
+
+	      <itemizedlist>
+		<listitem><para>directory enumeration is enriched with
+		Mac relevant filesystem metadata (UNIX mode,
+		FinderInfo, resource fork size and effective
+		permission), as a result the Mac client doesn't need
+		to fetch this metadata individuallly per directory
+		entry resulting in an often tremendous performance
+		increase.</para></listitem>
+
+		<listitem><para>The ability to query and modify the
+		UNIX mode of directory entries.</para></listitem>
+	      </itemizedlist>
+
+	      <para>There's a set of per share options that come into play when
+	      <emphasis>fruit:aapl</emphasis> is enabled. These opions, listed
+	      below, can be used to disable the computation of specific Mac
+	      metadata in the directory enumeration context, all are enabled by
+	      default:</para>
+
+	      <itemizedlist>
+		<listitem><para>readdir_attr:aapl_rsize = yes | no</para></listitem>
+		<listitem><para>readdir_attr:aapl_finder_info = yes | no</para></listitem>
+		<listitem><para>readdir_attr:aapl_max_access = yes | no</para></listitem>
+	      </itemizedlist>
+
+	      <para>See below for a description of these options.</para>
+
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>fruit:nfs_aces = yes | no</term>
+	    <listitem>
+	      <para>A <emphasis>global</emphasis> option whether support for
+	      querying and modifying the UNIX mode of directory entries via NFS
+	      ACEs is enabled, default <emphasis>yes</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>fruit:copyfile = yes | no</term>
+	    <listitem>
+	      <para>A <emphasis>global</emphasis> option whether to enable OS X
+	      specific copychunk ioctl that requests a copy of a whole file
+	      along with all attached metadata.</para>
+	      <para>WARNING: the copyfile request is blocking the
+	      client while the server does the copy.</para>.
+	      <para>The default is <emphasis>no</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	</variablelist>
+</refsect1>
+
+<refsect1>
 	<title>OPTIONS</title>
 
+	<para>The following options can be set either in the global smb.conf section
+	or per share.</para>
+
 	<variablelist>
 
 	  <varlistentry>
@@ -177,50 +250,6 @@
 	  </varlistentry>
 
 	  <varlistentry>
-	    <term>fruit:aapl = yes | no</term>
-	    <listitem>
-	      <para>A global option whether to enable Apple's SMB2+
-	      extension codenamed AAPL. Default
-	      <emphasis>yes</emphasis>. This extension enhances
-	      several deficiencies when connecting from Macs:</para>
-
-	      <itemizedlist>
-		<listitem><para>directory enumeration is enriched with
-		Mac relevant filesystem metadata (UNIX mode,
-		FinderInfo, resource fork size and effective
-		permission), as a result the Mac client doesn't need
-		to fetch this metadata individuallly per directory
-		entry resulting in an often tremendous performance
-		increase.</para></listitem>
-
-		<listitem><para>The ability to query and modify the
-		UNIX mode of directory entries.</para></listitem>
-	      </itemizedlist>
-
-	      <para>There's a set of per share options that can be
-	      used to disable the computation of specific Mac metadata
-	      in the directory enumeration context, all are enabled by
-	      default:</para>
-
-	      <itemizedlist>
-		<listitem><para>readdir_attr:aapl_rsize = true | false</para></listitem>
-		<listitem><para>readdir_attr:aapl_finder_info = true | false</para></listitem>
-		<listitem><para>readdir_attr:aapl_max_access = true | false</para></listitem>
-	      </itemizedlist>
-
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term>fruit:nfs_aces = yes | no</term>
-	    <listitem>
-	      <para>Whether support for querying and modifying the
-	      UNIX mode of directory entries via NFS ACEs is enabled,
-	      default <emphasis>yes</emphasis>.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
 	    <term>fruit:veto_appledouble = yes | no</term>
 	    <listitem>
 	      <para><emphasis>Note:</emphasis> this option only applies when
@@ -242,18 +271,6 @@
 	  </varlistentry>
 
 	  <varlistentry>
-	    <term>fruit:copyfile = yes | no</term>
-	    <listitem>
-	      <para>Whether to enable OS X specific copychunk ioctl
-	      that requests a copy of a whole file along with all
-	      attached metadata.</para>
-	      <para>WARNING: the copyfile request is blocking the
-	      client while the server does the copy.</para>.
-	      <para>The default is <emphasis>no</emphasis>.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
 	    <term>fruit:posix_rename = yes | no</term>
 	    <listitem>
 	      <para>Whether to enable POSIX directory rename behaviour
@@ -264,6 +281,32 @@
 	    </listitem>
 	  </varlistentry>
 
+	  <varlistentry>
+	    <term>readdir_attr:aapl_rsize = yes | no</term>
+	    <listitem>
+	      <para>Return resource fork size in SMB2 FIND responses.</para>
+	      <para>The default is <emphasis>yes</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>readdir_attr:aapl_finder_info = yes | no</term>
+	    <listitem>
+	      <para>Return FinderInfo in SMB2 FIND responses.</para>
+	      <para>The default is <emphasis>yes</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>readdir_attr:aapl_max_access = yes | no</term>
+	    <listitem>
+	      <para>Return the user's effective maximum permissions in SMB2 FIND
+	      responses. This is an expensive computation, setting this to off
+	      pretends the use has maximum effective permissions.</para>
+	      <para>The default is <emphasis>yes</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
 	</variablelist>
 </refsect1>