Configuration

The Guam configuration lives in rel/kolab_guam/releases/*/sys.config when running from source directly, and in /etc/guam/sys.config for installation from packages.

The configuration file consists of sections for each of the applications to configure, where it needs to be understood that kolab_guam is one such application, and lager for logging, and sasl for authentication, are two of the other sections.

This documentation only involves the kolab_guam section, and we refer you to the documentation upstream for the others.

Since Guam is a reverse IMAP proxy, it needs to be configured against an IMAP server (the backend “imap_servers”), and it needs to be configured to receive client connections (the “listeners”).

IMAP (backend) Server Configuration

The default configuration for imap_servers looks as follows:

 1        {
 2            imap_servers, [
 3                {
 4                    imap, [
 5                        { host, "127.0.0.1" },
 6                        { port, 143 },
 7                        { tls, starttls }
 8                    ]
 9                },
10                {
11                    imaps, [
12                        { host, "127.0.0.1" },
13                        { port, 993 },
14                        { tls, true }
15                    ]
16                }
17            ]
18        },

On line 4 and line 11 each start the configuration for a new backend server, named imap and imaps respectively.

Note

Strictly speaking, only one backend is required. The default configuration only uses two to show how multiple backends could be configured. One could configure completely different backends (say, ‘kolabnow.com’ and ‘myhome.dyndns.org’ for example).

The imap backend connects to host 127.0.0.1 on port 143 and is configured to use STARTTLS.

The imaps backend however connects to host 127.0.0.1 on port 993 and is configured to use implicit SSL/TLS.

Listener Configuration

The following listeners are configured by default:

 1     {
 2         listeners, [
 3             {
 4                 imap, [
 5                     { port, 9143 },
 6                     { imap_server, imap },
 7                     {
 8                         rules, [
 9                             { filter_groupware, [] }
10                         ]
11                     },
12                     {
13                         tls_config, [
14                             { certfile, "/etc/pki/tls/private/localhost.pem" },
15                             { cacertfile, "/etc/pki/tls/private/localhost.ca.pem" },
16                             { keyfile, "/etc/pki/tls/private/localhost.key" }
17                         ]
18                     }
19                 ]
20             },
21             {
22                 imaps, [
23                     { port, 9993 },
24                     { implicit_tls, true },
25                     { imap_server, imaps },
26                     {
27                         rules, [
28                             { filter_groupware, [] }
29                         ]
30                     },
31                     {
32                         tls_config, [
33                             { certfile, "/etc/pki/tls/private/localhost.pem" },
34                             { cacertfile, "/etc/pki/tls/private/localhost.ca.pem" },
35                             { keyfile, "/etc/pki/tls/private/localhost.key" }
36                         ]
37                     }
38                 ]
39             }
40         ]
41     }

Again, each listener is provided with an identity (imap and imaps respectively), listens on a different port (9143 and 9993 respectively), with subtly different configuration;

  • The imap listener on port 9143 is supposed to be used by clients that are configured to use STARTTLS,

  • The imaps listener on port 9993 is supposed to be used by clients that are configured to use implicit SSL/TLS (hence the { implicit_tls, true } on line 22.

The imap_server configuration for each of the listeners contains the name of the backend IMAP server configuration to use.

Note

Note that a plaintext, STARTTLS and implicit SSL/TLS listener can, each of them separately, use a plaintext, STARTTLS and/or implicit SSL/TLS backend IMAP server (configured in the imap_servers section).

Configuration in a Kolab Groupware Setup

In a Kolab Groupware setup, Guam is configured with listeners on ports 143 and 993, against an imaps IMAP server on localhost port 9993.