# 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)

  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()

    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)

    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()

    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)

    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)

    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()

    Notify systemd that service startup is complete.

  reloading()

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

  stopping()

    Notify systemd that the service is stopping.

  watchdog_clean()

    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()

    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()

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

  watchdog_reset(timeout)

    Reset the systemd watchdog timer to timeout seconds.

nobodd.systemd.get_systemd()

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