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:
(see the section called “Environment”)$EVENTD_PLUGINS_DIR
(fallback to$XDG_DATA_HOME
/eventd~/.local/share/eventd
)/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:
"
: [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=25eventd.conf
""
: [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-urgencies.event
""
: [Action] Name=notification-low [Notification] [NotificationBubble] Colour=#aaaaff [NotificationText] Colour=#000000notification-low.action
""
: [Action] Name=notification-critical [Notification] [NotificationBubble] Timeout=0 Colour=#ffaaaa [NotificationText] Colour=#000000notification-critical.action
"
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:
"
: [Queue utility] Anchor=top-left Margin=0 Spacing=0 Limit=1eventd.conf
""
: [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.event
""
: [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=25notification-utility.action
"
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:
"
: [Queue voip-overlay] Anchor=top-left Margin=10 100 Spacing=0 Limit=20eventd.conf
""
: [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.event
""
: [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=25notification-voip-overlay-on.action
""
: [File] Extends=notification-voip-overlay-on.action [Action] Name=notification-voip-overlay-off [Notification] Icon=theme:microphone-sensitivity-muted-symbolicnotification-voip-overlay-off.action
"
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
(fallback to $XDG_CONFIG_HOME
/eventd~/.config/eventd/
).
Here is their contents:
"
: [Relay] Relays=command; [Relay command] Forwards=command; Server=myothercomputer.localeventd.conf
""
: [Event command success] Actions=command-success; [Event command failure] Actions=command-failure;command.event
""
: [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-successcommand-success.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-failurecommand-failure.action
"
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
"
message and timecommand
succeded"Display a red bubble when a command fails, with the
"
message and timecommand
failed"Play the
"
sound when a command succeedscommand-success.ogg
"Play the
"
sound when a command failscommand-failure.ogg
"Display a notification with your favorite notification daemon when a command succeeds, with the
"
message and timecommand
succeded"Display a notification with your favorite notification daemon when a command fails, with the
"
message and timecommand
failed"Play the
"command-success"
sound when a command succeedsPlay 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.
"
: [Relay] Relays=one; [Relay one] Server=your.distant.computer Forwards=foo;bar;baz;eventd.conf
""
: [Event foo] [Event bar] [Event baz]foo.event
"
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
exec plugin: eventd-exec.conf(5)
file plugin: eventd-file.conf(5)
nd plugin: eventdctl-nd(1) eventd-nd.conf(5)
im plugin: eventdctl-im(1) eventd-im.conf(5)
sound plugin: eventd-sound.conf(5)
tts plugin: eventd-tts.conf(5)
notify plugin: eventd-notify.conf(5)
canberra plugin: eventd-canberra.conf(5)