Commit 8fff8822 authored by David Zeuthen's avatar David Zeuthen

Clarify pklocalauthority(8) man page

Suggestions from

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

Thanks.
parent 1439885f
......@@ -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
......@@ -266,6 +287,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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment