Customisations#
This section lists some customisations for Carbonio.
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.
-
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
-
Edit file
/opt/zextras/conf/nginx/template_custom/nginx.conf.web.http.default.template
to add the custom header. Search for thelocation
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"; }
-
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:
-
Become the
zextras
user# su - zextras
-
Go to the scripts directory
zextras$ cd /opt/zextras/libexec/scripts
-
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.