event(8gx)

💅 event — the Folder change notification daemon (yes bestie, it's giving whole entire daemon)

okay so this page lives in the Gromox admin reference section of the manual, and it's manual page event(8gx). Let's get into it 🫶

---

✨ SYNOPSIS ✨

event [-c config]

that's it. that's the whole vibe. one optional flag. slay.

---

🌸 DESCRIPTION 🌸

okay so the event daemon is a software bus — an inter-process communication (IPC) mechanism that lets a bunch of processes running concurrently and on multiple machines talk to each other. she's a whole group chat for daemons, fr fr 💬✨

in practice? midb(8gx), pop3(8gx) and imap(8gx) use her to notify imap(8gx) instances when folder/message states change. so like, when something new happens in a folder, the word gets spread. iconic behavior honestly 👑

---

🎀 OPTIONS 🎀

• -c config — reads configuration directives from the given file. if you don't pass this option, then /etc/gromox/gromox.cfg and /etc/gromox/event.cfg will both be read. (two files! she's thorough 💅)
• --version — outputs version information and then dips. bye 👋
• -? — displays the option summary. the little "help me help you" moment.

⚠️ heads up bestie: all time-based command-line options and configuration file directives follow the syntax described in gromox(7), section "Duration specifications". iykyk 📖

---

🦋 CONFIGURATION DIRECTIVES 🦋

the usual config file location is /etc/gromox/event.cfg. that's her home 🏠

• event_hosts_allow — a space-separated list of individual host addresses that are allowed to converse with the event service. the addresses must conform to gromox(7) § "Host addresses". no networks and no CIDR notations are permitted — like, do not try it, she will not accept it 🙈 Default: ::1
• event_listen_ip — the IPv6 socket address for exposing the event service on. the address must conform to gromox(7) § "Host addresses". Default: ::1
• event_listen_port — the TCP port number for exposing the event service on. Default: 33333
• event_log_file — target for log messages here. special values recognized: - (stderr/syslog depending on parent PID) or syslog. Default: - (auto)
• event_log_level — maximum verbosity of logging. 1=crit, 2=error, 3=warn, 4=notice, 5=info, 6=debug. Default: 4 (notice)
• event_threads_num — the minimum number of client processing threads to keep around. she likes to have helpers on standby 🧚 Default: 50
• running_identity — an unprivileged user account to switch the process to after startup. to inhibit the switch, assign the empty value. Default: gromox

---

🌈 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. so polite 💖

each connection to the event daemon starts out in Enqueue Mode, and this is the only mode from which commands can be issued. like, that's the greenhouse where commands grow 🌱

"FALSE" may be emitted by the server if there is a syntax error. (she's telling u something's wrong, respectfully 💀)

🍓 ID

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". (and the connection stays in Enqueue Mode, no plot twist here)

⭐ LISTEN

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 👇).

🌸 SELECT

the command SELECT <username> <folder> subscribes those connections that have registered as a listener for res_id to notifications.

okay this part is important so read it twice: 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, uses two connections to event(8gx). two. connections. no cap 😭

the server responds with "FALSE" if no listener exists, or "TRUE" on success.

🧚 UNSELECT

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

💜 QUIT

terminate the connection. that's it. that's the whole thing. goodbye 👋

🔥 PING

resets the inactivity timer on the connection. a little "still here bestie!" tap 🫶

👑 Partially parsed commands

any other input is treated as a notification item and is not interpreted by event(8gx) beyond checking the number of fields. she's just counting, not reading 📋

• FOLDER-TOUCH — the notification FOLDER-TOUCH <username> <folder> informs listeners that the folder metadata has changed and warrants being reloaded. this is also how the arrival of new messages is conveyed. so yes, folder touch = new mail energy ✨
• MESSAGE-FLAG — the notification MESSAGE-FLAG <username> <folder> <messageid> informs listeners that the message metadata has changed and warrants being reloaded. (this operation is no longer recognized since Gromox 2.17-26-g10564f3e7.) rip, she's deprecated 💀
• MESSAGE-UFLAG — the notification MESSAGE-UFLAG <username> <folder> <imapuid> informs listeners that the message metadata has changed and warrants being reloaded.
• MESSAGE-EXPUNGE — the notification MESSAGE-EXPUNGE <username> <folder> <messageid> informs listeners that the message was deleted. gone gone gone 🗑️

🕊️ Client behavior

clients in Dequeue Mode will receive notifications. each notification line received by the client needs to be acknowledged with a "TRUE" response. and listen — it is not possible to exit Dequeue Mode; connection termination is the only way out. there is no door, only the window 😭

events do not echo for a particular res_id. the event_proxy(4gx) and event_stub(4gx) components use the getpid() function when constructing the res_id for the ID/LISTEN commands. a process like imap(8gx) which uses both components will intentionally not see its own notifications over the gromox-event IPC system this way. she's not ignoring you, she's just built like that 💅

---

💖 SEE ALSO 💖

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

---

and that's the page, bestie 🎀 this documentation ships with Gromox, and you've been reading event(8gx) — go forth and notify responsibly 🌟🦋