event

Name

event — Folder change notification daemon

Synopsis

event [-c config]

Description

The event daemon is a software bus, inter-process communication (IPC) mechanism that allows communication between multiple processes running concurrently on multiple machines.

In practice, it is used by midb(8gx), pop3(8gx) and imap(8gx) to notify imap(8gx) instances of changed folder/message states.

Options

-c config

Read configuration directives from the given file. If this option is not specified, /etc/gromox/event.cfg will be read if it exists.

–version

Output version information and exit.

-?

Display option summary.

Files

  • config_file_path/event_acl.txt: A file with one address (IPv6 or v4-mapped) per line of allowed clients. In its absence, ::1 is default-whitelisted.

Configuration file directives

config_file_path
Colon-separated list of directories which will be scanned when locating further configuration files.
Default: /etc/gromox/event:/etc/gromox
event_listen_ip
An IPv6 address (or v4-mapped address) for exposing the event service on.
Default: ::1
event_listen_port
The TCP port number for exposing the event service on.
Default: 33333
event_threads_num
The minimum number of client processing threads to keep around.
Default: 50

Event protocol

The event service is exposed as a line-based text protocol. Upon connection, the event server gratitiously writes “OK” and will wait for commands. Each connection to the event daemon starts out in Enqueue Mode, and this is the only mode from which commands can be issued.

“FALSE” may be emitted by the server if there is a syntax error.

The command “ID <res_id>” declares the particular connection to be a notification sender. res_id is generally the hostname and the PID. The server always responds with “TRUE”. (The connection stays in Enqueue Mode.)

The command “LISTEN <res_id>” declares the particular connection to be a notification receiver. res_id follows the same pattern. The server responds with “TRUE” and the connection state changes to the Dequeue Mode (see below).

The command “SELECT <username> <folder>” subscribes those connections that have registered as a listener for res_id to notifications. (This means that a process wishing to use event_stub(4gx) to listen for notifications strictly requires loading event_proxy(4gx) too, and, in essence, use two connections to event(8gx).) The server responds with “FALSE” if no listener exists, or “TRUE” on success.

The command “UNSELECT <username> <folder>” unsubscribes those connections that had registered as a listener for res_id. The server always responds with “TRUE”.

Auxiliary self-explanatory commands available are: “QUIT” and “PING”.

Any other input is treated as a notification item and is not interpreted by event(8gx) beyond checking the number of fields:

The notification “FOLDER-TOUCH <username> <folder>” informs listeners that the folder metadata has changed and warrants being reloaded.

The notification “MESSAGE-FLAG <username> <folder> <messageid>” informs listeners that the message metadata has changed and warrants being reloaded.

Clients in Dequeue Mode will receive notifications. Each notification line received by the client needs to be acknowledged with a “TRUE” response. It is not possible to exit Dequeue Mode; connection termination is the only way out.

See also

gromox(7), event_proxy(4gx), event_stub(4gx)