Install & Configure the VNC Free Chat Zimlet

This section describes how to install and configure the VNC Free Chat Zimlet on a Zimbra 8.6/ 8.7 environment, which provides the VNC Free Chat client integrated in the ZWC.

Customizing zimbra proxy settings

Open the file as user zimbra

/opt/zimbra/conf/nginx/templates/nginx.conf.web.https.default.template

and search this line:

     #For long polling of Microsoft ActiveSync

Before this line insert:

    location ^~ /VNCMiddleware
    {
         proxy_cache off;
         proxy_read_timeout 500s;
         proxy_pass_header Cookie;      
         proxy_pass      http://$ChatServerIP:8080/VNCMiddleware;
    }
     #For long polling of Microsoft ActiveSync

Note1: replace $ChatServerIP with the actual IP of your Chat server. The actual config will be updated and applied after executing

    /opt/zimbra/libexec/zmproxyconfgen

and restarting the proxy via zmproxyctl restart or the whole Zimbra appication via zmcontrol restart - which will be covered in the following steps of this document.

Note2: On a Zimbra-Multiserver environment, this modification must be performed on ALL zimbra-proxy instances.

Installing zmpkg

In order to install any VNC zimlets, including the Zimbra Talk zimlet, you need to install and configure zmpkg first. The zmpkg installer bundle is available here.

Download the zmpkg installer bundle and transfer it to the machine where Zimbra is installed.

You can copy the link and use wget from the command line to download it directly into your Zimbra machine, for example:

wget http://packages.vnc.biz/zmpkg/bootstrap/zmpkg-installer-latest.tar.gz

Extract the downloaded file:

tar xfvz zmpkg-installer-latest.tar.gz

Change to the extracted directory and execute the installer as user root. The install script will take care of all needed dependencies and will install these too.

$ cd zmpkg-installer-1.4.4.2
$ sudo ./install.sh

Now switch to the zimbra user:

$ sudo su - zimbra

and check whether zmpkg has been installed or not, by using the zmpkg list command.

$ zmpkg list

Note: if your system is behind a proxy, you might have to set the $http_proxy environment variable accordingly:

export http_proxy=http://<proxy-host>:<proxy-port>/

It may be required to add the http_proxy variable to the zimbra user’s .profile or .bashrc files. Additionally you can also configure zmpkg to use that proxy directly. Create the file /opt/zimbra/extensions-extra/zmpkg/etc/apt/apt.conf.d/20proxy with this content:

Acquire:http:proxy "http://<proxy-host>:<proxy-port>/"

Configure zmpkg

Since zmpkg works like apt-get, it is possible to change the repository-URL where the Zimlets are installed from. To do so, you need to log in as the zimbra user and edit the apt-sources file

/opt/zimbra/extensions-extra/zmpkg/etc/apt/sources.list

$ sudo su - zimbra
$ vim /opt/zimbra/extensions-extra/zmpkg/etc/apt/sources.list

In order to install the Zimbra Talk zimlet, you need to add the commercial repository. Finally the source.list file should look like this:

## automatic entry generated by bootstrap install
## NOTE: you should retain formatting (spaces instead of tabs) for further automatic config upgrades to work
deb http://packages.vnc.biz/zmpkg/current judaspriest free restricted commercial

## uncomment this if you want to use commercial VNC products
## NOTE: these products are free for evaluation-only, but charged on usage
##       please see http://www.vnc.biz/ for more information
# deb http://packages.vnc.biz/zmpkg/current judaspriest commercial

## add your own repos here

zmpkg Usage

zmpkg and zm-apt-get can be used like the Debian/Ubuntu dpkg and apt-get procedures:

update, upgrade, install, download, etc.

All these commands must be executed as the zimbra user!

Updating repository

zm-apt-get update

Installing zimlets from a given .deb file

Install any zimlet deb package using

zmpkg install </path/to/package.deb>

After the installation of a zimlet, restart the mailboxd and flush the cache by using

zmmailboxdctl restart
zmprov fc all

to make the changes available in the ZCS.

Installing zimlets from a repository

Install any zimlet using zm-apt-get install <package name> command, for example:

zm-apt-get install zcs-vnc-freechat

After the installation of a zimlet, restart the mailboxd and flush the cache by using

zmmailboxdctl restart
zmprov fc all

to make the changes available in the ZCS.

Listing installed zimlets

To check if a zimlet is installed or get a list of all the installed zimlets and dependencies, execute the command

zmpkg list

Upgrading installed zimlets

To upgrade installed zimlets from the repository, just execute debian like

zm-apt-get update
zm-apt-get upgrade

Installing the zcs-vnc-freechat zimlet

After zmpkg has been installed successfully, while logged in as the zimbra user in the Zimbra ZCS environment, run the following shell commands

zm-apt-get update
zm-apt-get install zcs-vnc-freechat
zmcontrol restart

These commands use zmpkg to update the repository and install the Zimbra Talk zimlet. To make the changes available to the users it is required to restart all services.

Now you need to run the additional zmprov commands, listed in General Settings, if you did not execute these yet.

Note: On a Zimbra-Multiserver environment, zmpkg & the Zimlet must be installed on ALL zimbra-mailbox instances individually.

Configuring the zcs-vnc-freechat Zimlet

After the Zimbra ZCS environment restarted all services and the Zimbra Talk backend server has been fully installed and configured, next step is the configuration of the VNC Free Chat Zimlet:

Open Zimbra Admin interface as the Zimbra-admin, then navigate to the section “Configure -> VNC Free Chat Zimlet”, which brings you to the VNC Chat global configuration section.

Basic XMPP configuration

This section contains the basic parameters required by VNC Free Chat to work for all domains existing in the Zimbra ZCS environment5.

The settings which must be filled in here, have been displayed at the end of the Chat-application server's installation process:

VNC Free Chat installation (nearly) done.                                           
please visit this page and follow the instructions - https://doc.freechat.vnc.biz/install/configure-zimlet/
configure in Zimbra Admin UI these settings:

XMPP server URL:           https://<server-URL-forAdminUI>
XMPP server URL Port:      443
Authentication Token:      <shared secred>

After this configuration has been set, click the save button in the upper right corner of the screen.

Note: On a Zimbra-Multiserver environment, the Zimlet-configuration must be performed on ALL zimbra-mailbox instances by accessing the respective mailboxes Admin-UI individually.

Modifications necessary when using a self-signed SSL-certificate (Optional)

To generate a self-signed SSL-certificate by the installer and deploy it automatically during the installation process on the chat-application server, you have to execute the installer with the ss flag::

sudo ./install-vnc-free-chat.sh -ss

Instead of beeing asked in Step 3 of the chat-application server installation process for the location of the commercial certificates key- and certificate-file, you will be able to choose whether you want to use a self-signed certificate instead:

When selecting ”YES” here, you will be prompted in the next two screens to enter the path to the commercial certificate’s keyfile and certificatefile as described in Step 3 of the chat-application server installation process. Selecting ”NO” here will create a self-signed certificate and deploy it automatically on the chat-application server.

Note: When not using a commercial SSL-certificate, access to the VNC Free Chat server will only be available via the Zimlet. External client-applications will not be able to connect to the chat-server, when choosing this option.

Selecting No when asked whether to use a commercial or a self-signed SSL-certificate creates these three files (certificate request, private key, self-signed certificate):

vnc-chat-ssl-cert.csr
vnc-chat-ssl-cert.key
vnc-chat-ssl-cert.pem

available in location /etc/vnc-chat/ on the chat-application server once the installation has been finished. To make sure, the free-chat application works with this self-signed SSL-certificate, created by the installer, you need to ensure that:

Add SSL-certificate to Zimbra server’s trust store

  1. Copy the self signed certificate located in /etc/vnc-chat/vnc-chat-ssl-cert.pem to the Zimbra-Server’s /tmp/ directory

  2. Import it to the Zimbra-server’s trust store after setting the necessary permissions for user Zimbra:

        $sudo chmod 777 /tmp/vnc-chat-ssl-cert.pem
        $sudo su - zimbra
        $zmcertmgr addcacert /tmp/vnc-chat-ssl-cert.pem
        $zmmailboxdctl restart
        $zmprov fc all
    

    A restart of the mailboxd is required to take effect.

Add additional proxy customizations

in order to make the webclient perform all access to the VNC Free Chat server via the Zimbra server, a few more proxy customizations must be added in addition to the one described in section Customizing zimbra proxy settings:

Open the file as user zimbra

/opt/zimbra/conf/nginx/templates/nginx.conf.web.https.default.template

and search for the already inserted location:

    location ^~ /VNCMiddleware
    {
         proxy_cache off;
         proxy_read_timeout 500s;
         proxy_pass_header Cookie;      
         proxy_pass      http://$ChatServerIP:8080/VNCMiddleware;
    }
     #For long polling of Microsoft ActiveSync

Extent this modification by additional three locations, so that the modification finally looks like this:

    location ^~ /VNCMiddleware
    {
         proxy_cache off;
         proxy_read_timeout 500s;
         proxy_pass_header Cookie;      
         proxy_pass      http://$ChatServerIP:8080/VNCMiddleware;
    }
    location ^~ /mini
    {
        proxy_cache off;
        proxy_read_timeout 500s;
        proxy_pass_header Cookie;
        proxy_pass      https://$ChatServerIP:443/mini;
    }
    location ^~ /http-bind
    {
        proxy_cache off;
        proxy_read_timeout 500s;
        proxy_pass_header Cookie;
        proxy_pass      https://$ChatServerIP:443/http-bind;
    }
    location ^~ /middleware_lib.js
    {
        proxy_cache off;
        proxy_read_timeout 500s;
        proxy_pass_header Cookie;
        proxy_pass      https://$ChatServerIP:443/middleware_lib.js;
    }
     #For long polling of Microsoft ActiveSync

Note1: Replace $ChatServerIP with the actual IP of your Chat server. The configuration will be updated and applied after executing

/opt/zimbra/libexec/zmproxyconfgen

and restarting the proxy via

zmproxyctl restart

Note2: On a Zimbra-Multiserver environment, this modification must be performed on ALL zimbra-proxy instances.

Adjust XMPP server URL in Zimlet-configuration

Since all chat-server-access is handled by Zimbra through proxy-customizations now, finally the XMPP server URL must be replaced by the Zimbra-URL in the VNC Free Chat Zimlet configuration.

Open Zimbra Admin interface as the Zimbra-admin, then navigate to the section ”Configure -> Zimbra Talk Zimlet”, which brings you to the Zimbra Talk global configuration section.

Now modify the red framed URL in “Basic XMPP configuration” section:

to your Zimbra-URL and save the changes.

Uninstall VNC Free Chat

Uninstall VNC Free Chat application server

To uninstall the VNC Free Chat application, execute the VNC Free Chat installer with the -u flag and root privileges:

$ sudo ./install-vnc-free-chat.sh -u

Since this might take some time, we propose running the uninstall process in a screen. After the uninstall process has been started, you are prompted, if you are really sure to proceed:

If Yes is chosen here, the uninstall process will be started:

performing uninstall                                                                                                                                        
 * Stopping Prosody XMPP Server prosody
   ...done.
 * Stopping Jetty servlet engine (was reachable on http://<talkserver>:8080/). jetty8
 * Jetty servlet engine stopped. jetty8
   ...done.
 * Stopping nginx nginx
   ...done.
removing packages
0
0
0
0
0
0
cleaning up
VNC Free Chat is now removed
$

The line VNC Free Chat is now removed indicatees that the uninstall process has been finished and the VNC Free Chat application server has been completely removed from the system.

Uninstall VNC Free Chat Zimlet

To remove the VNC Free Chat Zimlet from your Zimbra-Environment, perform these commands as user zimbra:

$ sudo su - zimbra
$ zm-apt-get remove zcs-vnc-freechat

To complete the removal process, the mailboxd has to be restarted and we propose to flush the cache the along with it:

$ zmmailboxdctl restart
$ zmprov fc all

Note: In a multi-server environment, these actions must be performed on every Zimbra Mailbox server.

Upgrade VNC Free Chat to a new version

To upgrade VNC Free Chat you have to perform the update on the Zimbra-Talk application server and check for a new version of the VNC Free Chat Zimlet as well. If you upgrade only one of the two components, you might run into compatibility issues afterwards, which might render your VNC Free Chat setup unusable.

Upgrade the VNC Free Chat application server

You can upgrade the current installation by executing:

$ sudo apt-get update
$ sudo apt-get dist-upgrade

Despite the fact that the upgraded component services are restarted during the upgrade process, we recomment, doing a full reboot of the VNC Free Chat application server after the upgrade has been completed.

Upgrade the VNC Free Chat Zimlet

Check if the current stable repository is setup correctly for zmpkg:

$ sudo su - zimbra
$ cat /opt/zimbra/extensions-extra/zmpkg/etc/apt/sources.list
## automatic entry generated by bootstrap install
## NOTE: you should retain formatting (spaces instead of tabs)
##       for further automatic config upgrades to work
deb http://packages.vnc.biz/zmpkg/current judaspriest free restricted commercial

## add your own repos below

Comment out every other repository than

deb http://packages.vnc.biz/zmpkg/current judaspriest free restricted commercial

Now check for updates of the Zimlet and upgrade it in case there is a new version available by executing:

zm-apt-get update
zm-apt-get upgrade

In case a new version of the Zimlet has been found and installed, the mailbox-server has to be restarted and the caches flushed:

zmmailboxdctl restart
zmprov fc all

Note: On a multi-server environment, the Zimlet must be upgraded this way on every mailbox-server.


  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/vnc-chat/libexec/update-prosody-conf

    to update the configuration. 

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

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