diff options
-rw-r--r-- | docs/man/pklocalauthority.xml | 110 |
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 |