Collabora Online

Installation Guide

Collabora Productivity
Version 2021-05-30

Collabora Productivity Ltd. The Platinum Building, St John's Innovation Park, Cambridge, CB4 0DS, UK
Registered in England and Wales with company number 08644931
Telephone +44 (0)1223 362967 [email protected] https://www.collaboraoffice.com
Collabora Online Installation Guide

Table of Contents
ChangeLog.................................................................................................................................................4
Installation from packages..........................................................................................................................6
What is $customer_hash in the Following Text................................................................................6
How to Obtain $customer_hash if You are a Partner.......................................................................6
The Installation Procedure.....................................................................................................................6
Distro-specific Installation Instructions...................................................................................................6
Debian 9...........................................................................................................................................6
Debian 10.........................................................................................................................................7
Ubuntu 16.04....................................................................................................................................7
Ubuntu 18.04....................................................................................................................................7
Ubuntu 20.04....................................................................................................................................8
RHEL 7 / CentOS 7 (at least 7.2).....................................................................................................8
RHEL 8 / CentOS 8..........................................................................................................................8
SLES 15 / openSUSE Leap 15.x......................................................................................................8
How to upgrade......................................................................................................................................9
Localization.............................................................................................................................................9
Spelling dictionaries and thesauri...........................................................................................................9
Docker image...........................................................................................................................................10
Dockerfile..............................................................................................................................................10
Build Docker image..............................................................................................................................10
Create a container from the image and run it.......................................................................................10
Other optional environment variables that you can pass to collabora/online.................................10
Collabora Online for Kubernetes..............................................................................................................12
Helm chart for deploying Collabora Online in Kubernetes cluster.......................................................12
How to test this specific setup........................................................................................................12
Useful commands to check what is happening..............................................................................13
Notes..............................................................................................................................................13
Fonts.........................................................................................................................................................14
Updating ‘systemplate’.............................................................................................................................14
Configuration............................................................................................................................................15
User interface settings..........................................................................................................................15
Network settings...................................................................................................................................15
SSL configuration.................................................................................................................................16
Security settings...................................................................................................................................17
Backend storage configurations...........................................................................................................17
Logging.................................................................................................................................................17
Performance.........................................................................................................................................17
Allowed dictionary languages...............................................................................................................18
Admin Console.....................................................................................................................................18
Other settings.......................................................................................................................................18
Proxy settings...........................................................................................................................................19
Reverse proxy with Apache 2 webserver.............................................................................................19
Configure Collabora Online............................................................................................................19
Required Apache2 modules...........................................................................................................19
Reverse proxy settings in Apache2 config (SSL)...........................................................................19
Reverse proxy settings in Apache2 config (SSL termination)........................................................21
Reverse proxy with Nginx webserver...................................................................................................21
Load balancing.....................................................................................................................................23
Load balancing example with HAProxy..........................................................................................23
Load balancing example with Nginx...............................................................................................24

2
robots.txt...............................................................................................................................................25

3
Collabora Online Installation Guide

ChangeLog
Date Change

2016-07-04 Initial revision

2016-07-22 Security warning: WOPI host and WOPI client (loolwsd) should not run on the same domain.

2016-08-05 Removed ownCloud section (moved to a separate document), switch to Collabora Office 5.1.

2016-08-12 Rephrased instructions in Installation from Packages section.

2016-09-21 New SSL configuration section.

2016-09-26 Typo fixes in repo URLs, Apache2 reverse proxy setting update, HAProxy config update.

2016-10-12 HAProxy better explained, fixed typos in repo URLs.

2016-11-15 Typo fixes. In Cent OS 7 section note that Cent OS 7.2 is required. In Apache2 reverse proxy section:
ProxyPreserveHost On.

2016-11-23 Apache2 reverse proxy config updated.

2016-12-07 Collabora Online 2.0 released, logging settings changed.

2017-05-02 Collabora Online 2.1 released.

2017-05-09 Instructions added to create self-signed SSL certificate.

2017-06-01 Removed unsupported openSUSE versions. Clarification: Docker is an alternative to packages. Mentioned
loolconfig for setting up secure password for the Admin Console.

2017-06-13 Fixed wrong HAProxy configuration sample.

2017-07-12 Document loolwsd-systemplate-setup script

2017-08-22 Added support for Debian 9, RHEL 6 / CentOS 6, and SLES11 SP4

2017-09-12 Added a chapter about installing fonts. Added a note about fonts to Docker chapter. Mentioned the trigger
that updates systemplate upon updating of other packages. Added a section about Nginx reverse proxy.

2017-09-22 Added "Other optional environment variables that you can pass to collabora/code" section.

2017-10-25 Added a section about Nginx load balancer

2017-11-01 Load balancer config corrections

2018-01-15 Added a footnote about binding to privileged ports

2018-01-31 Collabora Online 3.0 released. New sections: Localization, Spelling dictionaries and thesauri, Hiba: A
hivatkozás forrása nem található, Allowed dictionary languages. Admin console authentication supports
PAM. SSL cipher list. IPv6 support.

2018-02-15 Add hint about robots.txt

2018-04-25 Document seccomp and capabilities security settings. Added a note about the necessity of using the same
version on all load balanced nodes. Ubuntu 18.04 is supported.

2018-05-10 Ubuntu 18.04 repositories

2018-05-11 Use of internal dictionaries is possible now

2018-09-12 Apache2 reverse proxy config for the SSL termination case

4
ChangeLog

Date Change

2018-10-10 Document net.listen and net.service_root settings (new in 3.4)

Document dictionaries environment variable for docker image.

2019-02-11 Added /hosting/capabilities to reverse proxy settings.

2019-02-14 Collabora Online 4.0 released. In repo URLs /3/ was changed to /4.2/.
Documented extra_params environment variable for Docker.

2019-02-28 Collabora Online 4.0.1 released. SLE 11 SP4 support is discontinued. New package repository for SLE 15 /
openSUSE 15.x

2019-05-20 Made WOPISrc-based load balancing in HAproxy/Nginx script the default, as it is supported since 2.1.4.

2020-03-05 Collabora Online 4.2.0 released. Updated repo URLs.

2020-05-03 How to upgrade section

Ubuntu 20.04 supported

2020-06-08 Corrected command to update the systemplate for Collabora Online 4.2

2020-07-06 Further adjusted command to update the systemplate

2020-07-21 Removed unnecessary step from installation instructions concerning SUSE systems

2020-11-04 Collabora Online 6.4.0 released. Updated repo URLs.

2020-11-22 New location of Dockerfiles and docker scripts:

https://github.com/CollaboraOnline/online/tree/master/docker

2020-11-29 Docker: bind mount requires --privileged flag

2021-05-12 Better HAProxy config

2021-05-21 Add Kubernetes chapter

2021-05-30 Use consistent hash in HAProxy config

5
Collabora Online Installation Guide

Installation from packages

Collabora Productivity provide signed binary packages for 64-bit Linux distributions. Currently Debian 8,
Debian 9, Debian 10, Ubuntu 16.04, Ubuntu 18.04, Ubuntu 20.04, RHEL 7 / CentOS 7, RHEL 8 /
CentOS 8, SLES 12, SLES 15 and openSUSE Leap 15.x are supported.

What is $customer_hash in the Following Text

In the following document, we use “$customer_hash” placeholder. Any time you will see it in the
instructions, please use the real ID that was provided to you by Collabora Productivity or their partner.
These URLs are customer-specific and must not be shared or disclosed.

The “$customer_hash” looks like “Example-413539ece39485afc35b4a469adfde0a279d2fd2” (this is not

a working example), and is specific to you.

How to Obtain $customer_hash if You are a Partner

If you are Collabora’s Partner, you can obtain the ID from the Partner portal. Just log into the Partner
portal at https://support.collaboraoffice.com/, and you will see this information in the form:

Collabora Online

Your secret URL key: Example-413539ece39485afc35b4a469adfde0a279d2fd2.

The Installation Procedure

On all the supported platforms, the installation procedure consist of three steps:

• Import of the signing key

• The installation itself
• Starting of the service, and enabling it for auto-start after reboot
The following chapter contains instructions for the supported Linux distributions. After you have installed
loolwsd (the Collabora Online’s websocket daemon), please continue with the chapter Configuration.

Distro-specific Installation Instructions

To install Collabora Office you need system administrator (root) privileges. The following command line
examples are supposed to be entered from a system administrator (root) account. Alternatively you can
use sudo.

export customer_hash=Example-413539ece39485afc35b4a469adfde0a279d2fd2

Debian 9
Please type the following commands into the shell as root:

# import the signing key

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 0C54D189F4BA284D

# add the repository URL to /etc/apt/sources.list

echo "deb https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-debian9-

$customer_hash ./" >> /etc/apt/sources.list

6
Installation from packages

# perform the installation

apt update && apt install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

Debian 10
Please type the following commands into the shell as root:

# import the signing key

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 0C54D189F4BA284D

# add the repository URL to /etc/apt/sources.list

echo "deb https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-debian10-

$customer_hash ./" >> /etc/apt/sources.list

# perform the installation

apt update && apt install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

Ubuntu 16.04
Please type the following commands into the shell as root:

# import the signing key

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 0C54D189F4BA284D

# add the repository URL to /etc/apt/sources.list

echo "deb https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-ubuntu1604-

$customer_hash ./" >> /etc/apt/sources.list

# perform the installation

apt update && apt install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

Ubuntu 18.04
Please type the following commands into the shell as root:

# import the signing key

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 0C54D189F4BA284D

# add the repository URL to /etc/apt/sources.list

echo "deb https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-ubuntu1804-

$customer_hash ./" >> /etc/apt/sources.list

# perform the installation

apt update && apt install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

7
Collabora Online Installation Guide

Ubuntu 20.04
Please type the following commands into the shell as root:

# import the signing key

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 0C54D189F4BA284D

# add the repository URL to /etc/apt/sources.list

echo "deb https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-ubuntu2004-

$customer_hash ./" >> /etc/apt/sources.list

# perform the installation

apt update && apt install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

RHEL 7 / CentOS 7 (at least 7.2)

Please type the following commands into the shell as root:

# import the signing key

wget https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-centos7-
$customer_hash/repodata/repomd.xml.key && rpm --import repomd.xml.key

# add the repository URL to yum

yum-config-manager --add-repo
https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-centos7-
$customer_hash

# perform the installation

yum install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

RHEL 8 / CentOS 8
Please type the following commands into the shell as root:

# import the signing key

wget https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-centos7-
$customer_hash/repodata/repomd.xml.key && rpm --import repomd.xml.key

# add the repository URL to yum

yum-config-manager --add-repo
https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-centos8-
$customer_hash

# perform the installation

yum install loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

SLES 15 / openSUSE Leap 15.x

Please type the following commands into the shell as root:

8
Installation from packages

# import the signing key

wget https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-opensuse15-
$customer_hash/repodata/repomd.xml.key && rpm --import repomd.xml.key

# add the repository URL to zypper

zypper ar -t yum "https://collaboraoffice.com/repos/CollaboraOnline/6.4/customer-

opensuse15-$customer_hash" "Collabora Online"

# perform the installation

zypper ref && zypper in loolwsd collabora-online-brand

After successful installation, please follow the chapter Configuration.

How to upgrade
If you are upgrading from Collabora Online 4.2x or earlier version, follow these steps:

1. Backup /etc/loolwsd/loolwsd.xml configuration file.

2. Remove loolwsd and collaboraoffice* packages.

3. Change the version number in the repository URL, e.g. from 4.2 to 6.4.

4. Install loolwsd package.

5. Restore /etc/loolwsd/loolwsd.xml configuration file.

Localization
For localization of tunnelled dialogs, you need to install Collabora Office language resources. They are
not direct dependencies of loolwsd. For example for German dialogs on Debian/Ubuntu:

apt install collaboraoffice*de*

Spelling dictionaries and thesauri

Collabora Online version 3.2.2 and higher can use internal spelling dictionaries and thesauri
(collaboraoffice*-dict-* packages). Collabora Online can use system spelling dictionaries and thesauri,
too, that are located in /usr/share/hunspell and /usr/share/mythes directories. See also: Allowed
dictionary languages

After successful installation, please follow the chapter Configuration.

9
Collabora Online Installation Guide

Docker image
As an alternative to native packages, Collabora Productivity provide scripts and Dockerfiles to create a
Collabora Online Docker image. You either need native packages, or the Docker image, not both!
Docker images can be created on demand from the latest version of Collabora Online and the
underlying system components. Please find everything in Collabora Online source code repository (on
GitHub).

https://github.com/CollaboraOnline/online/tree/master/docker

Dockerfile
The provided Dockerfile is a working sample. Feel free to add more packages to it, for example more
fonts, if you need them.

Build Docker image

Please follow the instructions in README of the above code location.

Create a container from the image and run it

You need to pass the domain name or IP address of your WOPI host in an environment variable.
Interactive mode:

docker run -t -i -p 9980:9980 -e "domain=your\\.wopihost\\.com" collabora/online

It will log to console.

Note: for the faster jail creation via bind mount (with Collabora Online 6.4 and higher), you need to use
docker run command with the --privileged flag.

Daemon mode:

docker run -t -d -p 9980:9980 -e "domain=your\\.wopihost\\.com" --restart always

collabora/online

You can follow logs with:

docker logs --follow <container name>

Read more about logging at https://docs.docker.com/engine/admin/logging/overview/.

Other optional environment variables that you can pass to collabora/online

username User name for the Admin Console
password Password for the Admin Console
When this environment variable is set (is not “”), then startup script will
DONT_GEN_SSL_CERT not generate a new SSL certificate signed by a dummy CA. It is useful,
if you want to use your own SSL certificate for some reason.
When this environment variable is set (is not “”), then startup script will
cert_domain generate a new SSL certificate signed by a dummy CA for this domain,
not for localhost
server_name When this environment variable is set (is not “”), then its value will be
used as server name in /etc/loolwsd/loolwsd.xml . Without this, CODE

10
Docker image

may not deliver a correct host for the websocket connection in case of
a proxy in front of it.
By default only limited set of spelling dictionaries and thesauri are
configured for Collabora Online, mainly for performance reasons. The
default set of languages is the following: de_DE en_GB en_US es_ES
fr_FR it nl pt_BR pt_PT ru. With the dictionaries environment variable
dictionaries
you can change this list. The dictionaries environment variable should
contain the space separated list of language codes (optionally followed
by country code). In order to save resources, it makes sense to load
only those dictionaries that are actually needed.
You can pass extra loolwsd command line parameter via this
environment variable. For example, if you want to start loolwsd without
SSL, when you test or develop, the syntax is: -e "extra_params=--
extra_params
o:ssl.enable=false" . To learn about all possible options, refer to the
self-documented /etc/loolwsd/loolwsd.xml configuration file in the
Docker image.

11
Collabora Online Installation Guide

Collabora Online for Kubernetes

In order for Collaborative Editing to function correctly on kubernetes, it is vital to ensure that all users
editing the same document end up being served by the same pod. Using the WOPI protocol, the https
URL includes a unique identifier (WOPISrc) for use with this document. Thus load balancing can be
done by using WOPISrc – ensuring that all URLs that contain the same WOPISrc are sent to the same
pod.

Helm chart for deploying Collabora Online in Kubernetes cluster

Yaml files available at https://github.com/CollaboraOnline/online/tree/master/kubernetes/helm/collabora-
online

How to test this specific setup

1. Install Kubernetes cluster locally - minikube - https://minikube.sigs.k8s.io/docs/

2. Install helm - https://helm.sh/docs/intro/install/

3. Install HAProxy Kubernetes Ingress Controller -

https://www.haproxy.com/documentation/kubernetes/latest/installation/community/kubernetes/

4. Prepare the namespace in local kubernetes cluster with this command:

kubectl create namespace collabora

5. Install helm-chart using below command:

helm install collabora-online ./kubernetes/helm/collabora-online/

6. Finally spin the collabora-online in kubernetes

A) HAProxy service is deployed as NodePort so we can access it with node’s ip address. To

get node ip
minikube ip
Example output:
192.168.0.106

B) Each container port is mapped to a NodePort port via the Service object. To find those ports
kubectl get svc –namespace=haproxy-controller
Example output:
|----------------|---------|--------------|------------|------------------------------------------|
|NAME |TYPE |CLUSTER-IP |EXTERNAL-IP |PORT(S) |
|----------------|---------|--------------|------------|------------------------------------------|
|haproxy-ingress |NodePort |10.108.214.98 |<none> |80:30536/TCP,443:31821/TCP,1024:30480/TCP |
|----------------|---------|--------------|------------|------------------------------------------|

In this instance, the following ports were mapped:

- Container port 80 to NodePort 30536
- Container port 443 to NodePort 31821
- Container port 1024 to NodePort 30480

C) Now in this case to make our hostname available we have to add following line into
/etc/hosts:
192.168.0.106 loolwsd.public.example.com

To check if everything is setup correctly you can run:

12
Collabora Online for Kubernetes

curl -I -H 'Host: loolwsd.public.example.com' 'http://192.168.0.106:30536/'

It should return a similar output as below:

HTTP/1.1 200 OK
last-modified: Tue, 18 May 2021 10:46:29
user-agent: LOOLWSD WOPI Agent 6.4.8
content-length: 2
content-type: text/plain

Useful commands to check what is happening

Where is this pods, are they ready?

kubectl -n collabora get pod

Example output:
NAME READY STATUS RESTARTS AGE
collabora-online-5fb4869564-dnzmk 1/1 Running 0 28h
collabora-online-5fb4869564-fb4cf 1/1 Running 0 28h
collabora-online-5fb4869564-wbrv2 1/1 Running 0 28h

What is the outside host that multiple loolwsd servers actually answering?

kubectl get ingress -n collabora

Example output:
|-----------|------------------|--------------------------|------------------------|-------|
| NAMESPACE | NAME | HOSTS | ADDRESS | PORTS |
|-----------|------------------|--------------------------|------------------------|-------|
| collabora | collabora-online |loolwsd.public.example.com| | 80 |
|-----------|------------------|--------------------------|------------------------|-------|

Notes
• If you wish to dive into advanced settings of kubernetes deployment feel free to update
values.yaml file to achieve that

• Don’t forget that you have to create the namespace (default is collabora) you specified in
collabora-online/values.yaml file

13
Collabora Online Installation Guide

Fonts
Collabora Online uses Collabora Office as its backend, which comes with a large variety of free fonts,
see the list below:

• Caladea and Carlito, which are metric-compatible with Cambria and Calibri

• Déja Vu

• Emoji One

• Gentium

• Google Open Sans and PT Serif

• Google Noto (full Unicode coverage)

• Karla

• Liberation Sans and Liberation Serif, which are metric-compatible with Arial and Times New
Roman

• Linux Libertine G

• Source Code Pro and Source Sans Pro

When you install loolwsd package, the post-install script will look for additional fonts on your system,
and install them for Collabora Online (in the systemplate). If you install fonts to your system after
installing loolwsd, you need to update the systemplate manually (see below).

Updating ‘systemplate’
Each document is isolated in its own chroot jail running its own instance of a LibreOfficeKit process,
and runs as a non-privileged ‘lool’ user. These chroot jails contain only the bare minimum of files
(libraries, fonts, etc.) needed for running Collabora Office (LibreOfficeKit). The template of the jails is
called ‘systemplate’, it is located at /opt/lool/systemplate, and it is generated after installation of the
loolwsd package. The systemplate is also re-generated after installing updates of packages that are in
use in systemplate (on RPM based systems) or after a successful apt update (on DEB based systems).

However, it is possible that the user wants to build systemplate manually, for example when new fonts
are installed, or a security update of system libraries is deployed by other means. Perform the following
command as root user.

In Collabora Online 6.4:

loolwsd-systemplate-setup /opt/lool/systemplate /opt/collaboraoffice6.4 >/dev/null

2>&1

In Collabora Online 4.2:

loolwsd-systemplate-setup /opt/lool/systemplate /opt/collaboraoffice6.2 >/dev/null

2>&1

In Collabora Online 4.0:

14
Updating ‘systemplate’

loolwsd-systemplate-setup /opt/lool/systemplate /opt/collaboraoffice6.0 >/dev/null

2>&1

Configuration
The postinstall script of loolwsd package added a non-privileged user to the system: lool. Collabora
Online service will be run by lool user. Also the service was registered to systemd, enabled on system
start and started. Useful commands:

• systemctl enable loolwsd – enable loolwsd on system start

• systemctl disable loolwsd – disable loolwsd on system start

• systemctl status loolwsd – check status of loolwsd

• systemctl stop loolwsd – stop loolwsd service

• systemctl start loolwsd – start loolwsd service

• systemctl restart loolwsd – stop then start loolwsd service

• journalctl -u loolwsd – read the log produced by loolwsd

Collabora Online has to be configured before use. Most of the options have sensible defaults.

Collabora online has layered configuration, which means that settings are read from
/etc/loolwsd/loolwsd.xml but can be overridden by command line switches (for example in systemd’s
loolwsd.service file). By using --o:name=value the setting called 'name' can be replaced by 'value'. For
example: --o:per_document.max_concurrency=12 . This will override the max_concurrency to 12,
regardless of what the XML has set.

Default configuration entries and values are set before loading the configuration file from disk. This
ensures that an upgrade to the server with new configuration entries will not break the server when the
XML is not upgraded, rather, the server will fallback to the defaults when it fails to find the entry in the
XML.

The loolwsd service has to be restarted after a change in configuration.

User interface settings

With Collabora Online 6.4 the systems administrator can set the “classic” menu + toolbar user interface
or the new “notebookbar” user interface. See the user_interface.mode setting in the configuration file.

Network settings
Collabora Online can use IPv4, IPv6 or both. By default it uses both. See the net.proto setting config
file.

From version 3.4 loolwsd server can bind to localhost only, which makes sense, when it is used behind
a reverse proxy. The corresponding setting is net.listen .

From version 3.4 it is possible to use a different service root than the toplevel. If the rules of your
organization do not permit running services in the root, you can use a subpath for it, like
https://example.org/IT/CollaboraOnline by setting /IT/CollaboraOnline as the net.service_root in the
configuration file.

15
Collabora Online Installation Guide

SSL configuration
Collabora Online uses WOPI protocol, which mandates SSL. However, it is possible to run Collabora
Online server without SSL, it is configurable. Basically there are 3 modes:

1. SSL

2. SSL termination

3. No SSL

When SSL is enabled, in /etc/loolwsd/loolwsd.xml the path to SSL key, SSL certificate and SSL CA
certificate has to be given in the ssl block. This also implies that it is recommended to run loolwsd from
a server which name is in DNS (e.g. hostname.example.com), and it has proper SSL certificate. Restart
loolwsd, check the status of the service, and if it is running, you can try if you can connect to it via SSL:

curl -v https://hostname.example.com:9980/hosting/discovery

If it fails, you have to debug SSL settings.

For testing purposes it is OK to use self signed certificates. Since Collabora Online 2.1 we no longer
ship self signed certificate for localhost, for security reasons. You can create the necessary files
yourself. The following example creates a certificate for hostname.example.com by a newly created
dummy certificate authority. The resulting .pem files are copied to default configuration directory of
loolwsd.

mkdir -p /opt/ssl/

cd /opt/ssl/

mkdir -p certs/ca

openssl genrsa -out certs/ca/root.key.pem 2048

openssl req -x509 -new -nodes -key certs/ca/root.key.pem -days 9131 -out
certs/ca/root.crt.pem -subj "/C=DE/ST=BW/L=Stuttgart/O=Dummy
Authority/CN=Dummy Authority"

mkdir -p certs/{servers,tmp}

mkdir -p "certs/servers/hostname.example.com"

openssl genrsa -out "certs/servers/hostname.example.com/privkey.pem" 2048 -key

"certs/servers/hostname.example.com/privkey.pem"

openssl req -key "certs/servers/hostname.example.com/privkey.pem" -new -sha256 -out

"certs/tmp/hostname.example.com.csr.pem" -subj
"/C=DE/ST=BW/L=Stuttgart/O=Dummy Authority/CN=hostname.example.com"

openssl x509 -req -in certs/tmp/hostname.example.com.csr.pem -CA

certs/ca/root.crt.pem -CAkey certs/ca/root.key.pem -CAcreateserial -out
certs/servers/hostname.example.com/cert.pem -days 9131

mv certs/servers/hostname.example.com/privkey.pem /etc/loolwsd/key.pem

mv certs/servers/hostname.example.com/cert.pem /etc/loolwsd/cert.pem

mv certs/ca/root.crt.pem /etc/loolwsd/ca-chain.cert.pem

The SSL termination option in the config file enables integration of Collabora Online with SSL
termination proxies, which handle incoming SSL connections, decrypt the SSL and pass on the
unencrypted request to the server. In this setup only the proxy server has to have proper SSL settings,

16
Configuration

Collabora Online server is hidden behind it, and Collabora Online communicates unencrypted with the
proxy.

If you set both enable and termination settings to false in /etc/loolwsd/loolwsd.xml , then Collabora
Online can be used in a HTTP-only environment, without encryption between browser and server. It is
not recommended to use Collabora Online in this mode, but for testing only it is OK.

You can set the list of accepted SSL ciphers with the cipher_list setting. The default cipher list is: ALL:!
ADH:!LOW:!EXP:!MD5:@STRENGTH .

Security settings
In Collabora Online 3.2 and higher, security settings are configurable due to popular demand. It is
allowed running without seccomp and capabilities. There are some significant security trade-offs here
which are now at least configurable. It is recommended to use the defaults. See the security section in
/etc/loolwsd/loowsd.xml .

Backend storage configurations

Currently there are two backend storages are implemented: file system and WOPI.

File system storage is disabled by default, and should not be used in production environment. It is
insecure by nature, because it serves any file that the lool user can read from the local file system,
including /etc/loolwsd/loolwsd.xml, /etc/passwd and so on. It can be used for testing only. To enable:

<filesystem allow=”true” /> in storage block of loolwsd.xml

or

--o:storage.filesystem[@allow]=true in command line

WOPI on the other hand is the recommended backend storage. WOPI is Web Application Open
Platform Interface, a protocol based on open standard for remote document access with authentication.
Collabora Online accepts connection requests only from trusted WOPI hosts. The administrator has to
list the host names and/or IP addresses of these trusted WOPI hosts in the storage.wopi block. Please
note that connection requests from the same machine are always accepted.

Logging
See the <logging> section in /etc/loolwsd/loolwsd.xml . Set the log level and verbosity to one of: none
(turns off logging), fatal, critical, error, warning, notice, information, debug, trace. The default log level is
warning. If <color> is set to true, then loolwsd will generate logging information containing console color
codes. It is possible to redirect logs to a file. The trace file defined in <trace> section provides extra
debug information.

Performance
There are two performance related settings.

One is num_prespawn_children. It is the number of child processes to keep started in advance and
waiting for new clients. More prespawn children consume more memory, but server answers more
quickly to requests under load. The default is 1.

The other is per_document.max_concurrency which limits the number of threads to use while
processing a document. The default here is 4.

17
Collabora Online Installation Guide

Allowed dictionary languages

When there are a lot of spellchecker dictionaries and thesauri installed on a system, it may take too
much time at startup to preload them. Therefore there is a limitation. By default only the following
languages are supported in Collabora Online 3.0 and higher:

de_DE en_GB en_US es_ES fr_FR it pt_BR pt_PT ru

This list is controlled by the allowed_languages setting, you can add or remove language tags as
needed.

Admin Console
You can do live monitoring of all the user sessions running on Collabora Online instance. The Admin
Console URL is: https://hostname:port/loleaflet/dist/admin/admin.html

Port is 9980 by default. It will ask for username and password which is set in the admin_console block
of /etc/loolwsd/loolwsd.xml or by --o:admin_console.username=username and
--o:admin_console.password=password in loolwsd command line. You must set username and
password. Admin Console is disabled if either of these are not set.

Note: in loolwsd 2.1.2 and higher it is possible to set up a password that is stored as salted hash in the
config file, instead of plain text. This is the recommended way to set up password for the Admin
Console. Use the loolconfig utility.

Note: in loolwsd 3.0 and higher there is support for authentication with PAM, if it is set up for loolwsd in
the system. For example, with a simple /etc/pam.d/loolwsd config below, the user which runs loolwsd
('lool' in production environment) can login to admin console with normal linux password.

auth required pam_unix.so

account required pam_unix.so

After entering the correct password you should be able to monitor the live documents opened, total
users, memory consumption, document URLs with number of users viewing that document etc. You can
also kill the documents directly from the panel which would result in closing the socket connection to the
respective document.

The admin-console front-end presents and fetches its data via a defined web socket protocol, which
can be used to collect information programatically to integrate with other monitoring and control
solutions. For the websocket protocol details of Admin Console, see the Admin Console section in the
protocol documentation:

https://cgit.freedesktop.org/libreoffice/online/tree/loleaflet/README and
https://cgit.freedesktop.org/libreoffice/online/tree/wsd/protocol.txt.

It is simple to subscribe to receive client notifications, query the open documents and change server
settings.

Other settings
See /etc/loolwsd/loolwsd.xml for other settings, everything is documented there.

18
Proxy settings

Proxy settings
Server part of Collabora Online (loolwsd daemon) is listening on port 9980 by default, and clients
should be able to communicate with it through port 9980. Sometimes it is not possible, for example a
corporate firewall can allow only ports of well known services, such as port 80 (HTTP) and port 443
(HTTPS). The loolwsd daemon is configurable. It can use other ports than 9980. Port can be set by the
command line option --port1 . However we cannot use for example port 443, when a web server is
running on the same server, which is already bound to port 443. Reverse proxy setup is also required,
when you would like to setup load balancing.

Reverse proxy with Apache 2 webserver

We assume that loolwsd and Apache2 are running on the same server: collaboraonline.example.com .
For this to work, you have to setup follow the steps below:

• Set the server name in Collabora Online configuration

• Enable the required Apache2 modules
• Add reverse proxy settings to Apache2 configuration file

Configure Collabora Online

Collabora Online configuration file is /etc/loolwsd/loolwsd.xml . Look for the setting server_name , which
is empty by default, and enter the host name here, for example collaboraonline.example.com . This is
necessary, because the proxy will redirect request to localhost . Answers from loolwsd server must
contain the original host name, otherwise the connection will fail.

Required Apache2 modules

Apache2 web server is modular. We need to enable the required modules for this reverse proxy setup.
We can use the a2enmod command to enable modules. If a module has been enabled already, nothing
happens.

• Enable proxy in general: a2enmod proxy

• Enable proxy for HTTP protocol: a2enmod proxy_http

• Enable SSL support: a2enmod proxy_connect

• Enable proxy of websockets: a2enmod proxy_wstunnel

On CentOS / RHEL there is no a2enmod available. Enabling the modules has to be done by adjusting
a config file and add the LoadModule oneself. (See here.)

Reverse proxy settings in Apache2 config (SSL)

These lines should be inserted into <VirtualHost> definition of the site.

########################################

# Reverse proxy for Collabora Online #

########################################

1 If you want to bind to a privileged port (below 1024), you need to add the following capability:
sudo setcap CAP_NET_BIND_SERVICE=+eip /usr/bin/loolwsd

19
Collabora Online Installation Guide

AllowEncodedSlashes NoDecode

SSLProxyEngine On

ProxyPreserveHost On

# cert is issued for collaboraonline.example.com and we proxy to localhost

SSLProxyVerify None

SSLProxyCheckPeerCN Off

SSLProxyCheckPeerName Off

# static html, js, images, etc. served from loolwsd

# loleaflet is the client part of LibreOffice Online

ProxyPass /loleaflet https://127.0.0.1:9980/loleaflet retry=0

ProxyPassReverse /loleaflet https://127.0.0.1:9980/loleaflet

# WOPI discovery URL

ProxyPass /hosting/discovery https://127.0.0.1:9980/hosting/discovery

retry=0

ProxyPassReverse /hosting/discovery https://127.0.0.1:9980/hosting/discovery

# Capabilities

ProxyPass /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities

retry=0

ProxyPassReverse /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities

# Main websocket

ProxyPassMatch "/lool/(.*)/ws$" wss://127.0.0.1:9980/lool/$1/ws nocanon

# Admin Console websocket

ProxyPass /lool/adminws wss://127.0.0.1:9980/lool/adminws

# Download as, Fullscreen presentation and Image upload operations

ProxyPass /lool https://127.0.0.1:9980/lool

ProxyPassReverse /lool https://127.0.0.1:9980/lool

20
Proxy settings

Reverse proxy settings in Apache2 config (SSL termination)

These lines should be inserted into <VirtualHost> definition of the site. Basically the configuration is the
same as above, but in this case we have HTTP-only connection between the proxy and the Collabora
Online server.

########################################

# Reverse proxy for Collabora Online #

########################################

AllowEncodedSlashes NoDecode

ProxyPreserveHost On

# static html, js, images, etc. served from loolwsd

# loleaflet is the client part of LibreOffice Online

ProxyPass /loleaflet http://127.0.0.1:9980/loleaflet retry=0

ProxyPassReverse /loleaflet http://127.0.0.1:9980/loleaflet

# WOPI discovery URL

ProxyPass /hosting/discovery http://127.0.0.1:9980/hosting/discovery

retry=0

ProxyPassReverse /hosting/discovery http://127.0.0.1:9980/hosting/discovery

# Capabilities

ProxyPass /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities

retry=0

ProxyPassReverse /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities

# Main websocket

ProxyPassMatch "/lool/(.*)/ws$" ws://127.0.0.1:9980/lool/$1/ws nocanon

# Admin Console websocket

ProxyPass /lool/adminws ws://127.0.0.1:9980/lool/adminws

# Download as, Fullscreen presentation and Image upload operations

ProxyPass /lool http://127.0.0.1:9980/lool

ProxyPassReverse /lool http://127.0.0.1:9980/lool

Reverse proxy with Nginx webserver

Add a new server block to your nginx config for collaboraonline.example.com.

21
Collabora Online Installation Guide

server {

listen 443 ssl;

server_name collaboraonline.example.com;

ssl_certificate /path/to/certficate;

ssl_certificate_key /path/to/key;

# static files

location ^~ /loleaflet {

proxy_pass https://127.0.0.1:9980;

proxy_set_header Host $http_host;

# WOPI discovery URL

location ^~ /hosting/discovery {

proxy_pass https://127.0.0.1:9980;

proxy_set_header Host $http_host;

# Capabilities

location ^~ /hosting/capabilities {

proxy_pass https://127.0.0.1:9980;

proxy_set_header Host $http_host;

# main websocket

location ~ ^/lool/(.*)/ws$ {

proxy_pass https://127.0.0.1:9980;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "Upgrade";

proxy_set_header Host $http_host;

proxy_read_timeout 36000s;

# download, presentation and image upload

location ~ ^/lool {

proxy_pass https://127.0.0.1:9980;

22
Proxy settings

proxy_set_header Host $http_host;

# Admin Console websocket

location ^~ /lool/adminws {

proxy_pass https://127.0.0.1:9980;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "Upgrade";

proxy_set_header Host $http_host;

proxy_read_timeout 36000s;

Load balancing
In order for Collaborative Editing to function correctly, it is vital to ensure that all users editing the same
document end up being served by the same Collabora Office instance. Using the WOPI protocol, the
https URL includes a unique identifier (WOPISrc) for use with this document. Thus load balancing can
be done by using WOPISrc – ensuring that all URLs that contain the same WOPISrc are sent to the
same Collabora Office instance.

Note: All load balanced nodes must run the same version of Collabora Online. Currently it is not
possible to run different versions on different nodes, e.g. upgrade Collabora Online on one node, and
leave the old version on another node. The WOPI discovery.xml served by Collabora Online through the
load balancer contains version specific URLs.

Load balancing example with HAProxy

In this example we will do load balancing between two Collabora Online server instances, which are
running in docker containers. Load balancing is based on WOPISrc URL parameter.

The browser reaches the proxy with HTTPS protocol. The proxy terminates the HTTPS connection and
passes traffic to backends via HTTP. Therefore in Collabora Online’s config file, in
/etc/loolwsd/loolwsd.xml , or in the command line which starts loolwsd daemon, SSL should be
disabled, and SSL termination should be enabled.

Let’s add the following blocks to /etc/haproxy/haproxy.cfg :

frontend loolwsd

bind *:443 ssl crt /path/to/your/certificate_and_key.pem

mode http

default_backend loolwsd

backend loolwsd

23
Collabora Online Installation Guide

timeout tunnel 3600s

mode http

balance balance url_param WOPISrc check_post

hash-type consistent

server loolwsd01 127.0.0.1:9993

server loolwsd02 127.0.0.1:9994

Start Docker containers as described above, with -p 127.0.0.1:9993:9980 and -p 127.0.0.1:9994:9980 .

Load balancing example with Nginx

Just like in the previous section (HAProxy), the Nginx load balancer also utilizes the WOPISrc URL
parameter. In this example SSL settings are managed by Certbot (see https://letsencrypt.org/). The load
balancer server listens on standard HTTPS port 443, and HTTP port 80 is redirected to HTTPS port
443. The loolwsd servers are reached through port 9980 directly (private network). The address for the
outside world (for WOPI hosts) is loolwsd.public.example.com.

upstream loolwsd {

zone loolwsd 64k;

hash $arg_WOPISrc;

server loolwsd1.private:9980;

server loolwsd2.private:9980;

server {

listen 80 default_server;

listen 443 ssl; # managed by Certbot

ssl_certificate /etc/letsencrypt/live/1b255632-ce4b-4581-9e80-
16f701c27034.pub.cloud.scaleway.com/fullchain.pem; # managed by Certbot

ssl_certificate_key /etc/letsencrypt/live/1b255632-ce4b-4581-9e80-
16f701c27034.pub.cloud.scaleway.com/privkey.pem; # managed by Certbot

include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot

if ($scheme != "https") {

return 301 https://$host$request_uri;

} # managed by Certbot

server_name loolwsd.public.example.com;

location / {

24
Proxy settings

proxy_pass http://loolwsd;

proxy_set_header Host $host;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

client_max_body_size 0;

robots.txt
When you use Collabora Online behind a reverse proxy, add Disallow: /loleaflet/* to your robots.txt file.

25