Clarify pkexec(1) variables

Signed-off-by: David Zeuthen <davidz@redhat.com>

5 files changed, 42 insertions, 38 deletions

diff --git a/actions/org.freedesktop.policykit.policy.in b/actions/org.freedesktop.policykit.policy.in
index 23608ee..7400b08 100644
--- a/actions/org.freedesktop.policykit.policy.in
+++ b/actions/org.freedesktop.policykit.policy.in
@@ -1,16 +1,15 @@
-<?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/policyconfig.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD polkit Policy Configuration 1.0//EN"
+"http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
 
-<!-- Policy definitions for core PolicyKit actions. Copyright (c) 2008 Red Hat, Inc. -->
+<!-- Policy definitions for core polkit actions. Copyright (c) 2008-2012 Red Hat, Inc. -->
 
 <policyconfig>
-  <vendor>The PolicyKit Project</vendor>
-  <vendor_url>http://hal.freedesktop.org/docs/PolicyKit/</vendor_url>
+  <vendor>The polkit project</vendor>
+  <vendor_url>http://www.freedesktop.org/wiki/Software/polkit/</vendor_url>
 
   <action id="org.freedesktop.policykit.exec">
-    <_description>Run programs as another user</_description>
+    <_description>Run a program as another user</_description>
     <_message>Authentication is required to run a program as another user</_message>
     <defaults>
       <allow_any>auth_admin</allow_any>
@@ -19,14 +18,4 @@
     </defaults>
   </action>
 
-  <action id="org.freedesktop.policykit.lockdown">
-    <_description>Configure lock down for an action</_description>
-    <_message>Authentication is required to configure lock down policy</_message>
-    <defaults>
-      <allow_any>no</allow_any>
-      <allow_inactive>no</allow_inactive>
-      <allow_active>auth_admin</allow_active>
-    </defaults>
-    <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/pklalockdown</annotate>
-  </action>
 </policyconfig>
diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml
index d84aa1d..236f9f1 100644
--- a/docs/man/pkexec.xml
+++ b/docs/man/pkexec.xml
@@ -82,8 +82,8 @@
   <refsect1 id="pkexec-security-notes"><title>SECURITY NOTES</title>
     <para>
       Executing a program as another user is a privileged
-      operation. By default the required authorization (See
-      <xref linkend="pkexec-required-authz"/>) requires administrator
+      operation. By default the action to check for (see
+      <xref linkend="pkexec-action"/>) requires administrator
       authentication. In addition, the authentication dialog presented
       to the user will display the full path to the program to be
       executed so the user is aware of what will happen.
@@ -125,7 +125,7 @@
     </para>
   </refsect1>
 
-  <refsect1 id="pkexec-required-authz"><title>REQUIRED AUTHORIZATIONS</title>
+  <refsect1 id="pkexec-action"><title>ACTION AND AUTHORIZATIONS</title>
     <para>
       By default, the
       <emphasis>org.freedesktop.policykit.exec</emphasis> action is
@@ -134,10 +134,13 @@
       annotation on an action with the value set to the full path of
       the program. In addition to specifying the program, the
       authentication message, description, icon and defaults can be
-      specified. The strings <literal>$(user)</literal>,
-      <literal>$(program)</literal> and
-      <literal>$(command_line)</literal> in the message will be
-      expanded, see <xref linkend="pkexec-variables"/>.
+      specified.
+    </para>
+    <para>
+      Note that authentication messages may reference variables (see
+      <xref linkend="pkexec-variables"/>), for example
+      <literal>$(user)</literal> will be expanded to the value of the
+      <literal>user</literal> variable.
     </para>
   </refsect1>
 
@@ -178,7 +181,7 @@
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><emphasis>user_full</emphasis></term>
+        <term><emphasis>user.gecos</emphasis></term>
         <listitem>
           <para>
             The full name of the user to execute the program as.
@@ -186,6 +189,17 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><emphasis>user.display</emphasis></term>
+        <listitem>
+          <para>
+            A representation of the user to execute the program as
+            that is suitable for display in an authentication dialog.
+            Is typically set to a combination of the user name and the
+            full name.
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
   </refsect1>
diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index 9718541..bd39299 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -486,7 +486,7 @@ System Context         |                        |
       <literal>polkit</literal> object (of type <type>Polkit</type>).
     </para>
 
-    <refsect2 id="polkit-rules-actions">
+    <refsect2 id="polkit-rules-polkit">
       <title>The <type>Polkit</type> type</title>
 
       <para>
@@ -616,10 +616,10 @@ polkit.addRule(function(action, subject) {
 });
 ]]></programlisting>
       <para>
-        will produce the following when the user runs 'pkexec bash -i' from a shelll:
+        will produce the following when the user runs 'pkexec -u bateman bash -i' from a shell:
       </para>
       <programlisting><![CDATA[
-May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user_full='root (root)' user='root']
+May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user='bateman' user.gecos='Patrick Bateman' user.display='Patrick Bateman (bateman)']
 May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:4: subject=[Subject pid=1352 user='davidz' groups=davidz,wheel, seat='seat0' session='1' local=true active=true]
 ]]></programlisting>
 
diff --git a/src/examples/org.freedesktop.policykit.examples.pkexec.policy.in b/src/examples/org.freedesktop.policykit.examples.pkexec.policy.in
index 9c05b77..049c024 100644
--- a/src/examples/org.freedesktop.policykit.examples.pkexec.policy.in
+++ b/src/examples/org.freedesktop.policykit.examples.pkexec.policy.in
@@ -1,15 +1,14 @@
 <?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/policyconfig.dtd">
+<!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD polkit Policy Configuration 1.0//EN"
+"http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
 <policyconfig>
 
-  <vendor>Examples for the PolicyKit Project</vendor>
-  <vendor_url>http://hal.freedesktop.org/docs/PolicyKit/</vendor_url>
+  <vendor>Examples for the polkit project</vendor>
+  <vendor_url>http://www.freedesktop.org/wiki/Software/polkit/</vendor_url>
 
   <action id="org.freedesktop.policykit.example.pkexec.run-frobnicate">
-    <_description>Run the PolicyKit example program Frobnicate</_description>
-    <_message>Authentication is required to run the PolicyKit example program Frobnicate (user=$(user), program=$(program), command_line=$(command_line))</_message>
+    <_description>Run the polkit example program Frobnicate</_description>
+    <_message>Authentication is required to run the polkit example program Frobnicate (user=$(user), user.gecos=$(user.gecos), user.display=$(user.display), program=$(program), command_line=$(command_line))</_message>
     <icon_name>audio-x-generic</icon_name> <!-- just an example -->
     <defaults>
       <allow_any>no</allow_any>
diff --git a/src/programs/pkexec.c b/src/programs/pkexec.c
index db13cf9..d87825c 100644
--- a/src/programs/pkexec.c
+++ b/src/programs/pkexec.c
@@ -669,11 +669,13 @@ main (int argc, char *argv[])
 
   details = polkit_details_new ();
   polkit_details_insert (details, "user", pw->pw_name);
+  if (pw->pw_gecos != NULL)
+    polkit_details_insert (details, "user.gecos", pw->pw_gecos);
   if (pw->pw_gecos != NULL && strlen (pw->pw_gecos) > 0)
     s = g_strdup_printf ("%s (%s)", pw->pw_gecos, pw->pw_name);
   else
     s = g_strdup_printf ("%s", pw->pw_name);
-  polkit_details_insert (details, "user_full", s);
+  polkit_details_insert (details, "user.display", s);
   g_free (s);
   polkit_details_insert (details, "program", path);
   polkit_details_insert (details, "command_line", command_line);
@@ -696,7 +698,7 @@ main (int argc, char *argv[])
                                   * be expanded to the path of the program e.g. "/bin/bash" and the latter
                                   * to the user e.g. "John Doe (johndoe)" or "johndoe".
                                   */
-                                 N_("Authentication is needed to run `$(program)' as user $(user)"));
+                                 N_("Authentication is needed to run `$(program)' as user $(user.display)"));
         }
     }
   polkit_details_insert (details, "polkit.gettext_domain", GETTEXT_PACKAGE);