Writing metadata xattr on directories with sticky bit set, FR#94

[netatalk.git] / doc / manpages / man5 / afp.conf.5.xml

diff --git a/doc/manpages/man5/afp.conf.5.xml b/doc/manpages/man5/afp.conf.5.xml
index 44b5a4681806a0e8cb8ed24c885455c4165d23bc..44e083c282f1f20a757ffaae0eb89ae60d290938 100644 (file)
--- a/doc/manpages/man5/afp.conf.5.xml
+++ b/doc/manpages/man5/afp.conf.5.xml
@@ -5,9 +5,9 @@
 
     <manvolnum>5</manvolnum>
 
 
     <manvolnum>5</manvolnum>
 

-    <refmiscinfo class="date">30 Apr 2013</refmiscinfo>
+    <refmiscinfo class="date">05 Jun 2014</refmiscinfo>

 
 

-    <refmiscinfo class="source">:NETATALK_VERSION:</refmiscinfo>
+    <refmiscinfo class="source">@NETATALK_VERSION@</refmiscinfo>

   </refmeta>
 
   <refnamediv>
   </refmeta>
 
   <refnamediv>


@@ -157,7 +157,7 @@
     <title>VARIABLE SUBSTITUTIONS</title>
 
     <para>You can use variables in volume names. The use of variables in paths
     <title>VARIABLE SUBSTITUTIONS</title>
 
     <para>You can use variables in volume names. The use of variables in paths

-    is not supported for now.</para>
+     is limited to $u.</para>

 
     <orderedlist>
       <listitem>
 
     <orderedlist>
       <listitem>


@@ -383,7 +383,7 @@
                 <listitem>
                   <para>allows Random Number and Two-Way Random Number
                   Exchange for authentication (requires a separate file
                 <listitem>
                   <para>allows Random Number and Two-Way Random Number
                   Exchange for authentication (requires a separate file

-                  containing the passwords, either :ETCDIR:/afppasswd file or
+                  containing the passwords, either @pkgconfdir@/afppasswd file or

                   the one specified via "<option>passwd file</option>". See
                   <citerefentry>
                       <refentrytitle>afppasswd</refentrytitle>
                   the one specified via "<option>passwd file</option>". See
                   <citerefentry>
                       <refentrytitle>afppasswd</refentrytitle>


@@ -428,7 +428,7 @@
 
           <listitem>
             <para>Sets the default path for UAMs for this server (default is
 
           <listitem>
             <para>Sets the default path for UAMs for this server (default is

-            :LIBDIR:/netatalk).</para>
+            @libdir@/netatalk).</para>

           </listitem>
         </varlistentry>
       </variablelist>
           </listitem>
         </varlistentry>
       </variablelist>


@@ -509,7 +509,7 @@
 
           <listitem>
             <para>Sets the path to the Randnum UAM passwd file for this server
 
           <listitem>
             <para>Sets the path to the Randnum UAM passwd file for this server

-            (default is :ETCDIR:/afppasswd).</para>
+            (default is @pkgconfdir@/afppasswd).</para>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -554,6 +554,16 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>afp interfaces = <replaceable>name [name ...]</replaceable>
+            <type>(G)</type></term>
+          <listitem>
+            <para>Specifies the network interfaces that the server should
+            listens on. The default is advertise the first IP address of the
+            system, but to listen for any incoming request.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>afp listen = <replaceable>ip address[:port] [ip address[:port]
           ...]</replaceable> <type>(G)</type></term>
         <varlistentry>
           <term>afp listen = <replaceable>ip address[:port] [ip address[:port]
           ...]</replaceable> <type>(G)</type></term>


@@ -565,6 +575,8 @@
             any incoming request. The network address may be specified either
             in dotted-decimal format for IPv4 or in hexadecimal format for
             IPv6.</para>
             any incoming request. The network address may be specified either
             in dotted-decimal format for IPv4 or in hexadecimal format for
             IPv6.</para>

+            <para>IPv6 address + port combination must use URL the format
+            using square brackets [IPv6]:port</para>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -661,10 +673,10 @@
 
           <listitem>
             <para>This specifies the DSI server quantum. The default value is
 
           <listitem>
             <para>This specifies the DSI server quantum. The default value is

-            1 MB. The maximum value is 0xFFFFFFFFF, the minimum is 32000. If
-            you specify a value that is out of range, the default value will
-            be set. Do not change this value unless you're absolutely sure,
-            what you're doing</para>
+            0x100000 (1 MiB). The maximum value is 0xFFFFFFFFF, the minimum is
+            32000. If you specify a value that is out of range, the default
+            value will be set. Do not change this value unless you're
+            absolutely sure, what you're doing</para>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -701,6 +713,24 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>recvfile = <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>no</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Whether to use splice() on Linux for receiving data.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>splice size = <replaceable>number</replaceable> (default:
+          <emphasis>64k</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Maximum number of bytes spliced.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>use sendfile = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>yes</emphasis>) <type>(G)</type></term>
         <varlistentry>
           <term>use sendfile = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>yes</emphasis>) <type>(G)</type></term>


@@ -712,6 +742,7 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+

         <varlistentry>
           <term>zeroconf = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>yes</emphasis>) <type>(G)</type></term>
         <varlistentry>
           <term>zeroconf = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>yes</emphasis>) <type>(G)</type></term>


@@ -776,6 +807,29 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>chmod request = <replaceable>preserve (default) | ignore | simple</replaceable>
+          <type>(G/V)</type></term>
+
+          <listitem>
+            <para>Advanced permission control that deals with ACLs.</para>
+
+            <itemizedlist>
+              <listitem><para>
+                <option>ignore</option> - UNIX chmod() requests are completely ignored
+                     </para></listitem>
+              <listitem><para>
+                <option>preserve</option> - preserve ZFS ACEs for
+                named users and groups or POSIX ACL group mask
+                     </para></listitem>
+              <listitem><para>
+                <option>simple</option> - just to a chmod() as
+                requested without any extra steps
+                     </para></listitem>
+                   </itemizedlist>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>close vol = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>no</emphasis>) <type>(G)</type></term>
         <varlistentry>
           <term>close vol = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>no</emphasis>) <type>(G)</type></term>


@@ -787,6 +841,44 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>cnid mysql host = <replaceable>MySQL server address</replaceable>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>name or address of a MySQL server for use with the mysql CNID
+            backend.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>cnid mysql user = <replaceable>MySQL user</replaceable>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>MySQL user for authentication with the server.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>cnid mysql pw = <replaceable>password</replaceable>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>Password for MySQL server.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>cnid mysql db = <replaceable>database name</replaceable>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>Name of an existing database for which the specified user
+            has full privileges.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>cnid server = <replaceable>ipaddress[:port]</replaceable>
           <type>(G)/(V)</type></term>
         <varlistentry>
           <term>cnid server = <replaceable>ipaddress[:port]</replaceable>
           <type>(G)/(V)</type></term>


@@ -799,6 +891,16 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>dbus daemon = <parameter>path</parameter>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>Sets the path to dbus-daemon binary used by Spotlight feature.
+            The default is <filename>/bin/dbus-daemon</filename>.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>dircachesize = <replaceable>number</replaceable>
           <type>(G)</type></term>
         <varlistentry>
           <term>dircachesize = <replaceable>number</replaceable>
           <type>(G)</type></term>


@@ -822,7 +924,23 @@
 
           <listitem>
             <para>Sets the path to the file which defines file extension
 
           <listitem>
             <para>Sets the path to the file which defines file extension

-            type/creator mappings. (default is :ETCDIR:/extmap.conf).</para>
+            type/creator mappings. (default is @pkgconfdir@/extmap.conf).</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>force xattr with sticky bit =
+          <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>no</emphasis>) <type>(G/V)</type></term>
+
+          <listitem>
+            <para>Writing metadata xattr on directories with the
+            sticky bit set may fail even though we may have write
+            access to a directory, because if the sticky bit is set
+            only the owner is allowed to write xattrs.</para>
+
+            <para>By enabling this option Netatalk will write the
+            metadata xattr as root.</para>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -846,6 +964,21 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>ignored attributes = <replaceable>all | nowrite | nodelete | norename</replaceable>
+          <type>(G)/(V)</type></term>
+
+          <listitem>
+            <para>Speficy a set of file and directory attributes that shall
+            be ignored by the server, <option>all</option> includes all
+            the other options.</para>
+            <para>In OS X when the Finder sets a lock on a file/directory or you
+            set the BSD uchg flag in the Terminal, all three attributes are
+            used. Thus in order to ignore the Finder lock/BSD uchg flag, add
+            set <emphasis>ignored attributes = all</emphasis>.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>login message = <replaceable>message</replaceable>
           <type>(G)/(V)</type></term>
         <varlistentry>
           <term>login message = <replaceable>message</replaceable>
           <type>(G)/(V)</type></term>


@@ -878,7 +1011,7 @@
             characters. This option is useful for clustered environments, to
             provide fault isolation etc. By default, afpd generate signature
             and saving it to
             characters. This option is useful for clustered environments, to
             provide fault isolation etc. By default, afpd generate signature
             and saving it to

-            <filename>:STATEDIR:/netatalk/afp_signature.conf</filename>
+            <filename>@localstatedir@/netatalk/afp_signature.conf</filename>

             automatically (based on random number). See also
             asip-status.pl(1).</para>
           </listitem>
             automatically (based on random number). See also
             asip-status.pl(1).</para>
           </listitem>


@@ -896,15 +1029,109 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>sparql results limit =
+          <replaceable>NUMBER</replaceable> (default:
+          <emphasis>UNLIMITED</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Impose a limit on the number of results queried from Tracker
+           via SPARQL queries.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>spotlight =
+          <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>no</emphasis>) <type>(G)/(V)</type></term>
+
+          <listitem>
+            <para>Whether to enable Spotlight searches. Note: once the global
+            option is enabled, any volume that is not enabled won't be
+            searchable at all. See also <emphasis>dbus daemon</emphasis>
+            option.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>spotlight attributes =
+          <replaceable>COMMA SEPERATED STRING</replaceable> (default:
+          <emphasis>EMPTY</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>A list of attributes that are allowed to be used in
+            Spotlight searches. By default all attributes can be
+            searched, passing a string limits attributes to elements
+            of the string. Example: <programlisting>spotlight
+            attributes = *,kMDItemTextContent</programlisting>
+           </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>spotlight expr =
+          <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>yes</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Whether to allow the use of logic expression in
+            searches.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>start dbus =
+          <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>yes</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Whether to start a dbus instance for use with Tracker.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>start tracker =
+          <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>yes</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Whether to start Tracker with 
+            <emphasis>tracker-control -s</emphasis>.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>veto message = <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>no</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Send optional AFP messages for vetoed files. Then whenever a
+            client tries to access any file or directory with a vetoed name,
+            it will be sent an AFP message indicating the name and the
+            directory.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>vol dbpath = <replaceable>path</replaceable>
         <varlistentry>
           <term>vol dbpath = <replaceable>path</replaceable>

-          <type>(G)</type></term>
+          <type>(G)/(V)</type></term>

 
           <listitem>
             <para>Sets the database information to be stored in path. You have
             to specify a writable location, even if the volume is read only.
             The default is
 
           <listitem>
             <para>Sets the database information to be stored in path. You have
             to specify a writable location, even if the volume is read only.
             The default is

-            <filename>:STATEDIR:/netatalk/CNID/</filename>.</para>
+            <filename>@localstatedir@/netatalk/CNID/$v/</filename>.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>vol dbnest = <replaceable>BOOLEAN</replaceable> (default:
+          <emphasis>no</emphasis>) <type>(G)</type></term>
+
+          <listitem>
+            <para>Setting this option to true brings back Netatalk 2
+            behaviour of storing the CNID database in a folder called
+            .AppleDB inside the volume root of each share.</para>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -1093,7 +1320,7 @@
       mode. You can adjust this behaviour with the configuration option
       <option>mac acls</option>:</para>
 
       mode. You can adjust this behaviour with the configuration option
       <option>mac acls</option>:</para>
 

-      <variablelist id="mac_acls">
+      <variablelist id="map_acls">

         <varlistentry>
           <term>map acls = <parameter>none|rights|mode</parameter>
           <type>(G)</type></term>
         <varlistentry>
           <term>map acls = <parameter>none|rights|mode</parameter>
           <type>(G)</type></term>


@@ -1276,6 +1503,16 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>ldap group attr = <parameter>dn</parameter>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>Name of the LDAP attribute with the groups short
+            name.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>ldap uuid string = <parameter>STRING</parameter>
           <type>(G)</type></term>
         <varlistentry>
           <term>ldap uuid string = <parameter>STRING</parameter>
           <type>(G)</type></term>


@@ -1301,7 +1538,8 @@
             internal UUID representation is converted to and from the binary
             format used in the objectGUID attribute found on objects in Active
             Directory when interacting with the server.</para>
             internal UUID representation is converted to and from the binary
             format used in the objectGUID attribute found on objects in Active
             Directory when interacting with the server.</para>

-
+            <para>See also the options <option>ldap user filter</option> and
+            <option>ldap group filter</option>.</para>

             <para><variablelist>
                 <varlistentry>
                   <term>string</term>
             <para><variablelist>
                 <varlistentry>
                   <term>string</term>


@@ -1323,14 +1561,27 @@
         </varlistentry>
 
         <varlistentry>
         </varlistentry>
 
         <varlistentry>

-          <term>ldap group attr = <parameter>dn</parameter>
+          <term>ldap user filter = <parameter>STRING (default: unused)</parameter>

           <type>(G)</type></term>
 
           <listitem>
           <type>(G)</type></term>
 
           <listitem>

-            <para>Name of the LDAP attribute with the groups short
-            name.</para>
+            <para>Optional LDAP filter that matches user objects. This is necessary for Active Directory
+            environments where users and groups are stored in the same directory subtree.</para>
+            <para>Recommended setting for Active Directory: <parameter>objectClass=user</parameter>.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>ldap group filter = <parameter>STRING (default: unused)</parameter>
+          <type>(G)</type></term>
+
+          <listitem>
+            <para>Optional LDAP filter that matches group objects. This is necessary for Active Directory
+            environments where users and groups are stored in the same directory subtree.</para>
+            <para>Recommended setting for Active Directory: <parameter>objectClass=group</parameter>.</para>

           </listitem>
         </varlistentry>
           </listitem>
         </varlistentry>

+

       </variablelist>
     </refsect2>
   </refsect1>
       </variablelist>
     </refsect2>
   </refsect1>


@@ -1446,8 +1697,8 @@
 
           <listitem>
             <para>set the CNID backend to be used for the volume, default is
 
           <listitem>
             <para>set the CNID backend to be used for the volume, default is

-            [:DEFAULT_CNID_SCHEME:] available schemes:
-            [:COMPILED_BACKENDS:]</para>
+            [@DEFAULT_CNID_SCHEME@] available schemes:
+            [@compiled_backends@]</para>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -1647,7 +1898,8 @@
           <listitem>
             <para>hide files and directories,where the path matches one of the
             '/' delimited vetoed names. The veto string must always be
           <listitem>
             <para>hide files and directories,where the path matches one of the
             '/' delimited vetoed names. The veto string must always be

-            terminated with a '/', eg. "veto1/", "veto1/veto2/".</para>
+            terminated with a '/', eg. "veto files = veto1/", "veto files =
+            veto1/veto2/".</para>

           </listitem>
         </varlistentry>
       </variablelist>
           </listitem>
         </varlistentry>
       </variablelist>


@@ -1694,6 +1946,23 @@
           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 

+        <varlistentry>
+          <term>delete veto files = <replaceable>BOOLEAN</replaceable>
+          (default: <emphasis>no</emphasis>) <type>(V)</type></term>
+
+          <listitem>
+            <para>This option is used when Netatalk is attempting to delete a
+            directory that contains one or more vetoed files or directories
+            (see the veto files option). If this option is set to no (the
+            default) then if a directory contains any non-vetoed files or
+            directories then the directory delete will fail. This is usually
+            what you want.</para>
+            <para>If this option is set to yes, then Netatalk will attempt to
+            recursively delete any files and directories within the vetoed
+            directory.</para>
+          </listitem>
+        </varlistentry>
+

         <varlistentry>
           <term>follow symlinks = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>no</emphasis>) <type>(V)</type></term>
         <varlistentry>
           <term>follow symlinks = <replaceable>BOOLEAN</replaceable> (default:
           <emphasis>no</emphasis>) <type>(V)</type></term>


@@ -1704,6 +1973,10 @@
             Setting the option to true causes afpd to follow symlinks on the
             server. symlinks may point outside of the AFP volume, currently
             afpd doesn't do any checks for "wide symlinks".</para>
             Setting the option to true causes afpd to follow symlinks on the
             server. symlinks may point outside of the AFP volume, currently
             afpd doesn't do any checks for "wide symlinks".</para>

+            <note>
+              <para>This option will subtly break when the symlinks point
+              across filesystem boundaries.</para>
+            </note>

           </listitem>
         </varlistentry>
 
           </listitem>
         </varlistentry>
 


@@ -1821,7 +2094,7 @@
     not by name. Netatalk needs a way to store these ID's in a persistent way,
     to achieve this several different CNID backends are available. The CNID
     Databases are by default located in the
     not by name. Netatalk needs a way to store these ID's in a persistent way,
     to achieve this several different CNID backends are available. The CNID
     Databases are by default located in the

-    <filename>:STATEDIR:/netatalk/CNID/(volumename)/.AppleDB/</filename>
+    <filename>@localstatedir@/netatalk/CNID/(volumename)/.AppleDB/</filename>

     directory.</para>
 
     <variablelist>
     directory.</para>
 
     <variablelist>