summaryrefslogtreecommitdiff
path: root/man/machinectl.xml
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2016-12-24 01:08:15 +0100
committerLennart Poettering <lennart@poettering.net>2016-12-27 18:32:45 +0100
commit7f129a1f7c934123061aa26029cff1784805f878 (patch)
tree08e64b18e474ded3f327c8dc877176ff2f063c0b /man/machinectl.xml
parent27e2e3231fc1edbbaa9f73be363900701ab4598d (diff)
man: document that "systemd-run -M" propagates exit codes, and "machinectl shell" does not
This adds a brief explanation, suggesting the use of "systemd-run -M" to acquire exit status/code information for the invoked process. My original plan was to propagate the exit code/status in "machinectl shell" too, but this would mean we'd have to actively watch the shell's runtime status, and thus would need full, highly privileged and continious access to the container's system manager, the way "systemd-run" does it. This would be quite a departure from the simplistic, low-priviliged OpenShell() bus call implementation of the current code, that really just acquires a PTY device with a shell connected. Moreover it would blur the lines between the two commands even further, which I think is not desirable. Hence, from now on: "machinectl shell" is the full-session, interactive shell for human users "systemd-run -M …" is the low-level tool, that supports on-interactive mode, and is more configurable and suitable for streaming. Fixes: #4215
Diffstat (limited to 'man/machinectl.xml')
-rw-r--r--man/machinectl.xml18
1 files changed, 12 insertions, 6 deletions
diff --git a/man/machinectl.xml b/man/machinectl.xml
index 8bebdcf9a1..38cf919a78 100644
--- a/man/machinectl.xml
+++ b/man/machinectl.xml
@@ -428,6 +428,9 @@
user may be selected. Use <option>--setenv=</option> to set
environment variables for the executed process.</para>
+ <para>Note that <command>machinectl shell</command> does not propagate the exit code/status of the invoked
+ shell process. Use <command>systemd-run</command> instead if that information is required (see below).</para>
+
<para>When using the <command>shell</command> command without
arguments, (thus invoking the executed shell or command on the
local host), it is in many ways similar to a <citerefentry
@@ -440,12 +443,15 @@
environment variables or resource limits, among other
properties.</para>
- <para>Note that
- <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>
+ <para>Note that <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ with its <option>--machine=</option> switch may be used in place of the <command>machinectl shell</command>
+ command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
+ as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
+ <command>systemd-run</command>'s <option>--wait</option> switch to propagate exit status information of the
+ invoked process. Use <command>systemd-run</command>'s <option>--pty</option> switch for acquiring an
+ interactive shell, similar to <command>machinectl shell</command>. In general, <command>systemd-run</command>
+ is preferable for scripting purposes. However, note that <command>systemd-run</command> might require higher
+ privileges than <command>machinectl shell</command>.</para></listitem>
</varlistentry>
<varlistentry>