zcore(8gx)

📦
version 3.6 · 2 versions
, in alpine 3.24

💅 NAME

zcore — the bridge for PHP-MAPI requests 🫶

(ok bestie this is zcore from section 8gx of the Gromox admin reference, and yes we're getting into it)

✨ SYNOPSIS ✨

zcore [-c config]

🦋 DESCRIPTION 🦋

So zcore is a bridge process — literally a proxy — sitting between PHP-MAPI and the Information Store. Those two have their own manpages btw: mapi(4gx) and exmdb_provider(4gx) respectively, go read them, iykyk.

It listens on /run/gromox/zcore.sock — and that path is hardcoded, no cap, don't @ me — waiting for zcore RPCs, which is a Gromox-specific protocol, and then it issues exmdb RPCs to exmdb_provider(4gx). And here's the iconic part: since exmdb_provider connections have basically no state to speak of, zcore is the process that defines the login sessions. It's giving main character energy, honestly. 🔥

💀 Real talk: zcore needs to run on the same server as the program that uses the PHP-MAPI functions. Same box. No long distance, bestie.

🎀 OPTIONS 🎀

  • -c config — read configuration directives from the given file. If you don't pass this option, /etc/gromox/gromox.cfg and /etc/gromox/zcore.cfg both get read. (Both! greedy little thing 💅)
  • --version — output version information and exit. Slay, short and sweet.
  • -? — display option summary. The "help me I'm lost" flag.

Also, heads up: all time-based command-line options and configuration file directives follow the syntax described in gromox(7), section "Duration specifications". So like, go look at that if you're doing time stuff. ⏰

🌸 CONFIGURATION DIRECTIVES (gromox.cfg) 🌸

These are the directives that get recognized when reading from /etc/gromox/gromox.cfg, or when you use the -c option to specify a custom file:

  • daemons_fd_limit — in gromox-zcore, this is treated as an alias for zcore_fd_limit. Same thing, different name, we love a nickname.
  • outgoing_smtp_url — see gromox.cfg(5):outgoing_smtp_url. (yeah, that's the whole description, it's a whole cross-reference moment)
  • zcore_fd_limit — requests that the file descriptor table be at least this large. The magic value 0 means "use the system default hard limit" — that's rlim_max, cf. setrlimit(2). Default: 0.

🧚 CONFIGURATION DIRECTIVES (zcore.cfg) 🧚

And these are the ones recognized when reading from /etc/gromox/zcore.cfg, or when the -c option points at a custom file:

  • address_cache_interval — Default: 5 minutes
  • address_table_size — Default: 3000
  • config_file_path — a colon-separated list of directories that get scanned when locating further configuration files, especially the ones used by subcomponent instances. (For example, mysql_adaptor(4gx) would be directed to look at /etc/gromox/zcore/mysql_adaptor.cfg before /etc/gromox/mysql_adaptor.cfg.) Default: /etc/gromox/zcore:/etc/gromox
  • data_file_path — a colon-separated list of directories that get scanned when locating data files. Default: /usr/share/gromox/zcore
  • host_id — a unique identifier for this system. It's used for the HELO line of outgoing SMTP connections, and as an unused identifier within muidStoreWrap entryids. The identifier should only use characters allowed for hostnames. Default: (system hostname)
  • mailbox_ping_interval — Default: 5 minutes
  • mail_max_length — Default: 64M
  • max_ext_rule_length — Default: 510K
  • max_rcpt_num — the maximum number of recipients that an e-mail is allowed to have. Default: 256
  • rpc_proxy_connection_num — for every exmdb server in exmdb_list.txt, establish and keep this many outbound connections for sending commands. (There is at most one additional connection, for async notification, alive per server.) Default: 10
  • submit_command — Default: /usr/bin/php /usr/share/gromox/submit.php
  • user_cache_interval — sets the time for how long the MAPI profile is cached before it's written to disk. Default: 1 hour
  • user_table_size — Default: 5000
  • x500_org_name — Default: (unspecified)
  • zcore_listen — the named path for the AF_LOCAL socket that zcore will listen on. Default: /run/gromox/zcore.sock
  • zcore_log_file — target for log messages here. Special values - (stderr/syslog depending on parent PID) or syslog are recognized. Default: - (auto)
  • zcore_log_level — maximum verbosity of logging. 1=crit, 2=error, 3=warn, 4=notice, 5=info, 6=debug. Default: 4 (notice)
  • zcore_max_obh_per_session — the maximum number of object handles each session can have at any one time (e.g. folders/messages/etc. open simultaneously). Use 0 to indicate unlimited. There is one session for each time a mailbox is opened. Default: 500
  • zcore_threads_num — the minimum number of client processing threads to keep around. Default: 10
  • zrpc_debug — log every incoming zcore RPC and the return code of the operation in a minimal fashion to stdout. Level 1 emits RPCs with a failure return code, level 2 emits all RPCs. ⚠️ Note the daemon log level needs to be "debug" (6) too. Default: 0

🔥 NETWORK PROTOCOL 🔥

The transmissions on the zcore socket are simple concatenations of protocol data units built using the NDR format. The PDU length is present within the PDU itself near the start. (so it's like, self-describing, we love a self-aware queen 👑)

{
     leuint32_t length;
     char pdu[];
}

pdu := {
     uint8_t call_id;
     string directory;
     switch (call_id) {
          ...
     }
}

💜 STORE LOOKUP 💜

zcore determines the store path for a user from the user database, which is provided by mysql_adaptor(4gx).

The filemap that specifies how paths are handled lives at data_file_path/exmdb_list.txt, whereby data_file_path is that eponymous directive from the config file.

Each line in this file consists of 4 columns separated by whitespace:

  • A portion of the store path to match on
  • The type of store ("private" or "public")
  • The IPv6 socket address of the server running exmdb_provider(4gx). The address must conform to gromox(7) § "Host addresses".
  • The TCP port number of the server

⭐ SIGNALS ⭐

  • Upon receipt of SIGHUP, configuration files are re-read — but only a few select directives can be changed this way, because many parts do not implement reload. So like, don't expect a full glow-up from one signal, bestie. 🙈
  • Upon receipt of SIGHUP, the address book cache will be dropped; the next regular request for the AB will cause it to be reloaded. Fresh start energy ✨

🍓 FILES 🍓

  • data_file_path/folder_names.txt — translations for essential folders in a message store.
  • data_file_path/notify_bounce/ — templates for read/nonread notification mails sent to originators.

🌈 NOTES 🌈

Behavior for the address book generally mirrors exchange_nsp(4gx), so go see that manpage for additional notes. iykyk 🫶

💖 SEE ALSO 💖

gromox(7)

okay that's the whole page!! this was the Gromox admin reference, zcore(8gx), brought to you with love and also a socket that is hardcoded whether you like it or not 💅🦋 mwah, go open a mailbox or something 🎀

📦 where this page comes from