PolicyKit configuration

Declaring Actions

A Mechanism needs to declare what Actions it supports. This is achieved by dropping one or more XML files with the suffix .policy into the /usr/share/PolicyKit/policy directory.

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 org.foobar.action-a, org.foobar.action-b and org.foobar.action-c would all go into the file org.foobar.policy while actions com.my-company.product-awesome.action-a, com.mycompany.product-awesome.action-b would go into the file com.mycompany.product-awesome.policy.

An example of a .policy file would be the following:

      
<?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>

The policy declaration includes:

Action Identifier: This identifies the action and can only contain the characters [a-z][0-9].-, 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.

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 com.acme.frakker.blit and com.acme.frakker.blop.
Defaults: The allow_any, allow_inactive and allow_active tags specify the default answer that libpolkit will return for respectively any, inactive and active sessions. See below for valid values and their meaning. Any of these elements, including the enclosing defaults elements may be omitted.
Textual descriptions: Simply included for convenience and organizational purposes. Useful for graphical editors for authorizations. Standard xml:lang mechnanisms are used to convey localized strings (note that intltool 0.36 or greater includes native support for handling .policy files).
Vendor: The vendor and vendor_url describes who is supplying the action. Both can be set at the top-level of the .policy file and each Action can further override it. These tags are optional.
Icon: The icon_name 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 .png. 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.

The following values for the defaults are

no
auth_self_one_shot
auth_self
auth_self_keep_session
auth_self_keep_always
auth_admin_one_shot
auth_admin
auth_admin_keep_session
auth_admin_keep_always
yes

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 org.freedesktop.networkmanager.dialup-trusted Action to return yes for local active sessions and the Action org.freedesktop.networkmanager.dialup-untrusted to perhaps return auth_admin_keep_session. See the section called “Beyond the Defaults” for how individual machines and sites can customize this.

The polkit-list-actions(1) tool will list all the Actions known to libpolkit in a convenient format. The polkit-policy-file-validate(1) tool can be used to check policy files as part of the software release and installation process.

Annotations

When declaring an Action, one can also annotate it with one or more key/value pairs:

      
  <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>

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 run-as-superuser, that can start graphical applications as uid 0. Suppose the user invokes it like this

        run-as-superuser /usr/bin/BlahBlaster

Now, the run-as-superuser 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 run-as-superuser mechanism can query what the action is simply by searching for the Action that has an annotation where org.freedesktop.PolicyKit.run-as-superuser.path equals the given path, e.g. /usr/bin/BlahBlaster. It then becomes part of the documentation for the run-as-superuser program to specify that applications wanting to use it, simply just needs to provide a PolicyKit .policy file that declares an Action with an annotation org.freedesktop.PolicyKit.run-as-superuser.path whose value is the path to the binary.