diff --git a/man/common-variables.xml b/man/common-variables.xml
index 2d26bf7242..9f322dbf23 100644
--- a/man/common-variables.xml
+++ b/man/common-variables.xml
@@ -167,28 +167,46 @@
$SYSTEMD_PAGERSECURE
- Takes a boolean argument. When true, the "secure" mode of the pager is enabled; if
- false, disabled. If $SYSTEMD_PAGERSECURE is not set at all, secure mode is enabled
- if the effective UID is not the same as the owner of the login session, see
- geteuid2
- and sd_pid_get_owner_uid3.
- In secure mode, will be set when invoking the pager, and the pager shall
- disable commands that open or create new files or start new subprocesses. When
- $SYSTEMD_PAGERSECURE is not set at all, pagers which are not known to implement
- secure mode will not be used. (Currently only
- less1
- implements secure mode.)
-
- Note: when commands are invoked with elevated privileges, for example under
+ Common pager commands like less1, in
+ addition to "paging", i.e. scrolling through the output, support opening of or writing to other files
+ and running arbitrary shell commands. When commands are invoked with elevated privileges, for example
+ under sudo8 or
pkexec1, care
- must be taken to ensure that unintended interactive features are not enabled. "Secure" mode for the
- pager may be enabled automatically as describe above. Setting SYSTEMD_PAGERSECURE=0
- or not removing it from the inherited environment allows the user to invoke arbitrary commands. Note
- that if the $SYSTEMD_PAGER or $PAGER variables are to be
- honoured, $SYSTEMD_PAGERSECURE must be set too. It might be reasonable to completely
- disable the pager using instead.
+ project='die-net'>pkexec1, the
+ pager becomes a security boundary. Care must be taken that only programs with strictly limited
+ functionality are used as pagers, and unintended interactive features like opening or creation of new
+ files or starting of subprocesses are not allowed. "Secure mode" for the pager may be enabled as
+ described below, if the pager supports that (most pagers are not written in a way
+ that takes this into consideration). It is recommended to either explicitly enable "secure mode" or to
+ completely disable the pager using or PAGER=cat when
+ allowing untrusted users to execute commands with elevated privileges.
+
+ This option takes a boolean argument. When set to true, the "secure mode" of the pager is
+ enabled. In "secure mode", will be set when invoking the pager, which
+ instructs the pager to disable commands that open or create new files or start new subprocesses.
+ Currently only less1 is known
+ to understand this variable and implement "secure mode".
+
+ When set to false, no limitation is placed on the pager. Setting
+ SYSTEMD_PAGERSECURE=0 or not removing it from the inherited environment may allow
+ the user to invoke arbitrary commands.
+
+ When $SYSTEMD_PAGERSECURE is not set, systemd tools attempt to automatically
+ figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is
+ enabled if the effective UID is not the same as the owner of the login session, see
+ geteuid2
+ and
+ sd_pid_get_owner_uid3.
+ In this case, SYSTEMD_PAGERSECURE=1 will be set and pagers which are not known to
+ implement "secure mode" will not be used at all.
+
+ Note that if the $SYSTEMD_PAGER or $PAGER variables are to
+ be honoured, $SYSTEMD_PAGERSECURE must be set too.
+