PKCHECK(1)

πŸ“¦
version 128 Β· 4 versions
, in alpine 3.24, arch rolling, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

πŸ’– PKCHECK(1) πŸ’–

okay bestie, so this is the manual page for pkcheck, part of polkit. it's the little tool that asks the big question: is this process allowed to do this thing? let's get into it 🫢

✨ NAME ✨

pkcheck β€” check whether a process is authorized πŸ’…

🌸 SYNOPSIS 🌸

pkcheck [--version] [--help|-h]

pkcheck [--list-temp]

pkcheck [--revoke-temp]

pkcheck --action-id|-a action
        {--process|-p { pid | pid,pid-start-time | pid,pid-start-time,uid }
        | --system-bus-name|-s busname} [--allow-user-interaction|-u]
        [--enable-internal-agent] [--detail|-d key value...]

πŸ¦‹ DESCRIPTION πŸ¦‹

so pkcheck is the girl who checks whether a process is authorized for an action. and which process, you ask? you tell her, either with --process (details below, keep scrolling bestie) or with --system-bus-name.

you can pass --detail zero or more times to hand over extra details about the action. and if you pass --allow-user-interaction, pkcheck will literally just sit there and block while it waits for authentication. patience is a virtue ✨

now, the invocation pkcheck --list-temp will list all the temporary authorizations for the current session. and pkcheck --revoke-temp will revoke all the temporary authorizations for the current session. cleanup queen πŸ‘‘

and lowkey, this command is just a simple wrapper around the polkit D-Bus interface β€” so if you want the real tea, go read the D-Bus interface documentation.

πŸ‘‘ RETURN VALUE πŸ‘‘

okay this part matters so pay attention bestie, we're talking exit codes:

  • if the specified process is authorized, pkcheck exits with a return value of 0. slay, we love a happy ending πŸ’–
  • if the authorization result contains any details, those get printed on standard output as key/value pairs using environment style reporting. like, first the key, then an equal sign, then the value, then a newline. so:
KEY1=VALUE1
KEY2=VALUE2
KEY3=VALUE3
...
  • any octets that are not in [a-zA-Z0-9_] get escaped using octal codes prefixed with \. for example, the UTF-8 string fΓΈl,δ½ ε₯½ will be printed as f\303\270l\54\344\275\240\345\245\275. iconic escaping behaviour honestly 🧚
  • if the specified process is not authorized, pkcheck exits with a return value of 1, and a diagnostic message is printed on standard error. details still go to standard output.
  • if the specified process is not authorized because no suitable authentication agent is available, or because the --allow-user-interaction wasn't passed, pkcheck exits with a return value of 2 and a diagnostic message is printed on standard error. details β†’ standard output.
  • if the specified process is not authorized because the authentication dialog / request was dismissed by the user, pkcheck exits with a return value of 3 and a diagnostic message is printed on standard error. details β†’ standard output.
  • if an error occurred while checking for authorization, pkcheck exits with a return value of 127 with a diagnostic message printed on standard error.
  • and if one or more of the options you passed are malformed, pkcheck exits with a return value of 126. and if stdin is a tty, this manual page also gets shown to you. it's giving "read the instructions, babe" 😭

πŸ’€ NOTES πŸ’€

do NOT use either the bare pid or the pid,start-time syntax forms for --process. there are race conditions in both. that's not a vibe, that's a bug waiting to happen.

new code should always use pid,pid-start-time,uid. periodt.

the value of start-time can be determined by consulting e.g. the proc(5) file system, depending on the operating system. and heads up: if fewer than 3 arguments are passed, pkcheck will attempt to look them up internally β€” but ngl, that may be racy. πŸ™ˆ

if your program is a daemon with e.g. a custom Unix domain socket, you should determine the uid parameter via operating system mechanisms such as PEERCRED. iykyk.

🌈 AUTHENTICATION AGENT 🌈

pkcheck, like any other polkit application, will use the authentication agent registered for the process in question. so, the usual.

but β€” if no authentication agent is available, pkcheck can register its own textual authentication agent if you pass the --enable-internal-agent option. she's self-sufficient, she's her own main character πŸ’…βœ¨

πŸŽ€ AUTHOR πŸŽ€

written by David Zeuthen <davidz@redhat.com> with a lot of help from many others. shoutout to the whole crew 🫢

πŸ“ 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. don't be shy, they wanna hear from you πŸ’œ

⭐ SEE ALSO ⭐

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

and that's the whole page bestie!! this came from polkit, dated May 2009 β€” yes it's older than some of us and it's still out here checking authorizations. respect the elders πŸ‘‘πŸ’– go forth and check your processes, no cap πŸ¦‹βœ¨

πŸ“¦ where this page comes from