Clarify pklocalauthority(8) man page

Suggestions from

 https://bugzilla.redhat.com/show_bug.cgi?id=534140

Thanks.

1 files changed, 79 insertions, 31 deletions

diff --git a/docs/man/pklocalauthority.xml b/docs/man/pklocalauthority.xml
index 8ef58ce..5ba01a6 100644
--- a/docs/man/pklocalauthority.xml
+++ b/docs/man/pklocalauthority.xml
@@ -33,6 +33,13 @@
       same files. This policy also ensures smooth upgrades when
       distributing PolicyKit using a package management system.
     </para>
+    <para>
+      Files shipped with PolicyKit and 3rd party packages (e.g. under
+      package manager control) typically have comments (such
+      as <quote>DO NOT EDIT THIS FILE, it will be overwritten on
+      update</quote>) telling the system administrator that changes
+      will be overwritten on update.
+    </para>
   </refsect1>
 
   <refsect1 id="pklocalauthority-admin-authentication">
@@ -57,20 +64,26 @@
       support this use-case as well.
     </para>
     <para>
-      Configuration for the Local Authority are read from files in
+      Configuration for the Local Authority is read from files in
       the <filename>/etc/polkit-1/localauthority.conf.d</filename>
-      directory. The file <filename>50-localauthority.conf</filename>
+      directory. All files are read in lexigraphical order (using the
+      C locale) meaning that later files can override earlier
+      ones. The file <filename>50-localauthority.conf</filename>
       contains the settings provided by the OS vendor. Users and 3rd
       party packages can drop configuration files with a priority
       higher than 60 to change the defaults. The configuration file
       format is simple. Each configuration file is a <emphasis>key
-      file</emphasis> with a single <literal>Configuration</literal>
-      group.  Only a single key, <literal>AdminIdentities</literal> is
-      read.  The value of this key is a semi-colon separated list of
-      identities that can be used when administrator authentication is
-      required. Users are specified by prefixing the user name with
+      file</emphasis> (also commonly known as a <emphasis>ini
+      file</emphasis>) with a single group
+      called <literal>[Configuration]</literal>.  Only a single
+      key, <literal>AdminIdentities</literal> is read.  The value of
+      this key is a semi-colon separated list of identities that can
+      be used when administrator authentication is required. Users are
+      specified by prefixing the user name with
       <literal>unix-user:</literal> and groups of users are specified
-      by prefixing with <literal>unix-group:</literal>.
+      by prefixing with <literal>unix-group:</literal>. See
+      <xref linkend="pklocalauthority-examples"/> for an example of a
+      configuration file.
     </para>
   </refsect1>
 
@@ -78,7 +91,7 @@
     <title>DIRECTORY STRUCTURE</title>
     <para>
       The Local Authority reads files with <filename>.pkla</filename>
-      from the following directories
+      extension from the following directories
     </para>
     <programlisting>
 /var/lib/polkit-1/
@@ -90,10 +103,11 @@
     `-- 90-mandatory.d
     </programlisting>
     <para>
-      Each <filename>.pkla</filename> contains one or more
+      Each <filename>.pkla</filename> file contains one or more
       authorization entries. If the underlying filesystem supports
       file monitoring, the Local Authority will reload information
-      whenever changes occur.
+      whenever <filename>.pkla</filename> files are added, removed or
+      changed.
     </para>
     <para>
       Each directory is intended for a specific audience
@@ -146,16 +160,20 @@
       groups with each group representing an authorization entry.
       A <filename>.pkla</filename> file MUST be named by using a
       scheme to ensure that the name is unique, e.g. reverse DNS
-      notation or similar.
+      notation or similar. For example, if the organization is
+      <quote>Acme Corp</quote> needs to modify policy for the
+      product <quote>Frobnicator</quote>, a name
+      like <filename>com.acme.frobnicator.pkla</filename> would be
+      suitable.
     </para>
   </refsect1>
 
   <refsect1 id="pklocalauthority-authorization-entry">
     <title>AUTHORIZATION ENTRY</title>
     <para>
-      Each group in a <filename>.pkla</filename> must have a name that
-      is unique within the file it belongs to. The following keys are
-      are processed.
+      Each group in a <filename>.pkla</filename> file must have a name
+      that is unique within the file it belongs to. The following keys
+      are are recognized:
     </para>
     <variablelist>
       <varlistentry>
@@ -219,7 +237,7 @@
         <listitem>
           <para>
             A semi-colon separated list of key/value pairs (of the
-            form key=value) that are add to the details of
+            form key=value) that are added to the details of
             authorization result on positive matches.
           </para>
         </listitem>
@@ -229,32 +247,35 @@
       All keys specified above are required except that only at least
       one
       of <emphasis>ResultAny</emphasis>, <emphasis>ResultInactive</emphasis>
-      and <emphasis>ResultActive</emphasis> is
-      present. The <emphasis>ReturnValue</emphasis> key is optional.
+      and <emphasis>ResultActive</emphasis> must
+      be present. The <emphasis>ReturnValue</emphasis> key is optional.
     </para>
   </refsect1>
 
   <refsect1 id="pklocalauthority-evaluation-order">
     <title>EVALUATION ORDER</title>
     <para>
-      Whenever a Mechanism does an authorization check to check if a
-      given Subject is authorized for a given action, the
-      authorization entries discussed above are consulted in the
-      following order. First, the user of the Subject is determined
-      and the groups that the user belongs are looked up.
+      When a Mechanism requests services from the Authority to check
+      if a given Subject is authorized for a given Action, the
+      authorization entries discussed above are consulted using the
+      following algorithm.
     </para>
     <para>
-      For each group identity, the authorization entries are consulted
-      in the standard lexigraphical order (using standard
-      lexicographical sorting (using the standard C locale) of file
-      names and appearance of each group in each file). If the
-      authorization check matches the data from the authorization
-      check, then the authorization result
+      First, the user of the Subject is determined and the groups that
+      the user belongs are looked up. For each group identity, the
+      authorization entries are consulted in the lexigraphical order
+      (using standard lexicographical sorting (using the standard C
+      locale) of file names and appearance of each group in each
+      file). If the authorization check matches the data from the
+      authorization check, then the authorization result
       from <emphasis>RequireAny</emphasis>, <emphasis>RequireInactive</emphasis>
       or <emphasis>RequireActive</emphasis> is used
       and <emphasis>ReturnValue</emphasis> is added to the
-      authorization result. Finally, the authorization entries are
-      consulted using the user identity in the same manner.
+      authorization result.
+    </para>
+    <para>
+      Finally, the authorization entries are consulted using the user
+      identity in the same manner.
     </para>
     <para>
       Note that processing continues even after a match. This allows
@@ -267,6 +288,33 @@
   <refsect1 id="pklocalauthority-examples">
     <title>EXAMPLES</title>
     <para>
+      The following <filename>.conf</filename> file
+    </para>
+    <programlisting>
+[Configuration]
+AdminIdentities=unix-group:desktop_admin_r
+    </programlisting>
+    <para>
+      that any user in the <literal>desktop_admin_r</literal> UNIX
+      group can be used for authentication when administrator
+      authentication is needed. This file would typically be installed
+      in the <filename>/etc/polkit-1/localauthority.conf.d</filename>
+      directory and given the
+      name <filename>60-desktop-policy.conf</filename> to ensure that
+      it is evaluted after
+      the <filename>50-localauthority.conf</filename> file shipped
+      with PolicyKit. If the local administrator wants to override this (suppose <filename>60-desktop-policy.conf</filename> was shipped as part of the OS) he can simply create a file <filename>99-my-admin-configuration.conf</filename> with the following content
+    </para>
+    <programlisting>
+[Configuration]
+AdminIdentities=unix-user:lisa;unix-user:marge
+    </programlisting>
+    <para>
+      to specify that only the users <literal>lisa</literal>
+      and <literal>marge</literal> can authenticate when
+      administrator authentication is needed.
+    </para>
+    <para>
       The following <filename>.pkla</filename> file grants
       authorization to all users in the <literal>staff</literal> group
       for actions matching the