diff options
Diffstat (limited to 'doc/spec/polkit-spec-configuration.xml')
| -rw-r--r-- | doc/spec/polkit-spec-configuration.xml | 295 |
1 files changed, 0 insertions, 295 deletions
diff --git a/doc/spec/polkit-spec-configuration.xml b/doc/spec/polkit-spec-configuration.xml deleted file mode 100644 index 63b432c..0000000 --- a/doc/spec/polkit-spec-configuration.xml +++ /dev/null @@ -1,295 +0,0 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> - -<chapter id="polkit-conf"> - <title>PolicyKit configuration</title> - - <sect1 id="conf-declaring-actions"> - <title>Declaring Actions</title> - - <para> - A Mechanism needs to declare what Actions it supports. This is - achieved by dropping one or more XML files with the suffix <literal>.policy</literal> - into the <literal>/usr/share/PolicyKit/policy</literal> directory. - </para> - <para> - 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 <literal>org.foobar.action-a</literal>, <literal>org.foobar.action-b</literal> - and <literal>org.foobar.action-c</literal> would all go into the - file <literal>org.foobar.policy</literal> while - actions <literal>com.my-company.product-awesome.action-a</literal>, <literal>com.mycompany.product-awesome.action-b</literal> - would go into the - file <literal>com.mycompany.product-awesome.policy</literal>. - </para> - <para> - An example of a <literal>.policy</literal> file would be the following: - </para> - <programlisting> - <![CDATA[ -<?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> -]]> - </programlisting> - <para> - The policy declaration includes: - <itemizedlist> - <listitem> - <para> - <emphasis>Action Identifier:</emphasis> This identifies - the action and can only contain the - characters <literal>[a-z][0-9].-</literal>, - 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. - </para><para> - 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 <literal>com.acme.frakker.blit</literal> - and <literal>com.acme.frakker.blop</literal>. - </para> - </listitem> - <listitem> - <para> - <emphasis>Defaults:</emphasis> - The <literal>allow_any</literal>, <literal>allow_inactive</literal> - and <literal>allow_active</literal> tags specify the - default answer that <literal>libpolkit</literal> will - return for respectively any, inactive and active - sessions. See below for valid values and their - meaning. Any of these elements, including the - enclosing <literal>defaults</literal> elements may be - omitted. - </para> - </listitem> - <listitem> - <para> - <emphasis>Textual descriptions:</emphasis> Simply included - for convenience and organizational purposes. Useful for - graphical editors for - authorizations. Standard <literal>xml:lang</literal> - mechnanisms are used to convey localized strings (note - that intltool 0.36 or greater includes native support for - handling <literal>.policy</literal> files). - </para> - </listitem> - <listitem> - <para> - <emphasis>Vendor:</emphasis> The <literal>vendor</literal> - and <literal>vendor_url</literal> describes who is - supplying the action. Both can be set at the top-level of - the <literal>.policy</literal> file and each Action can - further override it. These tags are optional. - </para> - </listitem> - <listitem> - <para> - <emphasis>Icon:</emphasis> - The <literal>icon_name</literal> 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 <literal>.png</literal>. 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. - </para> - </listitem> - </itemizedlist> - The following values for the defaults are - <itemizedlist> - <listitem> - <para> - <emphasis>no</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_self_one_shot</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_self</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_self_keep_session</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_self_keep_always</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_admin_one_shot</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_admin</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_admin_keep_session</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>auth_admin_keep_always</emphasis> - </para> - </listitem> - <listitem> - <para> - <emphasis>yes</emphasis> - </para> - </listitem> - </itemizedlist> - 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 <literal>org.freedesktop.networkmanager.dialup-trusted</literal> Action to - return <emphasis>yes</emphasis> for local active sessions and - the Action - <literal>org.freedesktop.networkmanager.dialup-untrusted</literal> to perhaps - return <emphasis>auth_admin_keep_session</emphasis>. See - <xref linkend="beyond-defaults"/> for how individual machines - and sites can customize this. - </para> - - <para> - The <literal>polkit-list-actions</literal>(1) tool will list all - the Actions known to <literal>libpolkit</literal> in a - convenient - format. The <literal>polkit-policy-file-validate</literal>(1) - tool can be used to check policy files as part of the software - release and installation process. - </para> - - <sect2 id="conf-declaring-actions-annotations"> - <title>Annotations</title> - <para> - When declaring an Action, one can also annotate it with one or - more key/value pairs: - </para> - <programlisting> - <![CDATA[ - <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> -]]> - </programlisting> - <para> - 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 - <literal>run-as-superuser</literal>, that can start graphical - applications as uid 0. Suppose the user invokes it like this - </para> - <programlisting> - run-as-superuser /usr/bin/BlahBlaster - </programlisting> - <para> - Now, the <literal>run-as-superuser</literal> 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 <literal>run-as-superuser</literal> mechanism can query - what the action is simply by searching for the Action that has - an annotation - where <literal>org.freedesktop.PolicyKit.run-as-superuser.path</literal> - equals the given path, - e.g. <literal>/usr/bin/BlahBlaster</literal>. It then becomes - part of the documentation for - the <literal>run-as-superuser</literal> program to specify - that applications wanting to use it, simply just needs to - provide a PolicyKit <literal>.policy</literal> file that - declares an Action with an - annotation <literal>org.freedesktop.PolicyKit.run-as-superuser.path</literal> - whose value is the path to the binary. - </para> - - </sect2> - </sect1> - - <sect1 id="beyond-defaults"> - <title>Beyond the Defaults</title> - - <para> - 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> - -</chapter> |