.. SPDX-License-Identifier: CC-BY-SA-4.0 or-later SPDX-FileCopyrightText: 2026 grommunio GmbH 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 * 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. .. code-block:: # 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 --------------- .. code-block:: 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: .. code-block:: ./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 `_ 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. __ https://github.com/grommunio/gromox/blob/master/exch/php/ews/autodiscover.php#L24 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. .. code-block:: text 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. .. code-block:: text 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.: .. code-block:: sh 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