ACC SHELL
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>PolicyKit configuration</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="PolicyKit Library Reference Manual">
<link rel="up" href="ref-design.html" title="Design Overview">
<link rel="prev" href="model-authentication-agent.html" title="Authentication Agent">
<link rel="next" href="beyond-defaults.html" title="Beyond the Defaults">
<meta name="generator" content="GTK-Doc V1.14 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="model-authentication-agent.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="ref-design.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">PolicyKit Library Reference Manual</th>
<td><a accesskey="n" href="beyond-defaults.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter" title="PolicyKit configuration">
<div class="titlepage"><div><div><h2 class="title">
<a name="polkit-conf"></a>PolicyKit configuration</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="sect1"><a href="polkit-conf.html#conf-declaring-actions">Declaring Actions</a></span></dt>
<dd><dl><dt><span class="sect2"><a href="polkit-conf.html#conf-declaring-actions-annotations">Annotations</a></span></dt></dl></dd>
<dt><span class="sect1"><a href="beyond-defaults.html">Beyond the Defaults</a></span></dt>
</dl></div>
<div class="sect1" title="Declaring Actions">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="conf-declaring-actions"></a>Declaring Actions</h2></div></div></div>
<p>
A Mechanism needs to declare what Actions it supports. This is
achieved by dropping one or more XML files with the suffix <code class="literal">.policy</code>
into the <code class="literal">/usr/share/PolicyKit/policy</code> directory.
</p>
<p>
The name of the XML file is significant. Each XML file can only
declare actions from the namespace of it's own name; for example
actions <code class="literal">org.foobar.action-a</code>, <code class="literal">org.foobar.action-b</code>
and <code class="literal">org.foobar.action-c</code> would all go into the
file <code class="literal">org.foobar.policy</code> while
actions <code class="literal">com.my-company.product-awesome.action-a</code>, <code class="literal">com.mycompany.product-awesome.action-b</code>
would go into the
file <code class="literal">com.mycompany.product-awesome.policy</code>.
</p>
<p>
An example of a <code class="literal">.policy</code> file would be the following:
</p>
<pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
"http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">
<policyconfig>
<vendor>The PolicyKit Project</vendor>
<vendor_url>http://hal.freedesktop.org/docs/PolicyKit/</vendor_url>
<icon_name>polkit-icon</icon_name>
<action id="org.gnome.policykit.examples.frobnicate">
<description>Frobnicate</description>
<description xml:lang="da">Frobniker</description>
<description xml:lang="en_CA">Frobnicate, Aye!</description>
<message>System policy prevents the PolicyKit-gnome example helper from Frobnicating</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Frobnikere!</message>
<message xml:lang="en_CA">System policy prevents the PolicyKit-gnome example helper from Frobnicating, Aye!</message>
<icon_name>polkit-icon-frobnicate</icon_name>
<vendor_url>http://hal.freedesktop.org/docs/PolicyKit/about-frobnicating</vendor_url>
<defaults>
<allow_any>no</allow_any>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.tweak">
<description>Tweak</description>
<description xml:lang="da">Tvæk</description>
<description xml:lang="en_CA">Tweak, Aye!</description>
<message>System policy prevents the PolicyKit-gnome example helper from Tweaking</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Tvække!</message>
<message xml:lang="en_CA">System policy prevents the PolicyKit-gnome example helper from Tweaking, Aye!</message>
<!-- just inherit icon_name and vendor_url -->
<defaults>
<allow_any>no</allow_any>
<allow_inactive>no</allow_inactive>
<allow_active>auth_admin</allow_active>
</defaults>
</action>
</policyconfig>
</pre>
<p>
The policy declaration includes:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
<span class="emphasis"><em>Action Identifier:</em></span> This identifies
the action and can only contain the
characters <code class="literal">[a-z][0-9].-</code>,
e.g. lower-case ASCII, digits, period and hyphen. In
addition the identifier needs to start with a lower-case
ASCII character. The rationale for having everything is
lower case is to make it easy to make a distinction
between PolicyKit actions and D-Bus methods / interfaces
as the latter is normally using CamelCase.
</p>
<p>
In order for the identifier to be unique, it is
recommended that a revser domain name is chosen, for
example if the company Acme Inc. has a product called
Frakker that exports two Actions Blit and Blop the action
names should be chosen
as <code class="literal">com.acme.frakker.blit</code>
and <code class="literal">com.acme.frakker.blop</code>.
</p>
</li>
<li class="listitem"><p>
<span class="emphasis"><em>Defaults:</em></span>
The <code class="literal">allow_any</code>, <code class="literal">allow_inactive</code>
and <code class="literal">allow_active</code> tags specify the
default answer that <code class="literal">libpolkit</code> will
return for respectively any, inactive and active
sessions. See below for valid values and their
meaning. Any of these elements, including the
enclosing <code class="literal">defaults</code> elements may be
omitted.
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>Textual descriptions:</em></span> Simply included
for convenience and organizational purposes. Useful for
graphical editors for
authorizations. Standard <code class="literal">xml:lang</code>
mechnanisms are used to convey localized strings (note
that intltool 0.36 or greater includes native support for
handling <code class="literal">.policy</code> files).
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>Vendor:</em></span> The <code class="literal">vendor</code>
and <code class="literal">vendor_url</code> describes who is
supplying the action. Both can be set at the top-level of
the <code class="literal">.policy</code> file and each Action can
further override it. These tags are optional.
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>Icon:</em></span>
The <code class="literal">icon_name</code> tag can be used to
specify an icon name for the action or group of
actions. The name must adhere to the freedesktop.org Icon
Naming spec (for theming purposes) and cannot include
directory separators and must not include filename
extensions like <code class="literal">.png</code>. Like with vendor
tags, this tag can be set at the top level and also be
specialized for each individual action. This tag is
optional.
</p></li>
</ul></div>
<p>
The following values for the defaults are
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
<span class="emphasis"><em>no</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_self_one_shot</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_self</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_self_keep_session</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_self_keep_always</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_admin_one_shot</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_admin</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_admin_keep_session</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>auth_admin_keep_always</em></span>
</p></li>
<li class="listitem"><p>
<span class="emphasis"><em>yes</em></span>
</p></li>
</ul></div>
<p>
The main point here is that individual upstream software
projects can provide sensible defaults, e.g. it's sensible for
the example with a dial-up mechanism to configure
the <code class="literal">org.freedesktop.networkmanager.dialup-trusted</code> Action to
return <span class="emphasis"><em>yes</em></span> for local active sessions and
the Action
<code class="literal">org.freedesktop.networkmanager.dialup-untrusted</code> to perhaps
return <span class="emphasis"><em>auth_admin_keep_session</em></span>. See
<a class="xref" href="beyond-defaults.html" title="Beyond the Defaults">the section called “Beyond the Defaults”</a> for how individual machines
and sites can customize this.
</p>
<p>
The <code class="literal">polkit-list-actions</code>(1) tool will list all
the Actions known to <code class="literal">libpolkit</code> in a
convenient
format. The <code class="literal">polkit-policy-file-validate</code>(1)
tool can be used to check policy files as part of the software
release and installation process.
</p>
<div class="sect2" title="Annotations">
<div class="titlepage"><div><div><h3 class="title">
<a name="conf-declaring-actions-annotations"></a>Annotations</h3></div></div></div>
<p>
When declaring an Action, one can also annotate it with one or
more key/value pairs:
</p>
<pre class="programlisting">
<action id="com.example.blahblaster.run-as-root">
<description>Run the graphical BlahBlaster application as the super user</description>
<message>System policy prevents the BlahBlaster application</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_admin</allow_active>
</defaults>
<annotate key="org.freedesktop.PolicyKit.run-as-superuser.path">/usr/bin/BlahBlaster</annotate>
</action>
</pre>
<p>
This is useful when writing an extensible Mechanism that other
applications wants to use. The example declaration above is
dealing with an (hypothetical and setuid root) mechanism,
let's call it
<code class="literal">run-as-superuser</code>, that can start graphical
applications as uid 0. Suppose the user invokes it like this
</p>
<pre class="programlisting">
run-as-superuser /usr/bin/BlahBlaster
</pre>
<p>
Now, the <code class="literal">run-as-superuser</code> mechanism is only
passed a path to the application to start. In order to
determine if the calling user is allowed to run the given
application as root, we need to determine the PolicyKit Action
and then use libpolkit as usual to get an answer (and possibly
make the user authenticate to gain the privilege to run the
application). By using annotations,
the <code class="literal">run-as-superuser</code> mechanism can query
what the action is simply by searching for the Action that has
an annotation
where <code class="literal">org.freedesktop.PolicyKit.run-as-superuser.path</code>
equals the given path,
e.g. <code class="literal">/usr/bin/BlahBlaster</code>. It then becomes
part of the documentation for
the <code class="literal">run-as-superuser</code> program to specify
that applications wanting to use it, simply just needs to
provide a PolicyKit <code class="literal">.policy</code> file that
declares an Action with an
annotation <code class="literal">org.freedesktop.PolicyKit.run-as-superuser.path</code>
whose value is the path to the binary.
</p>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.14</div>
</body>
</html>
ACC SHELL 2018