Carbonio Email Service provider

Have a Question?

An example of external service integration is a cluster connecting with a database instance hosted by a third-party service provider. Carbonio Mesh is utilised in Carbonio deployments such as this one.

Scenarios and requirements
  • Our sample scenario is a Carbonio Multi-Server system, which includes:
  • One or more Carbonio File Nodes.
  • One node in the cluster (potentially distinct from the Carbonio Files Nodes) is designated as the terminating gateway.
  • Carbonio Files uses a PostgreSQL database, which can be either
  • A server outside of the Carbonio system.
  • hosted remotely by a third-party supplier.

The setup requires access to the command line on the terminating gateway to configure it, as the process includes manual file editing and command execution, while some instructions at the conclusion of the procedure require connection to the database node.

Finally, keep the cluster credential password handy, as it is necessary for token creation.

Let’s get started by setting up Carbonio Mesh first, followed by Carbonio Files installation.

Security and Setup

There are a few tasks to do during the first setup.

  • Create a dedicated user.
  • Define policies. It is required to notify Carbonio Mesh of the services to be routed, which in our case is Carbonio Files’ database, carbonio-files-db.
  • First, establish a directory to contain all of the settings.
  • Then, modify the file /etc/carbonio/gateway/service-discover/policies.json and insert this text into it.
  • Finally, have the consul take up the new policy.
  • Export a new bootstrap token, which allows you to run consul commands and use its APIs. To extract the bootstrap token, run the following command and provide the cluster credential password.
  • Create a new token that is connected with the policy and will be the only one used to communicate with the external database.
Definition of the External Service.

To function effectively, the terminating gateway must be aware of the exact location of the remote service. As a result, we describe both the external service and how the terminating gateway may contact it, as well as provide Carbonio Files nodes access.

There is currently no CLI command for this, but we can utilise the APIs for this purpose. Create the file /etc/carbonio/gateway/service-discover/carbonio-files-db-external.json with content.

Then, send a curl request to register the external service.

Services Routing

Now that the terminating gateway and service have been established and registered, let Carbonio Mesh know which services can utilise the gateway.

To do so, add the following text to the file /etc/carbonio/gateway/service-discover/gateway-config.hcl, which identifies a carbonio-gateway as the terminating gateway for the carbonio-files-db service.

The above file has two commented items, which are optional and may not be mentioned at all in the configuration.


A dedicated SSL certificate for the service. This is normally unnecessary, unless a highly particular and intricate situation is put up. Indeed, consul is in charge of encrypting all traffic between nodes and with external resources: services and clients communicate with consul via localhost, therefore it is safe for them to communicate in plain text. Data received from consul on localhost is instantly SSL encrypted before leaving the node.


Server Name Indication is an additional layer of security on top of TLS that prevents name mismatches. In the common case where a single web server hosts multiple domains, each with its own SSL certificate, when a client request is received, the web server may not yet know which domain the client is attempting to access because the HTTPS TSL/SSL handshake occurs prior to the client sending the actual HTTP request for the domain. This may lead the client to obtain the incorrect certificate, thus terminating the secure connection. This difficulty is avoided by using an SNI, which allows the domain name to be sent directly during the SSL/TSL handshake.

Make sure you write the configuration by giving the following command:

At this moment, we are practically finished: The setup of Carbonio Mesh is now complete. Let’s now go over the final few chores.

Systemd Service

Now, develop a systemd unit to control whether the carbonio gateway is enabled or not, and hence whether access to the external database is permitted. Create and configure the file /lib/systemd/system/carbonio-gateway.service with the following content.

After saving the file, refresh systemd to make it aware of the new unit file, and then activate the new carbonio-gateway service.

Configuration of Carbonio-Files-DB

The carbonio-files-db-bootstrap script is often used to configure the database, including transferring the DB credentials to Carbonio Mesh and creating the databases. However, because the carbonio-files-db package is not installed, this job must be completed manually using the following instructions on the terminating gateway.

Configure the database name.

Configure username and password.

Now, we’ll log in to the database node and establish a postgres superuser. In this example, we assign password ScrtPsw987^2 to the user. Make sure you pick a strong password of your own.

First, log in as the postgres user and establish direct access to the database via the CLI client.

Then run the following instructions to create the user.

Exit the client after completing Carbonio Files Nodes Installation.

Carbonio Files installation differs differently from the typical Multi-Server configuration. Make certain that the carbonio-files-db package is not installed on any nodes following the installation. In our instance, the database capabilities are given by an external service rather than the package itself. To prevent problems, remove it.

Install the carbonio-files-ui package on each proxy node.

Install these packages on both nodes that will be used to execute Carbonio files. We recommend installing these on both Store Nodes.

Remove Services from Catalogue

When an external resource is no longer required, such as when a database is moved to the company’s data centre, the service configuration may be easily removed.

Stop the systemd unit service and remove the configuration file.

Remove the gateway configuration.

The carbonio-files-db package may now be installed on any node and made immediately available to Carbonio Files nodes.