Dependency installation

A pre-built version of Gromox is readily available by way of the grommunio Linux distribution. If you choose to build from source nevertheless, a number of dependencies are needed:

• autotools
• C and C++20 compiler
• fmt >= 8
• jsoncpp
• libHX >= 4.28
• libiconv (OpenBSD)
• libxml2 >= 2.7.3 (used for HTML parsing)
• libzstd >= 1.4
• MariaDB Connector/C or mariadb-client or compatible API
• OpenLDAP
• OpenSSL-compatible libssl
• OpenSSL-compatible libcrypto (must have SHA-3 if libxxhash is not used)
• perl5
• SQLite3
• tinyxml2 >= 8 (we use this for all things XML)
• wmime <https://github.com/grommunio/wmime/\>
• zlib

Optional deps:

• A resolver library
  • libc/libresolv with interface "res_nquery" & "ns_initparse" functions
  • c-ares
• cURL library
• GSSAPI library
  • mit-krb5-gssapi or
  • heimdal-gssapi or
  • libgssglue
  • (even if built with any, you can still use external helpers like /usr/libexec/squid/negotiate_wrapper_auth from Gromox)
• mit-krb5-gssapi
• libesedb
• libolecf
• libpff
• libxxhash >= 0.7
• Linux-PAM
• PHP 7/8 headers

When the grommunio repository is known to zypper, one can request to install the dependencies of the SRPM, which conveniently brings in everything that was used to build Gromox in the first place. By extension, the same mechanism can be used for other source repositories such as libexmdbpp.

## zypper si -d gromox
Loading repository data...
Reading installed packages...
Resolving package dependencies...

The following 62 NEW packages are going to be installed:
  autoconf automake binutils [...]
Overall download size: 70.8 MiB. Already cached: 0 B. After the operation,
additional 284.5 MiB will be used.
Continue? [y/n/v/...? shows all options] (y):

Source build procedure

The procedure is the well-established autotools run. Note that we changed the autoconf-supplied default install prefix from /usr/local to /usr.

For true developers, the qconf helper script may be used as a typing shortcut and to invoke the configure script with the paths normally used by the pre-built Gromox packages.

The rest of the documentation assumes that Gromox was configured with --prefix=/usr --sysconfdir=/etc --localstatedir=/var.

FreeBSD/OpenBSD

PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure CC=cc CXX=c++ CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib --with-php=/usr/local/bin/php-config-8.4

• FreeBSD uses /usr/local/libdata/pkgconfig, but some software packages might, when built from source, install to /usr/local/lib/pkgconfig instead. (wmime does this.) Therefore, specifying PKG_CONFIG_PATH may become necessary.
• Existing C++ libraries in /usr were built with clang and use (clang-libc++'s) std::__1::basic_string. If g++ is installed in the system, configure will use g++, but g++ will use GNU stdlibc++, which leads to references to std::__cxx11::basic_string instead. Therefore, specifying CC=/CXX= may become necessary to avoid link failures with undefined reference errors.

Solaris/OmniOSce

When OOCE is used, one may need to list some non-standard directories for everything to come together:

./configure LDFLAGS="-L/opt/ooce/lib/amd64"
LD_LIBRARY_PATH=/opt/ooce/lib/amd64:/opt/ooce/mariadb-10.11/lib/amd64:/usr/local/lib make

wmime notes

If instead of wmime you want to use vmime, provided it is new enough, you can do so with:

./configure wmime_CFLAGS="$(pkg-config vmime --cflags)" wmime_LIBS="$(pkg-config vmime --libs)"

ASAN notes

The following additional developer options are available:

• --with-asan: shorthand for enabling Address Sanitizer
• --with-ubsan: shorthand for enabling UB Sanitizer

Due to a [problem in libtool](2.4.7 <https://debbugs.gnu.org/56839/) and ASAN, it is necessary to also call make with the sanitizer libs (asan, ubsan or both, depending on choice) if they are shared libraries (usually gcc). The command is make LIBS="-lasan -lubsan".

stdlibc++ notes

When you build with -D_GLIBCXX_DEBUG, C++ libraries whose headers make use of types subject to debug substitution, in other words, wmime and jsoncpp, also need to be built with -D_GLIBCXX_DEBUG, else one may observe odd crashes.

Optional runtime components

• PHP command-line interface, to enable the scheduled/delayed message sending function.
• A mail transfer agent, for the ability to receive messages from, and send messages to, remote SMTP servers on the Internet. Spam handling should also occur in the MTA chain.
• For improved conversion from HTML to plaintext (in order of preference):
  • chawan, or pandoc, or w3m
• For improved conversion between HTML and RTF:
  • pandoc
• If tinkering with databases, the sqlite3 and mysql command-line clients may prove useful.
• If tinkering with coredumps, the zstd utility for decompressing files from /var/lib/systemd/coredump will help.

Minimal configuration

IPv6

The IPv6 kernel module needs to be available/enabled and the ::1 address must exist on the loopback device.

SQL database

A MariaDB/MySQL database is used to store (and replicate, if so needed later) users and other objects like groups/distribution lists, organizations, etc. The default database name Gromox's mysql_adaptor component will use is email, hence you would create that as a blank database. The default database access users is root with no password, which fits the default installation of MariaDB too. Any deviations will have to be specified in /etc/gromox/mysql_adaptor.cfg; the corresponding manpage is mysql_adaptor(4gx) and autodiscover(4gx). The database can then be populated using gromox-dbop -C.

Gromox only requires SELECT,UPDATE permissions on this database as it does not create or delete users. The grommunio Administration Backend is in charge of user management, and this role will need more permissions.

TLS certificates

Have a PEM-encoded certificate and key ready. The cert file should contain any necessary sections of the certificate chain (in case those CAs are not already available by way of /etc/ssl/certs). OpenSSL generally allows having the cert and the key in the same file, if you wish to do so. Add to /etc/gromox/http.cfg:

http_listen_tls_port = 443
http_support_tls = true
http_certificate_path = /etc/gromox/domain.example.pem
http_private_key_path = /etc/gromox/domain.example.key

The Gromox Autodiscover handler forces a HTTPS redirect, which is why a certificate should indeed be set up. Then, since you already have the certificates, you could also use them in e.g. the SMTP server's configuration.

Hostname

If the kernel hostname is different from the hostname used to access the service(s), then gromox.cfg needs the oxdisco_exonym=... line so that Autodiscover can construct the correct TLS upgrade redirect URLs to itself, for an external user.

x500_org_name

Do not bother changing this config directive's default value.

In various daemons, the x500_org_name config directive influences the DN used in muidEMSAB entryids. In Exchange, the DN would be derived from the Active Directory hierarchy or something — feel free to google for “X500 DN Exchange” and cringe —, but as far as MAPI is concerned, the value is arbitrary. The x500_org_name ought not be changed after initial installation as it will invalidate participants of e-mail messages, calendar events, etc.

Users & /run

Gromox services create AF_LOCAL sockets, and the standard location for this is the /run/gromox directory. A systemd-tmpfiles fragment is provided in the source tree at system/tmpfiles-gromox.conf which can trigger the creation of this directory when running under systemd.

Gromox services run in a privilege-reduced context. To that end, system/sysusers-gromox.conf is a systemd-sysusers fragment that will ensure the user identities are available.

(Gromox RPM packages will do this on their own already)

The directory /var/lib/gromox and all contents shall be owned by user gromox or grommunio. (The latter would be the grommunio-admin-api user, but is not created by Gromox's sysusers file.) The group owner shall be gromox with read-write permission. Others should not have any access whatsoever. This is all so that Gromox services and AAPI services alike can read/write to it irrespective of the creator of files.

drwxrwx--- 5 gromox gromox 62 Feb 13 23:15 /var/lib/gromox

The directory /etc/gromox and all contents are supposed to be owned by user root or grommunio, be owned by group gromoxcf read-only, and be otherwise inaccessible. Gromox has no need to update config files at all, just read them. One exception is pam.cfg which, if it exists, has to be readable by arbitrary programs.

drwxr-x--x 2 grommunio gromoxcf  64 Feb 20 21:47 /etc/gromox
-rw-r----- 1 grommunio gromoxcf 128 Feb 20 21:47 /etc/gromox/gromox.cfg
-rw-r----- 1 grommunio gromoxcf 128 Feb 20 21:47 /etc/gromox/mysql_adaptor.cfg
-rw-r--r-- 1 grommunio gromoxcf 128 Feb 20 21:47 /etc/gromox/pam.cfg

If you plan on utilizing SSO authentication via /usr/bin/ntlm_auth, you may need to add winbind to the list of supplementary groups for the gromox user, because the winbind socket (e.g. /var/run/samba/winbindd/pipe or /var/lib/samba/winbindd_privileged/pipe on SUSE Linux) may have limited permissions set on it. Consult with the winbind manuals for details on which gets used and when.

SMTP

exchange_emsmdb.cfg and zcore.cfg implicitly default to using localhost:25 as outgoing SMTP. At the same time, gromox-delivery-queue listens on port 25 by default, but it is only the local delivery agent (LDA). Therefore, the implied defaults only get you a system that can send mail to itself. To enable Internet mail or to add spam filtration, you will have to reconfigure gromox-delivery-queue (edit smtp.cfg) to listen on port 24 rather than 25, and install a full MTA like Postfix with configuration directives similar to:

virtual_mailbox_domains = domain.example otherdomain.example
virtual_transport = lmtp:localhost:24

Running from the source checkout

It is possible to run Gromox daemons from the source checkout. Heed the following notes.

Gromox daemons switch to unprivileged mode, and after doing so, will still need access to the build directory to access shared libraries. If any path component of the build directory is missing search (execute) permission, the daemon may be unable to start up. This happens predominantly when someone tries to build Gromox as root (not a great idea) in a subdirectory of /root (which often has mode 0700). For that scenario to succeed, /root would have to be made 0711 at least.

Gromox programs default to look for files in the installed system, i.e. /etc/gromox and /usr/share/gromox. If nothing else is needed, running daemons in place of their system counterparts is possible with no edits to configuration, e.g.:

systemctl stop gromox-http
./http

To test updates to data files such as folder_names.txt, the modifications will either have to be copied to the corresponding path in /usr/share/gromox; else, you can set up and run the daemon with an alternate config, e.g.:

cp /etc/gromox/http.cfg http.cfg
echo data_file_path=/root/gromox/data >>http.cfg
./http -c http.cfg

Service start

systemctl start <...>

• gromox-http — at the very least, the main process needs to be started. This is sufficient for e.g. Outlook to open and browse mailboxes.
• gromox-zcore — the zcore process is needed by anything using php-mapi (grommunio-web, grommunio-sync, ...)
• gromox-delivery-queue — LMTP/SMTP frontend of the local delivery agent (for incoming mail)
• gromox-delivery — Dequeueing backend of the local delivery agent
• gromox-imap — for ye Thunderbird