NAME

SYNOPSIS

eventd is using three differente types of configuration files: global, event and action files.

The files are searched in these directories in the following order:

1. /usr/share/eventd

2. /etc/eventd

3. $XDG_CONFIG_HOME/eventd (fallback to ~/.config/eventd/)

4. $EVENTD_CONFIG_DIR (see eventd(1))

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

Global configuration file

The global configuration file is named eventd.conf.

Each file found in the configuration directories is parsed one after the other, so the latest file can override settings in a preceding one.

Event and action files

The event and action files can be extended via a configuration key (see the section called “EVENT AND ACTION SECTIONS”).

If the same file is found in several places, the last one is used.

File concatenation is done after each directory was searched for files, so you can override them.

eventd will also walk through subdirectories, to let you organize your events.

An event file is mandatory for the event to be processed by eventd.

DESCRIPTION

eventd configuration files use a Key=Value syntax, organized in categories. Categories are specified using square brackets (e.g. [Category Name]). List values are semi-colon-separated (';'). More details are available in the m[blue]XDG Desktop Entry Specificationm[][1].

Global configuration file

This file is passed to every plugin so they can read their global configuration too.

Sections read in these files are identified as “Global sections”.

Event files

Event files describes the events that the daemon will recognise when an event collection plugin will push it.

These files are only ever read by eventd itself.

They define a list of action ids that eventd (and its plugins) should trigger when a matching event fires up.

Unknown action ids are silently ignored. If an event ends with an empty action list, it is discarded.

Sections read in these files are identified as “Event sections”.

Action files

Action files describes the actions that the plugins may do when dispatching an event. Each action can itself trigger subactions.

eventd itself reads very little information in there, but plugins can read as much as they want to determine their exact behaviour when the action is triggered.

Official action plugins require at least their own configuration section to do something. They have no “catch-all” action.

Sections read in these files are identified as “Action sections”.

CONFIGURATION KEY TYPES

Each key can be of a specified type. Basic types are integer, boolean or string, sometimes constrained like milliseconds or percentage.

For positives numeric types, -1 may be allowed to mean infinity.

For strings, a localised version may be used and will be indicated as such.

For lists, items are separated by a semicolon (';'). You can optionally end the list with a semicolon too.

Enumeration

An enumeration is a string which can take a limited set of values. Values are case-insensitive.

Accepted values depend on the key and will be listed in the relevant key descriptions.

Format strings

A format string can contain references to event data.

References use a shell-like format: ${reference-name}. Each reference is resolved to a data that is substitued to the reference at the corresponding place in the string.

You can use a fallback value if the data resolves to nothing. The syntax is: ${reference-name:-fallback-value}.

You can use a substitute value if the data resolves to something. The syntax is: ${reference-name:+substitute-value}.

You can replace parts of the data using the regex mechanism. The syntax is: ${reference-name/regex/replacement}. The replacement part is optional (including the preceding forward slash). If it is omitted, matching parts of the data will simply be removed. You can repeat the /regex/replacement part to replace as many patterns as you like. Each pattern is matched against the previous replacement so be careful in your order.

Examples (with data and resolved string):

"${name} is eating a ${fruit}."

name is "Bob" and fruit is "pear".

Resolves to: Bob is eating a pear.

"${name} is eating a ${fruit:-banana}."

name is "Bob" and fruit is "pear".

Resolves to: Bob is eating a pear.

"${name} is eating a ${fruit:-banana}."

name is "Bob" and fruit is nothing.

Resolves to: Bob is eating a banana.

"${name} is eating a ${meat}${condiment:+ with }${condiment}."

name is "Bob", meat is "steak" and condiment is "mustard".

Resolves to: Bob is eating a steak with mustard.

"${name} is eating a ${meat}${condiment:+ with }${condiment}."

name is "Bob", meat is "steak"and condiment is nothing.

Resolves to: Bob is eating a steak.

"${name} is eating a ${meat}${condiment/^/ with }."

name is "Bob", meat is "steak" and condiment is "mustard".

Resolves to: Bob is eating a steak with mustard.

"${name} is eating a ${meat}${condiment/^/ with }."

name is "Bob", meat is "steak"and condiment is nothing.

Resolves to: Bob is eating a steak.

"${name} is eating a ${meat}${condiment/^/ with /$/ from France}."

name is "Bob", meat is "steak" and condiment is "mustard".

Resolves to: Bob is eating a steak with mustard from France.

File URI

A file URI is a string that can be either a data name or a format string of an URI scheme.

In the former case, the data is searched in the event, and then parsed as an URI.

Two URI schemes are supported: file:// and data: (m[blue]Base64m[][2] extension only, charset and mime type may be ignored).

Colour strings

The colour string format is borrowed from the m[blue]CSS3 colour valuesm[][3]. Hexadecimal (#-prefixed) and decimal (rgb() format) RGB(A) notations are supported.

Here is a quick description:

#RRGGBB[AA], #RGB[A]

Each value is an hexadecimal value in the 0x00-0xff range.

The alpha value is an extension of the CSS3 notation and is optional.

The single-letter version means duplicating the character (e.g. "#123" means "#112233").

rgb(red, green, blue), rgba(red, green, blue, alpha)

Each colour value can be an integer in the 0-255 range or a percentage value.

The alpha value is a floating point value.

Other types

More specific types are described in the relevant key description.

CONFIGURATION IDS AND EVENT MATCHING

When eventd receive an event from one of its event collecting plugin, it searches the best match, using the following mechanism:

1. event will first try to get a list of possible matches basde on event’s category and name:

1. eventd will get the list of matches for both the category and the name of the event

2. If the list is empty, eventd will get the list matches for the category the event

3. If the list is still empty, the event is unknown and will not be dispatched.

2. event will then test all possible matches to find the best one.

If one of them matches, trigger its actions, otherwise continue

If none of them matches, the event is unknown and will not be dispatched.

Multiple events can match the name and the category. eventd provides a fine-grained matching mechanism. Several keys are dedicated to that. See the section called “Matching keys”.

GLOBAL SECTIONS

Section [Server]

This section controls the evp plugin, listed here as it is considered a core plugin.

TLSCertificate=

A file name

The path to the TLS certificate file.

TLSKey=

A file name

The path to the TLS private key file.

If not specified, the certificate file is expected to contain the key.

AvahiName= (defaults to "eventd hostname")

A string

The name that the server will publish using Avahi.

GnuTLSPriority=

A string

A convenience key to set the $G_TLS_GNUTLS_PRIORITY environment variable.

It will not override the environment variable if it is present when you run eventd.

Section [Relay]

This section controls the relay plugin, listed here as it is considered a core plugin.

Servers=

A list of names

A list of names that will be used to discover [Relay name] sections.

Section [Relay name]

This section controls the relay plugin, listed here as it is considered a core plugin.

Server=

A server string

The form is name[:port].

If you omit port or use 0, the SRV DNS record _evp._tcp.host will be used to find the real host and port to connect to.

Static servers the relay plugin will connect to.

Avahi=

An Avahi name

Avahi name of servers the relay plugin will connect to.

If you provide both Server= and Avahi=, the former is ignored.

AcceptUnknownCA=

A boolean

Whether to accept a certificate with an unknown CA (like a self-signed certificate).

Forwards=

A list of event categories

The list of event categories the plugin will forward.

If empty (but present), will forward everything.

Subscriptions=

A list of event categories

The list of event categories the plugin will subscribe to.

If empty (but present), will subscribe to everything.

EVENT AND ACTION SECTIONS

Section [File]

This section if for file inclusion. It allows a more customised management of your files.

Extends=

A file name

Prepend the specified file to this one.

EVENT SECTIONS

Section [Event category [name [sub-name]]]

This is the main event configuration section. It contains the core related settings.

The category and name are used to match the event while sub-name is only meant to differentiate sections and is not used anywhere in eventd.

Matching keys

IfData=

A list of data names

All data listed here must exist for this event id to match.

IfDataMatches=

A list of (data name,regex) tuples

If the named data is present, it must match the provided regex. All present data must match for this event id to match.

OnlyIfFlags=

A list of flag names

eventd will only dispatch an event if all of these flags are present.

NotIfFlags=

A list of flag names

eventd will only dispatch an event if none of these flags is present.

Importance= (defaults to 9223372036854775807 or 0, see below)

An integer (can be negative)

The less you put here, the more important this event configuration is. It allows you to order alternative configurations, as the first matching configuration is taken.

If you only have Category and/or Name keys, the default value is 9223372036854775807.

If you have more precise matching keys, the default value is then 0.

Event configuration keys

Disable=

A boolean

If true, the event is not dispatched.

Actions=

A list of action names

The list of actions to trigger when the event fires up.

See the section called “ACTION SECTIONS”.

ACTION SECTIONS

Section [Action]

This section allows to identify the action uniquely and link it to subactions if wanted.

Name=

An action name

This name can be used in the Subactions= key of this section or the Actions= key of the [Event] section.

Subactions=

A list of action names

The list of sub actions to trigger.

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.

XDG Desktop Entry Specification

http://standards.freedesktop.org/desktop-entry-spec/latest/

2.

Base64

https://en.wikipedia.org/wiki/Base64

3.

CSS3 colour values

http://www.w3.org/TR/2011/REC-css3-color-20110607/#numerical

Index

NAME

SYNOPSIS

Global configuration file

Event and action files

DESCRIPTION

Global configuration file

Event files

Action files

CONFIGURATION KEY TYPES

Enumeration

Format strings

File URI

Colour strings

Other types

CONFIGURATION IDS AND EVENT MATCHING

GLOBAL SECTIONS

Section [Server]

Section [Relay]

Section [Relay name]

EVENT AND ACTION SECTIONS

Section [File]

EVENT SECTIONS

Section [Event category [name [sub-name]]]

ACTION SECTIONS

Section [Action]

SEE ALSO

AUTHOR

NOTES