EVENTD

Section: eventd Manual (1)
Updated: 02/26/2016
Index Return to Main Contents

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.

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:

evp

: which implements our own EVENT protocol
It is considered as a core plugin and all its relevant configuration will reside in the main eventd man pages.

fdo-notifications

: which implements the m[blue]Desktop Notifications Specificationm[][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:

relay

: a relay plugin, to relay events to remote eventd
It is considered as a core plugin and all its relevant configuration will reside in the main eventd man pages.

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

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

-P, --paths

: Print plugins, configuration and events search paths

-V, --version

: Print version

-h, --help

: Show help options

These options are for the evp plugin, listed here as it is considered a core plugin.

-l, --listen=socket

: Add a socket to listen to
May be specified multiple times.

EXIT STATUS

: eventd ended successfully.

: Failed to parse command line paramaters.

: Filesystem is not UTF-8 encoded.

: 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 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. 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=relay;
    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 3. 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 4. Relaying remote events: static relay

Using evp and relay plugins, eventd can relay events from a remote computer to your local one.

The evp plugin does not require any special configuration in a static setup.

The relay plugin 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 the relay plugin 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 5. Relaying remote D-Bus notifications

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

You need to configure relay and fdo-notifications plugins on the remote computer and evp and notify plugins 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_NO_PLUGINS

: If this variable is set, eventd will not load any plugin.

$EVENTD_PLUGINS_DIR

: Additional directory to browse for plugins.
This directory is 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_DIR

: Additional directory to browse for configuration files.
This directory is 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.