Apache Module mod_systemd

Summary

This module provides support for systemd integration. It allows httpd to be used in a service with the systemd Type=notify or Type=notify-reload (see systemd.service(5) for more information). The module is activated if loaded.

[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

Special attention should be given to how ExecStop and/or KillMode are configured for the service. If configured, an ExecStop command should be a synchronous operation which itself exits when the daemon has terminated. Running httpd -k stop asynchronously initiates daemon termination, so does not satisfy this condition. The example above uses KillMode=mixed so that systemd sends SIGTERM to signal the parent process (and only the parent) to shut down. The entire process group is then sent SIGKILL after TimeoutStopSec elapses, if any processes are still running. See systemd.kill(5) for more information.

A service manager from systemd 253 onwards offers Type=notify-reload, which is worth using in preference. Under Type=notify a systemctl reload returns as soon as the ExecReload command has sent its signal, which is before the new configuration has been read, and it reports success whatever becomes of the restart afterwards. Type=notify-reload 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 RELOADING=1 notification the protocol expects while the configuration is being read, stamped with the MONOTONIC_USEC the service manager requires, and READY=1 once it has been loaded.

[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

The service manager runs ExecReload first, and sends the signal named by ReloadSignal only once that command has exited successfully. Keeping ExecReload is what makes the reload safe: httpd -k graceful 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 ExecReload 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.

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

Systemd socket activation is supported if httpd was built with it. Each Listen 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.

ExtendedStatus is enabled by default if the module is loaded. If ExtendedStatus is not disabled in the configuration, run-time load and request statistics are made available in the systemctl status output.

The systemd watchdog is supported. If the service unit sets WatchdogSec=, 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 Restart= 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.

That periodic notification is sent about every ten seconds, which is how often the parent process runs the hook it is sent from. A WatchdogSec= 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 WatchdogSec= of at least 20 seconds.

[Service]
WatchdogSec=30
Restart=on-failure

Directives

This module provides no directives.

Bugfix checklist

• httpd changelog
• Known issues
• Report a bug