From 6f11cd71cf99309a29d68399f91d12f07ef50895 Mon Sep 17 00:00:00 2001
From: Joe Orton <jorton@apache.org>
Date: Tue, 11 Feb 2020 16:20:00 +0000
Subject: [PATCH] Merge r1873835, r1873889 from trunk:

mod_systemd.xml: add basic unit example [skip ci]

Add some blurb on correctly stopping the service w/mod_systemd. [skip ci]

Submitted by: elukey, jorton


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1873914 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/mod_systemd.xml | 35 +++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/manual/mod/mod_systemd.xml b/docs/manual/mod/mod_systemd.xml
index 9d53e0cf9bc..089d6296609 100644
--- a/docs/manual/mod/mod_systemd.xml
+++ b/docs/manual/mod/mod_systemd.xml
@@ -36,6 +36,41 @@
     href="https://www.freedesktop.org/software/systemd/man/systemd.service.html">systemd.service(5)</a>
     for more information).  The module is activated if loaded.</p>
 
+    <example>
+    <title>Example of systemd service unit (more settings are probably needed for production systems)</title>
+    <pre>
+[Unit]
+Description=The Apache HTTP Server
+After=network.target
+
+[Service]
+Type=notify
+ExecStart=/usr/local/apache2/bin/httpd -D FOREGROUND -k start
+ExecReload=/usr/local/apache2/bin/httpd -k graceful
+KillMode=mixed
+
+[Install]
+WantedBy=multi-user.target
+    </pre>
+    </example>
+
+   <p>Special attention should be given to how <code>ExecStop</code>
+   and/or <code>KillMode</code> are configured for the service.  If
+   configured, an <code>ExecStop</code> command should be a
+   <em>synchronous operation</em> which itself exits when the daemon
+   has terminated.  Running <code>httpd -k stop</code>
+   <em>asynchronously</em> initiates daemon termination, so does not
+   satisfy this condition.  The example above uses
+   <code>KillMode=mixed</code> so that systemd sends
+   <code>SIGTERM</code> to signal the parent process (and only the
+   parent) to shut down.  The entire process group is then sent
+   <code>SIGKILL</code> after <code>TimeoutStopSec</code> elapses, if
+   any processes are still running.  See <a
+   href="https://www.freedesktop.org/software/systemd/man/systemd.kill.html">systemd.kill(5)</a>
+   for more information.</p>
+    
+   <p>This module does not provide support for Systemd socket activation.</p>
+
     <p><directive module="core">ExtendedStatus</directive> is
     enabled by default if the module is loaded.  If <directive
     module="core">ExtendedStatus</directive> is not disabled in
-- 
2.47.3