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 calls extend_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).

ready()[source]

Notify systemd that service startup is complete.

reloading()[source]

Notify systemd that the service is reloading its configuration. Call ready() when reload is complete.

stopping()[source]

Notify systemd that the service is stopping.

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 return None but systemd will continue expecting watchdog_ping() to be called periodically. In other words, you should call watchdog_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 returns None.

watchdog_ping()[source]

Ping the systemd watchdog. This must be done periodically if watchdog_period() returns a value other than None.

watchdog_reset(timeout)[source]

Reset the systemd watchdog timer to timeout seconds.

nobodd.systemd.get_systemd()[source]

Return a single top-level instance of Systemd; repeated calls will return the same instance.