man: document > /dev/stderr pitfalls (#7317)

Fixes: #7254
See: #2473

diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 7477195dabd87e6ec1ab26ab517c1c18e70ea68f..2c74c1f39ce89750de0b0d2b49a027f0a3dad2db 100644 (file)
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -244,7 +244,15 @@
 
         <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
         option is automatically determined and used. Specifically, when invoked with standard input, output and error
-        connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para></listitem>
+        connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
+
+        <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
+        to the service processes as-is. If the service runs with different privileges than
+        <command>systemd-run</command>, this means the service might not be able to re-open the passed file
+        descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
+        uses the <command>echo "hello" > /dev/stderr</command> construct for writing messages to stderr, this might
+        cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
+        "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para></listitem>
       </varlistentry>
 
       <varlistentry>

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 18cfe6b90a061b07e163717efdc62601c450cb21..fb5c0806169d97aad36e484aaf2ffb77ab3a87d2 100644 (file)
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -624,14 +624,19 @@
 
         <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the
         kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on
-        <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section above).</para>
+        <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section above). Also note
+        that in this case stdout (or stderr, see below) will be an <constant>AF_UNIX</constant> stream socket, and not
+        a pipe or FIFO that can be re-opened. This means when executing shell scripts the construct <command>echo
+        "hello" &gt; /dev/stderr</command> for writing text to stderr will not work. To mitigate this use the construct
+        <command>echo "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
 
         <para>This setting defaults to the value set with
         <option>DefaultStandardOutput=</option> in
         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
         which defaults to <option>journal</option>. Note that setting
         this parameter might result in additional dependencies to be
-        added to the unit (see above).</para></listitem>
+        added to the unit (see above).</para>
+      </listitem>
       </varlistentry>
 
       <varlistentry>