"🛡️ Polkit (PolicyKit) — Privilege Management"

If you like this project, consider supporting me on Buy Me a Coffee ☕️

tags:

• security
• sysadmin
• linux
• privilege-escalation
• polkit

• pkexec

  🛡️ Polkit (PolicyKit) — Privilege Management

Polkit (formerly PolicyKit) is a system-level toolkit for defining and handling privileges. It provides an organized way for unprivileged processes to communicate with privileged ones for system-wide actions. Polkit is used by systemd, D-Bus services, and desktop environments to control privilege escalation.

Common use cases:

• Running single commands as root via pkexec (alternative to sudo)
• Controlling access to system services (e.g., NetworkManager, systemd units)
• Managing desktop actions (mounting drives, printing, changing network settings)
• Restricting which users can perform administrative tasks without full sudo access

Status / Статус: Actively maintained and widely used on all modern Linux distributions. Essential component of systemd-based systems. Not legacy — there is no direct modern replacement.

📚 Table of Contents

• Installation & Configuration
• Core Concepts
• pkexec — Execute as Root
• pkaction — List & Describe Actions
• pkcheck — Check Authorization
• pkcontrol — Control polkitd
• Polkit Rules
• Polkit Actions (XML)
• Integration
• Logging & Troubleshooting
• Security Best Practices
• Real-World Examples
• Documentation Links

Installation & Configuration

Package Installation

# Debian/Ubuntu — usually pre-installed
sudo apt install policykit-1                              # Install polkit / Установить polkit

# RHEL/CentOS/Fedora
sudo dnf install polkit                                   # Install polkit / Установить polkit

# Arch Linux
sudo pacman -S polkit                                     # Install polkit / Установить polkit

# openSUSE
sudo zypper install polkit                                # Install polkit / Установить polkit

Verify Installation

pkaction --version                                        # Check polkit version / Проверить версию polkit
which polkitd                                             # Find polkitd binary / Найти бинарник polkitd
systemctl status polkit                                   # Check service status / Проверить статус сервиса

Key File Paths

[!NOTE] The daemon path varies by distribution. Newer systems use /usr/libexec/polkitd, older ones /usr/lib/polkit-1/polkitd. Check with which polkitd or systemctl cat polkit.

Core Concepts

How Polkit Works

Polkit operates on a subjects → actions → authorization model:

1. Subject — A process requesting privileged action (e.g., a user running pkexec)
2. Action — A named system operation defined in XML (e.g., org.freedesktop.packagekit.system-update)
3. Authorization — Polkit daemon evaluates rules to allow/deny/require-auth

Authorization Results

Polkit Agent

The polkit agent is a helper that prompts users for passwords during privilege escalation. It runs in the user session and communicates with polkitd via D-Bus.

# Common polkit agents / Типичные агенты polkit
/usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1   # GNOME
/usr/libexec/kf5/polkit-kde-authentication-agent-1               # KDE
lxpolkit                                                             # LXDE
mate-polkit                                                          # MATE
xfce-polkit                                                          # XFCE

[!WARNING] A polkit agent must be running in your session for interactive authentication prompts to work. Headless servers typically use auth_admin_keep or pre-configured rules to avoid interactive prompts.

pkexec — Execute as Root

pkexec runs a program with elevated privileges, similar to sudo but using polkit authorization.

Basic Usage

pkexec <COMMAND>                                        # Run command as root / Запуск от root
pkexec --user <USER> <COMMAND>                          # Run as specific user / Запуск от конкретного пользователя

Common Examples

pkexec systemctl restart nginx                          # Restart nginx as root / Перезапустить nginx от root
pkexec apt update                                       # Update packages / Обновить пакеты
pkexec useradd -m <USER>                                # Add user / Добавить пользователя
pkexec visudo                                           # Edit sudoers / Редактировать sudoers
pkexec cp /etc/config /etc/config.bak                   # Copy with root privileges / Копировать с привилегиями root

Environment Variables

# pkexec strips most environment variables by default for security
# To preserve specific variables, use --keep-env
pkexec --keep-env <VARIABLE>=<VALUE> <COMMAND>          # Preserve env var / Сохранить переменную окружения

# List variables polkit allows / Список разрешённых переменных
pkexec env                                              # Show effective env / Показать окружение

[!CAUTION] pkexec does NOT preserve shell aliases, functions, or most environment variables. For complex commands, wrap them in a script: pkexec /usr/local/bin/myscript.sh

Polkit Agent for pkexec

# pkexec can invoke a custom authentication agent
pkexec --agent /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 <COMMAND>

# On headless servers, set DISPLAY for graphical agent (if available)
DISPLAY=:0 pkexec <COMMAND>

pkaction — List & Describe Actions

pkaction queries available polkit actions and their properties.

List All Actions

pkaction                                                # List all actions / Список всех действий
pkaction --verbose                                      # List with details / Список с подробностями
pkaction --verbose --action-id <ACTION_ID>              # Show specific action / Показать конкретное действие

Query Action Properties

pkaction --action-id <ACTION_ID> --verbose              # Full details / Подробности
pkaction --action-id <ACTION_ID> --enable / --disable   # Check if enabled / Проверить включено ли

Common Action IDs

Create Custom Action

# Check if custom action exists
pkaction --action-id com.example.myaction --verbose 2>/dev/null || echo "Action not found"

pkcheck — Check Authorization

pkcheck tests whether a subject is authorized for an action. Used in scripts and daemons.

Basic Usage

pkcheck --action-id <ACTION_ID> --process <PID>         # Check process authorization / Проверить авторизацию процесса
pkcheck --action-id <ACTION_ID> --process $$            # Check current shell / Проверить текущий shell
pkcheck --action-id <ACTION_ID> --enable-internal-agent  # Allow user authentication / Разрешить аутентификацию

Check Authorization with Details

# Check if PID is authorized for action
pkcheck --action-id <ACTION_ID> --process <PID> --user <USER>

# Check with specific details
pkcheck --action-id <ACTION_ID> --process <PID> \
  --detail device /dev/sda1 \
  --detail origin /media/<USER>/usb

# Allow authentication if needed (shows dialog)
pkcheck --action-id <ACTION_ID> --process <PID> --enable-internal-agent

Exit Codes

pkcontrol — Control polkitd

pkcontrol controls the polkit daemon directly.

Daemon Operations

pkcontrol --version                                      # Show version / Показать версию
pkcontrol --help                                         # Show help / Показать справку

Manage polkitd

systemctl start polkit                                   # Start daemon / Запустить демон
systemctl stop polkit                                    # Stop daemon / Остановить демон
systemctl restart polkit                                 # Restart daemon / Перезапустить демон
systemctl reload polkit                                  # Reload rules / Перезагрузить правила
systemctl status polkit                                  # Check status / Проверить статус

# On older systems (sysvinit)
service polkit restart                                   # Restart via service / Перезапустить через service

[!WARNING] Stopping polkitd will break privilege escalation for all polkit-dependent services (systemd, NetworkManager, etc.). Never stop polkitd on production systems.

Polkit Rules

Polkit rules are JavaScript files that define authorization decisions. They are evaluated in lexical order (by filename).

Rules Directory Structure

# Distribution rules (read-only)
/usr/share/polkit-1/rules.d/

# System administrator rules (highest priority)
/etc/polkit-1/rules.d/

# Local authority rules (legacy, deprecated)
/etc/polkit-1/localauthority/

Rule File Naming

# Files are evaluated in lexicographic order
# Use numeric prefix for ordering
/etc/polkit-1/rules.d/00-defaults.rules    # First
/etc/polkit-1/rules.d/10-admin.rules       # Second
/etc/polkit-1/rules.d/90-custom.rules      # Last

Rule File Syntax

/etc/polkit-1/rules.d/<FILENAME>.rules

// Allow all users to run updates without authentication
polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.packagekit.system-update") {
        return polkit.Result.YES;
    }
});

Rule Templates

Allow Specific User for All Actions

/etc/polkit-1/rules.d/10-allow-user.rules

polkit.addRule(function(action, subject) {
    if (subject.user == "<USER>") {
        return polkit.Result.YES;
    }
});

Allow Group for Specific Action

/etc/polkit-1/rules.d/20-group-network.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.NetworkManager.settings.modify.system" &&
        subject.isInGroup("netadmin")) {
        return polkit.Result.YES;
    }
});

Require Authentication for Dangerous Actions

/etc/polkit-1/rules.d/30-restrict-dangerous.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.login1.reboot" ||
        action.id == "org.freedesktop.login1.power-off" ||
        action.id == "org.freedesktop.login1.halt") {
        return polkit.Result.AUTH_ADMIN;
    }
});

Deny Action for Everyone

/etc/polkit-1/rules.d/40-deny-reboot.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.login1.reboot") {
        return polkit.Result.NO;
    }
});

Allow USB Mounting for Local Users

/etc/polkit-1/rules.d/50-usb-mount.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.udisks2.filesystem-mount-system" &&
        subject.local == true) {
        return polkit.Result.YES;
    }
});

Allow Specific Command via pkexec

/etc/polkit-1/rules.d/60-myapp.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.policykit.exec" &&
        action.lookup("path") == "/usr/local/bin/myapp") {
        return polkit.Result.YES;
    }
});

Conditional Rules with Details

/etc/polkit-1/rules.d/70-conditional.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.udisks2.filesystem-mount" &&
        action.lookup("device").startsWith("/dev/sdb")) {
        return polkit.Result.AUTH_SELF;
    }
});

Rule Priority & Ordering

[!TIP] Rules are evaluated in order. The first rule that returns a result wins. Place restrictive rules after permissive ones, or use return to stop evaluation early.

Reload Rules

sudo systemctl reload polkit                              # Reload rules / Перезагрузить правила
# Rules take effect immediately for new requests

Polkit Actions (XML)

Actions are defined in XML files. Each file declares one or more actions with their descriptions, defaults, and vendor information.

Action File Structure

/usr/share/polkit-1/actions/com.example.myaction.policy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
<policyconfig>

  <vendor>My Company</vendor>
  <vendor_url>https://example.com</vendor_url>

  <action id="com.example.myaction">
    <description>My Custom Action</description>
    <message>Authentication is required to run my action</message>

    <defaults>
      <allow_any>no</allow_any>
      <allow_inactive>no</allow_inactive>
      <allow_active>auth_self</allow_active>
    </defaults>

    <annotate key="org.freedesktop.policykit.exec.path">/usr/local/bin/myapp</annotate>
    <annotate key="org.freedesktop.policykit.exec.allow_gui">false</annotate>
  </action>

</policyconfig>

Default Authorization Levels

Policy Values

Install Custom Action

# Copy action file
sudo cp com.example.myaction.policy /usr/share/polkit-1/actions/

# Verify
pkaction --action-id com.example.myaction --verbose

Reload Actions

sudo systemctl restart polkit                            # Restart to reload actions / Перезапустить для перезагрузки

Integration

Integration with systemd

Polkit controls access to many systemd operations.

# Check which systemd actions require polkit
systemctl list-units --type=service                       # List services / Список сервисов

# Common polkit-gated systemd operations
systemctl stop <SERVICE>                                  # May require polkit / Может потребовать polkit
systemctl start <SERVICE>                                 # May require polkit / Может потребовать polkit
systemctl enable <SERVICE>                                # May require polkit / Может потребовать polkit
systemctl mask <SERVICE>                                  # May require polkit / Может потребовать polkit
systemctl daemon-reload                                   # May require polkit / Может потребовать polkit

# Polkit rules for systemd
# /etc/polkit-1/rules.d/80-systemd.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units" &&
        subject.isInGroup("wheel")) {
        return polkit.Result.YES;
    }
});

Integration with D-Bus

Most polkit-protected services communicate via D-Bus. Polkitd listens on the system bus.

# Check polkitd D-Bus interface
busctl introspect org.freedesktop.PolicyKit1 /org/freedesktop/PolicyKit1/Authority

# Monitor polkit authorization requests
sudo dbus-monitor --system "interface='org.freedesktop.PolicyKit1.Authority'"

Integration with NetworkManager

# polkit rules for NetworkManager
# Allow users in "netadmin" group to modify system network settings

/etc/polkit-1/rules.d/90-networkmanager.rules

polkit.addRule(function(action, subject) {
    if (action.id.indexOf("org.freedesktop.NetworkManager.") === 0 &&
        subject.isInGroup("netadmin")) {
        return polkit.Result.YES;
    }
});

Integration with udisks2 (Storage)

# Allow local users to mount removable media
# /etc/polkit-1/rules.d/50-udisks2.rules

/etc/polkit-1/rules.d/50-udisks2.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.udisks2.filesystem-mount-system" &&
        subject.local == true) {
        return polkit.Result.YES;
    }
});

Integration with PackageKit

# Allow users in "wheel" group to install packages
# /etc/polkit-1/rules.d/70-packagekit.rules

/etc/polkit-1/rules.d/70-packagekit.rules

polkit.addRule(function(action, subject) {
    if (action.id.indexOf("org.freedesktop.packagekit.") === 0 &&
        subject.isInGroup("wheel")) {
        return polkit.Result.AUTH_SELF_KEEP;
    }
});

Logging & Troubleshooting

Enable Debug Logging

# Run polkitd with debug output
sudo /usr/lib/polkit-1/polkitd --no-debug                # Normal mode / Обычный режим
sudo /usr/lib/polkit-1/polkitd --replace                 # Replace running instance / Заменить текущий экземпляр

# For verbose logging, edit polkitd startup or use journalctl
sudo journalctl -u polkit -f                             # Follow polkit logs / Следить за логами polkit
sudo journalctl -u polkit --since "10 min ago"           # Recent logs / Недавние логи

View polkit Logs

# systemd-based systems
sudo journalctl -u polkit                                # All polkit logs / Все логи polkit
sudo journalctl -u polkit --priority=debug               # Debug level / Уровень отладки
sudo journalctl -u polkit --since "2026-01-01"           # Since date / С даты

# Older systems
sudo cat /var/log/auth.log | grep polkit                 # Check auth log / Проверить лог аутентификации
sudo grep polkit /var/log/secure                         # RHEL/CentOS / RHEL/CentOS

Common Issues

pkexec Not Working

# Check if polkitd is running
systemctl status polkit

# Check polkit version
pkaction --version

# Verify pkexec has correct permissions
ls -la /usr/bin/pkexec
# Should be: -rwsr-xr-x 1 root root

# Fix permissions if needed
sudo chmod 4755 /usr/bin/pkexec                          # Set SUID bit / Установить SUID бит
sudo chown root:root /usr/bin/pkexec                     # Set ownership / Установить владельца

Rules Not Taking Effect

# Check rule file syntax (no errors in output)
sudo python3 -c "
import os
rules_dir = '/etc/polkit-1/rules.d/'
for f in sorted(os.listdir(rules_dir)):
    if f.endswith('.rules'):
        print(f'Checking {f}...')
        with open(os.path.join(rules_dir, f)) as fh:
            content = fh.read()
            if 'polkit.addRule' in content:
                print(f'  OK: Contains addRule')
            else:
                print(f'  WARNING: Missing addRule')
"

# Reload polkitd after rule changes
sudo systemctl reload polkit

# Check for JavaScript errors in rules
# polkitd logs rule errors to journal
sudo journalctl -u polkit | grep -i "error\|syntax\|rule"

Authentication Dialog Not Appearing

# Ensure polkit agent is running
ps aux | grep polkit-agent

# Start GNOME agent manually
/usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 &

# Start KDE agent manually
/usr/libexec/kf5/polkit-kde-authentication-agent-1 &

# Check D-Bus session
echo $DBUS_SESSION_BUS_ADDRESS

polkitd Fails to Start

# Check for port conflicts
sudo ss -tlnp | grep polkitd

# Check JavaScript engine (polkitd requires mozjs or duktape)
sudo journalctl -u polkit -n 50                         # Check for JS errors / Проверить ошибки JS

# Verify polkitd binary
file /usr/lib/polkit-1/polkitd                           # Check binary type / Проверить тип бинарника
ldd /usr/lib/polkit-1/polkitd                            # Check dependencies / Проверить зависимости

Debug polkit Authorization

# Test specific authorization
pkcheck --action-id org.freedesktop.policykit.exec \
  --process $$ --enable-internal-agent                    # Test with auth / Тест с аутентификацией

# Monitor real-time authorization requests
sudo dbus-monitor --system \
  "interface='org.freedesktop.PolicyKit1.Authority'" \
  "member='CheckAuthorization'"                          # Monitor auth checks / Мониторинг проверок

Security Best Practices

General Principles

• Principle of least privilege: Only grant the minimum permissions needed / Принцип наименьших привилегий
• Use specific action IDs: Never grant org.freedesktop.policykit.exec without restricting path / Используйте конкретные ID действий
• Prefer auth_self over auth_admin: Let users authenticate themselves when appropriate / Предпочитайте auth_self
• Never set <allow_any>yes</allow_any>: This bypasses authentication on any session / Никогда не устанавливайте yes для allow_any
• Use group-based rules: Easier to manage than user-specific rules / Используйте правила на основе групп
• Audit rules regularly: Review /etc/polkit-1/rules.d/ periodically / Регулярно проверяйте правила

Dangerous Patterns to Avoid

// BAD: Grants root to everyone
polkit.addRule(function(action, subject) {
    return polkit.Result.YES;
});

// BAD: No restriction on which path can be executed
polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.policykit.exec") {
        return polkit.Result.YES;
    }
});

// BAD: Allows all NetworkManager actions without auth
polkit.addRule(function(action, subject) {
    if (action.id.indexOf("org.freedesktop.NetworkManager.") === 0) {
        return polkit.Result.YES;
    }
});

Secure Rule Template

/etc/polkit-1/rules.d/90-secure-defaults.rules

// Secure defaults: require auth for everything sensitive
polkit.addRule(function(action, subject) {
    // Never allow unauthenticated power operations
    if (action.id == "org.freedesktop.login1.reboot" ||
        action.id == "org.freedesktop.login1.power-off" ||
        action.id == "org.freedesktop.login1.halt") {
        return polkit.Result.AUTH_ADMIN;
    }
});

// Allow admins to manage services
polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units" &&
        subject.isInGroup("wheel")) {
        return polkit.Result.AUTH_ADMIN_KEEP;
    }
});

Real-World Examples

Allow User to Restart Specific Services

/etc/polkit-1/rules.d/50-webadmin.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units" &&
        subject.user == "<USER>" &&
        (action.lookup("unit") == "nginx.service" ||
         action.lookup("unit") == "php-fpm.service" ||
         action.lookup("unit") == "mysql.service")) {
        return polkit.Result.YES;
    }
});

Allow Group to Use NetworkManager

/etc/polkit-1/rules.d/60-network.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.NetworkManager.settings.modify.system" &&
        subject.isInGroup("netadmin")) {
        return polkit.Result.AUTH_SELF;
    }
});

Create Custom pkexec Action

1. Create action XML:

/usr/share/polkit-1/actions/com.example.restart-app.policy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
<policyconfig>
  <vendor>My Company</vendor>
  <vendor_url>https://example.com</vendor_url>

  <action id="com.example.restart-app">
    <description>Restart My Application</description>
    <message>Authentication is required to restart the application</message>
    <defaults>
      <allow_any>no</allow_any>
      <allow_inactive>no</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
    <annotate key="org.freedesktop.policykit.exec.path">/usr/local/bin/restart-app.sh</annotate>
    <annotate key="org.freedesktop.policykit.exec.allow_gui">false</annotate>
  </action>
</policyconfig>

2. Create the script:

/usr/local/bin/restart-app.sh

#!/bin/bash
systemctl restart myapp

3. Set permissions and use:

sudo chmod 755 /usr/local/bin/restart-app.sh             # Set script permissions / Установить права
pkexec com.example.restart-app                           # Run via polkit / Запуск через polkit

Migrate from sudo to polkit

# Instead of adding to sudoers:
# <USER> ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart nginx

# Create polkit rule:

/etc/polkit-1/rules.d/40-nginx-restart.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units" &&
        action.lookup("unit") == "nginx.service" &&
        subject.user == "<USER>") {
        return polkit.Result.YES;
    }
});

Restrict USB Storage Mounting

/etc/polkit-1/rules.d/55-usb-restrict.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.udisks2.filesystem-mount-system") {
        if (subject.isInGroup("usbusers")) {
            return polkit.Result.AUTH_SELF;
        }
        return polkit.Result.NO;
    }
});

Allow Printer Administration for Group

/etc/polkit-1/rules.d/65-printer.rules

polkit.addRule(function(action, action_id, subject) {
    if (action.id.indexOf("org.opensuse.cups-pk-helper.") === 0 &&
        subject.isInGroup("printadmin")) {
        return polkit.Result.YES;
    }
});

Emergency: Disable All polkit Authentication

/etc/polkit-1/rules.d/99-emergency.rules

// EMERGENCY ONLY: Allow everything without auth
// REMOVE THIS FILE IMMEDIATELY AFTER USE
polkit.addRule(function(action, subject) {
    return polkit.Result.YES;
});

# Apply
sudo systemctl reload polkit

# REMEMBER TO REMOVE:
sudo rm /etc/polkit-1/rules.d/99-emergency.rules
sudo systemctl reload polkit

[!CAUTION] Only use emergency rules for short-term troubleshooting. Leaving return polkit.Result.YES as a catch-all defeats all security policies and exposes the system to privilege escalation attacks.

Documentation Links

• Polkit Official Documentation
• Polkit Manual Pages
• pkexec(8) Manual
• pkaction(1) Manual
• pkcheck(1) Manual
• Polkit Rules Introduction
• Polkit Actions Format
• ArchWiki — Polkit
• Debian Wiki — PolicyKit
• Red Hat — Understanding Polkit