eventd.conf(5)

eventd main configuration file

Build version: 0.25.0 - v0.25.0

Name

eventd.conf — eventd main configuration file

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. In user mode (the default): $XDG_CONFIG_HOME/eventd (fallback to ~/.config/eventd/)

  3. In system mode: /etc/eventd

  4. $EVENTD_CONFIG_DIR (see eventd(1))

  5. Directory passed with --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 XDG Desktop Entry Specification.

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. The reference-name can be composed of alphabetic characters, dashes ('-') and underscores ('_').

You can use an array-like syntax for some values: ${reference-name[key]}. The key can be a name or a number depending on the data pointed by reference-name. You can use fallback values, substitute values or regexes on array members.

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

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

You can use a substitute value if (and only if) the data resolves to nothing or false. The syntax is: ${reference-name:!substitute-value}.

You can use a range substitute if the data resolves to a number or a boolean. The syntax is: ${reference-name:[separatorrange-startseparatorrange-end<repeatable>separatorsubstitute-value</repeatable>]}.

You can use a prettify flag to make a big value more readable. The syntax is: ${reference-name(flag[addition])]}. The following flags are supported:

f

Work on a number. It will display the value as a float, allowing for extra formatting, as with printf:

Optionally, you can add a width (optionally with zero-padding): [0]width

Optionally, you can add a precision: .presicion

p, b

Work on a number. They will reduce the number to a minimum, adding the corresponding SI prefix (or binary prefix for b).

You can use the same additions as flag f

t

Work on a number. The number will be used as a UNIX timestamp.

You can have an strftime-like format string as addition.

d

Work on a number. The number will be used as seconds.

You can have a nested format string as addition, with the following data available:

%{weeks}
%{days}
%{hours}
%{minutes}
%{seconds}
%{milliseconds}
%{microseconds}
%{nanoseconds}

.

The default format is %{weeks:+%{weeks} week%{weeks:[;2;2;;s]} }%{days:+%{days} day%{days:[;2;2;;s]} }%{hours:+%{hours} hour%{hours:[;2;2;;s]} }%{minutes:+%{minutes} minute%{minutes:[;2;2;;s]} }%{seconds:-0} second%{seconds:[;2;2;;s]}.

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 ${fruit}${addition:+ cooked with }${addition}."

name is "Bob", fruit is "pear" and addition is "chocolate".

Resolves to: Bob is eating a pear cooked with chocolate.

"${name} is eating a ${fruit}${addition:+ cooked with }${addition}."

name is "Bob", fruit is "pear"and addition is nothing.

Resolves to: Bob is eating a pear.

"${name} is eating a ${addition:! raw }${fruit}."

name is "Bob", fruit is "pear" and addition is "chocolate".

Resolves to: Bob is eating a pear.

"${name} is eating a ${addition:! raw }${fruit}."

name is "Bob", fruit is "pear"and addition is nothing.

Resolves to: Bob is eating a raw pear.

"${name} is eating a ${note:[;1;5;very bad;bad;good;very good]} ${fruit}."

name is "Bob", fruit is "apple"and note is 5.

Resolves to: Bob is eating a very good apple.

"Battery power: ${power(f03.1)}%."

power is 80.1.

Resolves to: Battery power: 080.1%.

"Disk space: ${space(b)}B."

space is 1048576.

Resolves to: Disk space: 1MiB.

"${time(t)}"

time is 1519910048.

Resolves to: Thu Mar 1 14:14:08 2018

"${time(t%F %T)}"

time is 1519910048.

Resolves to: 2018-03-01 14:14:08

"${buildtime(d)}"

buildtime is 905.

Resolves to: 15 minutes 5 seconds

"${name} is eating a ${fruit}${addition/^/ cooked with }."

name is "Bob", fruit is "pear" and addition is "chocolate".

Resolves to: Bob is eating a pear cooked with chocolate.

"${name} is eating a ${fruit}${addition/^/ cooked with }."

name is "Bob", fruit is "pear"and addition is nothing.

Resolves to: Bob is eating a pear.

"${name} is eating a ${fruit}${addition/^/ cooked with /$/ from Switzerland}."

name is "Bob", fruit is "pear" and addition is "chocolate".

Resolves to: Bob is eating a pear cooked with chocolate from Switzerland.

Please note that the config file format uses the backslash (\) for escaping sequences. Therefore, you will have to escape it if it is needed in your format string (e.g. to uses backreferences in the replacement part of the regex syntax).

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 either parsed as an URI or used directly if it is a GVariant of type "(msmsay)" containing the MIME type, the charset, and the data.

Three URI schemes are supported: file:// theme: and data: (Base64 extension only, charset and mime type may be ignored).

A theme: URI is has the form theme:[theme-name/]item-name.

Colour strings

The colour string format is borrowed from the CSS4 colour values. 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 number in the 0-255 range or a percentage value.

The alpha value is a floating point or a percentage value.

hsl(hue, saturation, lightness), hsla(hue, saturation, lightness, alpha)

Hue is an angle either in degrees (unit deg or no unit), gradians (unit grab), radians (unit rad) or turns (unit turn, a floating point number from 0 to 1).

The saturation and lightness values are percentage values.

The alpha value is the same as the rgba() notation.

hwb(hue, whiteness, blackness[, alpha])

Hue is the same as the hsl() notation.

The whiteness and blackness values are percentage values.

The alpha value is the same as the rgba() notation.

Binding strings

The binding string format supports two (and a half) notations. It can be either Modifier-Modifier-Bind or the GTK+ accelerator format. The bind can either be a keysym name, a keycode in square brackets (e.g. [10]) or a mouse button specification (e.g. MousePrimary or MouseDPrimary for double click).

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]

TLSCertificate=

A file name

The path to the TLS certificate file.

This certificate will also be used as the client certificate for the relay.

TLSKey=

A file name

The path to the TLS private key file.

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

TLSClientCertificates=

A file name

The path to a file containing a list of certificates.

When a client connects, a certificate will be required, and checked for matching against this list.

No identity or CA check is done.

PublishName=

A string

The name that the server will publish using DNS-SD.

WebSocketSecret=

A string

This secret is checked in client WebSocket handshake.

Use ws[s]://:secret@host/ URI (password with no user) to send a secret on client side.

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]

Servers=

A list of names

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

Section [Relay name]

URI=

An URI

Several schemes are supported.

evp://hostname[:port]

Use the Event protocol over TCP. TLS is used (and mandatory) if not connecting to localhost.

unix:@abstract-name, unix:path

Use the Event protocol over an UNIX stream socket.

file://path

Use the Event protocol over TCP on localhost using a random port. The port is expected to be written in the file pointed by path.

ws[s]://uri

Use the Event protocol over WebSocket. TLS is used if using the wss:// scheme.

Please note that connecting directly to eventd on a non-loopback interface requires TLS.

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 eventd will connect to.

DiscoverName=

A service name

eventd will monitor this name with discovery services and then connect to it.

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

PingInterval= (defaults to 300)

A time in seconds (0 to disable)

The interval at which eventd will send a PING message to the remote server.

ServerIdentity=

A server name

Server identity to check for in TLS certificate.

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.

You can use * as the name name to have data matches on a whole category.

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,operator,value) tuples

If the named data is present, it must compare as expected with the provided value. All present data must match for this event id to match.

Supported operators are ==, !=, <, <=, > and >=.

value is parsed as a GVariant (e.g. strings must be quoted), and the type must match exactly, so be sure to include it if necessary.

You can use the data[<replaceble>key</replaceble>] to match a value in an hash table. The key must then be present and the data must be a hash table, as it is considered part of the type check.

IfDataRegex=

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