nobodd.systemd
This module contains a singleton class intended for communication with the
systemd(1) service manager. It includes facilities for running a
service as Type=notify
where the service can actively communicate to
systemd that it is ready to handle requests, is reloading its configuration, is
shutting down, or that it needs more time to handle certain operations.
It also includes methods to ping the systemd watchdog, and to retrieve file-descriptors stored on behalf of the service (or provided as part of socket-activation).
Systemd Class
- class nobodd.systemd.Systemd(address=None)[source]
Provides a simple interface to systemd’s notification and watchdog services. It is suggested applications obtain a single, top-level instance of this class via
get_systemd()
and use it to communicate with systemd.- available()[source]
If systemd’s notification socket is not available, raises
RuntimeError
. Services expecting systemd notifications to be available can call this to assert that notifications will be noticed.
- extend_timeout(timeout)[source]
Notify systemd to extend the start / stop timeout by timeout seconds. A timeout will occur if the service does not call
ready()
or terminate within timeout seconds but only if the original timeout (set in the systemd configuration) has already been exceeded.For example, if the stopping timeout is configured as 90s, and the service calls
stopping()
, systemd expects the service to terminate within 90s. After 10s the service callsextend_timeout()
with a timeout of 10s. 20s later the service has not yet terminated but systemd does not consider the timeout expired as only 30s have elapsed of the original 90s timeout.
- listen_fds()[source]
Return file-descriptors passed to the service by systemd, e.g. as part of socket activation or file descriptor stores. It returns a
dict
mapping each file-descriptor to its name, or the string “unknown” if no name was given.
- main_pid(pid=None)[source]
Report the main PID of the process to systemd (for services that confuse systemd with their forking behaviour). If pid is None,
os.getpid()
is called to determine the calling process’ PID.
- notify(state)[source]
Send a notification to systemd. state is a string type (if it is a unicode string it will be encoded with the ‘ascii’ codec).
- reloading()[source]
Notify systemd that the service is reloading its configuration. Call
ready()
when reload is complete.
- watchdog_clean()[source]
Unsets the watchdog environment variables so that no future child processes will inherit them.
Warning
After calling this function,
watchdog_period()
will returnNone
but systemd will continue expectingwatchdog_ping()
to be called periodically. In other words, you should callwatchdog_period()
first and store its result somewhere before calling this function.
- watchdog_period()[source]
Returns the time (in seconds) before which systemd expects the process to call
watchdog_ping()
. If a watchdog timeout is not set, the function returnsNone
.
- watchdog_ping()[source]
Ping the systemd watchdog. This must be done periodically if
watchdog_period()
returns a value other thanNone
.