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