Debian Codegraph @

docs/man/pkexec.xml

raw
1 <?xml version="1.0"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY version SYSTEM "../version.xml">
5 ]>
6 <refentry id="pkexec.1" xmlns:xi="http://www.w3.org/2003/XInclude">
7 <refentryinfo>
8 <title>pkexec</title>
9 <date>May 2009</date>
10 <productname>polkit</productname>
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>pkexec</refentrytitle>
15 <manvolnum>1</manvolnum>
16 <refmiscinfo class="version"></refmiscinfo>
17 </refmeta>
18
19 <refnamediv>
20 <refname>pkexec</refname>
21 <refpurpose>Execute a command as another user</refpurpose>
22 </refnamediv>
23
24 <refsynopsisdiv>
25 <cmdsynopsis>
26 <command>pkexec</command>
27 <arg><option>--version</option></arg>
28 <arg><option>--disable-internal-agent</option></arg>
29 <arg><option>--help</option></arg>
30 </cmdsynopsis>
31
32 <cmdsynopsis>
33 <command>pkexec</command>
34 <arg choise="plain">
35 <option>--keep-cwd</option>
36 </arg>
37 <group>
38 <arg choice="plain">
39 <option>--user</option>
40 <replaceable>username</replaceable>
41 </arg>
42 </group>
43 <arg choice="plain"><replaceable>PROGRAM</replaceable></arg>
44 <group rep="repeat">
45 <arg choice="plain"><replaceable>ARGUMENTS</replaceable></arg>
46 </group>
47 </cmdsynopsis>
48
49 </refsynopsisdiv>
50
51 <refsect1 id="pkexec-description"><title>DESCRIPTION</title>
52 <para>
53 <command>pkexec</command> allows an authorized user to execute
54 <replaceable>PROGRAM</replaceable> as another user. If
55 <replaceable>PROGRAM</replaceable> is not specified, the default
56 shell will be run. If <replaceable>username</replaceable> is
57 not specified, then the program will be executed as the
58 administrative super user, <emphasis>root</emphasis>.
59 </para>
60 </refsect1>
61
62 <refsect1 id="pkexec-return-value"><title>RETURN VALUE</title>
63 <para>
64 Upon successful completion, the return value is the return value
65 of <replaceable>PROGRAM</replaceable>. If the calling process is
66 not authorized or an authorization could not be obtained through
67 authentication or an error occurred, <command>pkexec</command>
68 exits with a return value of 127. If the authorization could not
69 be obtained because the user dismissed the authentication
70 dialog, <command>pkexec</command> exits with a return value of
71 126.
72 </para>
73 </refsect1>
74
75 <refsect1 id="pkexec-auth-agent"><title>AUTHENTICATION AGENT</title>
76 <para>
77 <command>pkexec</command>, like any other polkit application,
78 will use the authentication agent registered for the calling
79 process or session. However, if no authentication agent is
80 available, then <command>pkexec</command> will register its own
81 textual authentication agent. This behavior can be turned off by
82 passing the <option>--disable-internal-agent</option> option.
83 </para>
84 </refsect1>
85
86 <refsect1 id="pkexec-security-notes"><title>SECURITY NOTES</title>
87 <para>
88 Executing a program as another user is a privileged
89 operation. By default the action to check for (see
90 <xref linkend="pkexec-action"/>) requires administrator
91 authentication. In addition, the authentication dialog presented
92 to the user will display the full path to the program to be
93 executed so the user is aware of what will happen.
94 </para>
95 <para>
96 The environment that <replaceable>PROGRAM</replaceable> will run
97 it, will be set to a minimal known and safe environment in order
98 to avoid injecting code
99 through <literal>LD_LIBRARY_PATH</literal> or similar
100 mechanisms. In addition the <literal>PKEXEC_UID</literal>
101 environment variable is set to the user id of the process
102 invoking <command>pkexec</command>. As a
103 result, <command>pkexec</command> will not by default allow you to run
104 X11 applications as another user since
105 the <literal>$DISPLAY</literal> and <literal>$XAUTHORITY</literal>
106 environment variables are not set. These two variables will be retained
107 if the <emphasis>org.freedesktop.policykit.exec.allow_gui</emphasis> annotation
108 on an action is set to a nonempty value; this is discouraged, though, and
109 should only be used for legacy programs.
110 </para>
111
112 <para>
113 <command>pkexec</command> will run <replaceable>PROGRAM</replaceable>
114 in <replaceable>username</replaceable>'s home directory, unless
115 <option>--keep-cwd</option> is used to override this behavior
116 </para>
117
118 <para>
119 Note that <command>pkexec</command> does no validation of
120 the <replaceable>ARGUMENTS</replaceable> passed
121 to <replaceable>PROGRAM</replaceable>. In the normal case (where
122 administrator authentication is required every
123 time <command>pkexec</command> is used), this is not a problem
124 since if the user is an administrator he might as well just
125 run <command>pkexec bash</command> to get root.
126 </para>
127
128 <para>
129 However, if an action is used for which the user can retain
130 authorization (or if the user is implicitly authorized) this
131 could be a security hole. Therefore, as a rule of thumb,
132 programs for which the default required authorization is
133 changed, should <emphasis role='strong'>never</emphasis> implicitly trust user input (e.g. like any
134 other well-written <emphasis>suid</emphasis> program).
135 </para>
136 </refsect1>
137
138 <refsect1 id="pkexec-action"><title>ACTION AND AUTHORIZATIONS</title>
139 <para>
140 By default, the
141 <emphasis>org.freedesktop.policykit.exec</emphasis> action is
142 used. To use another action, use the
143 <emphasis>org.freedesktop.policykit.exec.path</emphasis>
144 annotation on an action with the value set to the full path of
145 the program. In addition to specifying the program, the
146 authentication message, description, icon and defaults can be
147 specified. If the <emphasis>org.freedesktop.policykit.exec.argv1</emphasis>
148 annotation is present, the action will only be picked if the
149 first argument to the program matches the value of the annotation.
150 </para>
151 <para>
152 Note that authentication messages may reference variables (see
153 <xref linkend="pkexec-variables"/>), for example
154 <literal>$(user)</literal> will be expanded to the value of the
155 <literal>user</literal> variable.
156 </para>
157 </refsect1>
158
159 <refsect1 id="pkexec-wrapper"><title>WRAPPER USAGE</title>
160 <para>
161 To avoid modifying existing software to prefix their
162 command-line invocations with <command>pkexec</command>,
163 it's possible to use <command>pkexec</command> in a
164 <ulink url="http://en.wikipedia.org/wiki/Shebang_(Unix)">she-bang wrapper</ulink>
165 like this:
166 </para>
167 <programlisting><![CDATA[
168 #!/usr/bin/pkexec /usr/bin/python
169
170 import os
171 import sys
172
173 print "Hello, I'm running as uid %d"%(os.getuid())
174
175 for n in range(len(sys.argv)):
176 print "arg[%d]=`%s'"%(n, sys.argv[n])
177 ]]></programlisting>
178 <para>
179 If this script is installed into <filename>/usr/bin/my-pk-test</filename>,
180 then the following annotations
181 </para>
182 <programlisting><![CDATA[
183 [...]
184 <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/python</annotate>
185 <annotate key="org.freedesktop.policykit.exec.argv1">/usr/bin/my-pk-test</annotate>
186 [...]
187 ]]></programlisting>
188 <para>
189 can be used to select the appropriate polkit action. Be careful
190 to get the latter annotation right, otherwise it will match any
191 <command>pkexec</command> invocation of
192 <filename>/usr/bin/python</filename> scripts.
193 </para>
194 </refsect1>
195
196 <refsect1 id="pkexec-variables"><title>VARIABLES</title>
197 <para>
198 The following variables are set by
199 <command>pkexec</command>. They can be used in authorization
200 rules and messages shown in authentication dialogs:
201 </para>
202
203 <variablelist>
204 <varlistentry>
205 <term><emphasis>program</emphasis></term>
206 <listitem>
207 <para>
208 Fully qualified path to the program to be executed.
209 Example: <quote>/bin/cat</quote>
210 </para>
211 </listitem>
212 </varlistentry>
213 <varlistentry>
214 <term><emphasis>command_line</emphasis></term>
215 <listitem>
216 <para>
217 The requested command-line (do not use this for any
218 security checks, it is not secure).
219 Example: <quote>cat /srv/xyz/foobar</quote>
220 </para>
221 </listitem>
222 </varlistentry>
223 <varlistentry>
224 <term><emphasis>user</emphasis></term>
225 <listitem>
226 <para>
227 The user name of the user to execute the program as.
228 Example: <quote>davidz</quote>
229 </para>
230 </listitem>
231 </varlistentry>
232 <varlistentry>
233 <term><emphasis>user.gecos</emphasis></term>
234 <listitem>
235 <para>
236 The full name of the user to execute the program as.
237 Example: <quote>David Zeuthen</quote>
238 </para>
239 </listitem>
240 </varlistentry>
241 <varlistentry>
242 <term><emphasis>user.display</emphasis></term>
243 <listitem>
244 <para>
245 A representation of the user to execute the program as
246 that is suitable for display in an authentication dialog.
247 Is typically set to a combination of the user name and the
248 full name.
249 Example: <quote>David Zeuthen (davidz)</quote>
250 </para>
251 </listitem>
252 </varlistentry>
253 </variablelist>
254
255 </refsect1>
256
257 <refsect1 id="pkexec-author"><title>AUTHOR</title>
258 <para>
259 Written by David Zeuthen <email>[email protected]</email> with
260 a lot of help from many others.
261 </para>
262 </refsect1>
263
264 <refsect1 id="pkexec-bugs">
265 <title>BUGS</title>
266 <para>
267 Please send bug reports to either the distribution or the
268 polkit-devel mailing list,
269 see <ulink url="https://github.com/polkit-org/polkit#bugs-and-development"/>.
270 </para>
271 </refsect1>
272
273 <refsect1 id="pkexec-see-also">
274 <title>SEE ALSO</title>
275 <para>
276 <link linkend="polkit.8"><citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
277 <link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
278 <link linkend="pkaction.1"><citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
279 <link linkend="pkcheck.1"><citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
280 <link linkend="pkttyagent.1"><citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
281 </para>
282 </refsect1>
283 </refentry>