diff --git a/source/about/guam/building.rst b/source/about/guam/building.rst index 1b58997b..5d23f885 100644 --- a/source/about/guam/building.rst +++ b/source/about/guam/building.rst @@ -1,20 +1,19 @@ -======== 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 index eaff5ded..f88410a4 100644 --- a/source/about/guam/configuration.rst +++ b/source/about/guam/configuration.rst @@ -1,134 +1,133 @@ -============= 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/contributing.rst b/source/about/guam/contributing.rst new file mode 100644 index 00000000..5a1988f1 --- /dev/null +++ b/source/about/guam/contributing.rst @@ -0,0 +1,2 @@ +Contributing +============ diff --git a/source/about/guam/index.rst b/source/about/guam/index.rst index 19e6128e..d8bcb4a8 100644 --- a/source/about/guam/index.rst +++ b/source/about/guam/index.rst @@ -1,31 +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 +operations, such that IMAP clients that 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: * diff --git a/source/about/guam/installation.rst b/source/about/guam/installation.rst new file mode 100644 index 00000000..753fc3c3 --- /dev/null +++ b/source/about/guam/installation.rst @@ -0,0 +1,4 @@ +Installation +============ + +.. include:: rpm-requires.txt diff --git a/source/about/guam/packaging.rst b/source/about/guam/packaging.rst new file mode 100644 index 00000000..921e0149 --- /dev/null +++ b/source/about/guam/packaging.rst @@ -0,0 +1,2 @@ +Packaging +========= diff --git a/source/about/guam/rpm-buildrequires.txt b/source/about/guam/rpm-buildrequires.txt new file mode 100644 index 00000000..6e9a3b9f --- /dev/null +++ b/source/about/guam/rpm-buildrequires.txt @@ -0,0 +1,19 @@ +.. + Generate this information with: + + $ repoquery --requires guam.src | while read req; do + pkgnames=$(repoquery --whatprovides "${req}" --queryformat="%{NAME}" | sort -u) + for pkgname in ${pkgnames}; do + if [ -d "../${pkgname}/" ]; then + echo "#. :ref:\`about-${pkgname}\` $(echo ${req} | cut -d' ' -f2-)" + else + echo "#. ${req}" + fi + done + done + +#. erlang +#. erlang-eimap >= 0.1.5 +#. erlang-goldrush +#. erlang-lager >= 2.1.0 +#. erlang-rebar >= 2.5.1 diff --git a/source/about/guam/rpm-requires.txt b/source/about/guam/rpm-requires.txt new file mode 100644 index 00000000..d9bdb634 --- /dev/null +++ b/source/about/guam/rpm-requires.txt @@ -0,0 +1,50 @@ +.. + repoquery --requires guam.x86_64 | while read req; do + repoquery --whatprovides "${req}" --queryformat="%{NAME}" + done | sort -u | while read pkg; do + if [ -d "../${pkg}" ]; then + echo "#. :ref:\`about-${pkg}\`" + else + echo "#. ${pkg}" + fi + done + + repoquery --requires guam.x86_64 | while read req; do + pkgnames=$(repoquery --whatprovides "${req}" --queryformat="%{NAME}") + for pkgname in ${pkgnames}; do + if [ -d "../${pkgname}" ]; then + if [ $(echo ${req} | wc -w) -gt 1 ]; then + echo "#. :ref:\`about-${pkgname}\` $(echo ${req} | cut -d' ' -f2-)" + else + echo "#. :ref:\`about-${pkgname}\`" + fi + else + if [ $(echo ${req} | wc -w) -gt 1 ]; then + echo "#. ${pkgname} $(echo ${req} | cut -d' ' -f2-)" + else + echo "#. ${pkgname}" + fi + fi + done + done | sort -u + +#. :ref:`about-erlang-eimap` >= 0.1.2 +#. :ref:`about-erlang-goldrush` +#. :ref:`about-erlang-lager` >= 2.1.0 +#. :ref:`about-erlang` >= 17.4 +#. bash +#. coreutils +#. glibc +#. libgcc +#. libstdc++ +#. mesa-libGL +#. mesa-libGLU +#. ncurses-libs +#. openssl-libs +#. shadow-utils +#. systemd +#. systemd-libs +#. wxBase +#. wxGTK +#. wxGTK-gl +#. zlib diff --git a/source/about/guam/troubleshooting.rst b/source/about/guam/troubleshooting.rst new file mode 100644 index 00000000..4edddddf --- /dev/null +++ b/source/about/guam/troubleshooting.rst @@ -0,0 +1,2 @@ +Troubleshooting +=============== diff --git a/source/about/guam/version-matrix.rst b/source/about/guam/version-matrix.rst new file mode 100644 index 00000000..d382c261 --- /dev/null +++ b/source/about/guam/version-matrix.rst @@ -0,0 +1,30 @@ +.. _about-guam-version-matrix: + +Version Matrix +============== + +.. table:: Version Table for guam + + +---------------------+---------------+--------------------------------------+ + | Kolab Version(s) | Platform(s) | Version | + +=====================+===============+======================================+ + | Kolab:Winterfell | CentOS_7 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | | Debian_8.0 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | | Debian_9.0 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | | Fedora_23 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | | Ubuntu_14.04 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | | Ubuntu_16.04 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | | openSUSE_13.2 | 0.8-7 | + +---------------------+---------------+--------------------------------------+ + | Kolab:16 | CentOS_7 | 0.7.2-2 | + +---------------------+---------------+--------------------------------------+ + | Kolab:14 | CentOS_6 | 0.7.2-2 | + +---------------------+---------------+--------------------------------------+ + | | CentOS_7 | 0.7.2-2 | + +---------------------+---------------+--------------------------------------+