EVENTD(1)

NAME
eventd - small daemon to act on remote or local events

SYNOPSIS

eventd [OPTIONS...]

DESCRIPTION

eventd is a simple daemon to track remote or local events and do actions the user wants to.

eventd is composed by a core, the daemon itself, and various plugins. Plugins may be event collecting plugins or action plugins.

eventd core implements plugins loading and our own EVENT protocol to carry events on network. It also implements a relay, using the EVENT protocol to act as a client to another eventd.

The default operation mode is user mode. This means the user configuration will be read, and all plugins will be loaded. If $XDG_RUNTIME_DIR is not set, eventd will then operate in system mode. This means the system configuration (in /etc) will be read, and only some plugin will be loaded.

EVENTS

The core daemon will not dispatch unknown events to action plugins. Default events are distributed with eventd in /usr/share/eventd.

Official actions plugins will require at least a section in the matching event file to act on a specific event. Third party plugin are advised to do the same for consistency.

See eventd.conf(5) for detailed information.

PLUGINS

When eventd starts, it loads all the available plugins found in the following directories, in this order:

    1. $EVENTD_PLUGINS_DIR (see the section called “ENVIRONMENT”)

    2. $XDG_DATA_HOME/eventd (fallback to ~/.local/share/eventd)

    3. /usr/lib/eventd (actual path depends on your configuration)

Each plugin, identified by a compiled-in identifier, is loaded only once, on first encounter.

You can white- and blacklist plugins by definining environment variables (see the section called “ENVIRONMENT”).

These paths are standard paths. Actual paths may depend on your configuration, see eventd -P output.

  Event collection plugins

An event collection plugin will listen to clients and queue events in eventd.

The following event collection plugins are installed with eventd:

fdo-notifications
    which implements the Desktop Notifications Specification[1]

    Events generated by this plugin are of the "notification" category.

  Action plugins

An action plugin will do something when an event is dispatched by eventd.

The following action plugins are installed with eventd:

exec (see eventd-exec.conf(5))
    a simple exec plugin, to exec arbitrary commands

file (see eventd-file.conf(5))
    a simple file writer plugin, to write arbitrary string to arbitrary files

nd (see eventd-nd.conf(5))
    a notification plugin, aka "bubble" plugin

notify (see eventd-notify.conf(5))
    a libnotify client plugin

OPTIONS

-l, --listen=socket
    Add a socket to listen to for EVENT protocol clients.

    May be specified multiple times.

    The format is type:socket:

    unix, unix-runtime
        socket is the file name of the UNIX socket.

        The -runtime version takes a file name relative to $XDG_RUNTIME_DIR.

    tcp
        socket is a classic [address:]port.

    tcp-file, tcp-file-runtime
        The evp plugin will listen to a random port on the loopback interface only.

        socket is a file name the plugin will write the port to.

        The -runtime version takes a file name relative to $XDG_RUNTIME_DIR.

-t, --take-over
    Take over socket

    If possible, will take the sockets from an already running eventd.

-i, --private-socket=socket
    Socket to listen for internal control

    See eventdctl(1)

-c, --config-dir=directory
    Additionnal configuration directory

    See eventd.conf(5)

-P, --paths
    Print plugins, configuration and events search paths

-V, --version
    Print version

-h, --help
    Show help options

EXIT STATUS

0
    eventd ended successfully.

1
    Filesystem is not UTF-8 encoded.

3
    Failed to parse command line paramaters.

4
    The (required) runtime directory could not be created.

10
    Failed to start the control interface.

EXAMPLES

Example 1. As a notification daemon

With its fdo-notifications plugin and nd plugin with xcb backend, eventd can act as a notification daemon. The default generated notifications looks a lot like notify-osd’s ones.

This feature should work automagically using D-Bus on-demand spawning.

If you use several X displays or launch your session D-Bus daemon manually, you should add the following line to your ~/.xsession or equivalent file:

    eventdctl --auto-spawn notification-daemon switch xcb ${DISPLAY}

See eventdctl(1) for eventdctl call precisions.

Example 2. dunst-like style

This is the same use case as the previous example, with some configuration tweaks to match dunst’s style.

Here is the configuration:

    "eventd.conf":
        [Anchor top]
        Margin=0
        Spacing=0
        Limit=10
        [Notification]
        Text=${title} ${message}
        [NotificationBubble]
        Anchor=top
        # We use a really large minimum width so the plugin will clamp it to screen size
        MinWidth=7777777
        Padding=2
        Radius=0
        Colour=#1793D1
        [NotificationText]
        Font=Terminus 16px
        Colour=#DDDDDD
        [NotificationImage]
        MaxHeight=25
        Anchor=Center
        [NotificationIcon]
        Placement=Foreground
        MaxHeight=25
    "notification-urgencies.event":
        [Event notification  low]
        IfData=urgency;
        IfDataMatches=urgency,==,byte 0;
        Actions=notification-low;
        [Event notification  critical]
        IfData=urgency;
        IfDataMatches=urgency,==,byte 2;
        Actions=notification-critical;
    "notification-low.action":
        [Action]
        Name=notification-low
        [Notification]
        [NotificationBubble]
        Colour=#aaaaff
        [NotificationText]
        Colour=#000000
    "notification-critical.action":
        [Action]
        Name=notification-critical
        [Notification]
        [NotificationBubble]
        Timeout=0
        Colour=#ffaaaa
        [NotificationText]
        Colour=#000000

Example 3. Custom event: notify the end of a command

Here is a complete example of a custom event. Please refer to the relevant man page for further information.

We will use three files: one for the category "command" and one for each event, "success" and "failure". These files will be placed in $XDG_CONFIG_HOME/eventd (fallback to ~/.config/eventd/). Here is their contents:

    "eventd.conf":
        [Relay]
        Relays=command;
        [Relay command]
        Forwards=command;
        Server=myothercomputer.local
    "command.event":
        [Event command success]
        Actions=command-success;
        [Event command failure]
        Actions=command-failure;
    "command-success.action":
        [Action]
        Name=command-success
        [Notification]
        Title=${command} succeeded
        Message=${time}
        [Libnotify]
        Title=${command} succeeded
        Message=${time}
    "command-failure.action":
        [Action]
        Name=command-failure
        [Notification]
        Title=${command} failed
        Message=${time}
        [NotificationBubble]
        Colour=#ff0000
        [Libnotify]
        Title=${command} failed
        Message=${time}

This configuration will:

    • relay any event in the "command" category to "myothercomputer.local"

    • Display a grey (default colour) bubble when a command succeeds, with the "command succeded" message and time

    • Display a red bubble when a command fails, with the "command failed" message and time

    • Display a notification with your favorite notification daemon when a command succeeds, with the "command succeded" message and time

    • Display a notification with your favorite notification daemon when a command fails, with the "command failed" message and time

You can trigger the event manually using a command like that:

    make; eventc command $([ $? -eq 0 ] && echo success || echo failure) -d command=make

You can also hook your favorite shell to make it automatic. Here are some example for Zshell, Bash or Fish:

    Zshell zshrc:
        precmd() {
            local s=$? c=( $(fc -l -D -1 ) )
            eventc command $([[ ${s} == 0 ]] && echo success || echo failure) -d command="${c[3,-1]}" -d time="${c[2]}"
        }
    Bash bashrc:
        precmd() {
            command=$(history -1)
            [[ -z "${command} ]] && return
            eventc command $([ $? -eq 0 ] && echo success || echo failure) -d command="${command}"
        }
        # This command is called anytime the prompt is displayed
        # so this may not work perfectly as expected
        PROMPT_COMMAND=precmd
    Fish config:
        function notify_on_command_duration --on-variable CMD_DURATION
            eventc command $([ $? -eq 0 ] && echo success || echo failure) -d command="$_" -d time="$CMD_DURATION"
        end

Example 4. As a relay to a notification daemon

With its notify plugin, eventd can relay events to a notification daemon.

eventd allow a lot of flexibility in events and configuration. You can use these features while still having your usual notification daemon to display notifications. It may be useful for highly integrated notification daemons.

eventd notify plugin also has support for displaying a small icon over the usual notification image.

See eventd-notify.conf(5) for the notify plugin configuration.

Example 5. Relaying remote events: static relay

eventd can relay events to a remote computer from your local one.

eventd will connect to configured servers at startup. You can control connections using eventdctl with the following commands:

    eventdctl relay connect your.distant.computer
    eventdctl relay disconnect your.distant.computer

See eventd.conf(5) for configuration.

See eventdctl(1) for eventdctl call precisions.

    "eventd.conf":
        [Relay]
        Relays=one;
        [Relay one]
        Server=your.distant.computer
        Forwards=foo;bar;baz;
    "foo.event":
        [Event foo]
        [Event bar]
        [Event baz]

Example 6. Relaying remote events: DNS-SD

With DNS-SD supports, eventd will advertise itself on the network.

eventd will connect to configured servers when advertised.

From the above example, you simply need to configure eventd to search through DNS-SD (using the default name of the server, see eventd.conf(5)):

    "eventd.conf":
        [Relay]
        Relays=one;
        [Relay one]
        DiscoverName=eventd your.distant.computer
        Forwards=foo;bar;baz;

Example 7. Relaying remote D-Bus notifications

Combining fdo-notifications and notify plugins, you can easily relay remote D-Bus notifications to your local computer.

You need the fdo-notifications plugin on the remote computer and the notify plugin on the local one.

The default provided configurations for the notify plugin is enough on your local computer. On the remote one, you will need to configure a relay to your local computer. Here is the content of the needed file:

    "eventd.conf":
        [Relay]
        Relays=remote;
        [Relay remote]
        Server=myothercomputer.local
        Forwards=notification;

ENVIRONMENT

$EVENTD_PLUGINS_PATH
    A :-separated list of directories to browse for plugins.

    These directories are browsed first, before standard directories.

$EVENTD_PLUGINS_WHITELIST
    Comma-separated list of filename prefixes

    If a plugin id does not match, it will not be loaded. If unset, all plugins are allowed.

$EVENTD_PLUGINS_BLACKLIST
    Comma-separated list of filename prefixes

    If a plugin id matches, it will not be loaded. If unset, no plugins are disallowed.

    This blacklist is tested after the whitelist.

$EVENTD_CONFIG_PATH
    A :-separated list of directories to browse for configuration files.

    These directories are browsed last, after standard directories, and override their files.

SOCKETS

$XDG_RUNTIME_DIR/eventd/private
    Used internally by eventdctl(1) to communicate with eventd. This location can be overridden by the --private-socket option.

    If $XDG_RUNTIME_DIR is not set, we use $XDG_CACHE_HOME, with a fallback to ~/.cache.

SEE ALSO

eventd core man pages

    eventd(1)
        eventd daemon command-line options

    eventdctl(1)
        eventdctl (control tool) command-line options

    eventd.conf(5)
        eventd configuration

        Contains information about all the event configuration

    Plugins installed with eventd will use the same scheme: eventd-plugin-name for their additional eventd command-line options, eventdctl-plugin-name for their additional eventdctl command-line options, eventd-plugin-name.conf for their configuration,

Plugins man pages

        • exec plugin: eventd-exec.conf(5)

        • file plugin: eventd-file.conf(5)

        • nd plugin: eventdctl-nd(1) eventd-nd.conf(5)

        • notify plugin: eventd-notify.conf(5)

AUTHOR

Quentin Glidic <sardemff7@eventd.org>
    Developer

NOTES

1.  Desktop Notifications Specification
    http://people.gnome.org/~mccann/docs/notification-spec/notification-spec-latest.html