docs/manual/mod/mod_systemd.html.en.utf8

<!DOCTYPE html SYSTEM "about:legacy-compat">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="width=device-width, initial-scale=1" name="viewport">
<!--
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
              This file is generated from xml source: DO NOT EDIT
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      -->
<title>mod_systemd - Apache HTTP Server Version 2.5</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet">
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size">
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css"><link rel="stylesheet" type="text/css" href="../style/css/prettify.css">
<script src="../style/scripts/prettify.min.js">
</script>

<link href="../images/favicon.png" rel="shortcut icon"></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="https://cwiki.apache.org/confluence/display/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a> | <a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2">Report a bug</a></p>
<p class="apache">Apache HTTP Server Version 2.5</p>
<img alt="" src="../images/feather.png"></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif"></a></div>
<div id="path">
<a href="https://www.apache.org/">Apache</a> &gt; <a href="https://httpd.apache.org/">HTTP Server</a> &gt; <a href="https://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_systemd</h1>
<button aria-label="Toggle language list" class="lang-toggle"><svg xmlns="http://www.w3.org/2000/svg" stroke-width="2" stroke="currentColor" fill="none" viewBox="0 0 24 24" height="16" width="16"><circle r="10" cy="12" cx="12"/><line y2="12" x2="22" y1="12" x1="2"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg></button>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_systemd.html" title="English">&nbsp;en&nbsp;</a> |
<a href="../fr/mod/mod_systemd.html" hreflang="fr" rel="alternate" title="Fran&ccedil;ais">&nbsp;fr&nbsp;</a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides better support for systemd integration</td></tr>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module&nbsp;Identifier:</a></th><td>systemd_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">Source&nbsp;File:</a></th><td>mod_systemd.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.4.42 and later</td></tr></table>
<h3>Summary</h3>

    <p>This module provides support for systemd integration. It allows
    httpd to be used in a service with the systemd
    <code>Type=notify</code> or <code>Type=notify-reload</code> (see <a 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>

    <div class="example"><h3>Example of systemd service unit (more settings are probably needed for production systems)</h3><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></div>

   <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>A service manager from systemd 253 onwards offers
   <code>Type=notify-reload</code>, which is worth using in preference.
   Under <code>Type=notify</code> a <code>systemctl reload</code>
   returns as soon as the <code>ExecReload</code> command has sent its
   signal, which is before the new configuration has been read, and it
   reports success whatever becomes of the restart afterwards.
   <code>Type=notify-reload</code> instead holds the reload open until
   the server reports it finished, so the command waits for the new
   configuration to be in use and fails if it never is.  mod_systemd
   sends the <code>RELOADING=1</code> notification the protocol expects
   while the configuration is being read, stamped with the
   <code>MONOTONIC_USEC</code> the service manager requires, and
   <code>READY=1</code> once it has been loaded.</p>

    <div class="example"><h3>Example of a service unit which reloads synchronously</h3><pre>[Service]
Type=notify-reload
ReloadSignal=SIGCONT
ExecStart=/usr/local/apache2/bin/httpd -D FOREGROUND -k start
ExecReload=/usr/local/apache2/bin/httpd -k graceful
KillMode=mixed</pre></div>

   <p>The service manager runs <code>ExecReload</code> first, and sends
   the signal named by <code>ReloadSignal</code> only once that command
   has exited successfully.  Keeping <code>ExecReload</code> is what
   makes the reload safe: <code>httpd -k graceful</code> parses the new
   configuration in a process of its own and exits without signalling
   anything if it does not parse, so the reload fails and the running
   server carries on with the configuration it already has.  Leaving
   <code>ExecReload</code> out, and letting the service manager signal
   the server directly, gives up that check: the running parent reads
   the new configuration itself, and a configuration which does not
   parse makes it exit, taking the server down.</p>

   <p>The signal sent after <code>ExecReload</code> has run is then
   redundant, so <code>ReloadSignal</code> should name one httpd does
   not act on, such as <code>SIGCONT</code>.  It matters that it is set:
   the default is <code>SIGHUP</code>, which httpd takes as an
   <em>ungraceful</em> restart, dropping the connections a reload is
   meant to preserve.  A unit which does leave out
   <code>ExecReload</code> must set <code>ReloadSignal=SIGUSR1</code>,
   the signal httpd restarts gracefully on.</p>

   <p>Systemd socket activation is supported if httpd was built with
   it.  Each <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code> port
   must then be one passed in by systemd; a port which was not is a
   fatal configuration error rather than one httpd opens for itself.
   Socket activation is used only if this module is loaded, so it can
   be built in and left unused.</p>

    <p><code class="directive"><a href="../mod/core.html#extendedstatus">ExtendedStatus</a></code> is
    enabled by default if the module is loaded.  If <code class="directive"><a href="../mod/core.html#extendedstatus">ExtendedStatus</a></code> is not disabled in
    the configuration, run-time load and request statistics are made
    available in the <code>systemctl status</code> output.</p>

    <p>The systemd watchdog is supported.  If the service unit sets
    <code>WatchdogSec=</code>, the parent process sends the keep-alive
    notification which tells systemd the server is still alive; a server
    which stops sending it is terminated and, with a suitable
    <code>Restart=</code> setting, restarted.  The notification is sent
    while the configuration is being read and again once it is loaded, so
    that a reload is covered, and periodically from the parent process
    while the server runs.</p>

    <p>That periodic notification is sent about every ten seconds, which
    is how often the parent process runs the hook it is sent from.  A
    <code>WatchdogSec=</code> of less than twice that cannot be met, and
    would have systemd terminating a server which is working normally;
    such a setting is reported as a warning at startup.  Use a
    <code>WatchdogSec=</code> of at least 20 seconds.</p>

    <div class="example"><h3>Adding watchdog supervision to either unit above</h3><pre>[Service]
WatchdogSec=30
Restart=on-failure</pre></div>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<p>This module provides no
            directives.</p>
<h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_systemd">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_systemd">Report a bug</a></li></ul></div>

</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_systemd.html" title="English">&nbsp;en&nbsp;</a> |
<a href="../fr/mod/mod_systemd.html" hreflang="fr" rel="alternate" title="Fran&ccedil;ais">&nbsp;fr&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Copyright 2026 The Apache Software Foundation.<br>Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="https://cwiki.apache.org/confluence/display/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a> | <a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2">Report a bug</a></p></div><script><!--//--><![CDATA[//><!--
if (typeof(prettyPrint) !== 'undefined') {
    prettyPrint();
}
var langToggle = document.querySelector('.lang-toggle');
var topLang = document.querySelector('.toplang');
if (langToggle && topLang) {
    langToggle.addEventListener('click', function() { topLang.classList.toggle('open'); });
}
var qv = document.getElementById('quickview');
if (qv) {
    document.body.appendChild(qv);
    var qvBtn = document.createElement('button');
    qvBtn.className = 'qv-toggle';
    qvBtn.setAttribute('aria-label', 'Toggle page navigation');
    qvBtn.innerHTML = '&#9776;';
    document.body.appendChild(qvBtn);
    qvBtn.addEventListener('click', function() {
        var isOpen = qv.classList.toggle('open');
        if (isOpen) {
            qv.style.top = window.scrollY + 10 + 'px';
        }
    });
    window.addEventListener('scroll', function() { qv.classList.remove('open'); });
}
//--><!]]></script>
</body></html>