eventd(1)

small daemon to act on remote or local events

Build version: 0.25.0 - v0.25.0

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. eventd can server the EVENT protocol over WebSocket. The detection is automatic at the client connection.

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 distributed with eventd:

fdo-notifications

which implements the Desktop Notifications Specification

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

im (see eventd-im.conf(5))

an IM plugin

sound (see eventd-sound.conf(5))

a sound file playing plugin

tts (see eventd-tts.conf(5))

a Text-to-Speech plugin

notify (see eventd-notify.conf(5))

a libnotify client plugin

canberra (see eventd-canberra.conf(5))

a libcanberra 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 for libnotify/notify-send

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

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

On a systemd-enabled system, eventd is a user service, so you must use systemctl --user and not systemctl to manage it. To enable eventd, just run the following commands:

systemctl --user enable eventd
systemctl --user start eventd-control.socket eventd.socket # just the first time for the current session

The second command can be replaced by a session or a computer restart.

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":
    [Queue default]
    Anchor=top
    Margin=0
    Spacing=0
    Limit=10

    [Notification]
    Text=${title} ${message}

    [NotificationBubble]
    # We use a really large minimum width so the plugin will clamp it to screen size
    MinWidth=7777777
    Padding=2
    Radius=0
    BorderBlur=0
    Colour=#1793D1

    [NotificationText]
    Font=Terminus 16px
    Colour=#DDDDDD

    [NotificationImage]
    Height=25
    Anchor=Center

    [NotificationIcon]
    Placement=Foreground
    Height=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. Putting specific notifications at a different position

Some notifications appear when you change monitor brightness, mouse resolution or volume. However, you know when they pop, and they may not be as critical as others, disturbing even. To that end, we will put them in the top left corner.

Here is the configuration:

"eventd.conf":
    [Queue utility]
    Anchor=top-left
    Margin=0
    Spacing=0
    Limit=1

"notification-utility.event":
    [Event notification * mouse-tool]
    IfDataMatches=client-name,==,"mouse-tool";
    Actions=notification-utility;

    [Event notification * volume-tool]
    IfDataMatches=client-name,==,"volume-tool";
    Actions=notification-utility;

"notification-utility.action":
    [Action]
    Name=notification-utility

    [Notification]
    Text=${title} ${message}

    [NotificationBubble]
    Queue=utility
    Padding=2
    Radius=0
    BorderBlur=0

    [NotificationImage]
    Height=25
    Anchor=Center

    [NotificationIcon]
    Placement=Foreground
    Height=25

Example 4. VOIP overlay-like feature

Some VOIP software (mostly gaming ones) have an overlay feature to easily see who is speaking at any given time. Using the relevant plugins (to the VOIP softwares) to dispatch voip talking events, we can create an overlay with the nd plugin.

Here is the configuration:

"eventd.conf":
    [Queue voip-overlay]
    Anchor=top-left
    Margin=10 100
    Spacing=0
    Limit=20

"notification-voip.event":
    [Event voip talking on]
    IfDataMatches=talking,==,true;
    Actions=notification-voip-overlay-on;
    [Event voip talking off]
    IfData=talking;
    IfDataMatches=talking,==,false;
    Actions=notification-voip-overlay-off;

"notification-voip-overlay-on.action":
    [Action]
    Name=notification-voip-overlay-on

    [Notification]
    Text=${buddy-name}
    Icon=theme:microphone-sensitivity-high-symbolic

    [NotificationBubble]
    Queue=utility
    Padding=2
    Radius=0
    BorderBlur=0

    [NotificationImage]
    Height=25
    Anchor=Center

    [NotificationIcon]
    Placement=Foreground
    Height=25

"notification-voip-overlay-off.action":
    [File]
    Extends=notification-voip-overlay-on.action

    [Action]
    Name=notification-voip-overlay-off

    [Notification]
    Icon=theme:microphone-sensitivity-muted-symbolic

Example 5. 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}

    [Sound]
    File=file://command-success.ogg

    [Libnotify]
    Title=${command} succeeded
    Message=${time}

    [Libcanberra]
    Name=command-success

"command-failure.action":
    [Action]
    Name=command-failure

    [Notification]
    Title=${command} failed
    Message=${time}

    [NotificationBubble]
    Colour=#ff0000

    [Sound]
    File=file://command-failure.ogg

    [Libnotify]
    Title=${command} failed
    Message=${time}

    [Libcanberra]
    Name=command-failure

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

  • Play the "command-success.ogg" sound when a command succeeds

  • Play the "command-failure.ogg" sound when a command fails

  • 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

  • Play the "command-success" sound when a command succeeds

  • Play the "command-failure" sound when a command fails

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 6. 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 7. 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 8. 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 9. 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 distributed 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