From 98ab0daeeb07aa3333ff0b1bdba990af6d6e4924 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 18 Apr 2020 17:47:51 +0200 Subject: [PATCH] docs: use "polkit" to refer to PolicyKit See d35f51ea848ca76bd3747db69e8c5dd864e82bc3 for justification. First use in each file is turned into a link to the documentation page. --- NEWS | 2 +- docs/PORTABILITY_AND_STABILITY.md | 2 +- docs/USERDB_AND_DESKTOPS.md | 3 ++- man/org.freedesktop.hostname1.xml | 9 +++++---- man/org.freedesktop.locale1.xml | 9 +++++---- man/org.freedesktop.login1.xml | 15 ++++++++------- man/org.freedesktop.systemd1.xml | 11 ++++++----- man/org.freedesktop.timedate1.xml | 5 +++-- 8 files changed, 31 insertions(+), 25 deletions(-) diff --git a/NEWS b/NEWS index cac6c1b294..15979ae34d 100644 --- a/NEWS +++ b/NEWS @@ -280,7 +280,7 @@ CHANGES WITH 245: such files in version 243. * systemd-logind will now validate access to the operation of changing - the virtual terminal via a PolicyKit action. By default, only users + the virtual terminal via a polkit action. By default, only users with at least one session on a local VT are granted permission. * When systemd sets up PAM sessions that invoked service processes diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index 95bfcb98d3..064932970f 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -87,7 +87,7 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy | [Boot Loader interface](https://systemd.io/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no | | [Service bus API](https://www.freedesktop.org/wiki/Software/systemd/dbus) | D-Bus | yes | yes | system-config-services | no | - | no | | [logind](https://www.freedesktop.org/wiki/Software/systemd/logind) | D-Bus | yes | yes | GNOME | no | - | no | -| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, PolicyKit, ... | no | - | no | +| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, polkit, ... | no | - | no | | [sd-daemon.h API](https://www.freedesktop.org/software/systemd/man/sd-daemon.html) | C Library or Drop-in | yes | yes | numerous | yes | - | yes | | [sd-id128.h API](https://www.freedesktop.org/software/systemd/man/sd-id128.html) | C Library | yes | yes | - | yes | - | no | | [sd-journal.h API](https://www.freedesktop.org/software/systemd/man/sd-journal.html) | C Library | yes | yes | - | maybe | - | no | diff --git a/docs/USERDB_AND_DESKTOPS.md b/docs/USERDB_AND_DESKTOPS.md index 6859c59da1..a19f746a26 100644 --- a/docs/USERDB_AND_DESKTOPS.md +++ b/docs/USERDB_AND_DESKTOPS.md @@ -77,7 +77,8 @@ supports is directly available in these JSON records. Hence it makes sense for any user management UI to expose them directly. `systemd-homed` exposes APIs to add, remove and make changes to local users via -D-Bus, with full PolicyKit hook-up. On the command line this is exposed via the +D-Bus, with full [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) +hook-up. On the command line this is exposed via the `homectl` command. A graphical UI that exposes similar functionality would be very useful, exposing the various new account settings, and in particular providing a stream-lined UI for enrolling new-style authentication tokens such diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml index f6eb9f3545..406a6a369e 100644 --- a/man/org.freedesktop.hostname1.xml +++ b/man/org.freedesktop.hostname1.xml @@ -141,7 +141,8 @@ node /org/freedesktop/hostname1 { Whenever the hostname or other metadata is changed via the daemon, PropertyChanged signals are sent out to subscribed clients. Changing a hostname - using this interface is authenticated via PolicyKit. + using this interface is authenticated via + polkit. @@ -237,7 +238,7 @@ node /org/freedesktop/hostname1 { GetProductUUID() returns the "product uuid" as exposed by the kernel based on DMI information in /sys/class/dmi/id/product_uuid. Reading the file directly - requires root privileges, and this method allows access to unprivileged clients through the PolicyKit + requires root privileges, and this method allows access to unprivileged clients through the polkit framework. KernelName, KernelRelease, and @@ -256,10 +257,10 @@ node /org/freedesktop/hostname1 { Security - The interactive boolean parameters can be used to control whether PolicyKit + The interactive boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required. - The PolicyKit action for SetHostname() is + The polkit action for SetHostname() is org.freedesktop.hostname1.set-hostname. For SetStaticHostname() and SetPrettyHostname() it is org.freedesktop.hostname1.set-static-hostname. For diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml index 52f9abcf9d..f15945e766 100644 --- a/man/org.freedesktop.locale1.xml +++ b/man/org.freedesktop.locale1.xml @@ -126,7 +126,8 @@ node /org/freedesktop/locale1 { Use the empty string for the keymap parameters you wish not to set. - The interactive boolean parameters can be used to control whether PolicyKit + The interactive boolean parameters can be used to control whether + polkit should interactively ask the user for authentication credentials if required. @@ -160,9 +161,9 @@ node /org/freedesktop/locale1 { Security - Changing the system locale or keymap using this interface is authenticated via PolicyKit. The - PolicyKit action for SetLocale() is - org.freedesktop.locale1.set-locale. The PolicyKit action for + Changing the system locale or keymap using this interface is authenticated via polkit. The + polkit action for SetLocale() is + org.freedesktop.locale1.set-locale. The polkit action for SetX11Keyboard() and SetVConsoleKeyboard() is org.freedesktop.locale1.set-keyboard. diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 0d686d65a1..e5521e155a 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -499,19 +499,20 @@ node /org/freedesktop/login1 { directory of a user is kept around and he may continue to run processes while he is logged out. If disabled, the runtime directory goes away as soon as they log out. SetUserLinger() expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the - PolicyKit authorization interactivity (see below). Note that the user linger state is persistently + polkit + authorization interactivity (see below). Note that the user linger state is persistently stored on disk. AttachDevice() may be used to assign a specific device to a specific seat. The device is identified by its /sys path and must be eligible for seat assignments. AttachDevice() takes three - arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see + arguments: the seat id, the sysfs path, and a boolean for controlling polkit interactivity (see below). Device assignments are persistently stored on disk. To create a new seat, simply specify a previously unused seat id. For more information about the seat assignment logic see Multi-Seat for Linux. FlushDevices() removes all explicit seat assignments for devices, resetting - all assignments to the automatic defaults. The only argument it takes is the PolicyKit interactivity + all assignments to the automatic defaults. The only argument it takes is the polkit interactivity boolean (see below). PowerOff(), Reboot(), Halt(), @@ -521,9 +522,9 @@ node /org/freedesktop/login1 { the machine is powered down). HybridSleep() results in the system entering a hybrid-sleep mode, i.e. the system is both hibernated and suspended. SuspendThenHibernate() results in the system being suspended, then later woken - using an RTC timer and hibernated. The only argument is the PolicyKit interactivity boolean + using an RTC timer and hibernated. The only argument is the polkit interactivity boolean interactive (see below). The main purpose of these calls is that they enforce - PolicyKit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged + polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users. They also enforce inhibition locks. UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. @@ -678,7 +679,7 @@ node /org/freedesktop/login1 { Security - A number of operations are protected via the PolicyKit privilege + A number of operations are protected via the polkit privilege system. SetUserLinger() requires the org.freedesktop.login1.set-user-linger privilege. AttachDevice() requires @@ -731,7 +732,7 @@ node /org/freedesktop/login1 { org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock type and mode taken. - The interactive boolean parameters can be used to control whether PolicyKit + The interactive boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required. diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 996c717904..da5541be90 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -40,9 +40,10 @@ Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if their corresponding settings in the unit files are in seconds. - In contrast to most of the other services of the systemd suite, PID 1 does not use PolicyKit for - controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy - language. (This is done in order to avoid a cyclic dependency between PolicyKit and systemd/PID 1.) This + In contrast to most of the other services of the systemd suite, PID 1 does not use + polkit + for controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy + language. (This is done in order to avoid a cyclic dependency between polkit and systemd/PID 1.) This means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged processes directly. However, some operations (such as shutdown/reboot/suspend) are made available through the D-Bus API of logind, see @@ -1463,7 +1464,7 @@ node /org/freedesktop/systemd1 { Security Read access is generally granted to all clients. Additionally, for unprivileged clients, some - operations are allowed through the PolicyKit privilege system. Operations which modify unit state + operations are allowed through the polkit privilege system. Operations which modify unit state (StartUnit(), StopUnit(), KillUnit(), RestartUnit() and similar, SetProperty) require org.freedesktop.systemd1.manage-units. Operations which modify unit file @@ -2127,7 +2128,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { allowed for everyone. All operations are allowed for clients with the CAP_SYS_ADMIN capability or when the org.freedesktop.systemd1.manage-units privilege is granted by - PolicyKit. + polkit. diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml index 73bd9dfedd..3111ebbc42 100644 --- a/man/org.freedesktop.timedate1.xml +++ b/man/org.freedesktop.timedate1.xml @@ -165,9 +165,10 @@ node /org/freedesktop/timedate1 { Security The interactive boolean parameters can be used to control whether - PolicyKit should interactively ask the user for authentication credentials if required. + polkit + should interactively ask the user for authentication credentials if required. - The PolicyKit action for SetTimezone() is + The polkit action for SetTimezone() is org.freedesktop.timedate1.set-timezone. For SetLocalRTC() it is org.freedesktop.timedate1.set-local-rtc, for