Installation Guide

Installation Prerequisites

Before performing an installation these prerequisites must be fulfilled:

$ zmcontrol status | grep proxy
proxy                   Running
$

In case you do not have a proxy running, follow the steps decribed in Zimbra-Wiki to enable it.

When the proxy is installed properly it should listen on port 443:

$ sudo netstat -nlp | grep 443
tcp        0      0 0.0.0.0:443           0.0.0.0:*             LISTEN      28098/nginx.conf
$

Certificate Requirements

The TLS certificate installed at the VNC Chat server must only cover the talk-server’s hostname:

yourchatserver.yourdomain.tld

In case your installation should be restricted to use the ZWC only for VNC Free Chat and external xmpp-clients, like Pidgin, should not be supported, you can even use a self signed SSL-certificate, having the sole requirement to be trusted by the Zimbra-Server. This allows you to let the installer actually automatically create and deploy a self-signed certificate during the installation process.

To make this option available, the installer must be executed with a specific flag. The whole process on how to use a self-signed certificate, including all necessary configurations, modifications and limitations is explained here in section Modifications necessary when using a self-signed SSL-certificate later on.

In case you want to support the use of external xmpp-clients, the talk-server’s SSL-certificate must be generally trusted (commercial, let’s encrypt)

To order a certificate matching the requirements you can create a CSR using this command:

$ openssl req -out yourchatserver.yourdomain.tld.csr -new -newkey rsa:2048 -nodes -keyout yourchatserver.yourdomain.tld.key

For better certificate management, put the key and crt files into the folder /etc/ssl/owncerts. You need to provide the TLS key and the TLS certificate. The certificate file must also include the complete CA chain!

Note 1: Please do not use a certificate with a password1.

Note 2: You may also order a LetsEncrypt-certificate for your talk-server hostname. This [Zimbra-Wiki] (https://wiki.zimbra.com/wiki/Installing_a_LetsEncrypt_SSL_Certificate) article describes, how to install a LetsEncrypt SSL-certificate on Zimbra. For the chat-server you need to provide the privkey1.pem and fullchain1.pem files when prompted for it during the installation process. Please make sure that you create a dedicated certificate for the chat server.

System Requirements

Evaluation and Testing

Production Environments

Firewall Settings

The Chat application server must only have these ports accessible:

Port Protocol Usage
80 TCP HTTP/BOSH/Websocket
443 TCP HTTPS/BOSH/Websocket
5222 TCP XMPP client to server connections
5269 TCP XMPP server to server connections

Please note: In case you do not want to use external clients, like Pidgin, the only instance to be able to access the Chat-application-server is the Zimbra-Server on Ports 80 and 443, so you

In addition to that, the Chat application server must have access to Zimbra’s WSDL-Interface and Admin-UI. The respective ports required can be obtained by executing this query as user zimbra on the attached Zimbra-Server:

$ zmprov gs `zmhostname` zimbraAdminPort zimbraMailSSLPort zimbraMailPort
# zimbra.yourdomain.tld
zimbraAdminPort: 7071
zimbraMailPort: 8080
zimbraMailSSLPort: 8443
$  

Preparing Zimbra Environment

Required Information / Credentials

During the installation of the Chat server, the installer will ask for several settings and information about your Zimbra and network environment. It is recommended to fetch this information now and copy it to a textfile for convenient usage later on. Execute all the following commands as user zimbra.

$ zmhostname
zimbra.yourdomain.tld
$
$ zmlocalconfig -s zimbra_ldap_password
zimbra_ldap_password = w_A77uZ9
$

The installer will check for additional settings and fetch these automatically. If any additional adjustments are required on your zimbra server, the installer will provide details.

General Settings

In preparation you should change these settings prior to installing the Chat server:

$ zmprov mcf zimbraZimletJspEnabled TRUE
$ zmprov mc default zimbraProxyAllowedDomains "*yourdomain.tld"
$ zmprov mcf +zimbraHttpThrottleSafeIPs $ChatServerIPv4
$ zmprov mcf zimbraHttpDosFilterMaxRequestsPerSec 100

Note: Replace the $ChatServerIP by the actual IP of your Chat server, as well as yourdomain.tld by the actual domain name you get when executing this command on the Chat application server:

$ hostname -d
yourdomain.tld
$

If you do not adjust the settings now, the installer will prompt you for it during the installation process.

DNS entries

This section lists the required DNS entries for the Chat components.

The XMPP server is called xmpp.yourdomain.tld. This server serves the yourdomain.tld. So a user JID2 will be for example alice.doe@yourdomain.tld . For each Chat service and subdomain a SRV DNS record is required, so the clients are informed which server provides the corresponding service, according to the official prosody documentation3:

The target domain (xmpp.example.com) MUST be an existing A record of the target server, it must not be an IP address, and cannot be a CNAME record.

;;
;; VNC XMPP server
;;
;; A records for XMPP server
;; OWNER-NAME                   TTL     CLASS   RR      IPV4
;yourdomain.tld.                       300     IN      A       $YOUR.IPv4   ; Use this record if the server has this dns name
xmpp.yourdomain.tld.                   300     IN      A       $YOUR.IPv4   ; Zimbra Talk prosody full hostname
;turn.yourdomain.tld.                  300     IN      A       $YOUR.IPv4   ; required for xmpp-file-transfer, which is not available in the current chat-implementation. So it is not necessary.

;;
;; XMPP special records
;;
;; TXT records for BOSH and Websocket
;; OWNER-NAM                    TTL     CLASS   RR      TEXT
_xmppconnect.xmpp.yourdomain.tld.      300     IN      TXT     "_xmpp-client-xbosh=https://xmpp.yourdomain.tld:443/http-bind"
_xmppconnect.yourdomain.tld.           300     IN      TXT     "_xmpp-client-xbosh=https://xmpp.yourdomain.tld:443/http-bind"
;;
;; SRV records for XMPP
;; SRVCE.PROT.OWNER-NAME                              TTL     CLASS   RR  PRI     WEIGHT  PORT    TARGET
_xmpp-client._tcp.yourdomain.tld.                     300     IN      SRV 0       5       5222    xmpp.yourdomain.tld.
_xmpp-server._tcp.yourdomain.tld.                     300     IN      SRV 0       5       5269    xmpp.yourdomain.tld.
_xmpp-client._tcp.xmpp.yourdomain.tld.                300     IN      SRV 0       5       5222    xmpp.yourdomain.tld.
_xmpp-server._tcp.xmpp.yourdomain.tld.                300     IN      SRV 0       5       5269    xmpp.yourdomain.tld.

During the installation, the installer will create ready-to-use configs for BIND and dnsmasq, stored to the files /etc/vnc-chat/dnsmasq.conf and /etc/vnc-chat/bind.conf

When installation is finished, a tool is provided to check for correct DNS settings, located in /usr/share/vnc-chat/libexec/check_chat_dns.sh

You can find real BIND and dnsmasq examples at the Appendix.


  1. A password secured TLS certificate is currently not supported by Chat 

  2. http://tools.ietf.org/html/rfc6122 

  3. http://prosody.im/doc/dns 

  4. see Section ”Split DNS” on page in Appendix 

  5. The domains must also be configured in the backend. Currently all domains are configured during the installation. Whenever a domain is added, run /usr/share/ztalk/libexec/update-prosody-conf to update configuration. 

  6. see https://en.wikipedia.org/wiki/Private_network 

  7. see https://en.wikipedia.org/wiki/Network_address_translation