|  |  |  | PolicyKit Library Reference Manual |  | 
|---|
      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.
    
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.