--- /dev/null
+.\"
+.\" PolicyKit.conf manual page.
+.\" Copyright (C) 2007 David Zeuthen <david@fubar.dk>
+.\"
+.TH POLICYKIT.CONF 5
+.SH NAME
+@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@fubar.dk> with a lot of help from many
+others.
+
<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>
projects / platform / upstream / polkit.git / commitdiff