Configuration

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

systemctl enable coolwsd – enable coolwsd on system start
systemctl disable coolwsd – disable coolwsd on system start
systemctl status coolwsd – check status of coolwsd
systemctl stop coolwsd – stop coolwsd service
systemctl start coolwsd – start coolwsd service
systemctl restart coolwsd – stop then start coolwsd service
journalctl -u coolwsd – read the log produced by coolwsd

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/coolwsd/coolwsd.xml but can be overridden by command line switches (for example in systemd’s coolwsd.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 coolwsd 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.

With Collabora Online 21.11 the use of classic and notebookbar is deprecated , use compact for classic and use tabbed for notebookbar. See the user_interface.mode setting in the configuration file.

Overwrite mode

The overwrite_mode setting, when set to false, disables the overwrite mode making the insert key ineffectual. Setting it to false benefits user bases that don’t use this feature and might otherwise turn on the overwrite mode by mistake when pressing accidently the inder key.

Help url

Set the help_url to customize the root url of all help links. When set to empty all help buttons are hidden from dialogs.

Network settings

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

It is possible for a coolwsd server to bind to localhost only, which makes sense, when it is used behind a reverse proxy. The corresponding setting is net.listen.

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:

SSL
SSL termination
No SSL

When SSL is enabled, in /etc/coolwsd/coolwsd.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 coolwsd from a server which name is in DNS (e.g. hostname.example.com), and it has proper SSL certificate. Restart coolwsd, 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 coolwsd.

 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
 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/coolwsd/key.pem
 mv certs/servers/hostname.example.com/cert.pem /etc/coolwsd/cert.pem
 mv certs/ca/root.crt.pem /etc/coolwsd/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/coolwsd/coolwsd.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

Security settings are configurable, and coolwsd is allowed to run 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/coolwsd/coolwsd.xml.

Validating digital signatures

Collabora Online uses NSS (Mozilla’s Network Security Services) for validation of digital signatures. NSS comes with default configuration that includes a few trusted root CAs, but users may want to import their own trusted root CAs. The certificates.database_path configuration option in /etc/coolwsd/coolwsd.xml specifies the NSS certificate database that should be used with Collabora Online. This database should be readable by the coolwsd process. Custom root certificates can be imported into this database. For detailed instructions about creating NSS certificate database and importing certificates, please refer to the manual of the certutil tool, that is provided by mozilla-nss-tools, nss-tools or libnss3-tools package, depending on the Linux distribution.

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 cool user can read from the local file system, including /etc/coolwsd/coolwsd.xml, /etc/passwd and so on. It can be used for testing only. To enable:

in storage block of coolwsd.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/coolwsd/coolwsd.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 coolwsd 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 considerable time at startup to preload them. Therefore by default, only dictionaries for the following languages are enabled:

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*/browser/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/coolwsd/coolwsd.xml or by --o:admin_console.username=username and --o:admin_console.password=password in coolwsd command line. You must set username and password. Admin Console is disabled if either of these are not set.

Note: 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 coolconfig utility.

Note: there is support for authentication with PAM, if it is set up for coolwsd in the system. For example, with a simple /etc/pam.d/coolwsd config below, the user which runs coolwsd (‘cool’ 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://github.com/CollaboraOnline/online/blob/master/browser/README

and

https://github.com/CollaboraOnline/online/blob/master/wsd/protocol.txt .

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

Monitoring usage metrics

Collabora Online is capable of providing a wide variety of metrics related to system usage, eg. memory or CPU use, number of running kit processes or views in document sessions etc. The metrics can be retrieved in Prometheus-compatible format via the following URL:

https://*hostname*:*port*/cool/getMetrics

The URL uses the same authentication as the admin console. The available metrics are listed at: https://github.com/CollaboraOnline/online/blob/master/wsd/metrics.txt .

Feature Locking

Collabora Online provides a way to lock the user out from using certain features or make them read-only users. When a user clicks on a feature that is locked, the user will be prompted with a popup with details about unlocking. To disable any feature you can specify its UNO command in the locked_commands field. When a locked user is treated with read-only permission locked_commands option is ignored. Other related options can be found in coolwsd.xml. To mark a user locked, the WOPI client should return CheckFileInfo containing a field IsUserLocked with a boolean value. To make the locked users read-only set is_lock_readonly setting to true.

To allow/deny feature_lock per WOPI host:

<locked_hosts desc="Allow/deny feature-locked hosts. When allowed, the below host specification overrides the CheckFileInfo response." allow="true">
  <fallback desc="What to do if the given host is not covered by any rule in locked_hosts" read_only="true" disabled_commands="true"/>
  <host desc="Regex pattern of hostname to set as full-featured or locked." read_only="false" disabled_commands="false">pattern1</host>
</locked_hosts>

Please note that locked_hosts allow should be true to enable allow/deny feature_lock per WOPI host. If host pattern does not match for locked_host the fallback setting will be applied. This also overwrites the isUserLocked CheckFileInfo response.

Explaining all cases possible with above settings:
case-1: CheckFileInfo property isUserLocked is passed and locked_hosts’s allow=true then COOL will follow the locked_hosts settings i.e. if host is mentioned in locked_hosts then it will follow that settings else it will follow fallback settings
case-2: If is_lock_readonly is set to true COOL will make all the locked_host readonly who has disabled_commands set to true

Feature Restriction

Collabora provides a way to completely disable/hide certain features from the user. You can specify the feature’s UNO command to disable it in restricted_commands. To mark a user restricted, the WOPI client should return CheckFileInfo containing a field IsUserRestricted with a boolean value.

Multihost Configuration

To use multiple host and aliases with one COOL server you have to set alias_groups mode attribute to ‘groups’ and define group for each intergrator’s instance.

For example:

* If you have two hosts:

1. host1 has no aliases

2. host2 has aliases like aliasname1, aliasname2, aliasname3. For all these aliases regex would be aliasname[0-9]{1}.

<alias_groups desc="default mode is 'first' it allows only the first host when groups are not defined. set mode to 'groups' and define group to allow multiple host and its aliases" mode="groups">
<!-- If you need to use multiple wopi hosts, please change the mode to "groups" and
add the hosts below.  If one host is accessible under multiple ip addresses
or names, add them as aliases. -->

   <group>
      <host desc="hostname to allow or deny." allow="true">https://host1:443</host>
   </group>

   <group>
      <host desc="hostname to allow or deny." allow="true">https://host2:443</host>
      <alias desc="regex pattern of aliasname">https://aliasname[0-9]{1}:443</alias>
   </group>

   <!-- More "group"s possible here -->
</alias_groups>

You can add multiple groups. Here host1 and host2 can be any service COOL has integration with Available integrations.

Remote/Dynamic Configuration

The following new configuration makes it possible to:
Allow or deny WOPI host for single and multihost configuration i.e. alias_groups
Make WOPI host read-only or locked i.e. locked_hosts
Setting remote_font_config url
Customize unlock dialog

These changes can be now done without restarting Collabora server. Collabora server will request a JSON response to the remote server every 60 second and if there is new changes in JSON it will overwrite coolwsd.xml settings. Thus, adding the respective WOPI hosts and locked_hosts to the allow/deny list. The configuration will take effect the next time a document gets open.

Note: Collabora uses ETag header to identify whether the JSON is changed from last request or not. Therefore it is recommended to add ETag header in JSON response of remote server.

Note: With production versions only HTTPS protocol is allowed for security reasons.

Enable remote server configuration by adding url

<remote_config >
  <remote_url desc="remote server to which you will send request to get remote config in response" type="string" default="">https://server_url_endpoint</remote_url>
</remote_config>

JSON format

Configuration will be overwritten if JSON response has been changed

{
  "kind": "configuration",
  "remote_font_config":
  {
    "url": "https://.../fonts.json"
  },

  "storage":
  {
    "wopi":
    {
      "alias_groups":
      {
        "mode" : "groups",
        "groups":
        [
          { "host": "scheme://hostname:port", "allow": "true" , "aliases": ["scheme://aliasname1:port", "scheme://alias-regex-pattern:port”]},
        ]
      }
    }
  },

  "feature_locking":
  {
    "locked_hosts":
    {
      "allow":"true",
      "hosts":
      [
          { "host": "pattern1", "read_only": true, "disabled_commands": true },
          { "host": "pattern2", "read_only": false, "disabled_commands": true },
      ]
    },
    // unlock dialog customization
    "unlock_image": "https://<hostname>/static/<image_endpoint>",
    "translations":
      [
        {
          "language": "de",
          "unlock_title": "Gehen Sie zur Detailseite und entdecken Sie alle Funktionen:",
          "writer_unlock_highlights": "Überprüfen und schreiben Sie mit Leichtigkeit",
          "calc_unlock_highlights": "Machen Sie sich ein besseres Bild von Ihren Daten",
          "impress_unlock_highlights": "Bringen Sie Ihre nächste Präsentation auf den Punkt",
          "draw_unlock_highlights": "Zeichne und organisiere dich",
        },
        // more translations possible
      ]
  },
}

Please note that JSON response is checked every minute for changes. Every block in JSON is optional i.e. you can use any of the remote_font_config, storage, feature_locking JSON individually.

JSON config will overwrite values given in coolwsd.xml file i.e. groups tag will overwrite all host tags in wopi section. locked_hosts allow should be true to enable allow/deny feature_lock per WOPI host. If host pattern does not match for locked_host, the fallback setting will be applied. unlock_image and translations will overwrite respective xml:value pair in feature_locking section

Enable download and availability of more fonts by pointing to a font configuration file

<remote_font_config>
    <url desc="URL of optional JSON file that lists fonts to be included in Online" type="string" default="">https://someserver/path/file.json</url>
</remote_font_config>

Remote font configuration JSON format

The JSON file pointed to by the above should have contents like in this example

{
    "kind": "fontconfiguration",
    "server": "Some pretty name",
    "fonts": [
        {
            "uri": "https://somehost/path/f1.ttf"
        },
        {
            "uri": "https://someotherhost/path/f2.ttf",
            "stamp": "foo3"
        },
        {
            "uri": "https://whatever/path/x42.ttf"
        }
    ]
}

The JSON file is re-downloaded and scanned whenever it has changed. This is checked once a minute.

If an element in the fonts array has a stamp property then the font file will be re-downloaded and taken into use whenever the stamp has been changed. (And the old version of the font is forgotten.) The stamp can be any string, its contents is not interpreted in any way. The only thing checked is whether it changes. If no stamp property is provided, the web server in question is queried once a minute to check whether the font file has been updated.

The name of a font file is irrelevant. The name of the font is read from the contents of the file. The file should be a TrueType or OpenType font.

AutoSave settings

Since 24.04, by default, Cool saves documents that have unsaved changes every 5 minutes, and idle documents every 30 seconds. Saves are nearly instantaneous for users as saving is done out of the document process. This can be changed in /etc/coolwsd/coolwsd.xml, with the settings autosave_duration_secs and idlesave_duration_secs.

Other settings

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