From 02f7660fd221282d92843546be7ccf92c323e097 Mon Sep 17 00:00:00 2001 From: Stefan Saenger Date: Fri, 21 Nov 2025 14:07:08 +0100 Subject: [PATCH] add readme --- README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..98eef6d --- /dev/null +++ b/README.md @@ -0,0 +1,128 @@ +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.
+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.
+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.
+ +* **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.
+ +* 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.
+The naming the convention for the disclaimer files has to follow this scheme: + + . + +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. + +!!!tip "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 + + + +