killjoy

Monitor systemd units.

killjoy is a systemd unit monitoring application. It discovers systemd units and tracks their states. When a unit changes to a state of interest, killjoy contacts notifiers. Examples of notifiers include:

• killjoy Notifier: Logfile
• killjoy Notifier: Notification

Concepts

To understand killjoy, one must first understand systemd:

systemd is a suite of basic building blocks for a Linux system. It provides a system and service manager that runs as PID 1 and starts the rest of the system.

— systemd

Units are the resources that systemd knows how to manage. For example, here are several units which might be present on a host, and the resources they represent:

• nginx.service: Lightweight HTTP server and IMAP/POP3 proxy server
• logrotate.service: Rotate log files
• logrotate.timer: Rotate log files daily (i.e. periodically trigger logrotate.service)
• boot.mount: The /boot mount point

This list of units is small; a host can have many hundreds of units, of eleven different types.

There can be multiple systemd instances running on a host at a given time. Typically, there is one system-wide instance, and one instance per logged-in user. Each systemd instance maintains distinct units.

When killjoy starts, it reads a list of rules, where each rule declares units that killjoy should watch. For example, rules might state:

• Connect to the system bus and watch nginx.service. If it enters the "failed" state, contact the "logfile" notifier.
• Connect to the session bus and watch all .timer units. If any enter the "active" state, contact the "notification" notifier.

A notifier is an application that knows how to consume a D-Bus message from killjoy. The clear separation between killjoy and the notifiers means that anyone may write a notifier at any time, in whichever language they wish, to do whatever they want, and with no coordination from the killjoy development team. Two notifiers are developed in conjunction with killjoy, and they are small enough to be easily studied:

• killjoy Notifier: Logfile
• killjoy Notifier: Notification

For further conceptual information, see systemd(1), especially the section on concepts.

Alternatives

killjoy is inspired by sagbescheid, SystemdMon, pynagsystemd, and OnFailure=, but there are differences in features, reliability, and efficiency. Of special note:

• killjoy lets a user write generic rules, like "monitor all .timer units." This is in contrast to the case where a user must explicitly state every unit to be monitored. Furthermore, units may appear or disappear at runtime, e.g. when a package is installed or uninstalled, and killjoy correctly handles these events.
• killjoy is cleanly separated from notifiers. Users aren't restricted to the notifiers bundled with killjoy.

Installation

Arch Linux users may install using the killjoy-git AUR package. A stable package will be created when killjoy further matures.

Rust developers may install this app with cargo install killjoy. Note that libdbus must be installed. (On Ubuntu, this is provided by the libdbus-1-dev package.)

Configuration

killjoy searches for a configuration file at killjoy/settings.json as per the XDG Base Directory Specification, and the first one found is used. In practice, this means that the configuration file should typically be installed at ~/.config/killjoy/settings.json.

A sample configuration file is as follows:

{
    "version": 1,
    "rules": [
        {
            "bus_type": "session",
            "active_states": ["activating", "active", "deactivating", "inactive", "failed"],
            "expression": "foo.service",
            "expression_type": "unit name",
            "notifiers": ["logfile", "notification"]
        }
    ],
    "notifiers": {
        "logfile": {
            "bus_type": "session",
            "bus_name": "name.jerebear.KilljoyNotifierLogfile1"
        },
        "notification": {
            "bus_type": "session",
            "bus_name": "name.jerebear.KilljoyNotifierNotification1"
        }
    }
}

The contents of the settings file may be validated with killjoy settings validate.

The meaning of the configuration file is as follows:

• version defines how the rest of the configuration file is interpreted. There is currently one configuration file format, and this key should always be set to 1.
• rules is a list of rules stating which units should be monitored. For each rule:
  • bus_type defines which D-Bus buses killjoy shall connect to in search of systemd instances. It may be session or system.
  • All possible active_states are listed above; see systemd(1) for details.
  • expression_type and expression define which units should be monitored (out of all the units killjoy discovers when talking to systemd). If expression_type is:
    • unit name, then expression should be an exact unit name, like foo.service.
    • unit type, then expression should be a unit suffix, like .service.
    • regex, then expression should be a regex like ^f[aeiou]{2}\.service$. Note the presence of the line begin and end anchors, ^ and $.
  • notifiers is a list of notifier labels.
• notifiers is a map, where keys are notifier labels, and values define how to contact that notifier.
  • bus_type defines which message bus killjoy should connect to when sending a message to this notifier.
  • bus_name defines the bus name (i.e. address) of the notifier on the message bus.

Usage

The typical way to use killjoy is to let it automatically start on login:

systemctl --user enable --now killjoy.service

killjoy may also be invoked manually. Execute killjoy to run killjoy in the foreground, or killjoy --help to learn about its features.

Changelog

See annotated git tags.

License

killjoy is licensed under the GPLv3 or any later version.