PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Tue Jul 24 20:29:32 EEST 2007
doc/man/Makefile.am | 2
doc/man/PolicyKit.8.in | 5
doc/man/PolicyKit.conf.5.in | 198 +++++++++++++++++++++++++++++++++
doc/man/polkit-check-caller.1.in | 5
doc/man/polkit-check-session.1.in | 5
doc/man/polkit-list-actions.1.in | 44 +++++++
doc/spec/polkit-spec-configuration.xml | 14 +-
7 files changed, 256 insertions(+), 17 deletions(-)
New commits:
diff-tree 46773df61c984813aece7d06e9a9fe5cc27476a9 (from 600bca82cfeebdcde832d330a2c896c18026bf89)
Author: David Zeuthen <davidz at redhat.com>
Date: Tue Jul 24 13:29:33 2007 -0400
document the /etc/PolicyKit/PolicyKit.conf file with a manual page
Also add a man page for polkit-list-actions(1).
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 2c06738..9d4405e 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -1,7 +1,7 @@
if MAN_PAGES_ENABLED
-MAN_IN_FILES = polkit-check-caller.1.in polkit-check-session.1.in polkit-policy-file-validate.1.in PolicyKit.8.in polkit-reload-config.1.in
+MAN_IN_FILES = polkit-check-caller.1.in polkit-check-session.1.in polkit-policy-file-validate.1.in PolicyKit.8.in PolicyKit.conf.5.in polkit-reload-config.1.in polkit-list-actions.1.in
man_MANS = $(MAN_IN_FILES:.in=)
diff --git a/doc/man/PolicyKit.8.in b/doc/man/PolicyKit.8.in
index 319121b..9027288 100644
--- a/doc/man/PolicyKit.8.in
+++ b/doc/man/PolicyKit.8.in
@@ -22,11 +22,6 @@ on how to subscribe.
.SH SEE ALSO
.PP
-\&\fIpolkit-module-builtins\fR\|(8),
-\&\fIpolkit-module-default\fR\|(8),
-\&\fIpolkit-module-allow-all\fR\|(8),
-\&\fIpolkit-module-deny-all\fR\|(8),
-\&\fIpolkit-module-run-program\fR\|(8),
\&\fIpolkit-check-caller\fR\|(1),
\&\fIpolkit-check-session\fR\|(1),
\&\fIpolkit-policy-file-validate\fR\|(1),
diff --git a/doc/man/PolicyKit.conf.5.in b/doc/man/PolicyKit.conf.5.in
new file mode 100644
index 0000000..c75d307
--- /dev/null
+++ b/doc/man/PolicyKit.conf.5.in
@@ -0,0 +1,198 @@
+.\"
+.\" PolicyKit.conf manual page.
+.\" Copyright (C) 2007 David Zeuthen <david at fubar.dk>
+.\"
+.TH POLICYKIT.CONF 5
+.SH NAME
+ at sysconfdir@/PolicyKit/PolicyKit.conf \- PolicyKit configuration file
+.SH DESCRIPTION
+.PP
+
+The
+.I @sysconfdir@/PolicyKit/PolicyKit.conf
+configuration file provides a way for system administrators to
+override policy that mechanisms use
+.I libpolkit
+to determine whether a caller is privileged to use the mechanism in the way specified by the given
+.I action
+identifier.
+
+Changes to this configuration file are not immediately propagated; the
+utility \&\fIpolkit-reload-config\fR\|(1) can be used to notify
+running processes of the changes to the configuration file.
+
+.B TODO:
+we need to have a tool to verify the PolicyKit.conf file.
+
+For more information about the big picture refer to the \fIPolicyKit
+spec\fP which can be found in
+.I "@docdir@/spec/polkit-spec.html"
+depending on the distribution.
+
+.SH CONFIGURATION FILE
+.PP
+
+The configuration file is an XML document. It must
+have the following doctype declaration:
+
+ <!DOCTYPE pkconfig PUBLIC "-//freedesktop//DTD PolicyKit Configuration 1.0//EN"
+ "http://hal.freedesktop.org/releases/PolicyKit/1.0/config.dtd">
+
+The following elements may be present in the configuration file
+
+.I config
+
+Root element. A single attribute
+.I version
+must be present and must be set to
+.I "0.1"
+at this point. There can only be one
+.I config
+element in the configuration file.
+
+.I match
+
+This element is for matching information related to the decision
+making process and includes values describing both the caller and the
+action. This element can be embedded in both
+.I config
+and other
+.I match
+elements (hence allowing for nested matching).
+
+There can only be a single attribute in each
+.I match
+element and POSIX Extended Regular Expression syntax are supported in
+the value part. The following attributes are supported:
+
+.I
+.TP
+.B user
+This matches on the user. Both the UNIX uid (e.g. 500) and the user
+name (e.g. davidz) are tried in the matching process. For example .B
+user="davidz|504" matches the UNIX user with uid 504 and the UNIX user
+with the name "davidz".
+.TP
+.B action
+For matching on the action, for example
+.B action="hal-storage-*"
+will match on all actions whose name begins with the string with "hal-storage-".
+
+.PP
+
+.I return
+
+This element is for used to specify what result
+.I libpolkit
+should return. It can only be embedded in
+.I config
+and
+.I match
+elements and can embed no elements itself. The
+.I return
+element is typically used deeply inside a number of
+.I match
+elements. A single attribute
+.I result
+is supported and it can assume the following values
+
+.TP
+.B no
+Access denied.
+.TP
+.B auth_root
+Access denied, but authentication of the caller as root will grant
+access to only that caller.
+.TP
+.B auth_root_keep_session
+Access denied, but authentication of the caller as root will grant
+access for the remainder of the session the caller stems from.
+.TP
+.B auth_root_keep_always
+Access denied, but authentication of the caller as root will grant
+access to the user of the caller in the future.
+.TP
+.B auth_self
+Access denied, but authentication of the caller as himself will grant
+access to only that caller.
+.TP
+.B auth_self_keep_session
+Access denied, but authentication of the caller as himself will grant
+access for the remainder of the session the caller stems from.
+.TP
+.B auth_self_keep_always
+Access denied, but authentication of the caller as himself will grant
+access to the user of the caller in the future.
+.TP
+.B yes
+Access granted.
+
+.SH EXAMPLES
+
+For brevity the standard XML and doctype headers are omitted in the
+following configuration file examples. The actions used may also be
+fictional, use \&\fIpolkit-list-actions\fR\|(1) to learn about the
+actions installed on the system.
+
+.I ALLOW EVERYTHING
+
+ <config version="0.1">
+.br
+ <match user="davidz|504">
+.br
+ <return result="yes"/>
+.br
+ </match>
+.br
+ </config>
+.br
+
+The two UNIX users "davidz" and user with UNIX uid 504 will be allowed
+to do any action.
+
+.I MOUNTING FIXED DRIVES
+
+Suppose the action
+.I hal-storage-mount-fixed
+is used by \&\fIhald\fR\|(8) to determine whether mounting internal
+hard drives are allowed. Then this configuration file
+
+ <config version="0.1">
+.br
+ <match action="hal-storage-mount-fixed">
+ <match user="davidz">
+.br
+ <return result="yes"/>
+.br
+ </match>
+ <match user="freddy">
+.br
+ <return result="no"/>
+.br
+ </match>
+.br
+ </match>
+.br
+ </config>
+.br
+
+specifies that UNIX user "davidz" is always allowed to do the action,
+while UNIX user "freddy" is never allowed to do the action.
+
+.SH BUGS
+.PP
+Please send bug reports to either the distribution or the HAL
+mailing list, see
+.I "http://lists.freedesktop.org/mailman/listinfo/hal"
+on how to subscribe.
+
+.SH SEE ALSO
+.PP
+\&\fIPolicyKit\fR\|(8),
+\&\fIpolkit-list-actions\fR\|(1)
+
+
+.SH AUTHOR
+Written by David Zeuthen <david at fubar.dk> with a lot of help from many
+others.
+
diff --git a/doc/man/polkit-check-caller.1.in b/doc/man/polkit-check-caller.1.in
index 2b30ace..df67b33 100644
--- a/doc/man/polkit-check-caller.1.in
+++ b/doc/man/polkit-check-caller.1.in
@@ -13,9 +13,8 @@ polkit-check-caller \- check access
.SH DESCRIPTION
\fIpolkit-check-caller\fP can be used to determine if a given caller
-can access a given resource in a given way. For more information about
-the big picture refer to the \fIPolicyKit spec\fP which can be found
-in
+can a given action. For more information about the big picture refer
+to the \fIPolicyKit spec\fP which can be found in
.I "@docdir@/spec/polkit-spec.html"
depending on the distribution.
diff --git a/doc/man/polkit-check-session.1.in b/doc/man/polkit-check-session.1.in
index 019b917..76542ea 100644
--- a/doc/man/polkit-check-session.1.in
+++ b/doc/man/polkit-check-session.1.in
@@ -13,9 +13,8 @@ polkit-check-session \- check access
.SH DESCRIPTION
\fIpolkit-check-session\fP can be used to determine if a given session
-can access a given resource in a given way. For more information about
-the big picture refer to the \fIPolicyKit spec\fP which can be found
-in
+can do a given action. For more information about the big picture
+refer to the \fIPolicyKit spec\fP which can be found in
.I "@docdir@/spec/polkit-spec.html"
depending on the distribution.
diff --git a/doc/man/polkit-list-actions.1.in b/doc/man/polkit-list-actions.1.in
new file mode 100644
index 0000000..3c22900
--- /dev/null
+++ b/doc/man/polkit-list-actions.1.in
@@ -0,0 +1,44 @@
+.\"
+.\" polkit-list-actions manual page.
+.\" Copyright (C) 2007 David Zeuthen <david at fubar.dk>
+.\"
+.TH POLKIT-LIST-ACTIONS 1
+.SH NAME
+polkit-list-actions \- list actions registered with PolicyKit
+.SH SYNOPSIS
+.PP
+.B polkit-list-actions
+[options]
+
+.SH DESCRIPTION
+
+\fIpolkit-list-actions\fP simply list the actions that mechanisms have
+registered with PolicyKit. For more information about the big picture
+refer to the \fIPolicyKit spec\fP which can be found in
+.I "@docdir@/spec/polkit-spec.html"
+depending on the distribution.
+
+.SH OPTIONS
+The following options are supported:
+.TP
+.I "--help"
+Print out usage.
+.TP
+.I "--version"
+Print the version.
+
+.SH BUGS
+.PP
+Please send bug reports to either the distribution or the HAL
+mailing list, see
+.I "http://lists.freedesktop.org/mailman/listinfo/hal"
+on how to subscribe.
+
+.SH SEE ALSO
+.PP
+\&\fIPolicyKit\fR\|(8)
+
+.SH AUTHOR
+Written by David Zeuthen <david at fubar.dk> with a lot of help from many
+others.
+
diff --git a/doc/spec/polkit-spec-configuration.xml b/doc/spec/polkit-spec-configuration.xml
index 707425b..a96b340 100644
--- a/doc/spec/polkit-spec-configuration.xml
+++ b/doc/spec/polkit-spec-configuration.xml
@@ -186,11 +186,15 @@
<title>Beyond the Defaults</title>
<para>
- TODO: To be written. Will include how machines and sites can
- tweak what answer <literal>libpolkit</literal> returns depending
- on the Action and Subject. For example it includes 1) locking
- down a guest account; 2) discriminating depending on uid, gid,
- SELinux context, exec-path.
+ System administrators and sites can tweak what
+ answer <literal>libpolkit</literal> returns depending on the
+ Action and Subject and other factors through the configuration
+ file <literal>/etc/PolicyKit/PolicyKit.conf</literal>. The
+ configuration file format, along with examples, is described in
+ the associated manual page of the same name. Note that this file
+ is not supposed to be modified by individual packages, it is
+ solely the responsibility of the system administrator to make
+ changes to this file.
</para>
</sect1>
More information about the hal-commit
mailing list