add readme
This commit is contained in:
128
README.md
Normal file
128
README.md
Normal file
@@ -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.<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.
|
||||
|
||||
!!!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
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user