PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Thu Nov 12 10:50:17 PST 2009
docs/man/pklocalauthority.xml | 110 ++++++++++++++++++++++++++++++------------
1 file changed, 79 insertions(+), 31 deletions(-)
New commits:
commit 8fff882210e464620c550100069db944a4d73c88
Author: David Zeuthen <davidz at redhat.com>
Date: Thu Nov 12 13:49:35 2009 -0500
Clarify pklocalauthority(8) man page
Suggestions from
https://bugzilla.redhat.com/show_bug.cgi?id=534140
Thanks.
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
More information about the hal-commit
mailing list