Carbonio Installation

This page provides hardware and software requirements for Carbonio and directions for its installation. Please review carefully this whole page before attempting to install.


System Requirements

Hardware requirements


Intel/AMD 64-bit CPU 1.5 GHz


8 Gb min, 16Gb recommended

Disk space (Operating system and Carbonio)

40 Gb

These requirements are valid for Carbonio Single-Server or for each Carbonio Node in a Multi-Server Installation and may vary depending on the size on the infrastructure, which includes the number of mailboxes and the functionalities running.

Supported Virtualization Platforms

VMware vSphere 6.x

VMware vSphere 7.x



Virtualbox (testing purposes only)

Software Requirements

Carbonio is available for 64-bit CPUs only and can be installed on top of any vanilla Ubuntu 20.04 LTS Server Edition or RHEL 8 installation and requires valid DNS resolution for

  • the domain (MX and A record)

  • the FQDN (A record)

See the dedicated box below for details and examples.

Support for other distributions will be announced in due course when it becomes available.

On RHEL 8, make sure you also have :

  • an active subscription (you must be able to fetch from BaseOS and the other main repositories)

Configuring DNS resolution

To make sure that the DNS is correctly configured for both A and MX records: to do so, you can use any DNS resolution server, including dnsmasq, systemd-resolved, and bind.

We show as an example, only suitable for demo or testing purposes, how to install and configure dnsmasq for DNS resolution.

Example: Set up of dnsmasq

Follow these simple steps to set up dnsmasq on your testing environment.


On Ubuntu 20.04, installing and running dnsmasq may raise a port conflict over port 53 UDP with the default systemd-resolved service, so make sure to disable the latter before continuing with the next steps.

# apt install dnsmasq
# dnf install dnsmasq

To configure it, add the following lines to file /etc/dnsmasq.conf:


Finally, restart the dnsmasq service

# systemctl restart dnsmasq

Single-Server Installation

The installation on Ubuntu 20.04 or RHEL 8 is organised in steps, some of which are preliminary configuration tasks, and some is optional. During the installation and configuration of Carbonio, it is necessary to execute commands from the command line, so make sure you have access to it.

We remark that, unless differently stated, all CLI commands must be run as the root user.

Step 1: Setting Hostname

Carbonio needs a valid FQDN as hostname and a valid entry in the /etc/hosts file. To configure them, execute these two commands. First, set the hostname

# hostnamectl set-hostname mail.carbonio.local

then update /etc/hosts

# echo " mail.carbonio.local mail" >> /etc/hosts


Replace with the actual management IP to be assigned to the server.


Step 2: Repository Configuration and System Upgrade

Instructions for setting up Carbonio repository will be provided by Zextras Sales Department.

Step 3: Installation and Configuration of Carbonio

The installation of Carbonio requires to run the command

# apt install service-discover-server \
carbonio-directory-server \
carbonio-proxy \
carbonio-webui carbonio-files-ui \
carbonio-chats-ui \
carbonio-admin-login-ui \
carbonio-mta \
carbonio-mailbox-db \
carbonio-appserver carbonio-logger \
carbonio-advanced carbonio-zal \
carbonio-user-management \
carbonio-files carbonio-files-db \
carbonio-preview \
carbonio-docs-connector-ce carbonio-docs-editor \
pgpool2 postgresql-12-pgpool2
# dnf install service-discover-server \
carbonio-directory-server \
carbonio-proxy \
carbonio-webui carbonio-files-ui \
carbonio-chats-ui \
carbonio-admin-login-ui \
carbonio-mta \
carbonio-mailbox-db \
carbonio-appserver carbonio-logger \
carbonio-advanced carbonio-zal \
carbonio-user-management \
carbonio-files carbonio-files-db \
carbonio-preview \
carbonio-docs-connector-ce carbonio-docs-editor \
pgpool2 postgresql-12-pgpool2

Post Installation tasks

Step 4: Set up PostgreSQL and Pgpool-II


This step is optional, but strongly suggested.

PostgreSQL database is used by Carbonio and, to improve connection efficiency and resource consumption, we set up Pgpool to work with PostgreSQL.

First, modify the port on which PostgreSQL listens for connections.

# vi /etc/postgresql/12/main/postgresql.conf
# port = 5433
# systemctl stop postgresql

Next, configure pgpool to use PostgreSQL’s port.

# echo "backend_clustering_mode = 'raw'
# port = 5432
# backend_hostname0 = ''
# backend_port0 = 5433" > /etc/pgpool2/pgpool.conf

Finally, restart both services using this single command.

# systemctl restart pgpool2.service

Step 5: Bootstrap Carbonio

Once all packages have been installed and the PostgreSQL user and database for Carbonio Files have been setup, use the following command to configure and launch Carbonio.

# carbonio-bootstrap

Before finalising the bootstrap, press y to apply the configuration. The process will continue until its completion: click Enter to continue.

What does carbonio-bootstrap do?

This command makes a few checks and then starts the installation, during which a few messages are shown, including the name of the log file that will store all messages produced during the process:

Operations logged to /tmp/zmsetup.20211014-154807.log

In case the connection is lost during the installation, it is possible to log in again and check the content of that file for information about the status of the installation. If the file does not exist anymore, the installation has already been completed and in that case the log file can be found in directory /opt/zextras/log.

The first part of the bootstrap enables all necessary services and creates a new administrator account (zextras@carbonio.local), initially without password (see below for instruction to set it).

Step 6: Setup Carbonio Mesh

Carbonio Mesh is required to allow communication between Carbonio and ts components. The configuration is automatically generated by command

# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!


Replace My_Mesh_Password£0! with a robust password of your choice.

This command will:

  • find the hostname IP address (hostname -i)

  • set the cluster credential password to My_Mesh_Password£0!, which is used for setups, management, and to access the administration GUI. See section Carbonio Mesh Administration Interface for more information.

  • store the setup in file /etc/zextras/service-discover/cluster-credentials.tar.gpg


    Make sure to store the password in a safe place (like e.g., a password manager). In case the password is lost or the credential file becomes corrupted and unusable, you can Regenerate Carbonio Mesh Credentials.

Complete Carbonio Mesh and Carbonio setup by running

# pending setups

Step 7: Configure Carbonio Databases

Carbonio relies on a number of databases to store and keep track of all the objects it needs to manage, therefore it is necessary to create and configure all of them using these commands. First, become the postgres users and start psql.

# sudo -u postgres psql

Then run the following command in order to create roles, database, and grant appropriate access rights.

# CREATE ROLE "carbonio-files-adm" WITH LOGIN SUPERUSER encrypted password 'My-Files-pwd01$'
# CREATE DATABASE "carbonio-files-adm" owner "carbonio-files-adm"
# CREATE ROLE "powerstore" WITH LOGIN encrypted password 'My-PowerStore-pwd98%'
# CREATE DATABASE "powerstore" owner "powerstore"
# CREATE ROLE "activesync" WITH LOGIN encrypted password 'My-Sync-pass-_#4'
# CREATE DATABASE "activesync" owner "activesync"
# CREATE ROLE "abq" WITH LOGIN encrypted password 'My_AbQ-psw]4<'
# CREATE DATABASE "abq" owner "abq"
# \q


Make sure to use different passwords for each role.

Remember to replace all passwords with robust passwords of your choice and store them in a safe place (preferably using a password manager), as you might need them in the future.

Step 8: Bootstrap Database of Carbonio Files

The final steps is to bootstrap Carbonio Files's DB (replacing the example password My_Mesh_Password£0! with the chosen one):

# PGPASSWORD=My_Mesh_Password£0! carbonio-files-db-bootstrap carbonio-files-adm

Step 9: Carbonio VideoServer and video recording

Carbonio VideoServer is Carbonio component that provides video-conferencing and video-recording functionalities to Carbonio Chats. Since it is not installed by default, you need to install it separately.

# apt install carbonio-videoserver carbonio-videoserver-recorder
# dnf install carbonio-videoserver carbonio-videoserver-recorder

Once the package has been successfully installed, you will be asked for the public IP Address of Carbonio VideoServer: enter it, then execute the following commands to start the service.

# systemctl enable videoserver.service
# systemctl start  videoserver.service

Finally, the following commands enable video recording and must be executed as the zextras user.

# su - zextras
# zxsuite chats video-server add port 8100 servlet 8090 secret MY_Video-ReC-pass7=6
# zxsuite config set global teamVideoServerRecordingEnabled true
# zxsuite config set cos default teamChatEnabled true

Here, port 8100 is the default port used by Carbonio VideoServer, while 8100 for recording. Change these values according to your needs or preferences. Remember also to replace with your domain name.

In case you forget the password used for the video recording setup, (MY_Video-ReC-pass7=6), you can retrieve it using this command.

# grep -i -e nat_1_1 -e api_secret /etc/janus/janus.jcfg

For information about Carbonio VideoServer, advances settings, and recording options, refer to Section Carbonio VideoServer.

Step 10: JDBC Configuration

We are reaching the end of the installation. This is the last configuration step which will set up the JDBC connections with PostgreSQL.

# zxsuite config set global powerstoreMetadataDb '{"url":"jdbc:postgresql://","user":"powerstore","password":"My-PowerStore-pwd98%"}'
# zxsuite config set global activeSyncDb '{"url":"jdbc:postgresql://","user":"activesync","password":"My-Sync-pass-_#4"}'
# zxsuite config set global abqMetadataDb '{"url":"jdbc:postgresql://","user":"abq","password":"'My_AbQ-psw]4<"}'
# zxsuite mobile doRestartService module
# zxsuite powerstore doRestartService module

Step 8: Licence Activation

We are now on the last mile. To verify there is no dangling installation or configuration task, run:

# pending-setups

Finally, as the zextras user, activate Carbonio license, replacing TOKEN with your licence token.

# zxsuite core activate-license TOKEN

Installation Complete

At this point installation is complete and you can start using Carbonio and access its graphic interface as explained in section Access to the Web Interface.

If you need to access the administration interface, you need to create a system user with administrative access, a task explained in Create System User below.

Step 6. Change Password for System User (Optional)

In order to change the password used by the zextras@carbonio.local user for the Web access, log in to a shell terminal as the zextras user and execute these two commands. The first allows to switch to the zextras user, with the second you actually change the password.

# su - zextras
# zmprov setpassword zextras@carbonio.local newpassword

Make sure that newpassword meets good security criteria.

The zextras and zextras@carbonio.local users

There is a clear distinction between these two users, which are intended to execute different tasks:


This the unix account of the administrator and must be used to carry out administrative tasks from the command line.


This is the default administrator user to be used to access the Admin UI and manage Carbonio from the web interface.

Access to the Web Interface

To access Carbonio's Administration Console, point a supported browser to either of the URL below.

Since Carbonio uses SSL to allow access to the Administration Console, it is strongly suggested to install an SSL certificate. Please refer to Section Deploy an SSL certificate for installation of the certificate.

Multi-Server Installation

This section describes a Carbonio multi-server installation, that is, a Carbonio installation spread across multiple nodes, each with a precise and dedicated task.


In this suggested scenario we will set up a Carbonio multi-server environment, composed by five nodes as follows:

  1. A Directory-Server node, used to manage the configuration of the infrastructure and provisioning of users and domains

  2. An MTA node, that takes care of the transfer and forwarding of mail, including filtering and much more functions

  3. A Proxy node, which acts as a reverse proxy, centralizing access to mailboxes. It allows backend services (like e.g., mailbox servers) to be hidden from the public Internet

  4. Two Application nodes, one to be used as the actual Mailserver or to host other services, and one to be used as Logger node


    The Logger node must be unique within a Carbonio infrastructure!

In addition to the listed services, an additional functionality (Carbonio Mesh) adds fault detection and dynamic routing between components of the infrastructure.

While your set up may vary, it is important that you install on each node the packages that provide the service(s) you want to run to each node. As an example, you can have MTA and Directory-Server installed on the same node.

In our scenario, we use 5 nodes equipped with Ubuntu 20.04 LTS.


For each node, the single server’s Software Requirements are valid and apply for multi-server installation as well. Regarding the System Requirements, consider that by dividing the load on more nodes you may need less resources (although we recommend at least 4GB of RAM on each node). Moreover, make sure that both DNS resolution and the hostname are configured.


It is mandatory to configure the hostname, especially on the Directory-Server node, otherwise the services will not be able to bind to the correct address, leading to a disruption in Carbonio's functionality.

There are no additional requirements, just a few remarks:

  • Repositories: All packages required by a multi-server setup are available in the same repository as the single server installation, hence there is no need of further configuration.

  • Acquaintance with the use of CLI is necessary. All commands must be issued as the root user, unless stated otherwise.

  • Give meaningful names to the nodes. For example, call them,, and so on. Replace with your domain name.

Install packages

On each node, different packages should be installed.


The service-discover-server package must be installed on one node only, while on the other nodes only the agent is needed.

  • Directory-server node

    # apt install service-discover-server carbonio-directory-server
    # dnf install service-discover-server carbonio-directory-server
  • MTA node

    # apt install service-discover-agent carbonio-mta
    # dnf install service-discover-agent carbonio-mta
  • Proxy node

    # apt install service-discover-agent carbonio-proxy carbonio-webui
    # dnf install service-discover-agent carbonio-proxy carbonio-webui
  • Store node

    # apt install service-discover-agent carbonio-appserver
    # dnf install service-discover-agent carbonio-appserver
  • Logger node

    # apt install service-discover-agent carbonio-appserver carbonio-logger
    # dnf install service-discover-agent carbonio-appserver carbonio-logger

Configure Nodes

After the installation has successfully completed, it is necessary to bootstrap the Directory-Server node as the first task, because you need to LDAP bind password to configure the other nodes as well. Nonetheless, to save some time, you can start the bootstrap on the other nodes as well.

Log in to the Directory-Server node and execute the command

# carbonio-bootstrap

This command will execute a number of tasks and will set up the node. At the end, you will be prompted with a menu and, if you already configured the DNS, you only need to click y for confirmation.

Then you need to retrieve the LDAP bind passwords with command

# zmlocalconfig -s zimbra_ldap_password

Copy it because it is needed on the other nodes.

On all other nodes, execute the carbonio-bootstrap command and, on the menu click 1 to enter the Common Configuration. Here, you need the Directory-Server node hostname and the LDAP bind password. Click 2, and enter the Directory-Server node hostname, then 4 and enter the LDAP bind Password.

Once done, each node also requires a specific configuration based on role. By default, all the bind password are configured with the same credential.

  • MTA node: enter the password for amavis and postfix user

  • Proxy node: enter the password for nginx user

  • Store node: configure the MTA address

  • Logger node: configure the MTA address

The Logger node requires a specific configuration and setup that is described in section Logger Node Configuration.

At this point, the nodes have been configured and the installation has been completed.

It is however required to configure the services running on the nodes before actually finalise the installation and start using Carbonio: the two tasks needed are to Update Multi-Server SSH keys and to setup Carbonio Mesh, which is explained below.

Configure Carbonio Mesh

In order to configure Carbonio Mesh, execute the following command on the Directory-Server node.

# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!


Use a robust password of your choice.

The outcome of the previous command is a GPG key that you need to copy to all other nodes.

Assuming that you have nodes proxy, mta, store, and logger (see the Multi-Server example installation scenario, use the following commands, provided you use the correct hostname or IP address of the nodes.

# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg proxy:/etc/zextras/service-discover/cluster-credentials.tar.gpg

# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg mta:/etc/zextras/service-discover/cluster-credentials.tar.gpg

# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg store:/etc/zextras/service-discover/cluster-credentials.tar.gpg

# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg logger:/etc/zextras/service-discover/cluster-credentials.tar.gpg

Finally, log in to each nodes and run the command, making sure to use the same password used in the first step.

# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!

Complete Installation

To complete the installation, execute the following command On each server, which will make sure that all services can operate flawlessly.

# pending-setups

The command will open a short menu which lists all tasks and scripts that need to be executed. Select each one or click a to run all the scripts at once.

After all nodes have been configured, execute the following command on each node to enable Carbonio at startup.

# systemctl enable carbonio

Installation is now complete, you can access Carbonio‘s graphic interface as explained in section Access to the Web Interface.

Access to the Web Interface

The URLs to which to connect to are:

Carbonio upgrade

Carbonio does not need any installer, but whenever new versions are released, the repositories are updated and packages are available for installation along with the other system updates. Therefore, to upgrade Carbonio, first check for new packages:

# apt update
# dnf update

Then either

  • upgrade Carbonio packages only

    # apt install "carbonio-*"
    # dnf install "carbonio-*"


  • upgrade the whole system

    # apt upgrade
    # dnf upgrade


Even if you choose to upgrade only Carbonio, remember that you should keep the whole system up to date, because new system packages may contain security fixes or bug fixes.


Problem: Error in upgrading

In early Carbonio versions, up to 4.0.3 included, an error similar to the following one may arise during upgrades in both Single-Server or Multi-Server installations:

Preparing to unpack .../114-carbonio-core_4.0.5-1ubuntu1~focal_amd64.deb ...
Unpacking carbonio-core (4.0.5-1ubuntu1~focal) over (4.0.3-1ubuntu1~focal) ...
dpkg: error processing archive /tmp/apt-dpkg-install-GOKoug/114-carbonio-core_4.0.5-1ubuntu1~focal_amd64.deb (--unpack):
trying to overwrite '/opt/zextras/.mini_alue_ce', which is also in package carbonio-ce 4.0.3-1ubuntu1~focal
dpkg-deb: error: paste subprocess was killed by signal (Broken pipe)


Errors were encountered while processing:
E: Sub-process /usr/bin/dpkg returned an error code (1)

In this case, the error message stems from carbonio-ce package, but it may be related to any Carbonio package, for example carbonio-mta, carbonio-proxy, and so on. If this is the case, use the proper package name (instead of carbonio-ce) in the commands given below.


This is a known problem, fixed in 4.0.4, for which the following workaround exists: install package carbonio-ce (or the one that failed):

# apt install carbonio-ce

Make sure that the carbonio-core package is installed and is the latest version available:

# apt policy carbonio-core

The outcome of the command shows the available versions of a package and should include three asterisks (***) before the latest available version. If not, install the package:

# apt install carbonio-core

Once installed, if a message appears, that some packages are not needed anymore, execute:

# apt autoremove

It is worth noticing that the manual installation of the package does not have any effect on its existing configurations, so you can proceed without any fear to lose them.