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.

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 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, 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:

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

or

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

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.

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:

list is controlled by the allowed_languages setting, you can add or remove language tags as needed.
 de_DE en_GB en_US es_ES fr_FR it pt_BR pt_PT ru

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.

1
2
 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.