PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Wed Jul 15 14:11:52 PDT 2009
data/org.freedesktop.PolicyKit1.service.in | 2
docs/man/Makefile.am | 8
docs/man/PolicyKit-1.xml | 438 -----------------------------
docs/man/pkaction.xml | 4
docs/man/pkcheck.xml | 4
docs/man/pkexec.xml | 4
docs/man/polkit.xml | 438 +++++++++++++++++++++++++++++
docs/man/polkitd-1.xml | 67 ----
docs/man/polkitd.xml | 67 ++++
docs/polkit/Makefile.am | 3
docs/polkit/polkit-1-docs.xml | 4
src/polkitd/Makefile.am | 8
12 files changed, 524 insertions(+), 523 deletions(-)
New commits:
commit 002ce3d1364f7db00989d19e49c3a137e6ce6404
Author: David Zeuthen <davidz at redhat.com>
Date: Wed Jul 15 17:08:41 2009 -0400
Rename some man pages and the daemon binary
diff --git a/data/org.freedesktop.PolicyKit1.service.in b/data/org.freedesktop.PolicyKit1.service.in
index 09abeed..5a54ca1 100644
--- a/data/org.freedesktop.PolicyKit1.service.in
+++ b/data/org.freedesktop.PolicyKit1.service.in
@@ -1,4 +1,4 @@
[D-BUS Service]
Name=org.freedesktop.PolicyKit1
-Exec=@libexecdir@/polkitd-1
+Exec=@libexecdir@/polkitd
User=root
diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am
index 7804a46..6a2cf2b 100644
--- a/docs/man/Makefile.am
+++ b/docs/man/Makefile.am
@@ -4,8 +4,8 @@ NULL =
if MAN_PAGES_ENABLED
man_MANS = \
- PolicyKit-1.8 \
- polkitd-1.8 \
+ polkit.8 \
+ polkitd.8 \
pkexec.1 \
pkcheck.1 \
pkaction.1 \
@@ -17,11 +17,11 @@ man_MANS = \
endif # MAN_PAGES_ENABLED
EXTRA_DIST = \
- PolicyKit-1.xml \
+ polkit.xml \
+ polkitd.xml \
pkexec.xml \
pkcheck.xml \
pkaction.xml \
- polkitd-1.xml \
$(NULL)
clean-local:
diff --git a/docs/man/PolicyKit-1.xml b/docs/man/PolicyKit-1.xml
deleted file mode 100644
index e56b470..0000000
--- a/docs/man/PolicyKit-1.xml
+++ /dev/null
@@ -1,438 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<refentry id="PolicyKit-1.8" xmlns:xi="http://www.w3.org/2003/XInclude">
- <refentryinfo>
- <title>PolicyKit-1</title>
- <date>January 2009</date>
- <productname>PolicyKit-1</productname>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>PolicyKit-1</refentrytitle>
- <manvolnum>8</manvolnum>
- <refmiscinfo class="version"></refmiscinfo>
- </refmeta>
-
- <refnamediv>
- <refname>PolicyKit-1</refname>
- <refpurpose>Authorization API</refpurpose>
- </refnamediv>
-
- <refsect1 id="PolicyKit-1-overview"><title>OVERVIEW</title>
- <para>
- PolicyKit provides an authorization API intended to be used by
- privileged programs (<quote>MECHANISMS</quote>) offering service
- to unprivileged programs (<quote>CLIENTS</quote>) through some
- form of IPC mechanism such as D-Bus or Unix pipes. In this
- scenario, the mechanism typically treats the client as
- untrusted. For every request from a client, the mechanism needs
- to determine if the request is authorized or if it should refuse
- to service the client. Using the PolicyKit API, a mechanism can
- offload this decision to a trusted party: The PolicyKit
- Authority.
- </para>
-
- <para>
- In addition to acting as an authority, PolicyKit allows users to
- obtain temporary authorization through authenticating either an
- administrative user or the owner of the session the client
- belongs to. This is useful for scenarios where a mechanism needs
- to verify that the operator of the system really is the user or
- really is an administrative user.
- </para>
-
- </refsect1>
-
- <refsect1 id="PolicyKit-1-system-architecture"><title>SYSTEM ARCHITECTURE</title>
- <para>
- The system architecture of PolicyKit is comprised of
- the <emphasis>Authority</emphasis> (implemented as a service on
- the system message bus) and a
- <emphasis>Authentication Agent</emphasis> per user session
- (provided and started by the user session e.g. GNOME or KDE).
- Additionally, PolicyKit supports a number of extension points –
- specifically, vendors and/or sites can write extensions to
- completely control authorization policy. In a block diagram, the
- architecture looks like this:
- </para>
- <mediaobject id="polkit-architecture">
- <imageobject>
- <imagedata fileref="polkit-architecture.png" format="PNG"/>
- </imageobject>
- <textobject>
- <programlisting><![CDATA[
- +-------------------+
- | Authentication |
- | Agent |
- +-------------------+
- | libpolkit-agent-1 |
- +-------------------+
- ^ +--------+
- | | Client |
- +--------------+ +--------+
- | ^
- | |
-User Session | |
-=======================|========================|=============
-System Context | |
- | |
- | +---+
- V |
- /------------\ |
- | System Bus | |
- \------------/ |
- ^ ^ V
- | | +---------------------+
- +--------------+ | | Mechanism |
- | | +---------------------+
- V +----> | libpolkit-gobject-1 |
-+------------------+ +---------------------+
-| org.freedesktop. |
-| PolicyKit1 |
-+------------------+
-| Backends and |
-| Extensions |
-+------------------+
-]]></programlisting>
- </textobject>
- </mediaobject>
- <para>
- For convenience, the <literal>libpolkit-gobject-1</literal>
- library wraps the PolicyKit D-Bus API using GObject. However, a
- mechanism can also use the D-Bus API or the
- <citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- command to check authorizations.
- </para>
-
- <para>
- The <literal>libpolkit-agent-1</literal> library provides an
- abstraction of the native authentication system, e.g.
- <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- and also facilities registration and communication with the
- PolicyKit D-Bus service.
- </para>
-
- <para>
- PolicyKit extensions and authority backends are implemented
- using the
- <literal>libpolkit-backend-1</literal> library.
- </para>
-
- <para>
- See the
- <ulink url="file:///usr/share/gtk-doc/html/polkit-1/index.html">developer
- documentation</ulink> for more information about using and
- extending PolicyKit.
- </para>
- </refsect1>
-
- <refsect1 id="PolicyKit-1-authentication-agents"><title>AUTHENTICATION AGENTS</title>
- <para>
- An authentication agent is used to make the user of a session
- prove that the user of the session really is the user (by
- authenticating as the user) or an administrative user (by
- authenticating as a administrator). In order to integrate well
- with the rest of the user session (e.g. match the look and
- feel), authentication agents are meant to be provided by the
- user session that the user uses. For example, an authentication
- agent may look like this:
- </para>
- <mediaobject id="polkit-authentication-agent-example">
- <imageobject>
- <imagedata fileref="polkit-authentication-agent-example.png" format="PNG"/>
- </imageobject>
- <textobject>
- <programlisting><![CDATA[
-+----------------------------------------------------------+
-| Authenticate [X] |
-+----------------------------------------------------------+
-| |
-| [Icon] Authentication is required to run ATA SMART |
-| self tests |
-| |
-| An application is attempting to perform an |
-| action that requires privileges. Authentication |
-| as the super user is required to perform this |
-| action. |
-| |
-| Password for root: [_________________________] |
-| |
-| [V] Details: |
-| Drive: ATA INTEL SSDSA2MH08 (045C) |
-| Device: /dev/sda |
-| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
-| Vendor: The DeviceKit Project |
-| |
-| [Cancel] [Authenticate] |
-+----------------------------------------------------------+
-]]></programlisting>
- </textobject>
- </mediaobject>
- <para>
- If the system is configured without a <emphasis>root</emphasis>
- account it may allow you to select the administrative user who
- is authenticating:
- </para>
- <mediaobject id="polkit-authentication-agent-example-wheel">
- <imageobject>
- <imagedata fileref="polkit-authentication-agent-example-wheel.png" format="PNG"/>
- </imageobject>
- <textobject>
- <programlisting><![CDATA[
-+----------------------------------------------------------+
-| Authenticate [X] |
-+----------------------------------------------------------+
-| |
-| [Icon] Authentication is required to run ATA SMART |
-| self tests |
-| |
-| An application is attempting to perform an |
-| action that requires privileges. Authentication |
-| as one of the users below is required to |
-| perform this action. |
-| |
-| [[Face] Patrick Bateman (bateman) [V]] |
-| |
-| Password for bateman: [______________________] |
-| |
-| [V] Details: |
-| Drive: ATA INTEL SSDSA2MH08 (045C) |
-| Device: /dev/sda |
-| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
-| Vendor: The DeviceKit Project |
-| |
-| [Cancel] [Authenticate] |
-+----------------------------------------------------------+
-]]></programlisting>
- </textobject>
- </mediaobject>
- <para>
- See <xref linkend="pkla"/> for how to set up the local authority
- implemention for systems without a <literal>root</literal>
- account.
- </para>
- </refsect1>
-
- <refsect1 id="PolicyKit-1-declaring-actions"><title>DECLARING ACTIONS</title>
- <para>
- A mechanism need to declare a set of <quote>ACTIONS</quote> in
- order to use PolicyKit. Actions correspond to operations that
- clients can request the mechanism to carry out and are defined
- in XML files that the mechanism installs into
- the <filename>/usr/share/polkit-1/actions</filename> directory.
- </para>
-
- <para>
- PolicyKit actions are namespaced and can only contain the
- characters <literal>[a-z][0-9].-</literal> e.g. lower-case
- ASCII, digits, period and hyphen. Each XML file can contain more
- than one action but all actions need to be in the same namespace
- and the file needs to be named after the namespace and have the
- extension <literal>.policy</literal>.
- </para>
-
- <para>
- The XML file must have the following doctype declaration
- </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">
-]]></programlisting>
- <para>
- The <emphasis>policyconfig</emphasis> element must be present
- exactly once. Elements that can be used
- inside <emphasis>policyconfig</emphasis> includes:
- </para>
- <variablelist>
- <varlistentry>
- <term><emphasis>vendor</emphasis></term>
- <listitem><para>The name of the project or vendor that is
- supplying the actions in the XML
- document. Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>vendor_url</emphasis></term>
- <listitem><para>A URL to the project or vendor that is
- supplying the actions in the XML document.
- Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>icon_name</emphasis></term>
- <listitem><para>An icon representing the project or vendor
- that is supplying the actions in the XML document. The icon
- name must adhere to
- the <ulink url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Freedesktop.org
- Icon Naming Specification</ulink>. Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>action</emphasis></term>
- <listitem><para>Declares an action. The action name is
- specified using the <literal>id</literal> attribute and can
- only contain the characters <literal>[a-z][0-9].-</literal>
- e.g. lower-case ASCII, digits, period and
- hyphen.</para></listitem>
- </varlistentry>
- </variablelist>
- <para>
- Elements that can be used inside <emphasis>action</emphasis> includes:
- </para>
- <variablelist>
- <varlistentry>
- <term><emphasis>description</emphasis></term>
- <listitem><para>A human readable description of the action, e.g. <quote>Install unsigned software</quote>.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>message</emphasis></term>
- <listitem><para>A human readable message displayed to the user when asking for credentials when authentication is needed, e.g. <quote>Installing unsigned software requires authentication</quote>.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>defaults</emphasis></term>
- <listitem><para>This element is used to specify implicit authorizations for clients.</para>
- <para>
- Elements that can be used inside <emphasis>defaults</emphasis> includes:
- </para>
- <variablelist>
- <varlistentry>
- <term><emphasis>allow_any</emphasis></term>
- <listitem><para>Implicit authorizations that apply to
- any client. Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>allow_inactive</emphasis></term>
- <listitem><para>Implicit authorizations that apply to
- clients in inactive sessions on local
- consoles. Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>allow_active</emphasis></term>
- <listitem><para>Implicit authorizations that apply to
- clients in active sessions on local
- consoles. Optional.</para></listitem>
- </varlistentry>
- </variablelist>
- <para>
- Each of
- the <emphasis>allow_any</emphasis>, <emphasis>allow_inactive</emphasis>
- and <emphasis>allow_active</emphasis> elements can contain
- the following values:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>no</literal></term>
- <listitem><para>Not authorized.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>yes</literal></term>
- <listitem><para>Authorized.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>auth_self</literal></term>
- <listitem><para>Authentication by the owner of the
- session that the client originates from is
- required.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>auth_admin</literal></term>
- <listitem><para>Authentication by an administrative user
- is required.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>auth_self_keep</literal></term>
- <listitem><para>Like <literal>auth_self</literal> but
- the authorization is kept for a brief
- period.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>auth_admin_keep</literal></term>
- <listitem><para>Like <literal>auth_admin</literal> but the authorization is kept for a brief period.</para></listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>annotate</emphasis></term>
- <listitem><para>Used for annotating an action with a key/value
- pair. The key is specified using the
- the <literal>key</literal> attribute and the value is
- specified using the <literal>value</literal> attribute. This
- element may appear zero or more times. See
- <citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- for an example of how this can be used. </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>vendor</emphasis></term>
- <listitem><para>Used for overriding the vendor on a per-action
- basis. Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>vendor_url</emphasis></term>
- <listitem><para>Used for overriding the vendor URL on a
- per-action basis. Optional.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>icon_name</emphasis></term>
- <listitem><para>Used for overriding the icon name on a
- per-action basis. Optional.</para></listitem>
- </varlistentry>
- </variablelist>
- <para>
- For localization, <emphasis>description</emphasis>
- and <emphasis>message</emphasis> elements may occur multiple
- times with different <literal>xml:lang</literal> attributes.
- </para>
- <para>
- To list installed PolicyKit actions, use the
- <citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- command.
- </para>
- </refsect1>
-
- <refsect1 id="pkla"><title>LOCAL AUTHORITY IMPLEMENTATION</title>
- <para>
- The default authority implementation in PolicyKit is using the
- local filesystem to store authorizations. TODO: write some more
- here including a link to a
- <citerefentry><refentrytitle>pklamanage</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- command.
- </para>
- </refsect1>
-
- <refsect1 id="PolicyKit-1-author"><title>AUTHOR</title>
- <para>
- Written by David Zeuthen <email>davidz at redhat.com</email> with
- a lot of help from many others.
- </para>
- </refsect1>
-
- <refsect1 id="PolicyKit-1-bugs">
- <title>BUGS</title>
- <para>
- Please send bug reports to either the distribution or the
- polkit-devel mailing list,
- see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
- on how to subscribe.
- </para>
- </refsect1>
-
- <refsect1 id="PolicyKit-1-see-also">
- <title>SEE ALSO</title>
- <para>
- <citerefentry>
- <refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>polkitd-1</refentrytitle><manvolnum>8</manvolnum>
- </citerefentry>
- </para>
- </refsect1>
-</refentry>
diff --git a/docs/man/pkaction.xml b/docs/man/pkaction.xml
index 6a54384..ba91e9a 100644
--- a/docs/man/pkaction.xml
+++ b/docs/man/pkaction.xml
@@ -7,7 +7,7 @@
<refentryinfo>
<title>pkaction</title>
<date>May 2009</date>
- <productname>PolicyKit-1</productname>
+ <productname>polkit</productname>
</refentryinfo>
<refmeta>
@@ -93,7 +93,7 @@
<title>SEE ALSO</title>
<para>
<citerefentry>
- <refentrytitle>PolicyKit-1</refentrytitle><manvolnum>8</manvolnum>
+ <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
diff --git a/docs/man/pkcheck.xml b/docs/man/pkcheck.xml
index 15ff1fc..c3c5bc0 100644
--- a/docs/man/pkcheck.xml
+++ b/docs/man/pkcheck.xml
@@ -7,7 +7,7 @@
<refentryinfo>
<title>pkcheck</title>
<date>May 2009</date>
- <productname>PolicyKit-1</productname>
+ <productname>polkit</productname>
</refentryinfo>
<refmeta>
@@ -164,7 +164,7 @@ KEY3=VALUE3
<title>SEE ALSO</title>
<para>
<citerefentry>
- <refentrytitle>PolicyKit-1</refentrytitle><manvolnum>8</manvolnum>
+ <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml
index 98da6b8..0847c2e 100644
--- a/docs/man/pkexec.xml
+++ b/docs/man/pkexec.xml
@@ -7,7 +7,7 @@
<refentryinfo>
<title>pkexec</title>
<date>May 2009</date>
- <productname>PolicyKit-1</productname>
+ <productname>polkit</productname>
</refentryinfo>
<refmeta>
@@ -249,7 +249,7 @@
<title>SEE ALSO</title>
<para>
<citerefentry>
- <refentrytitle>PolicyKit-1</refentrytitle><manvolnum>8</manvolnum>
+ <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
new file mode 100644
index 0000000..27382e0
--- /dev/null
+++ b/docs/man/polkit.xml
@@ -0,0 +1,438 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<refentry id="polkit.8" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <refentryinfo>
+ <title>polkit</title>
+ <date>January 2009</date>
+ <productname>polkit</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>polkit</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="version"></refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>polkit</refname>
+ <refpurpose>Authorization Framework</refpurpose>
+ </refnamediv>
+
+ <refsect1 id="polkit-overview"><title>OVERVIEW</title>
+ <para>
+ PolicyKit provides an authorization API intended to be used by
+ privileged programs (<quote>MECHANISMS</quote>) offering service
+ to unprivileged programs (<quote>CLIENTS</quote>) through some
+ form of IPC mechanism such as D-Bus or Unix pipes. In this
+ scenario, the mechanism typically treats the client as
+ untrusted. For every request from a client, the mechanism needs
+ to determine if the request is authorized or if it should refuse
+ to service the client. Using the PolicyKit API, a mechanism can
+ offload this decision to a trusted party: The PolicyKit
+ Authority.
+ </para>
+
+ <para>
+ In addition to acting as an authority, PolicyKit allows users to
+ obtain temporary authorization through authenticating either an
+ administrative user or the owner of the session the client
+ belongs to. This is useful for scenarios where a mechanism needs
+ to verify that the operator of the system really is the user or
+ really is an administrative user.
+ </para>
+
+ </refsect1>
+
+ <refsect1 id="polkit-system-architecture"><title>SYSTEM ARCHITECTURE</title>
+ <para>
+ The system architecture of PolicyKit is comprised of
+ the <emphasis>Authority</emphasis> (implemented as a service on
+ the system message bus) and a
+ <emphasis>Authentication Agent</emphasis> per user session
+ (provided and started by the user session e.g. GNOME or KDE).
+ Additionally, PolicyKit supports a number of extension points –
+ specifically, vendors and/or sites can write extensions to
+ completely control authorization policy. In a block diagram, the
+ architecture looks like this:
+ </para>
+ <mediaobject id="polkit-architecture">
+ <imageobject>
+ <imagedata fileref="polkit-architecture.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <programlisting><![CDATA[
+ +-------------------+
+ | Authentication |
+ | Agent |
+ +-------------------+
+ | libpolkit-agent-1 |
+ +-------------------+
+ ^ +--------+
+ | | Client |
+ +--------------+ +--------+
+ | ^
+ | |
+User Session | |
+=======================|========================|=============
+System Context | |
+ | |
+ | +---+
+ V |
+ /------------\ |
+ | System Bus | |
+ \------------/ |
+ ^ ^ V
+ | | +---------------------+
+ +--------------+ | | Mechanism |
+ | | +---------------------+
+ V +----> | libpolkit-gobject-1 |
++------------------+ +---------------------+
+| org.freedesktop. |
+| PolicyKit1 |
++------------------+
+| Backends and |
+| Extensions |
++------------------+
+]]></programlisting>
+ </textobject>
+ </mediaobject>
+ <para>
+ For convenience, the <literal>libpolkit-gobject-1</literal>
+ library wraps the PolicyKit D-Bus API using GObject. However, a
+ mechanism can also use the D-Bus API or the
+ <citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ command to check authorizations.
+ </para>
+
+ <para>
+ The <literal>libpolkit-agent-1</literal> library provides an
+ abstraction of the native authentication system, e.g.
+ <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ and also facilities registration and communication with the
+ PolicyKit D-Bus service.
+ </para>
+
+ <para>
+ PolicyKit extensions and authority backends are implemented
+ using the
+ <literal>libpolkit-backend-1</literal> library.
+ </para>
+
+ <para>
+ See the
+ <ulink url="file:///usr/share/gtk-doc/html/polkit-1/index.html">developer
+ documentation</ulink> for more information about using and
+ extending PolicyKit.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkit-authentication-agents"><title>AUTHENTICATION AGENTS</title>
+ <para>
+ An authentication agent is used to make the user of a session
+ prove that the user of the session really is the user (by
+ authenticating as the user) or an administrative user (by
+ authenticating as a administrator). In order to integrate well
+ with the rest of the user session (e.g. match the look and
+ feel), authentication agents are meant to be provided by the
+ user session that the user uses. For example, an authentication
+ agent may look like this:
+ </para>
+ <mediaobject id="polkit-authentication-agent-example">
+ <imageobject>
+ <imagedata fileref="polkit-authentication-agent-example.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <programlisting><![CDATA[
++----------------------------------------------------------+
+| Authenticate [X] |
++----------------------------------------------------------+
+| |
+| [Icon] Authentication is required to run ATA SMART |
+| self tests |
+| |
+| An application is attempting to perform an |
+| action that requires privileges. Authentication |
+| as the super user is required to perform this |
+| action. |
+| |
+| Password for root: [_________________________] |
+| |
+| [V] Details: |
+| Drive: ATA INTEL SSDSA2MH08 (045C) |
+| Device: /dev/sda |
+| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
+| Vendor: The DeviceKit Project |
+| |
+| [Cancel] [Authenticate] |
++----------------------------------------------------------+
+]]></programlisting>
+ </textobject>
+ </mediaobject>
+ <para>
+ If the system is configured without a <emphasis>root</emphasis>
+ account it may allow you to select the administrative user who
+ is authenticating:
+ </para>
+ <mediaobject id="polkit-authentication-agent-example-wheel">
+ <imageobject>
+ <imagedata fileref="polkit-authentication-agent-example-wheel.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <programlisting><![CDATA[
++----------------------------------------------------------+
+| Authenticate [X] |
++----------------------------------------------------------+
+| |
+| [Icon] Authentication is required to run ATA SMART |
+| self tests |
+| |
+| An application is attempting to perform an |
+| action that requires privileges. Authentication |
+| as one of the users below is required to |
+| perform this action. |
+| |
+| [[Face] Patrick Bateman (bateman) [V]] |
+| |
+| Password for bateman: [______________________] |
+| |
+| [V] Details: |
+| Drive: ATA INTEL SSDSA2MH08 (045C) |
+| Device: /dev/sda |
+| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |
+| Vendor: The DeviceKit Project |
+| |
+| [Cancel] [Authenticate] |
++----------------------------------------------------------+
+]]></programlisting>
+ </textobject>
+ </mediaobject>
+ <para>
+ See <xref linkend="pkla"/> for how to set up the local authority
+ implemention for systems without a <literal>root</literal>
+ account.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkit-declaring-actions"><title>DECLARING ACTIONS</title>
+ <para>
+ A mechanism need to declare a set of <quote>ACTIONS</quote> in
+ order to use PolicyKit. Actions correspond to operations that
+ clients can request the mechanism to carry out and are defined
+ in XML files that the mechanism installs into
+ the <filename>/usr/share/polkit-1/actions</filename> directory.
+ </para>
+
+ <para>
+ PolicyKit actions are namespaced and can only contain the
+ characters <literal>[a-z][0-9].-</literal> e.g. lower-case
+ ASCII, digits, period and hyphen. Each XML file can contain more
+ than one action but all actions need to be in the same namespace
+ and the file needs to be named after the namespace and have the
+ extension <literal>.policy</literal>.
+ </para>
+
+ <para>
+ The XML file must have the following doctype declaration
+ </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">
+]]></programlisting>
+ <para>
+ The <emphasis>policyconfig</emphasis> element must be present
+ exactly once. Elements that can be used
+ inside <emphasis>policyconfig</emphasis> includes:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>vendor</emphasis></term>
+ <listitem><para>The name of the project or vendor that is
+ supplying the actions in the XML
+ document. Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>vendor_url</emphasis></term>
+ <listitem><para>A URL to the project or vendor that is
+ supplying the actions in the XML document.
+ Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>icon_name</emphasis></term>
+ <listitem><para>An icon representing the project or vendor
+ that is supplying the actions in the XML document. The icon
+ name must adhere to
+ the <ulink url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Freedesktop.org
+ Icon Naming Specification</ulink>. Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>action</emphasis></term>
+ <listitem><para>Declares an action. The action name is
+ specified using the <literal>id</literal> attribute and can
+ only contain the characters <literal>[a-z][0-9].-</literal>
+ e.g. lower-case ASCII, digits, period and
+ hyphen.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Elements that can be used inside <emphasis>action</emphasis> includes:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>description</emphasis></term>
+ <listitem><para>A human readable description of the action, e.g. <quote>Install unsigned software</quote>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>message</emphasis></term>
+ <listitem><para>A human readable message displayed to the user when asking for credentials when authentication is needed, e.g. <quote>Installing unsigned software requires authentication</quote>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>defaults</emphasis></term>
+ <listitem><para>This element is used to specify implicit authorizations for clients.</para>
+ <para>
+ Elements that can be used inside <emphasis>defaults</emphasis> includes:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>allow_any</emphasis></term>
+ <listitem><para>Implicit authorizations that apply to
+ any client. Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>allow_inactive</emphasis></term>
+ <listitem><para>Implicit authorizations that apply to
+ clients in inactive sessions on local
+ consoles. Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>allow_active</emphasis></term>
+ <listitem><para>Implicit authorizations that apply to
+ clients in active sessions on local
+ consoles. Optional.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Each of
+ the <emphasis>allow_any</emphasis>, <emphasis>allow_inactive</emphasis>
+ and <emphasis>allow_active</emphasis> elements can contain
+ the following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>no</literal></term>
+ <listitem><para>Not authorized.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>yes</literal></term>
+ <listitem><para>Authorized.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>auth_self</literal></term>
+ <listitem><para>Authentication by the owner of the
+ session that the client originates from is
+ required.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>auth_admin</literal></term>
+ <listitem><para>Authentication by an administrative user
+ is required.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>auth_self_keep</literal></term>
+ <listitem><para>Like <literal>auth_self</literal> but
+ the authorization is kept for a brief
+ period.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>auth_admin_keep</literal></term>
+ <listitem><para>Like <literal>auth_admin</literal> but the authorization is kept for a brief period.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>annotate</emphasis></term>
+ <listitem><para>Used for annotating an action with a key/value
+ pair. The key is specified using the
+ the <literal>key</literal> attribute and the value is
+ specified using the <literal>value</literal> attribute. This
+ element may appear zero or more times. See
+ <citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for an example of how this can be used. </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>vendor</emphasis></term>
+ <listitem><para>Used for overriding the vendor on a per-action
+ basis. Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>vendor_url</emphasis></term>
+ <listitem><para>Used for overriding the vendor URL on a
+ per-action basis. Optional.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>icon_name</emphasis></term>
+ <listitem><para>Used for overriding the icon name on a
+ per-action basis. Optional.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ For localization, <emphasis>description</emphasis>
+ and <emphasis>message</emphasis> elements may occur multiple
+ times with different <literal>xml:lang</literal> attributes.
+ </para>
+ <para>
+ To list installed PolicyKit actions, use the
+ <citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ command.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pkla"><title>LOCAL AUTHORITY IMPLEMENTATION</title>
+ <para>
+ The default authority implementation in PolicyKit is using the
+ local filesystem to store authorizations. TODO: write some more
+ here including a link to a
+ <citerefentry><refentrytitle>pklamanage</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ command.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkit-author"><title>AUTHOR</title>
+ <para>
+ Written by David Zeuthen <email>davidz at redhat.com</email> with
+ a lot of help from many others.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkit-bugs">
+ <title>BUGS</title>
+ <para>
+ Please send bug reports to either the distribution or the
+ polkit-devel mailing list,
+ see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
+ on how to subscribe.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkit-see-also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/docs/man/polkitd-1.xml b/docs/man/polkitd-1.xml
deleted file mode 100644
index 03ea247..0000000
--- a/docs/man/polkitd-1.xml
+++ /dev/null
@@ -1,67 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<refentry id="polkitd-1.8">
- <refentryinfo>
- <title>polkitd-1</title>
- <date>May 2009</date>
- <productname>PolicyKit-1</productname>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>polkitd-1</refentrytitle>
- <manvolnum>8</manvolnum>
- <refmiscinfo class="version"></refmiscinfo>
- </refmeta>
-
- <refnamediv>
- <refname>polkitd-1</refname>
- <refpurpose>PolicyKit daemon</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>polkitd-1</command>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1 id="polkitd-1-description"><title>DESCRIPTION</title>
- <para>
- <command>polkitd-1</command> provides
- the <emphasis>org.freedesktop.PolicyKit1</emphasis> D-Bus
- service on the system message bus. Users or administrators
- should never need to start this daemon as it will be
- automatically started by
- <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- whenever an application calls into the service.
- </para>
- </refsect1>
-
- <refsect1 id="polkitd-1-author"><title>AUTHOR</title>
- <para>
- Written by David Zeuthen <email>davidz at redhat.com</email> with
- a lot of help from many others.
- </para>
- </refsect1>
-
- <refsect1 id="polkitd-1-bugs">
- <title>BUGS</title>
- <para>
- Please send bug reports to either the distribution or the
- polkit-devel mailing list,
- see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
- on how to subscribe.
- </para>
- </refsect1>
-
- <refsect1 id="polkitd-1-see-also">
- <title>SEE ALSO</title>
- <para>
- <citerefentry>
- <refentrytitle>PolicyKit-1</refentrytitle><manvolnum>8</manvolnum>
- </citerefentry>
- </para>
- </refsect1>
-</refentry>
diff --git a/docs/man/polkitd.xml b/docs/man/polkitd.xml
new file mode 100644
index 0000000..7e5cc02
--- /dev/null
+++ b/docs/man/polkitd.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<refentry id="polkitd.8">
+ <refentryinfo>
+ <title>polkitd</title>
+ <date>May 2009</date>
+ <productname>polkit</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>polkitd</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="version"></refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>polkitd</refname>
+ <refpurpose>PolicyKit daemon</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>polkitd</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="polkitd-description"><title>DESCRIPTION</title>
+ <para>
+ <command>polkitd</command> provides
+ the <emphasis>org.freedesktop.PolicyKit1</emphasis> D-Bus
+ service on the system message bus. Users or administrators
+ should never need to start this daemon as it will be
+ automatically started by
+ <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ whenever an application calls into the service.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkitd-author"><title>AUTHOR</title>
+ <para>
+ Written by David Zeuthen <email>davidz at redhat.com</email> with
+ a lot of help from many others.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkitd-bugs">
+ <title>BUGS</title>
+ <para>
+ Please send bug reports to either the distribution or the
+ polkit-devel mailing list,
+ see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
+ on how to subscribe.
+ </para>
+ </refsect1>
+
+ <refsect1 id="polkitd-see-also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/docs/polkit/Makefile.am b/docs/polkit/Makefile.am
index 39977ad..bd94167 100644
--- a/docs/polkit/Makefile.am
+++ b/docs/polkit/Makefile.am
@@ -59,7 +59,8 @@ content_files = \
../version.xml \
../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml \
../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml \
- ../man/PolicyKit-1.xml \
+ ../man/polkit.xml \
+ ../man/polkitd.xml \
../man/pkcheck.xml \
../man/pkaction.xml \
../man/pkexec.xml \
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index 0e4f70e..eeab10b 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -107,8 +107,8 @@
<part id="manpages">
<title>Manual Pages</title>
- <xi:include href="../man/PolicyKit-1.xml"/>
- <xi:include href="../man/polkitd-1.xml"/>
+ <xi:include href="../man/polkit.xml"/>
+ <xi:include href="../man/polkitd.xml"/>
<xi:include href="../man/pkcheck.xml"/>
<xi:include href="../man/pkaction.xml"/>
<xi:include href="../man/pkexec.xml"/>
diff --git a/src/polkitd/Makefile.am b/src/polkitd/Makefile.am
index c425d68..1234417 100644
--- a/src/polkitd/Makefile.am
+++ b/src/polkitd/Makefile.am
@@ -14,19 +14,19 @@ INCLUDES = \
-D_REENTRANT \
$(NULL)
-libexec_PROGRAMS = polkitd-1
+libexec_PROGRAMS = polkitd
-polkitd_1_SOURCES = \
+polkitd_SOURCES = \
main.c \
$(NULL)
-polkitd_1_CFLAGS = \
+polkitd_CFLAGS = \
-DPOLKIT_BACKEND_I_KNOW_API_IS_SUBJECT_TO_CHANGE \
-DG_LOG_DOMAIN=\"polkitd-1\" \
$(GLIB_CFLAGS) \
$(NULL)
-polkitd_1_LDADD = \
+polkitd_LDADD = \
$(DBUS_GLIB_LIBS) \
$(GLIB_LIBS) \
$(top_builddir)/src/polkit/libpolkit-gobject-1.la \
More information about the hal-commit
mailing list