From 55b3314cb1f4fd887f50b7a312efd8703dfa8889 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Mon, 21 May 2012 10:17:19 -0400 Subject: docs: clarify how rules files work After feedback from Matthias Clasen . Signed-off-by: David Zeuthen --- docs/man/polkit.xml | 71 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 51 insertions(+), 20 deletions(-) diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml index bbe44f7..2aa1da1 100644 --- a/docs/man/polkit.xml +++ b/docs/man/polkit.xml @@ -448,18 +448,33 @@ System Context | | AUTHORIZATION RULES - polkitd reads .rules files from the /etc/polkit-1/rules.d directory in - lexical order. This directory is monitored so if a rules file is - changed, added or removed, existing rules are purged and all - files are read and processed again. Rules files are written in - the JavaScript - programming language and interface with - polkitd through the global - polkit object (of type Polkit) - using the following methods: + polkitd reads + .rules files from the + /etc/polkit-1/rules.d and + /usr/share/polkit-1/rules.d + directories by sorting the files in lexical order based on the + basename on each file (and if there's a tie, files in + /etc + are processed before files in + /usr). + For example, for the following four + files, the order is + + + /etc/polkit-1/rules.d/10-auth.rules + /usr/share/polkit-1/rules.d/10-auth.rules + /etc/polkit-1/rules.d/15-auth.rules + /usr/share/polkit-1/rules.d/20-auth.rules + + + Both directories are monitored so if a rules file is changed, + added or removed, existing rules are purged and all files are + read and processed again. Rules files are written in the + JavaScript + programming language and interface with polkitd + through the global + polkit object (of type Polkit). + The following methods are available: @@ -498,12 +513,21 @@ System Context | | The addRule() method is used for adding a function that is called whenever an authorization check for action, subject - and details is performed. The function - should return one of the values "no", + and details is performed. Functions are + called in the order they have been added until one of the + functions returns a value. Hence, to add an authorization rule + that is processed before other rules, put it in a file in + /etc/polkit-1/rules.d + with a name that sorts before other rules files, for example + 00-early-checks.rules. Each function should + return one of the values "no", "yes", "auth_self", "auth_self_keep", "auth_admin", - "auth_admin_keep" as defined above. + "auth_admin_keep" as defined above. If the + function returns null, + undefined or does not return a value at + all, the next function is tried. @@ -513,10 +537,15 @@ System Context | | identies may be used for administrator authentication for the authorization check identified by action, subject and - details. The function should return an - array of strings where each string is of the form + details. Functions added are called in + the order they have been added until one of the functions + returns a value. Each function should return an array of strings + where each string is of the form "unix-group:<group>" or - "unix-user:<user>". + "unix-user:<user>". If the function + returns null, + undefined or does not return a value at + all, the next function is tried. @@ -640,7 +669,9 @@ System Context | | Authorzation Rules Examples - Allow all users in the admin group to perform user administration: + Allow all users in the admin group to + perform user administration without changing policy for other + users: