diff --git a/source/about/guam/building.rst b/source/about/guam/building.rst new file mode 100644 index 00000000..1b58997b --- /dev/null +++ b/source/about/guam/building.rst @@ -0,0 +1,20 @@ +======== +Building +======== + +Build Requirements +================== + +The following requirements need to be fulfilled to build Guam: + +.. include:: rpm-buildrequires.txt + +Build Instructions +================== + +.. parsed-literal:: + + $ :command:`rebar compile -v` + $ :command:`rebar eunit -v` + $ :command:`cd rel/` + $ :command:`rebar generate -v` diff --git a/source/about/guam/configuration.rst b/source/about/guam/configuration.rst new file mode 100644 index 00000000..eaff5ded --- /dev/null +++ b/source/about/guam/configuration.rst @@ -0,0 +1,134 @@ +============= +Configuration +============= + +The **Guam** configuration lives in +:file:`rel/kolab_guam/releases/*/sys.config` when running from source +directly, and in :file:`/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: + +.. code-block:: erlang + :linenos: + + { + imap_servers, [ + { + imap, [ + { host, "127.0.0.1" }, + { port, 143 }, + { tls, starttls } + ] + }, + { + imaps, [ + { host, "127.0.0.1" }, + { port, 993 }, + { tls, true } + ] + } + ] + }, + +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: + +.. code-block:: erlang + :linenos: + + { + listeners, [ + { + imap, [ + { port, 9143 }, + { imap_server, imap }, + { + rules, [ + { filter_groupware, [] } + ] + }, + { + tls_config, [ + { certfile, "/etc/pki/tls/private/localhost.pem" } + ] + } + ] + }, + { + imaps, [ + { port, 9993 }, + { implicit_tls, true }, + { imap_server, imaps }, + { + rules, [ + { filter_groupware, [] } + ] + }, + { + tls_config, [ + { certfile, "/etc/pki/tls/private/localhost.pem" } + ] + } + ] + } + ] + } + +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`. diff --git a/source/about/guam/index.rst b/source/about/guam/index.rst new file mode 100644 index 00000000..19e6128e --- /dev/null +++ b/source/about/guam/index.rst @@ -0,0 +1,31 @@ +.. _about-guam: + +==== +Guam +==== + +**Guam** is an intelligent reverse IMAP proxy that applies rulesets to +commands, command results and payload, provided context. + +Current features include filtering groupware folders from IMAP folder +operations, such that IMAP clients who do not understand Kolab Groupware +folders are not shown those folders. + +Future features include Data-Loss Prevention (DLP) capabilities and Audit +Trail integration. + +**Guam** is a Kolab product hosted at `Phabricator`_: + +* Project URL: https://git.kolab.org/tag/guam/ + +* Git URL (anonymous): https://git.kolab.org/diffusion/G/guam.git + +* Git URL (authorized): ssh://git@git.kolab.org/diffusion/G/guam.git + +.. rubric:: Further Information + +.. toctree:: + :maxdepth: 1 + :glob: + + *