summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/machinectl.xml40
1 files changed, 35 insertions, 5 deletions
diff --git a/man/machinectl.xml b/man/machinectl.xml
index 2f68f91b93..6cf405ed29 100644
--- a/man/machinectl.xml
+++ b/man/machinectl.xml
@@ -403,7 +403,7 @@
</varlistentry>
<varlistentry>
- <term><command>shell</command> [<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
+ <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
<listitem><para>Open an interactive shell session in a
container or on the local host. The first argument refers to
@@ -415,10 +415,29 @@
immediately invokes a user process. This command runs the
specified executable with the specified arguments, or
<filename>/bin/sh</filename> if none is specified. By default
- opens a <literal>root</literal> shell, but using
- <option>--uid=</option> a different user may be selected. Use
- <option>--setenv=</option> to set environment variables for
- the executed process.</para></listitem>
+ opens a <literal>root</literal> shell, but by using
+ <option>--uid=</option>, or by prefixing the machine name with
+ a username and an <literal>@</literal> character, a different
+ user may be selected. Use <option>--setenv=</option> to set
+ environment variables for the executed process.</para>
+
+ <para>When using the <command>shell</command> command without
+ arguments (thus invoking the executed shell or command on the
+ local host) it is similar in many ways to a <citerefentry
+ project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ session, but unlike <command>su</command> completely isolates
+ the new session from the originating session, so that it
+ shares no process or session properties, and is in a clean and
+ well-defined state. It will be tracked in a new utmp, login,
+ audit and keyring session, and will not inherit an environment
+ variables or resource limits, among other properties.</para>
+
+ <para>Note that the
+ <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ may be used in place of the <command>shell</command> command,
+ and allows more detailed, low-level configuration of the
+ invoked unit. However, it is frequently more privileged than
+ the <command>shell</command> command.</para></listitem>
</varlistentry>
<varlistentry>
@@ -995,6 +1014,17 @@
current directory.</para>
</example>
+ <example>
+ <title>Create a new shell session</title>
+
+ <programlisting># machinectl shell --uid=lennart</programlisting>
+
+ <para>This creates a new shell session on the local host, for
+ the user ID <literal>lennart</literal>, in a <citerefentry
+ project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
+ fashion.</para>
+ </example>
+
</refsect1>
<refsect1>