From 8fff882210e464620c550100069db944a4d73c88 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Thu, 12 Nov 2009 13:49:35 -0500 Subject: [PATCH] Clarify pklocalauthority(8) man page Suggestions from https://bugzilla.redhat.com/show_bug.cgi?id=534140 Thanks. --- docs/man/pklocalauthority.xml | 110 ++++++++++++++++++++++++++++++------------ 1 file 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. + + Files shipped with PolicyKit and 3rd party packages (e.g. under + package manager control) typically have comments (such + as DO NOT EDIT THIS FILE, it will be overwritten on + update) telling the system administrator that changes + will be overwritten on update. + @@ -57,20 +64,26 @@ support this use-case as well. - Configuration for the Local Authority are read from files in + Configuration for the Local Authority is read from files in the /etc/polkit-1/localauthority.conf.d - directory. The file 50-localauthority.conf + directory. All files are read in lexigraphical order (using the + C locale) meaning that later files can override earlier + ones. The file 50-localauthority.conf 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 key - file with a single Configuration - group. Only a single key, AdminIdentities 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 (also commonly known as a ini + file) with a single group + called [Configuration]. Only a single + key, AdminIdentities 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 unix-user: and groups of users are specified - by prefixing with unix-group:. + by prefixing with unix-group:. See + for an example of a + configuration file. @@ -78,7 +91,7 @@ DIRECTORY STRUCTURE The Local Authority reads files with .pkla - from the following directories + extension from the following directories /var/lib/polkit-1/ @@ -90,10 +103,11 @@ `-- 90-mandatory.d - Each .pkla contains one or more + Each .pkla file contains one or more authorization entries. If the underlying filesystem supports file monitoring, the Local Authority will reload information - whenever changes occur. + whenever .pkla files are added, removed or + changed. Each directory is intended for a specific audience @@ -146,16 +160,20 @@ groups with each group representing an authorization entry. A .pkla 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 + Acme Corp needs to modify policy for the + product Frobnicator, a name + like com.acme.frobnicator.pkla would be + suitable. AUTHORIZATION ENTRY - Each group in a .pkla must have a name that - is unique within the file it belongs to. The following keys are - are processed. + Each group in a .pkla file must have a name + that is unique within the file it belongs to. The following keys + are are recognized: @@ -219,7 +237,7 @@ 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. @@ -229,32 +247,35 @@ All keys specified above are required except that only at least one of ResultAny, ResultInactive - and ResultActive is - present. The ReturnValue key is optional. + and ResultActive must + be present. The ReturnValue key is optional. EVALUATION ORDER - 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. - 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 RequireAny, RequireInactive or RequireActive is used and ReturnValue is added to the - authorization result. Finally, the authorization entries are - consulted using the user identity in the same manner. + authorization result. + + + Finally, the authorization entries are consulted using the user + identity in the same manner. Note that processing continues even after a match. This allows @@ -267,6 +288,33 @@ EXAMPLES + The following .conf file + + +[Configuration] +AdminIdentities=unix-group:desktop_admin_r + + + that any user in the desktop_admin_r UNIX + group can be used for authentication when administrator + authentication is needed. This file would typically be installed + in the /etc/polkit-1/localauthority.conf.d + directory and given the + name 60-desktop-policy.conf to ensure that + it is evaluted after + the 50-localauthority.conf file shipped + with PolicyKit. If the local administrator wants to override this (suppose 60-desktop-policy.conf was shipped as part of the OS) he can simply create a file 99-my-admin-configuration.conf with the following content + + +[Configuration] +AdminIdentities=unix-user:lisa;unix-user:marge + + + to specify that only the users lisa + and marge can authenticate when + administrator authentication is needed. + + The following .pkla file grants authorization to all users in the staff group for actions matching the -- 2.7.4