graceful and (nearly) immediate lighttpd restart option
For *some* configurations, it *may* be safe to background the current
lighttpd server (or workers) to continue processing active requests
and, in parallel, to start up a new lighttpd server with a new
configuration. For other configurations, doing so might not be safe!
Therefore, this option must be explicitly configured to enable:
server.feature-flags += ("server.graceful-restart-bg" => "enable")
server.systemd-socket-activation = "enable"
Along with enabling server.feature-flags "server.graceful-restart-bg",
enabling server.systemd-socket-activation allows transfer of open
listening sockets to the new lighttpd server instance, and occurs
without closing the listening sockets and without destroying the
kernel listen backlog queue on the socket.
Safe configurations may include lighttpd.conf which connect to
standalone backend daemons, e.g. proxying to other servers,
including PHP-FPM backends.
Unsafe configurations include lighttpd.conf which use "bin-path" option
in *.server configs, instructing lighttpd to execute the backends.
Using the graceful-and-immediate-restart option is likely *unsafe* if
the backend daemon expects only one instance of itself to run at a time.
Current implementation of graceful and immediate restart option keeps
the backgrounded lighttpd in the same process group, so that subsequent
SIGINT or SIGTERM will shut down both the new and the backgrounded
servers. (An alternative option (commented out in the code) is to
background and detach from the new lighttpd process.) Regardless,
existing subprocesses, such as CGI, remain in original process group.
As a result, the new lighttpd server may receive SIGCHLD for unknown
processes inherited from the old server, which the new lighttpd server
will reap and discard. The original lighttpd server, now a child, will
be unable to detect exit or reap and report status on those pre-existing
Graceful restart is triggered in lighttpd by sending lighttpd SIGUSR1.
If lighttpd is configured with workers, then SIGINT (not SIGUSR1) is
sent to the process group, including other processes started by
lighttpd, e.g. CGI. To work well with graceful restart, CGI scripts and
other processes should trap SIGINT (and SIGUSR1 for good measure).
Long-running scripts may want to checkpoint and close, e.g. a CGI script
implementing a long-running websocket connection.
provide standard types in first.h instead of base.h
provide lighttpd types in base_decls.h instead of settings.h
reduce headers exposed by headers for core data structures
do not expose <pcre.h> or <stdlib.h> in headers
move stat_cache_entry to stat_cache.h
reduce use of "server.h" and "base.h" in headers
more consistent cleanup of resources at shutdown
(e.g. upon error conditions)
Notes: graceful restart with SIGUSR1
- not available if chroot()ed, oneshot mode, or if idle timeout occurs
- preserve process id (pid)
- preserve existing listen sockets
- i.e. does not close old listen sockets from prior configs
(even if old listen sockets no longer in the new config)
(sockets may have been bound w/ root privileges no longer available)
- will fail to add listen sockets from new config if privileges
lighttpd configured to drop privileges to non-root user, and
new listen socket attempts to bind to low-numbered port requiring
- will fail if listen sockets in new config conflict with any previous
old listen sockets
- These failure modes will result in lighttpd shutting down instead of
graceful restart. These failure modes are not detectable with
preflight checks ('lighttpd -tt -f lighttpd.conf') because the
new instance of lighttpd running the preflight check does not
known config state of n prior graceful restarts, or even the
config state of the currently running lighttpd server.
- due to lighttpd feature of optionally managing backends
(e.g. fastcgi and scgi via "bin-path"), lighttpd must wait for
all child processes to exit prior to restarting. Restarting new
workers while old workers (and old backends) were still running would
result in failure of restarted lighttpd process to be able to bind to
sockets already in use by old backends (e.g. unix "socket" path)
"graceful restart with SIGUSR1"