IMSErious

Execute commands in response to Dovecot Internet Message Store Events.

Synopsis

imserious [-t] [-c file] imserious [--test] [--config file] imserious [-hv] imserious [--help] [--version]

Optional arguments: -h, --help print help message -v, --version print program version -t, --test test configuration -c, --config CONFIG path to configuration

Summary

IMSErious is a service that listens for Dovecot push notification events, as sent by its OX (Open-Xchange) driver, and executes commands in response. This allows, for example, waking up an [MRA] or issuing desktop notifications on new messages.

Configuration

IMSErious is configured from a [TOML] file specified as the first argument, defaulting to /usr/local/etc/imserious.toml:

```toml listen = "10.0.0.1:12525" # listen address, default 127.0.0.1:12525 allow = [ "10.0.0.2/32" ] # allowed notification IP ranges, default all endpoint = "/notify" # path to API endpoint, default /notify max_connections = 8 # connection limit, default 8 timeout = "5s" # request timeout, default 5s

optional Basic auth

[auth] user = "foo" pass = "bar"

optional TLS

[tls] cert = "/etc/ssl/foo.example.com.crt" key = "/etc/ssl/foo.example.com.key" periodic_reload = "1d" # optionally reload keys periodically, no default

optional stdout logging

[log] maxlevel = "info" # One of error, warn, info (default), debug, trace # May be overridden by setting IMSERIOUSLOG env var format = "compact" # One of full (default), compact, pretty, json ansi = false # Format "pretty" with ANSI codes, default false timestamp = false # Display a timestamp, default false target = false # Display the log target, default false level = false # Display the log level, default false

[[handler]] user = "freaky" # Username, required event = "MessageNew" # Event type, optional, default MessageNew # Note this is currently the only type supported by Dovecot's OX driver delay = "5s" # Delay execution this long after initial event, optional, default none limitperiod = "30s" # Rate limit executions over this interval, optional, default 30s limitburst = 1 # Allow this many executions per interval, optional, default 1 periodic = "300s" # Execute unconditionally after this long, optional, default none command = "/usr/local/bin/fdm -a eda -l fetch" ```

Handlers

A handler is a command to execute in response to a specific event/user pair. Multiple handlers for the same event and user may be specified to trigger different commands with their own rate limits, periodic configuration, etc.

Commands only support basic shell word splitting and quoting - if shell metacharacters are required they should be provided by executing via a shell such as with /bin/sh -c.

Event fields will be exposed in IMSE_* env vars if available - only IMSE_USER and IMSE_EVENTare guaranteed to be set if periodic execution is specified.

• IMSE_USER - user being notified
• IMSE_EVENT - event name
• IMSE_REMOTE_IP - notifying IP address
• IMSE_REMOTE_PORT - notifying TCP port
• IMSE_UNSEEN - number of unseen messages
• IMSE_FOLDER - IMAP folder name
• IMSE_FROM - From: address of a new email (if any)
• IMSE_SNIPPET - a sample of the body of a new email (if any)

Security

It should not need to be said that there are potentially serious security implications from allowing remote clients to trigger commands on your server. While every effort has been made to limit the potential for harm, it is your responsibility not to use this program unsafely.

It is strongly discouraged to run an open instance of IMSErious on a public network, or as a privileged user.