gromox

Name

gromox — Overview of the Gromox groupware server

Description

Gromox is a groupware server capable of serving as a replacement for Microsoft Exchange. Connectivity options include RPC/HTTP (Outlook Anywhere), IMAP, POP3, an SMTP-speaking LDA, and a PHP module with a Z-MAPI function subset.

Gromox relies on other components to provide a sensibly complete mail system, such as Postfix as a mail transfer agent, and grommunio-admin for user management. A web interface is available with grommunio-web. The grommunio distribution ships these essentials and has a ready-to-run installation of Gromox. system.

Manual page listing

Gromox documentation consists of at least a dozen manual pages ("manpages") on its individual components. We have grouped these according to their principal function.

Overview and definitions

• gromox(7gx) — This page, an overview of the Gromox groupware server.

• mapi(7gx) — Definition for "Messaging Application Programming Interface"

Exchange subsystem and its components

• autodiscover(4gx) — Autodiscover HTTP Service Protocol handler

• exchange_emsmdb(4gx) — http(8gx) processing plugin for the Wire Format Protocol (Outlook/Exchange RPCs).

• exchange_nsp(4gx) — http(8gx) processing plugin for the Exchange Server Name Service Provider Interface Protocol.

• exchange_rfr(4gx) — http(8gx) processing plugin for the Address Book Name Service Provider Interface Referral Protocol.

• exmdb_provider(4gx) — http(8gx) service plugin for exmdb connections

• freebusy(8gx) — Helper program for the EWS Freebusy mechanism

• http(8gx)

• mod_cache(4gx) — http(8gx) processing plugin for serving objects from a local filesystem

• mod_fastcgi(4gx) — http(8gx) processing plugin for proxying requests to FastCGI servers

• mod_rewrite(4gx) — http(8gx) processing plugin for altering HTTP request URIs before processing

• mh_emsmdb(4gx) — MAPI-HTTP processor for EMSMDB

• mh_nsp(4gx) — MAPI-HTTP processor for NSPI

• timer(8gx) — deferred command executor

PHP-MAPI subsystem

• rtf2html(1gx) — C++ helper program for the mapi(4gx) mapi_decompressrtf function

• zcore(8gx) — Bridge for PHP-MAPI requests

Mail retrieval agent subsystem (MRA)

• imap(8gx) — IMAP server

• midb_agent(4gx) — Service plugin for conversing with midb(8gx)

• pop3(8gx) — POP3 server

Local delivery agent (LDA)

• alias_resolve(4gx) — Alias resolution for delivery(8gx) using MySQL

• delivery(8gx) — Backend for local delivery

• delivery-queue(8gx) — LMTP/SMTP frontend for local delivery

• user_filter(4gx) — Service plugin for application of user login limits

Auxiliary services

• pam_gromox(4gx) — a PAM plugin to authenticate with Gromox

• rtf2html(1gx) — C++ helper for php_mapi's mapi_decompressrtf function

• event(8gx) — Folder change notification daemon

• midb(8gx) — Message Index database daemon

System administration

• cleaner(8gx) — Utility to purge orphaned attachments/content files

• gromox-abktconv(8) — Utility for converting between ABKT and JSON

• gromox-abktpull(8) — Utility to extract ABKT templates from LDIF

• gromox-compress(8) — Utility to recompress Gromox content files

• gromox-dbop(8) — User database maintenance utility

• gromox-dscli(8) — Autodiscover command line utility

• gromox-mailq(8) — SMTP queue lister

• gromox-mbop(8) — Mailbox operations utility

• gromox-mkmidb(8) — Tool for creating a blank message index database

• gromox-mkprivate(8) — Tool for creating a blank private store

• gromox-mkpublic(8) — Tool for creating a blank public store

Mail import, export and conversion

• gromox-eml2mbox(8) — Utility to concatenate Internet Mail messages into mbox format

• gromox-eml2mt(8) — Utility for analysis/importing Internet Mail messages

• gromox-exm2eml(8) — Utility to export messages as Internet Mail, iCalendar or vCard

• gromox-ical2mt(8) — Utility for analysis/import of iCalendar objects

• gromox-kdb2mt(8) — Utility for analysis/import of Kopano mailboxes

• gromox-mt2exm(8) — Utility for bulk-importing mail items into a Gromox store

• gromox-oxm2mt(8) — Utility for analysis and import of Outlook .msg files

• gromox-pff2mt(8) — Utility for analysis/import of PFF/PST/OST files

• gromox-snapshot(8) — Helper to create btrfs snapshots of mailboxes

• gromox-vcf2mt(8) — Utility for analysis/import of vCard objects

• kdb-uidextract(8) — Helper for creating a gromox-kdb2mt ACL map

• kdb-uidextract-limited(8) — Helper for creating a gromox-kdb2mt ACL map

Service plugins

Service plugins can be used by various processes (i.e. from different subsystems), as such, we have put them in this general category.

• authmgr(4gx) — Demultiplexer for authentication requests

• ip6_container(4gx) — trivial source connection counter

• ldap_adaptor(4gx) — LDAP connector for authentication

• mysql_adaptor(4gx) — MySQL/MariaDB connector for user metadata and authentication

• timer_agent(4gx) — Service plugin for deferred command execution with timer(8gx)

Historic commands that have been removed

The following is a list of programs that no longer exist. It is intended solely to capture keyword searches within the documentation for said obsolete/removed commands.

• autodiscover(8gx): renamed to gromox-dscli to avoid a name clash with the autodiscover(4gx) manpage

• delmsg(8gx): integrated into gromox-mbop as a subcommand

• rebuild(8gx): use `sqlite3 corrupt.db ".clone fixed.db"` or `sqlite3 corrupt.db .recover | sqlite3 fixed.db` instead.

Language bindings

• mapi(4gx) — PHP module providing MAPI functions

Configuration files

Program configuration files reside within /etc/gromox. The format for .cfg files is: one "key=value" pair per line. Empty lines are ignored, as are lines beginning with a '#' character. Lines can have a maximum length of 1024. Each key=value line is logically split at the equals sign, and whitespace is trimmed around key and value. Comments at the end of a value are not supported. Escape sequences are not supported.

The format for .ini files is: one "key=value" pair per line. Empty lines are ignored, as are lines beginning with a ';' character.

Many programs have a config_file_path directive with which the search path for further config files can be specified. For example, http(8gx) defaults to config_file_path=/etc/gromox/http:/etc/gromox, so the mysql_adaptor(4gx) plugin as loaded by http will first try /etc/gromox/http/mysql_adaptor.cfg, then /etc/gromox/mysql_adaptor.cfg. This allows having one file that is shared between multiple programs as well as being able to override on a per program-basis.

Listing of config files per component

A list of components and the config files they potentially use.

• alias_resolve(4gx) inside delivery(8gx): /etc/gromox/alias_resolve.cfg, /etc/gromox/mysql_adaptor.cfg

• authmgr(4gx) inside delivery(8gx), delivery-queue(8gx), http(8gx), imap(8gx), midb(8gx), pam_gromox(4gx), pop3(8gx), zcore(8gx): /etc/gromox/authmgr.cfg

• autodiscover(4gx) inside php-fpm(8): /etc/gromox/autodiscover.ini, /etc/gromox/mysql_adaptor.cfg

• delivery(8gx): /etc/gromox/alias_resolve.cfg, /etc/gromox/exmdb_local.cfg, /etc/gromox/ldap_adaptor.cfg, /etc/gromox/mlist_expand.cfg, /etc/gromox/mysql_adaptor.cfg, /etc/gromox/remote_delivery.cfg

• delivery-queue(8gx): /etc/gromox/authmgr.cfg, /etc/gromox/midb_agent.cfg, /etc/gromox/ldap_adaptor.cfg, /etc/gromox/mysql_adaptor.cfg, /etc/gromox/user_filter.cfg

• event(8gx): /etc/gromox/event.cfg

• exchange_emsmdb(4gx) inside http(8gx): /etc/gromox/exchange_emsmdb.cfg

• exchange_nsp(4gx) inside http(8gx): /etc/gromox/exchange_nsp.cfg

• exchange_rfr(4gx) inside http(8gx): no config file

• exmdb_provider(4gx) inside http(8gx): /etc/gromox/exmdb_provider.cfg

• freebusy(8gx) subprocess run from php-fpm(8): no config file

• http(8gx): /etc/gromox/cache.txt, /etc/gromox/exchange_emsmdb.cfg, /etc/gromox/exchange_nsp.cfg, etc/gromox/exmdb_provider.cfg, /etc/gromox/fastcgi.txt, /etc/gromox/rewrite.txt

• imap(8gx): /etc/gromox/authmgr.cfg, /etc/gromox/event_proxy.cfg, /etc/gromox/event_stub.cfg, /etc/gromox/imap.cfg, /etc/gromox/ldap_adaptor.cfg, /etc/gromox/mysql_adaptor.cfg

• ip6_container(4gx) inside (no process by default): /etc/gromox/ip6_container.cfg

• midb_agent(4gx) inside delivery-queue(8gx), imap(8gx), pop3(8gx): /etc/gromox/midb_agent.cfg

• mlist_expand(4gx) inside delivery(8gx): /etc/gromox/mlist_expand.cfg

• mod_cache(4gx) inside http(8gx): /etc/gromox/http.cfg, /etc/gromox/cache.txt

• mod_fastcgi(4gx) inside http(8gx): /etc/gromox/http.cfg, /etc/gromox/fastcgi.txt

• mod_rewrite(4gx) inside http(8gx): /etc/gromox/http.cfg, /etc/gromox/rewrite.txt

• mh_emsmdb(4gx) inside http(8gx): no config file

• mh_nsp(4gx) inside http(8gx): no config file

• pop3(8gx): /etc/gromox/authmgr.cfg, /etc/gromox/event_proxy.cfg, /etc/gromox/imap.cfg, /etc/gromox/ldap_adaptor.cfg, /etc/gromox/mysql_adaptor.cfg

• remote_delivery(4gx) inside delivery(8gx): /etc/gromox/remote_delivery.cfg

• rtf2html(1gx): no config file

• timer(8gx): /etc/gromox/timer.cfg

• timer_agent(4gx) inside http(8gx), zcore(8gx): /etc/gromox/timer_agent.cfg

• user_filter(4gx) inside delivery-queue(8gx), http(8gx), imap(8gx), pop3(8gx): /etc/gromox/user_filter.cfg

• zcore(8gx): /etc/gromox/authmgr.cfg, /etc/gromox/zcore.cfg, /etc/gromox/ldap_adaptor.cfg, /etc/gromox/mysql_adaptor.cfg, /etc/gromox/timer_agent.cfg

Listing of components per config file

• /etc/gromox/alias_resolve.cfg: used by the alias_resolve(4gx) plugin, accessed process-wise by the delivery(8gx) process.

• /etc/gromox/authmgr.cfg: used by the authmgr(4gx) and pam_gromox(4gx) plugin, accessed process-wise by delivery(8gx), delivery-queue(8gx), http(8gx), imap(8gx), midb(8gx), pop3(8gx), zcore(8gx), and arbitrary PAM applications.

• /etc/gromox/autodiscover.ini: used by the autodiscover(4gx) component, accessed process-wise by php-fpm(8).

• /etc/gromox/event.cfg: used by the event(8gx) process.

• /etc/gromox/event_proxy.cfg: used by the event_proxy(4gx) plugin, accessed process-wise by imap(8gx), midb(8gx), pop3(8gx).

• /etc/gromox/event_stub.cfg: used by the event_stub(4gx) plugin, accessed process-wise by imap(8gx).

• /etc/gromox/exchange_emsmdb.cfg: used by the exchange_emsmdb(4gx) plugin, accessed process-wise by http(8gx).

• /etc/gromox/exchange_nsp.cfg: used by the exchange_nsp(4gx) plugin, accessed process-wise by http(8gx).

• /etc/gromox/exmdb_local.cfg: used by the exmdb_local(4gx) plugin, accessed process-wise by delivery(8gx).

• /etc/gromox/exmdb_provider.cfg: used by the exmdb_provider(4gx) plugin, accessed process-wise by http(8gx).

• /etc/gromox/http.cfg: used by the mod_cache(4gx), mod_fastcgi(4gx), mod_rewrite(4gx) plugins, and the http(8gx) process.

• /etc/gromox/imap.cfg: used by the imap(8gx) process.

• /etc/gromox/ip6_container.cfg: used by the ip6_container(4gx) plugin.

• /etc/gromox/ldap_adaptor.cfg: used by the ldap_adaptor(4gx) plugin, accessed process-wise by delivery(8gx), delivery-queue(8gx), http(8gx), imap(8gx), midb(8gx), pop3(8gx), zcore(8gx), and arbitrary PAM applications.

• /etc/gromox/midb_agent.cfg: used by the midb_agent(4gx) plugin, accessed process-wise by delivery-queue(8gx), imap(8gx), pop3(8gx).

• /etc/gromox/mlist_expand.cfg: used by the mlist_expand(4gx) plugin, accessed process-wise by delivery(8gx).

• /etc/gromox/mysql_adaptor.cfg: used by the alias_resolve(4gx), mysql_adaptor(4gx) plugins, accessed process-wise by delivery(8gx), delivery-queue(8gx), http(8gx), imap(8gx), midb(8gx), pop3(8gx), zcore(8gx), and arbitrary PAM applications.

• /etc/gromox/midb.cfg: used by the midb(8gx) process.

• /etc/gromox/mod_cache.txt: used by the mod_cache(4gx) plugin, accessed process-wise by http(8gx).

• /etc/gromox/mod_fastcgi.txt: used by the mod_fastcgi(4gx) plugin, accessed process-wise by http(8gx).

• /etc/gromox/mod_rewrite.txt: used by the mod_rewrite(4gx) plugin, accessed process-wise by http(8gx).

• /etc/gromox/mysql_adaptor.cfg: used by the autodiscover(4gx) plugin, http(8gx), imap(8gx), pop3(8gx), zcore(8gx) processes.

• /etc/gromox/pam.cfg: used by the pam_gromox(4gx) plugin, accessed process-wise by arbitrary PAM applications.

• /etc/gromox/pop3.cfg: used by the pop3(8gx) process.

• /etc/gromox/remote_delivery.cfg: used by the remote_delivery(4gx) plugin, accessed process-wise by delivery(8gx).

• /etc/gromox/timer.cfg: used by the timer(8gx) process.

• /etc/gromox/timer_agent.cfg: used by the timer_agent(4gx) plugin, accessed process-wise by http(8gx), zcore(8gx).

• /etc/gromox/user_filter.cfg: used by the user_filter(4gx) plugin, accessed process-wise by delivery-queue(8gx), http(8gx), imap(8gx), pop3(8gx)

• /etc/gromox/zcore.cfg: used by the zcore(8gx) process.

Databases

• User information is held in a MariaDB/MySQL database. This database can be accessed by multiple Gromox servers, and so enables distributed Gromox operation. The MariaDB system itself provides the necessary utilities for distributing or replicating this database.

• Per-user e-mail messages are stored in a SQLite database (e.g. /var/lib/gromox/user/m1/1/1/exchange.sqlite3), as is a message index (e.g. /var/lib/gromox/user/m1/1/1/midb.sqlite3). These are normally only used by one system, but can be shared through network filesystems provided that file locking is properly implemented in the filesystem driver. Normal file mechanisms can be used to backup or transfer the database to another Gromox host.

Listening sockets

• /run/gromox/zcore.sock — zcore(8gx)

• *:24 — delivery-queue(8gx) LMTP/SMTP service (when Postfix is on 25)

• :*25 — Normally, your own MTA (postfix(1), exim(8), whatever the case may be). delivery-queue(8gx) will only be on 25 in developer setups that wish to cut and skip Postfix/etc. to get a simpler test setup.

• *:80 — http(8gx) HTTP service

• *:110 — pop3(8gx) POP3 service

• *:143 — imap(8gx) IMAP service

• *:443 — http(8gx) HTTP over implicit TLS

• *:993 — imap(8gx) IMAP over implicit TLS

• *:995 — pop3(8gx) POP3 over implicit TLS

• [::1]:5000 — exmdb_provider(4gx) plugin inside http(8gx)

• [::1]:5555 — midb(8gx) service

• [::1]:6666 — timer(8gx) service

• [::1]:33333 — event(8gx) service

Files

The exact paths depend on the options used when Gromox's build was configured. Especially the path for libraries, represented in this documentation as /usr/lib/gromox, may for example actually be /usr/lib64/gromox or /usr/lib/riscv64-linux-gnu, depending on the platform.

• /usr/lib/gromox/libgxf_*.so: flusher plugins for delivery-queue(8gx)

• /usr/lib/gromox/libgxh_*.so: HTTP processing plugins for http(8gx)

• /usr/lib/gromox/libgxm_*.so: hook plugins for delivery(8gx)

• /usr/lib/gromox/libgxp_*.so: PDU processing plugins for http(8gx)

• /usr/lib/gromox/libgxs_*.so: service plugins

• /usr/share/gromox/cpid.txt: mapping between character set IDs and names

• /usr/share/gromox/folder_names.txt: Translations for essential folders in a message store.

• /usr/share/gromox/lang_charset.txt: mapping from language code to character set

• /usr/share/gromox/lcid.txt: mapping between locale IDs and names

• /usr/share/gromox/mime_extension.txt: mapping between file extensiosn and MIME types

• /var/lib/gromox/user: directory hierarchy for private mailboxes

• /var/lib/gromox/domain: directory hierarchy for public mailboxes (public folders)

  It is presently not possible to use a single directory for both mailbox types, since exmdb_list.txt uses the infix to determine the mode of access.
• .../user/account@domain: individual mailbox container

  The directory name has no required form. It is entirely dependent upon the users.maildir column in MySQL. Some implementations of user management use a 2-level hierarchy, e.g. /user/1/0.

• .../a@d/exmdb/exchange.sqlite3: mail store with almost everything (no mail bodies)

• .../a@d/cid/: attachments and message bodies (PR_BODY, PR_HTML, PR_RTF_COMPRESSED).

• .../a@d/eml/mid_string: RFC 5322 representation for a message.

  mid_string has no required form. Typically, there is timestamp.seqid.hostname which represents EMLs captured by delivery(8gx) on ingestion, and timestamp.seqid.midb for EMLs generated by midb(8gx) out of MAPI messages.
• .../a@d/ext/mid_string: Digest for the RFC 5322 file.

  This JSON-encoded file contains e.g. indexing information for individual MIME parts of the RFC 5322 representation. Generated by midb(8gx).