Merging upstream version 2.40.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 17 insertions, 6 deletions

diff --git a/login-utils/su.1.adoc b/login-utils/su.1.adoc
index 36a892f..2db2e04 100644
--- a/login-utils/su.1.adoc
+++ b/login-utils/su.1.adoc
@@ -46,8 +46,15 @@ Specify the primary group. This option is available to the root user only.
 Specify a supplementary group. This option is available to the root user only. The first specified supplementary group is also used as a primary group if the option *--group* is not specified.
 
 *-*, *-l*, *--login*::
-Start the shell as a login shell with an environment similar to a real login:
-
+Start the shell as a login shell with an environment similar to a real login.
++
+Note that on systemd-based systems, a new session may be defined as a real
+entry point to the system. However, *su* does not create a real session (by
+PAM) from this point of view. You need to use tools like *systemd-run* or
+*machinectl* to initiate a complete, real session.
++
+*su* does:
++
 * clears all the environment variables except *TERM* and variables specified by *--whitelist-environment*
 * initializes the environment variables *HOME*, *SHELL*, *USER*, *LOGNAME*, and *PATH*
 * changes to the target user's home directory
@@ -62,18 +69,22 @@ Create a pseudo-terminal for the session. The independent terminal provides bett
 This feature is mostly designed for interactive sessions. If the standard input is not a terminal, but for example a pipe (e.g., *echo "date" | su --pty*), then the *ECHO* flag for the pseudo-terminal is disabled to avoid messy output.
 
 *-s*, **--shell**=__shell__::
-Run the specified _shell_ instead of the default. The shell to run is selected according to the following rules, in order:
-
+Run the specified _shell_ instead of the default. If the target user has a restricted shell (i.e., not listed in _/etc/shells_), the *--shell* option and the *SHELL* environment variables are ignored unless the calling user is root.
++
+The shell to run is selected according to the following rules, in order:
++
 * the shell specified with *--shell*
 * the shell specified in the environment variable *SHELL*, if the *--preserve-environment* option is used
 * the shell listed in the passwd entry of the target user
 * /bin/sh
 
-If the target user has a restricted shell (i.e., not listed in _/etc/shells_), the *--shell* option and the *SHELL* environment variables are ignored unless the calling user is root.
-
 **--session-command=**__command__::
 Same as *-c*, but do not create a new session. (Discouraged.)
 
+*-T*, *--no-pty**::
+Do not create a pseudo-terminal, opposite of *--pty* and *-P*.
+Note that running without a pseudo-terminal opens the security risk of privilege escalation through TIOCSTI/TIOCLINUX ioctl command injection.
+
 *-w*, **--whitelist-environment**=__list__::
 Don't reset the environment variables specified in the comma-separated _list_ when clearing the environment for *--login*. The whitelist is ignored for the environment variables *HOME*, *SHELL*, *USER*, *LOGNAME*, and *PATH*.