1PKEXEC(1) pkexec PKEXEC(1)
2
6 pkexec - Execute a command as another user
7
9 pkexec [--version] [--disable-internal-agent] [--help]
10 pkexec [--user username] PROGRAM [ARGUMENTS...]
12
14 pkexec allows an authorized user to execute PROGRAM as another user. If
15 username is not specified, then the program will be executed as the
16 administrative super user, root.
17
19 Upon successful completion, the return value is the return value of
20 PROGRAM. If the calling process is not authorized or an authorization
21 could not be obtained through authentication or an error occured,
22 pkexec exits with a return value of 127. If the authorization could not
23 be obtained because the user dismissed the authentication dialog,
24 pkexec exits with a return value of 126.
25
27 pkexec, like any other polkit application, will use the authentication
28 agent registered for the calling process or session. However, if no
29 authentication agent is available, then pkexec will register its own
30 textual authentication agent. This behavior can be turned off by
31 passing the --disable-internal-agent option.
32
34 Executing a program as another user is a privileged operation. By
35 default the action to check for (see the section called “ACTION AND
36 AUTHORIZATIONS”) requires administrator authentication. In addition,
37 the authentication dialog presented to the user will display the full
38 path to the program to be executed so the user is aware of what will
39 happen.
40 The environment that PROGRAM will run it, will be set to a minimal
42 known and safe environment in order to avoid injecting code through
43 LD_LIBRARY_PATH or similar mechanisms. In addition the PKEXEC_UID
44 environment variable is set to the user id of the process invoking
45 pkexec. As a result, pkexec will not by default allow you to run X11
46 applications as another user since the $DISPLAY and $XAUTHORITY
47 environment variables are not set. These two variables will be retained
48 if the org.freedesktop.policykit.exec.allow_gui annotation on an action
49 is set to a nonempty value; this is discouraged, though, and should
50 only be used for legacy programs.
51 Note that pkexec does no validation of the ARGUMENTS passed to PROGRAM.
53 In the normal case (where administrator authentication is required
54 every time pkexec is used), this is not a problem since if the user is
55 an administrator he might as well just run pkexec bash to get root.
56 However, if an action is used for which the user can retain
58 authorization (or if the user is implicitly authorized) this could be a
59 security hole. Therefore, as a rule of thumb, programs for which the
60 default required authorization is changed, should never implicitly
61 trust user input (e.g. like any other well-written suid program).
62
64 By default, the org.freedesktop.policykit.exec action is used. To use
65 another action, use the org.freedesktop.policykit.exec.path annotation
66 on an action with the value set to the full path of the program. In
67 addition to specifying the program, the authentication message,
68 description, icon and defaults can be specified. If the
69 org.freedesktop.policykit.exec.argv1 annotation is present, the action
70 will only be picked if the first argument to the program matches the
71 value of the annotation.
72 Note that authentication messages may reference variables (see the
74 section called “VARIABLES”), for example $(user) will be expanded to
75 the value of the user variable.
76
78 To avoid modifying existing software to prefix their command-line
79 invocations with pkexec, it's possible to use pkexec in a she-bang
80 wrapper[1] like this:
81 #!/usr/bin/pkexec /usr/bin/python
83 import os
85 import sys
86 print "Hello, I'm running as uid %d"%(os.getuid())
88 for n in range(len(sys.argv)):
90 print "arg[%d]=`%s'"%(n, sys.argv[n])
91 If this script is installed into /usr/bin/my-pk-test, then the
93 following annotations
94 [...]
96 <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/python</annotate>
97 <annotate key="org.freedesktop.policykit.exec.argv1">/usr/bin/my-pk-test</annotate>
98 [...]
99 can be used to select the appropriate polkit action. Be careful to get
101 the latter annotation right, otherwise it will match any pkexec
102 invocation of /usr/bin/python scripts.
103
105 The following variables are set by pkexec. They can be used in
106 authorization rules and messages shown in authentication dialogs:
107 program
109 Fully qualified path to the program to be executed. Example:
110 “/bin/cat”
111 command_line
113 The requested command-line (do not use this for any security
114 checks, it is not secure). Example: “cat /srv/xyz/foobar”
115 user
117 The user name of the user to execute the program as. Example:
118 “davidz”
119 user.gecos
121 The full name of the user to execute the program as. Example:
122 “David Zeuthen”
123 user.display
125 A representation of the user to execute the program as that is
126 suitable for display in an authentication dialog. Is typically set
127 to a combination of the user name and the full name. Example:
128 “David Zeuthen (davidz)”
129
131 Written by David Zeuthen <davidz@redhat.com> with a lot of help from
132 many others.
133
135 Please send bug reports to either the distribution or the polkit-devel
136 mailing list, see the link
137 http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to
138 subscribe.
139
141 polkit(8), polkitd(8), pkaction(1), pkcheck(1), pkttyagent(1)
142
144 1. she-bang wrapper
145 http://en.wikipedia.org/wiki/Shebang_(Unix)
146polkit May 2009 PKEXEC(1)