vnc-milter/README.md

# VNC Disclaimer Middleware Installation and Setup

The VNC Disclaimer Middleware is provided as debian package (deb) for Ubuntu 22.04 distributions in a gitea repository, maintained by VNC.

It is plugged into the Zimbra MTA using the milter protocol.<br/>
Upon startup it reads distribution lists and member accounts from the Zimbra LDAP and caches the information.
The cached information is refreshed in a configurable interval with a default value of 10 minutes. <br/>
When an eMail is processed using this milter, these following actions are performed:

* determine the distribution-list membership of the sender
* add the respective disclaimer according to the configuration in the corresponding format (plain text/ html) to the end of the eMail, but only if the desired disclaimer has not been added to the eMail conversation yet, e.g. if replying to an eMail that already contains a disclaimer.

## Prequesites

### Gather system information

In order to setup the VNC Disclaimer Middleware for your Zimbra environment, the following information, queried as user **zimbra** via CLI, is required.<br/>

* **Zimbra LDAP URL**

        zimbra@zcs:~$ zmlocalconfig ldap_url
        ldap_url = ldap://zim.nowhere.org:389
        zimbra@zcs:~$

* **Zimbra LDAP credentials**

        zimbra@zcs:~$ zmlocalconfig -s zimbra_ldap_password
        zimbra_ldap_password = MyLDAPpw
        zimbra@zcs:~$

### Requirements for the VNC Disclaimer Middleware host

* required OS: Ubuntu 22.04
* the machine must be able to resolve the hostname of the Zimbra LDAP node via distributions
* access to an account profile with sudo permissions

## Installation

* setup the software repository for the VNC Disclaimer Middleware installation using an account with **sudo** permissions.

        sudo curl https://repos.vnc.de/api/packages/primerica/debian/repository.key -o /etc/apt/keyrings/gitea-primerica.asc
        echo "deb [signed-by=/etc/apt/keyrings/gitea-primerica.asc] https://repos.vnc.de/api/packages/primerica/debian jammy main" | sudo tee -a /etc/apt/sources.list.d/gitea.list
        sudo apt update

* install the VNC Disclaimer Middleware via apt

        sudo apt install vnc-disclaimer

## Setup & configuration

* adjust mandatory parameters in configuration file **/etc/vncdisclaimer/clouddird.cf** using the information gathered from the Zimbra LDAP before and replace the values accordingly:

        # Zimbra LDAP URI
        disclaimer-ldap-uri=ldap://zim.nowhere.org:389

        # Zimbra LDAP bind password
        disclaimer-ldap-password=MyLDAPpw


!!!tip "If parameters are no set in /etc/vncdisclaimer/clouddird.cf their default values are used."

### Optional configuration parameters and their default values

In addition to the two LDAP config parameters, that are mandatory and have to be configured for your environment, there are optional config parameters to adjust as well. <br/>

* Parameters and their default values (if unset):

**Config Parameter**|**Description**|**Default value**
-----------|---------------------------|--------------
disclaimer-directory| absolute path to the directory containing the mail disclaimer files| /etc/vncdisclaimer/disclaimers/
disclaimer-ldap-bind-dn| Zimbra LDAP bind dn (uid=zimbra,cn=admins,cn=zimbra)|zimbra,cn=admins,cn=zimbra
disclaimer-milter-port| ip port to bind for the disclaimer milter service| 9001
threadpool-size| maximum number of parallel tasks| 20
disclaimer-cache-seconds| number of seconds to cache disclaimer files and Zimbra distribution lists|600
disclaimer-charset| character set to read the disclaimer files with, see https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html for supported values| UTF-8
disclaimer-exceptions-file| file name of the list containing the sender addresses that should be excluded from disclaimer processing, relative to the directory location of this config file (clouddird.cf)| disclaimer-exceptions.txt
debug| enable debug mode for more verbose logging| off

### Setup disclaimers

The disclaimer have to be created in **/etc/vncdisclaimer/disclaimers/** if nothing else is provided in **clouddird.cf**.
A few examples are provided for plain-text and HTML version for disclaimer in the directory after the installation already. <br/>
The naming the convention for the disclaimer files has to follow this scheme:

        <distributionlist-address>.<type>

where,

* **distributionlist-address** is the eMail-address of the respective Zimbra distribution-list, where the senders, that should have the content of this file attached as disclaimer to the eMails they send, need to be members of
* **type** is either **txt** for plain text or **html** for HTML mail parts.

**Note:** "all disclaimer files have to be encoded in UTF-8 and use LF only as newline character (standard unix format, see
https://en.wikipedia.org/wiki/Newline ), in doubt, please use **dos2unix** to convert the files"

* Finally start the VNC Disclaimer Middleware service:

        sudo systemctl status vncmilter

* To apply any change performed to the configuration, the vncmilter service needs to be restarted:

        sudo systemctl restart vncmilter


## Zimbra MTA Integration

Log into the CLI of each **Zimbra MTA node** of your Zimbra Collaboration Suite installation via ssh, become user **zimbra** and

* set **zimbraMilterServerEnabled** to **TRUE**

        zimbra@zcs:~$ zmprov ms `zmhostname` zimbraMilterServerEnabled TRUE

* add the **VNC Disclaimer Middleware** to your configuration, using the IP of your VNC disclaimer middleware server (in this example 192.168.21.42 is used):

        zimbra@zcs:~$ zmprov ms `zmhostname` zimbraMtaSmtpdMilters "inet:192.168.21.42:9001"

* restart the MTA services to apply the changes:

        zimbra@zcs:~$ zmmtactl restart && zmprov fc all

Now all eMails are processed by the VNC Middleware service.

## Miscellaneous

* all account listed in the **disclaimer-exceptions-file** (default location: /etc/vncdisclaimer/disclaimer-exceptions.txt) will not get any disclaimers attached to their eMails up on sending.
* all Zimbra accounts that are not listed in the **disclaimer-exceptions-file** and are not members of a distribution list, where the name convention reflects a disclaimer file in **/etc/vncdisclaimer/disclaimers/**, will get the **default** disclaimer setup in **/etc/vncdisclaimer/disclaimers/default.html(.txt)** attached to their eMails up on sending.
* in case an account is member in multiple distribution-lists, that each have disclaimer configursation files setup for their names, all the suiting disclaimers according to the account's membership will be added to the account's eMails up on sending