From 11ec9b664356d5689ca8cdf50355aa0a3e6bb513 Mon Sep 17 00:00:00 2001
From: Rainer Jung <rjung@apache.org>
Date: Mon, 23 Aug 2010 11:13:23 +0000
Subject: [PATCH] Add information about "||" and "|$" piped log syntax to the
 docs.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@988071 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/logs.xml               | 18 ++++++++++++++++++
 docs/manual/mod/core.xml           |  7 +++++--
 docs/manual/mod/mod_log_config.xml |  3 ++-
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/docs/manual/logs.xml b/docs/manual/logs.xml
index 1007e49cb8..2cd776f524 100644
--- a/docs/manual/logs.xml
+++ b/docs/manual/logs.xml
@@ -565,6 +565,24 @@
     <p>As with conditional logging, piped logs are a very powerful
     tool, but they should not be used where a simpler solution like
     off-line post-processing is available.</p>
+
+    <p>By default the piped log process is spawned without invoking
+    a shell. Use "<code>|$</code>" instead of "<code>|</code>"
+    to spawn using a shell (usually with <code>/bin/sh -c</code>):</p>
+
+    <example>
+      # Invoke "rotatelogs" using a shell
+      CustomLog "|$/usr/local/apache/bin/rotatelogs
+      /var/log/access_log 86400" common
+    </example>
+
+    <p>This was the default behaviour for Apache 2.2.
+    Depending on the shell specifics this might lead to
+    an additional shell process for the lifetime of the logging
+    pipe program and signal handling problems during restart.
+    For compatibility reasons with Apache 2.2 the notation
+    "<code>||</code>" is also supported and equivalent to using
+    "<code>|</code>".</p>
   </section>
 
   <section id="virtualhost">
diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index 021b8b8153..820d9146c1 100644
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -993,13 +993,16 @@ in case of an error</description>
     </example>
 
     <p>If the <var>file-path</var>
-    begins with a pipe (|) then it is assumed to be a command to spawn
-    to handle the error log.</p>
+    begins with a pipe character "<code>|</code>" then it is assumed to be a
+    command to spawn to handle the error log.</p>
 
     <example><title>Example</title>
     ErrorLog "|/usr/local/bin/httpd_errors"
     </example>
 
+    <p>See the notes on <a href="../logs.html#piped">piped logs</a> for
+    more information.</p>
+
     <p>Using <code>syslog</code> instead of a filename enables logging
     via syslogd(8) if the system supports it. The default is to use
     syslog facility <code>local7</code>, but you can override this by
diff --git a/docs/manual/mod/mod_log_config.xml b/docs/manual/mod/mod_log_config.xml
index b25f30501e..7761b69edc 100644
--- a/docs/manual/mod/mod_log_config.xml
+++ b/docs/manual/mod/mod_log_config.xml
@@ -391,7 +391,8 @@
       <dt><var>pipe</var></dt>
       <dd>The pipe character "<code>|</code>", followed by the path
       to a program to receive the log information on its standard
-      input.
+      input. See the notes on <a href="../logs.html#piped">piped logs</a>
+      for more information.
 
       <note type="warning"><title>Security:</title>
       <p>If a program is used, then it will be run as the user who
-- 
2.40.0