3. Configuration¶

The major difference between the traditional setup of WebApp and the setup of Web Meetings is that the front end server, which provides SSL secured HTTPS connectivity, is the NGINX web server. The Apache server that hosts WebApp will need to be configured to listen to different port than 443. As an example we are choosing port 8000. This is due to the necessity to support secure web sockets for the web meetings service.

Important

On Web Meetings servers NGINX provides the frontend HTTPS connection.

3.1. Combined Setup of Web Meetings Components and WebApp on the same host¶

The suggested setup for single host KC systems is to combine WebApp and the Web Meeting components on the same server.

Note

Other setup variations are possible when multiple hosts are involed. Please contact Kopano Professional Services for more info.

3.1.1. Configuring Apache¶

Please configure Apache and WebApp as described in the KC Administrators Manual. In the following steps we will configure Apache to use a different port. Furthermore, if you are modifying an existing system, please remove the SSL configuration from Apache.

3.1.1.1. Configuring apache on Debian Wheezy (7.0) and Ubuntu¶

To configure Apache2 to listen on port 8000, edit /etc/apache2/ports.conf

NameVirtualHost *:8000
Listen 127.0.0.1:8000

(Remove /etc/apache2/mods-enabled/ssl.conf and ssl.load if SSL was configured in Apache)

Restart apache2:

service apache2 restart

3.1.1.2. Configuring Apache on CentOS 7.0¶

To configure Apache2 to listen on port 8000, edit /etc/httpd/conf/httpd.conf and locate the Listen setting and replace with the following:

NameVirtualHost *:8000
Listen 127.0.0.1:8000

(Please deactivate SSL if SSL was priorly configured in apache)

Restart apache2

service httpd restart

3.1.2. Configuring NGINX¶

Please configure NGINX by adding a conf.d file for your server that passes /webapp requests to the Apache2 server on port 8000 and everything else to the spreed.webrtc server. Below is an example for the test server spreed.example.com. Please note that Chrome, Firefox or Iridium will only remember your camera/mic access grant if the connection is a HTTPS connection. A simple HTTP setup will require granting camera/mic access every time. Here is the example /etc/nginx/conf.d/webapp_webmeetings_ssl.conf file, the bottom part includes the support for upgrading HTTP(S) connections to websocket. We assume for this setup that WebApp will be reached under the /webapp/ URL path and Web Meetings under the /webmeetings/ URL path.

Please enter this configuration into the existing default.conf file or remove the default.conf file. For further info please refer to http://nginx.org. Please note that the setting ssl_ciphers is one line and must end with a semicolon:

server {
        listen 212.234.234.234:443 ssl;
        server_name webapp.example.com;
        ssl on;
        ssl_certificate /etc/nginx/webapp.example.com.chained.crt;
        ssl_certificate_key /etc/nginx/webapp.example.com.key;
        ssl_session_cache shared:SSL:1m;
        ssl_session_timeout 5m;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA256:DHE-DSS-AES128-SHA256:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256:AES128:AES:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK ;
        ssl_prefer_server_ciphers on;
        #
        # ssl_dhparam require you to create a dhparam.pem, this takes a long time
        #ssl_dhparam /etc/ssl/certs/dhparam.pem;
        #
        location /webmeetings {
                proxy_pass http://localhost:8090;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
        location /webapp {
                proxy_pass http://localhost:8000;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
}
map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
}
proxy_buffering on;
proxy_ignore_client_abort off;
proxy_redirect off;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;

Note

Please consider, that when also proxying Z-Push connections you should raise your proxy timeouts accordingly. e.g. proxy_connect_timeout 3600; proxy_send_timeout 3600; proxy_read_timeout 3600;

Then optionally generate a dhparam.pem file (this is going to take a long time):

cd /etc/ssl/certs && openssl dhparam -out dhparam.pem 4096

And then uncomment the following line in your configuration file:

ssl_dhparam /etc/ssl/certs/dhparam.pem;

Important

Do not forget to create the ssl-certificate and -key as configured above.

Important

Make sure you have installed a version from the nginx repository with support for the websockets (>=1.4).

Important

Make sure that port in the proxy_pass setting for the location / matches the port that kopano-webmeetings is running on. See the following section about Configuring kopano-webmeetings.

Restart NGINX

/etc/init.d/nginx restart

3.1.3. Configuring kopano-webmeetings¶

Please configure kopano-webmeetings powered by Spreed.WebRTC by editing its config file at /etc/kopano/webmeetings.cfg. If you set up your installation according to our standard recommendation, then the only changes you need to make are to assign your own secrets to sessionSecret, encryptionSecret and sharedsecret_secret. Please note that the length of sessionSecret and encryptionSecret must be exactly 16, 24 or 32 bytes to select AES-128, AES-192 or AES-256.

You need to choose a free port in case the default port defined in listen 8090 is not free.

The relevant settings are listed below, please search for these config options in your config file and adapt appropriately.

The turnURIs and turnSecret options require a TURN server to be setup or to be present on a different machine. For a local LAN setup you should be able to test without, so the turnURIs parameter is optional. If you use the Kopano TURN service then you don’t need to set turnURIs and turnSecret (Kopano TURN service is configured in the Kopano webmeetings WebApp plugin).

Please edit the following items in the webmeetings.cfg in addtion to what is already in there:

[http]
; HTTP listener in format ip:port.
listen = 127.0.0.1:8090
; Full path to directory where to find the server web assets.
root = /usr/share/kopano-webmeetings/www
...
; Use basePath if the server does not run on the root path (/) of your server.
basePath = /webmeetings

[app]
;turnURIs = turn:turnserver:port?transport=udp
;turnSecret = the-default-turn-shared-secret-do-not-keep
sessionSecret = the-default-secret-do-not-keep-me
plugin = /webapp/plugins/spreedwebrtc/php/AngularPluginWrapper.php
encryptionSecret = the-default-encryption-block-key
...
authorizeRoomJoin = true
authorizeRoomCreation = true

[users]
enabled = true
mode = sharedsecret
sharedsecret_secret = TopSecretReplaceAndEnterTheSameInTheWebAppPluginConfigPHP

Restart the kopano-webmeetings server:

service kopano-webmeetings restart

Important

Make sure the port configured in the listen property is available and not blocked by a different service. If you change the port in the listen property, then you will need to adapt it in the proxy_pass setting for / in the NGINX configuration.

Important

Make sure you use the same shared secret you configured in sharedsecret_secret in kopano-presence and in the WebApp plugin. See the respective following sections.

Important

The value of sessionSecret and encryptionSecret should each have their own individual hex encoded string value. Their length must be exactly 16, 24 or 32 bytes to select AES-128, AES-192 or AES-256. You can generate a secret easily with xxd -ps -l 32 -c 32 /dev/random

3.1.4. Configuring kopano-presence¶

Please configure the kopano-presence service settings in /etc/kopano/presence.cfg.

plugins = spreed

Please configure the shared secret in /etc/kopano/presence.cfg in the server_secret_key property. This should be the same as the one configured in kopano-webmeetings.

server_secret_key = TopSecretReplaceAndEnterTheSameInTheWebAppPluginConfigPHP

You will need to add and activate the apache modules proxy and proxy_http:

a2enmod proxy
a2enmod proxy_http

Please configure a proxy pass entry in the kopano-webapp apache2 sites-available file for the kopano-presence service. Edit the file /etc/apache2/sites-available/kopano-webapp.conf and add the ProxyPass and ProxyPassReverse config lines below and ensure that the port number matches the port configured in /etc/kopano/presence.cfg.

Alias /webapp /usr/share/kopano-webapp
ProxyPass /webapp/presence http://localhost:1234/
ProxyPassReverse /webapp/presence http://localhost:1234/

Restart apache2

service apache2 restart

3.1.5. Configuring kopano-webmeetings WebApp plugin¶

Please configure the kopano-webmeetings powered by Spreed.WebRTC WebApp plugin. The recommended setup is that webapp and webmeetings are running behind the same NGINX host and webmeetings below the /webmeetings/ URL path. In this case no changes are required to PLUGIN_SPREEDWEBRTC_SPREED_URL. In this case PLUGIN_SPREEDWEBRTC_SPREED_DOMAIN and PLUGIN_SPREEDWEBRTC_WEBAPP_DOMAIN remain empty.

Edit /etc/kopano/webapp/config-meetings.php and make the following changes (set PLUGIN_SPREEDWEBRTC_USER_DEFAULT_ENABLE to true and set PLUGIN_SPREEDWEBRTC_WEBMEETINGS_SHARED_SECRET to your secret from webmeetings.cfg and assign your own secrets to PLUGIN_SPREEDWEBRTC_WEBAUTH_CODE_TOKEN_SECRET and PLUGIN_SPREEDWEBRTC_WEBAUTH_ACCESS_TOKEN_SECRET):

DEFINE('PLUGIN_SPREEDWEBRTC_USER_DEFAULT_ENABLE', true);

DEFINE('PLUGIN_SPREEDWEBRTC_SPREED_DOMAIN', '');

DEFINE('PLUGIN_SPREEDWEBRTC_SPREED_URL', '/webmeetings/');

DEFINE('PLUGIN_SPREEDWEBRTC_WEBAPP_DOMAIN', '');

DEFINE('PLUGIN_SPREEDWEBRTC_WEBMEETINGS_SHARED_SECRET', 'TopSecretReplaceAndEnterTheSameInTheWebAppPluginConfigPHP');

DEFINE('PLUGIN_SPREEDWEBRTC_WEBAUTH_CODE_TOKEN_SECRET', 'the-default-secret-do-not-keep-me');

DEFINE('PLUGIN_SPREEDWEBRTC_WEBAUTH_ACCESS_TOKEN_SECRET', 'the-default-secret-do-not-keep-me');

Important

Upgrading from kopano-webmeetings WebApp plugin version 1.0 to 1.1: please take note, that the PLUGIN_SPREEDWEBRTC_WEBAPP_URL, PLUGIN_SPREEDWEBRTC_WEBAUTH_CODE_TOKEN_SECRET and PLUGIN_SPREEDWEBRTC_WEBAUTH_ACCESS_TOKEN_SECRET settings are new and require configuration. Please backup your configuration files, install the latest configuration files from the package and merge your settings.

If WebApp and Web Meetings are not running behind a common NGINX host, you will need to make further settings to PLUGIN_SPREEDWEBRTC_SPREED_DOMAIN and PLUGIN_SPREEDWEBRTC_WEBAPP_DOMAIN.

Important

Please note that this kind of distributed setup limits the available features, such as screen sharing.

Set the Spreed Base URL, which will be your server URL. If you server doesn’t yet have a DNS entry you can use an IP in the URL like https://212.234.234.234. In general these are the URLs to call from the client browser in front of NGINX.

DEFINE('PLUGIN_SPREEDWEBRTC_SPREED_DOMAIN', 'https://webmeetings.example.com');

DEFINE('PLUGIN_SPREEDWEBRTC_SPREED_URL', '/webmeetings/');

DEFINE('PLUGIN_SPREEDWEBRTC_WEBAPP_DOMAIN', 'https://webapp.example.com');

You need to configure the shared secret for the kopano-presence service in PLUGIN_SPREEDWEBRTC_PRESENCE_SHARED_SECRET:

DEFINE('PLUGIN_SPREEDWEBRTC_PRESENCE_SHARED_SECRET', 'TopSecretReplaceAndEnterTheSameInTheWebAppPluginConfigPHP');

To simplify your setup Kopano provides a TURN service. Please fill out the form at https://portal.kopano.com/content/turn-server-access-request to obtain your personal credentials. To enable the TURN service please set PLUGIN_SPREEDWEBRTC_TURN_USE_KOPANO_SERVICE to true. You enter the credentials supplied by Kopano in PLUGIN_SPREEDWEBRTC_TURN_AUTHENTICATION_USER and PLUGIN_SPREEDWEBRTC_TURN_AUTHENTICATION_PASSWORD:

DEFINE('PLUGIN_SPREEDWEBRTC_TURN_USE_KOPANO_SERVICE', true);
DEFINE('PLUGIN_SPREEDWEBRTC_TURN_AUTHENTICATION_URL', 'https://turnauth.kopano.com/turnserverauth/');
DEFINE('PLUGIN_SPREEDWEBRTC_TURN_AUTHENTICATION_USER', 'turn-server-account-provided-by-kopano');
DEFINE('PLUGIN_SPREEDWEBRTC_TURN_AUTHENTICATION_PASSWORD', 'turn-server-password-provided-by-kopano');

Restart Apache2

service apache2 restart

Important

Make sure you have the same shared secret in PLUGIN_SPREEDWEBRTC_WEBMEETINGS_SHARED_SECRET as in webmeetings.cfg.

Important

Make sure you have the same shared secret in PLUGIN_SPREEDWEBRTC_PRESENCE_SHARED_SECRET as in presence.cfg.

In the following table we summarize the shared secrets that must be defined or generated and in which configuration files and parameters they are located.

Table 3.1. Shared secrets used between the Kopano Web Meetings components

Component	config-meetings.php	webmeetings.cfg	presence.cfg
webmeetings session secret		sessionSecret
webmeetings encryption secret		encryptionSecret
webmeetings shared secret	PLUGIN_SPREEDWEBRTC_ WEBMEETINGS_SHARED_SECRET	sharedsecret_secret
presence shared secret	PLUGIN_SPREEDWEBRTC_ PRESENCE_SHARED_SECRET		server_secret_key
webauth code token shared secret	PLUGIN_SPREEDWEBRTC_ WEBAUTH_CODE_TOKEN_SECRET
webauth access tok en shared secret	PLUGIN_SPREEDWEBRTC_ WEBAUTH_ACCESS_TOKEN_SECRET