'\" t .\" Title: polkit-agent-helper .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: June 2025 .\" Manual: polkit-agent-helper .\" Source: polkit .\" Language: English .\" .TH "POLKIT\-AGENT\-HELPE" "8" "June 2025" "polkit" "polkit-agent-helper" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" polkit-agent-helper \- polkit authentication agent helper .SH "SYNOPSIS" .HP \w'\fBpolkit\-agent\-helper\-1\fR\ 'u \fBpolkit\-agent\-helper\-1\fR .SH "DESCRIPTION" .PP \fBpolkit\-agent\-helper\-1\fR is a privileged helper binary used internally by polkit authentication agents\&. It is not intended to be invoked directly by users or administrators\&. The helper is called by the authentication agent (via \fIPolkitAgentSession\fR) associated with the user session that initiated the authorization request\&. Its purpose is to verify the user\*(Aqs credentials through the system\*(Aqs authentication framework and relay authentication prompts between the agent and the authentication back\-end\&. .PP Multiple variants of this helper exist, one of which is selected at build time depending on the target platform\*(Aqs authentication infrastructure: .PP PAM .RS 4 Used on Linux systems with Pluggable Authentication Modules\&. This is the most common variant\&. .RE .PP BSD Auth .RS 4 Used on OpenBSD systems with native BSD authentication\&. .RE .PP Shadow .RS 4 Used on systems without PAM that rely on shadow password databases for credential verification\&. .RE .PP Regardless of the variant, the installed binary is always named \fBpolkit\-agent\-helper\-1\fR and resides in /usr/lib/polkit\-1/\&. .PP See the \fBpolkit\fR(8) man page for an overview of how authentication agents interact with the rest of the polkit architecture\&. .SH "SANDBOXING" .PP When the polkit\-agent\-helper\&.socket systemd socket unit is enabled (i\&.e\&. not masked or disabled), \fBpolkit\-agent\-helper\-1\fR is socket\-activated and runs as a systemd service (polkit\-agent\-helper@\&.service) started directly by systemd, removing the need for the SUID bit on the binary\&. This service operates in a tightly restricted sandbox\&. The service unit enables, among others, the following security directives: PrivateDevices=yes, ProtectHome=yes, PrivateNetwork=yes, PrivateTmp=yes, ProtectSystem=strict, and DevicePolicy=closed\&. See \fBsystemd.exec\fR(5) for details on each directive\&. .PP This sandboxing is intentional and significantly reduces the attack surface of the authentication helper\&. However, PAM modules that require access to hardware devices (e\&.g\&. USB security keys, TPM chips, fingerprint readers), user home directories (e\&.g\&. ~/\&.config key files), or other resources restricted by the sandbox will not function correctly under this configuration\&. .PP The recommended approach is for \fIPAM module creators\fR to ship a systemd drop\-in override file for the polkit\-agent\-helper@\&.service unit that relaxes only the specific directives their module requires\&. PAM module creators are in the best position to know what access their module needs, and maintaining the override alongside the module ensures it stays up to date as the module evolves\&. .PP A drop\-in override provided by the package vendor is a file placed in the directory /usr/lib/systemd/system/polkit\-agent\-helper@\&.service\&.d/\&. It should be prefixed with the owning module\*(Aqs name\&. It must have the extension \&.conf and contain only the directives to be overridden, prefixed with a [Service] section header\&. For example, a PAM module that needs access to TPM devices would install the following file: .sp .if n \{\ .RS 4 .\} .nf # /usr/lib/systemd/system/polkit\-agent\-helper@\&.service\&.d/pinpam\-tpm\-access\&.conf [Service] DevicePolicy=auto DeviceAllow=char\-tpm rw PrivateDevices=no .fi .if n \{\ .RE .\} .PP Similarly, a module that needs to read files from the authenticating user\*(Aqs home directory would install: .sp .if n \{\ .RS 4 .\} .nf # /usr/lib/systemd/system/polkit\-agent\-helper@\&.service\&.d/home\-access\&.conf [Service] ProtectHome=read\-only .fi .if n \{\ .RE .\} .PP Only the directives that need to change should be included in the override; all other sandboxing remains in effect\&. Administrators may also place site\-specific overrides in /etc/systemd/system/polkit\-agent\-helper@\&.service\&.d/, which take precedence over vendor\-supplied drop\-ins\&. .PP Note that without such an override, affected PAM modules will fail silently or fall back to password authentication, which can be difficult to diagnose\&. If a PAM module works with \fBsudo\fR(8) or login services but not with polkit, the agent helper sandbox is the likely cause\&. .SH "AUTHOR" .PP Written by David Zeuthen, the polkit team and many kind contributors\&. .SH "BUGS" .PP Please send bug reports to either the distribution or the polkit\-devel mailing list, see \m[blue]\fB\%https://github.com/polkit-org/polkit#bugs-and-development\fR\m[]\&. .SH "SEE ALSO" .PP \fBpolkit\fR(8), \fBpolkitd\fR(8), \fBpkttyagent\fR(1), \fBsystemd.exec\fR(5), \fBpam\fR(8)