Ctrl+K
What do you think about our new Documentation Layout? Take the survey
Back to Documentation Hub

Customisations

Customisations#

This section lists some customisations for Carbonio. Directions to install Custom Fonts for Carbonio Docs has been moved to the Carbonio User Guides section.

NGINX Templates#

There are several reason why an administrator wants to customise NGINX, for example adding a custom header for internal audit. Editing the NGINX configuration file is not an option, because it will be overwritten during upgrades. The most viable option is to use a template made available by NGINX. In the remainder of this section we introduce some details about NGINX working, relevant for the customisations, then we show the procedure.

Two directories are used by NGINX to generate its initial configuration: files from /opt/zextras/conf/nginx/templates are processed and saved in /opt/zextras/conf/nginx/includes, which are then read and used during the everyday operations. To allow for custom changes, there is an additional directory, /opt/zextras/conf/nginx/template_custom, which contains files that override setting in the corresponding file in the templates directory.

In other words, whenever the configuration is read, if under the templates and templates_custom directories a file with the same filename is present, the one in the templates_custom directory is used.

This means that a user can not store preferences in a file with a custom filename, but must override the default nginx.conf.web.http.default.template template.

Custom Configuration

Now, to implement the configuration mentioned at the beginning of this section, the procedure is the following.

  1. Copy file over to the custom directory.

    # cp /opt/zextras/conf/nginx/templates/nginx.conf.web.http.default.template \
  /opt/zextras/conf/nginx/template_custom/nginx.conf.web.http.default.template

  2. Edit file /opt/zextras/conf/nginx/template_custom/nginx.conf.web.http.default.template to add the custom header. Search for the location directive to which you want to add the custom header and add the following line:

    proxy_set_header X-CUSTOM-Forwarded-For "audit@example.com";

    The resulting configuration would look similar to the following

    location = /
{
  if ($http_cookie !~ "ZM_AUTH_TOKEN=") {
      return 307 "/static/login/";
  }

proxy_set_header X-CUSTOM-Forwarded-For "audit@example.com";
}

  3. Restart the proxy system as the zextras user.

    zextras$ zmproxyctl restart

    NGINX will generate the configuration from the template files, then start.

Update of Customisations

When a customisation is operational, the template does usually not need any modification until the next update of NGINX. When updated NGINX packages are available, it is suggested to check for any changes in the default configuration, to find if any incompatible values has been introduced or if some directive has been removed, modified, or added. In case in the new packages the default template has changed, the differences must be reflected in the customised template, because otherwise the NGINX service may not start properly.

Remove the Customisations

To remove the customisation, simply remove the customised template and restart the proxy.

It is worth highlighting a few points:

  • Whenever a customised template is used, the processed file (the one in the includes directory will become an additional header that marks the configuration as being generated from a custom template and explains how to restore the default.

  • In the log file it will be written which template is picked up and to which file it is saved.

Add an Index to MariaDB#

When the number of e-mails grows to large numbers, it is possible to add an index to the MariaDB database that stores them, to speed up some routine operation that run periodically on Carbonio.

Indeed, Carbonio Backup’s Coherency Check and Carbonio Storage’s doCheckBlobs work by verifying if the hash of the files matches the one stored in the database and emit a warning if they differ, also providing the capability to replace the correct one for the Carbonio Backup.

To prevent and minimise any data loss in case an issue arises, both tasks operate on a subset of data and limit the number of items changed by filtering the data by mailbox_id and locator of the mail_item table.

Therefore, these two operations may become database-intensive and become very slow, to the point of slowing down the entire mailbox and become evident to all users.

Starting from Carbonio 23.1.0, there is the possibility to add an index to the locator field and therefore improving performance, by using a script that is shipped with Carbonio: simply execute it and you are done. The steps to add index to locator are:

  1. Become the zextras user

    # su - zextras

  2. Go to the scripts directory

    zextras$ cd /opt/zextras/libexec/scripts

  3. Execute the script:

    zextras$ perl -I. migrate20221110-AddIndexLocatorOnMailItem.pl

You are now done, from the MariaDB prompt you can check that the mail_item table now contains the new index.

MariaDB> SHOW INDEXES FROM mail_item;

+-----------+------------+------------------+--------------+--------------+-----------+-------------+----------+--------+------+------------+
| Table     | Non_unique | Key_name         | Seq_in_index | Column_name  | Collation | Cardinality | Sub_part | Packed | Null | Index_type |
+-----------+------------+------------------+--------------+--------------+-----------+-------------+----------+--------+------+------------+
| ...       |        ..  | ..               |           .. | ...          | .         |          .. |     .... | ...    | ...  | .....      |
| mail_item |          1 | i_locator        |            2 | locator      | A         |           2 |      255 | NULL   | YES  | BTREE      |
+-----------+------------+------------------+--------------+--------------+-----------+-------------+----------+--------+------+------------+

Custom Fonts for Carbonio Docs#

On a Linux system, fonts are usually under directory /usr/share/fonts, and installing new font families usually is as simple as to use the package manager. For example, to install the Roboto fonts, use the command:

# apt-get install fonts-roboto

# dnf install fonts-roboto

To allow Carbonio Docs to access the fonts, first copy all the files:

# cp -Rf /usr/share/fonts/* /opt/zextras/docs/generated/systemplate/usr/share/fonts/

Then make sure that the owner of the whole fonts sub-tree is the user carbonio-docs-editor:

# chown -R carbonio-docs-editor:carbonio-docs-editor /opt/zextras/docs/generated/systemplate/usr/share/fonts/

Finally, restart the service.

# systemctl restart carbonio-docs-editor.service

Repeat the same steps on any Node on which Carbonio Docs is installed.

Contents