PKEXEC(1)

✨ pkexec(1) — the manual, but make it cute ✨

okay bestie, so this is the pkexec page from the pkexec manual, and I'm gonna walk you through it like we're texting at 2am 💖

---

🎀 NAME 🎀

pkexec — run a command as a whole other user, no cap 👑

---

🦋 SYNOPSIS 🦋

pkexec [--version] [--disable-internal-agent] [--help]

pkexec [--keep-cwd] [--user username] PROGRAM [ARGUMENTS...]

---

💅 DESCRIPTION 💅

pkexec lets an authorized user run PROGRAM as somebody else. Literally the whole plot. ✨

If you don't say which PROGRAM, it just runs the default shell. Surprise! 🐚

And if you don't say which username, then it runs the thing as the administrative super user, root. That's the big one, bestie. That's main character energy fr fr.

---

💀 RETURN VALUE 💀

If everything goes great, the return value is just the return value of PROGRAM. Simple. Iconic. 🫶

But if the calling process isn't authorized, or an authorization couldn't be obtained through authentication, or literally any error happens — pkexec exits with a return value of 127.

And if the authorization couldn't be obtained because the user dismissed the authentication dialog (they hit cancel, they closed it, they said no thank you 🙈), then pkexec exits with a return value of 126.

---

🌸 AUTHENTICATION AGENT 🌸

pkexec, like literally every other polkit application, will use the authentication agent that's registered for the calling process or session. That's just how it do. 💫

BUT — if there's no authentication agent available, then pkexec registers its own textual authentication agent. Cute, self-sufficient, independent. She doesn't need anyone. 💁‍♀️

You can turn that behavior off by passing the --disable-internal-agent option, if that's more your vibe.

---

🔥 SECURITY NOTES 🔥

okay this is the part where we get serious for a sec. pay attention bestie, this is important.

Running a program as another user is a privileged operation. By default, the action to check for (see the section called "ACTION AND AUTHORIZATIONS") requires administrator authentication. And on top of that, the authentication dialog shown to the user will display the full path to the program that's about to be executed, so the user actually knows what's gonna happen. No sneaky business. 👀

The environment that PROGRAM runs in gets set to a minimal known and safe environment, specifically so nobody can inject code through LD_LIBRARY_PATH or similar mechanisms. Sketched behavior = blocked. 💅

Also, the PKEXEC_UID environment variable gets set to the user id of the process invoking pkexec. 📝

As a result of all that, pkexec will not by default let you run X11 applications as another user, because the $DISPLAY and $XAUTHORITY environment variables are not set. Sorry to the GUI girlies. 😭

Those two variables will be retained if the org.freedesktop.policykit.exec.allow_gui annotation on an action is set to a nonempty value. But that is discouraged, though, and should only be used for legacy programs. You've been warned. ⚠️

pkexec will run PROGRAM in username's home directory, unless --keep-cwd is used to override this behavior. 🏠

Now — note that pkexec does no validation of the ARGUMENTS passed to PROGRAM. In the normal case (where administrator authentication is required every time pkexec is used), this is not a problem, since if the user is an administrator he might as well just run pkexec bash to get root. Like, the horse has left the barn at that point, bestie. 🐴

However, if an action is used for which the user can retain authorization (or if the user is implicitly authorized), this could be a security hole. Therefore, as a rule of thumb, programs for which the default required authorization is changed should never implicitly trust user input (e.g. like any other well-written suid program). Periodt. 🎯

---

👑 ACTION AND AUTHORIZATIONS 👑

By default, the org.freedesktop.policykit.exec action is used. 📌

To use another action, use the org.freedesktop.policykit.exec.path 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. ✨

If the org.freedesktop.policykit.exec.argv1 annotation is present, the action will only be picked if the first argument to the program matches the value of the annotation. Matching game: won. 🏆

Note that authentication messages may reference variables (see the section called "VARIABLES"), for example $(user) will be expanded to the value of the user variable. Cute little template magic. 🪄

---

🧚 WRAPPER USAGE 🧚

So you don't have to go modify existing software to prefix their command-line invocations with pkexec, it's possible to use pkexec in a she-bang wrapper[1] like this:

#!/usr/bin/pkexec /usr/bin/python

import os
import sys

print "Hello, I'm running as uid %d"%(os.getuid())

for n in range(len(sys.argv)):
    print "arg[%d]=`%s'"%(n, sys.argv[n])

If this script is installed into /usr/bin/my-pk-test, then the following annotations

[...]
<annotate key="org.freedesktop.policykit.exec.path">/usr/bin/python</annotate>
<annotate key="org.freedesktop.policykit.exec.argv1">/usr/bin/my-pk-test</annotate>
[...]

can be used to select the appropriate polkit action. 🎯

Be careful to get the latter annotation right, otherwise it will match any pkexec invocation of /usr/bin/python scripts. 😬

---

🌈 VARIABLES 🌈

The following variables are set by pkexec. They can be used in authorization rules and messages shown in authentication dialogs:

• program — Fully qualified path to the program to be executed. Example: /bin/cat 🐱
• command_line — The requested command-line (do not use this for any security checks, it is not secure). Example: cat /srv/xyz/foobar
• user — The user name of the user to execute the program as. Example: davidz 💜
• user.gecos — The full name of the user to execute the program as. Example: David Zeuthen
• user.display — 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. Example: David Zeuthen (davidz) ✨

---

💖 AUTHOR 💖

Written by David Zeuthen <davidz@redhat.com> with a lot of help from many others. 🫶 community effort, we love to see it.

---

🙈 BUGS 🙈

Please send bug reports to either the distribution or the polkit-devel mailing list, see https://github.com/polkit-org/polkit#bugs-and-development. They want to hear from you, bestie, don't be shy. 📬

---

⭐ SEE ALSO ⭐

polkit(8), polkitd(8), pkaction(1), pkcheck(1), pkttyagent(1)

---

📝 NOTES 📝

1. she-bang wrapper — http://en.wikipedia.org/wiki/Shebang_(Unix)

---

and that's the whole page bestie!! 🎀✨ This one came out of the polkit project, from way back in May 2009 — old but iconic, an absolute classic, we stan a legacy utility. mwah 💋 go forth and run things as root responsibly fr fr 🫶