EVENTD.CONF(5)

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

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[2] 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[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 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.

  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 an empty name to have data matches on a whole category. This means the category and the sub-name will be separated with two spaces.

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.

    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 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.  CSS4 colour values
    https://www.w3.org/TR/css-color-4/#hex-notation