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 CE, it is necessary to execute commands from the command line, so make sure you have access to it.


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 CE 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.

Installation on Other Linux Distributions

While they are not officially supported, Linux distributions compatible with Ubuntu 20.04 (e.g., Debian) and RHEL 8 (e.g., AlmaLinux, Rocky Linux) may be used as base OS for Carbonio CE, provided all dependencies can be satisfied. This may include adding third-party repositories or manually installing software packages.

The following requirements must be satisfied before attempting to install Carbonio CE.

  1. valid DNS resolution for both the domain (MX and A records) and the FQDN (A record)

  2. Python 3, latest version available on the Operating System chosen

  3. Perl, latest version available on the Operating System chosen

See the dedicated box below for details and examples.

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

Additional requirements

  • Acquaintance with the use of CLI is necessary. All carbonio commands must be executed as the zextras user (these commands will feature a zextras$ prompt), while all other commands must be issued as the root user, unless stated otherwise.

  • Commands or groups of commands may be different between Ubuntu and RHEL 8. This is shown by blue tabs: click on the tab of your choice to find the correct command.

  • When no such tabs are given, the commands to run are the same on Ubuntu and RHEL 8.

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 for demo or test environment

Follow these simple steps to set up dnsmasq. These instructions are suitable for a demo or testing environment only.


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:


Remember to replace the IP address with the one of your server. Then, make sure that the etc/resolv.conf contains the line:


This will ensure that the local running dnsmasq is used for DNS resolution. Finally, restart the dnsmasq service

# systemctl restart dnsmasq

RHEL 8-only Preliminary Tasks

A few task are required for the installation of Carbonio CE on RHEL 8 systems, they concern the configuration of SELinux, the firewall, and the installation and configuration of Postgres 12. Indeed, The version of Postgres shipped by RHEL 8 is older than required by Carbonio CE.


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

# subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms

The CodeReady repository enabled:

# subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms

The dedicated postgresql repository:

# yum -y install

SELinux and Firewall


Must be set to disabled or permissive in file /etc/selinux/config. You can check the current profile using the command

# sestatus

All the ports needed by Carbonio CE are open on the firewall or the firewall is disabled. To disable the firewall, issue the commands

# systemctl stop firewalld.service
# systemctl disable firewalld.service


We need to make sure that Postresql 12 is installed, by running commands

# dnf -qy module disable postgresql
# dnf -y install postgresql12 postgresql12-server

Then, initialise and enable it.

# /usr/pgsql-12/bin/postgresql-12-setup initdb
# systemctl enable --now postgresql-12

To complete the setup, edit file /var/lib/pgsql/12/data/pg_hba.conf, find the line:

# IPv4 local connections:
host    all             all               ident

remove the # before host if present and change it as follows:

# IPv4 local connections:
host    all             all               md5

To make sure the changes are picked up by Postgres, reload it.

# systemctl reload postgresql-12

Step 1: Repository Configuration

In order to add Carbonio CE’s repository, go to the following page and fill in the form:

You will receive an e-mail containing:

  • the URL of the repository

  • the GPG key of the repository

Follow the instructions in the e-mail to add these data to your system.

Repository and Channels

The following are important information concerning the packages repository Carbonio CE and its content. Please read them carefully, as they might save you some time in case of installation or upgrade problems and help you to provide more precise bug reports.

The repository hosts simultaneously packages of two channels:

  • Release Candidate (RC). Packages in this channel are made available as soon as they are built by Zextras development and tested by the QA team. While they are stable, they are not suitable for a use in a production environment, because they might still contain some bug, new functionalities that have not yet reached a production-level quality, or some broken dependencies might be introduced.

    Usually these problems are fixed within days or even hours, so in case just try again before you report some problem.

    Use this channel and its packages for testing (or demo) installations only.

  • RELEASE. This channel contains only packages that are stable and suitable for a production environment.


When reporting a problem or opening a ticket, remember to always add the channel if you are using, as this helps us to analyse the problem quickly.


  1. I want to help testing things, which channel should I use?

    RC channel.

  2. I need to install Carbonio in a production environment which channel should I use?

    RELEASE channel.

  3. How will we be informed about new RC packages?

    There will be no notification, because RC channel is updated continuously.

  4. How will we be informed about a potential new release incoming?

    A red message on the homepage of the documentation site will notify you of the release of a new stable version. You may also be informed through other means of communication such as email and social media.

  5. Could there be bugs in the packages downloaded from the RC channel?

    Yes, RC versions have a risk of containing bugs (which in some cases could lead to data loss). If you find a bug in an RC package we kindly ask you to report it on the appropriate community page. We will try to resolve it as quickly as possible.

Step 2: Setting Hostname

Carbonio CE 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

then update /etc/hosts with IP and hostname

# echo " mail" >> /etc/hosts

You can also simply get the current IP and hostname and save them:

# echo "$(hostname -I) $HOSTNAME.$DOMAIN"


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

Installation task

Step 3: System Upgrade and Package Installation

After configuring the repositories, the installation of Carbonio CE requires to run a few commands.

We start by updating and upgrading the system.

# apt update && apt upgrade
# dnf upgrade

Next, we install all packages needed for Carbonio CE.

# apt install service-discover-server \
carbonio-directory-server \
carbonio-proxy \
carbonio-webui carbonio-files-ui \
carbonio-mta \
carbonio-appserver carbonio-logger \
carbonio-user-management \
carbonio-files-ce carbonio-files-db \
carbonio-storages-ce \
carbonio-preview-ce \
carbonio-docs-connector-ce carbonio-docs-editor \
carbonio-admin-ui carbonio-admin-console-ui \
carbonio-admin-login-ui postgresql-12

The installation on RHEL is divided in two steps. First, install the Carbonio Mesh service

# dnf install service-discover-server

Then, proceed with all other packages

# dnf install carbonio-directory-server \
carbonio-proxy \
carbonio-webui carbonio-files-ui \
carbonio-mta  \
carbonio-appserver carbonio-logger  \
carbonio-user-management carbonio-preview-ce \
carbonio-files-ce carbonio-files-db \
carbonio-storages-ce \
carbonio-docs-connector-ce carbonio-docs-editor \
carbonio-admin-ui carbonio-admin-console-ui \

Post-Installation tasks

Step 4: Bootstrap Carbonio CE

Once all packages have been installed, use the following command to configure and launch Carbonio CE.

# 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 (, initially without password (see below for instruction to set it).

Configuration and Setup tasks

The next steps concern the configuration and setup of the various Carbonio CE components.

Step 5: Setup Carbonio Mesh

Carbonio Mesh is required to allow communication between Carbonio CE and its components. The configuration is interactively generated by command

# service-discover setup-wizard

This command will:

  • ask for the IP address and netmask

  • ask for the Carbonio Mesh secret, which is used for setups, management, and to access the administration GUI. See section Carbonio Mesh Administration Interface for more information.

    This password will be denoted as MESH_SECRET throughout the documentation.


    We suggest to use a robust password which is at least 16 characters long, including at least one of lowercase and uppercase letters, numbers, special characters and store it in a password manager.

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


    In case the password is lost or the credential file becomes corrupted and unusable, you can Regenerate Carbonio Mesh Secret.

To complete Carbonio Mesh installation, run

# pending-setups -a


The secret needed to run the above command is stored in file /var/lib/service-discover/password which is accessible only by the root user.

One final command is needed to fix access permission to Carbonio Mesh tokens.

# chmod a+r /etc/zextras/carbonio-mailbox/token

Step 6: Create Main DB Role and Database for Carbonio CE

Carbonio CE relies on a number of databases to store and keep track of all the objects it needs to manage. The main database can be configured in two steps, but if you are running Carbonio CE on RHEL 8, please first configure Postgres according to the guidelines.

The first step is to create a role with administrative rights and an associated password.

# su - postgres -c "psql --command=\"CREATE ROLE carbonio_adm WITH LOGIN SUPERUSER encrypted password 'DB_ADM_PWD';\""

Remember to replace the password with a robust password of your choice and store it in a safe place (preferably using a password manager), as you need it in the remainder of the procedure, and you also might need them in the future. This password will be denoted as DB_ADM_PWD.

The second step is to create the database.

# su - postgres -c "psql --command=\"CREATE DATABASE carbonio_adm owner carbonio_adm;\""

Step 7: Bootstrap Carbonio Files Databases

The password DB_ADM_PWD created in the previous step for the carbonio_adm role in database is required in this step, in which we configure the database of Carbonio Files. First, we bootstrap the database.

# PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm

Then restart the main mailbox process as the zextras user.

zextras$ zmcontrol stop
zextras$ zmcontrol start

Installation Complete

At this point installation is complete and you can start using Carbonio CE 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.

(Optional) Change Password for System User

In order to change the password used by the 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
# carbonio prov setpassword newpassword

Make sure that newpassword meets good security criteria.

The zextras and 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 CE from the web interface.

Access to the Web Interface

To access Carbonio's web interface, point a supported browser to either of the URL below. In a Multi-Server installation, replace the URL with the IP address or the hostname of the Proxy Node, i.e., SRV4_IP in our scenario.


Since Carbonio CE uses SSL, it is strongly suggested to install an SSL certificate. Please refer to Section Deploy an SSL certificate for directions..

Web Client

The web client is used for regular access to the e-mail account and can be used also to access other functionalities (Carbonio Files, Carbonio Docs if installed), as well as other client protocols such as IMAP or POP, and is available at In Carbonio User Guides you can find directions that guide you in your first steps with Carbonio CE and introduction to the most common tasks

Carbonio Admin Panel

The Carbonio Admin Panel is used for Administration access and is available at:

Here, you can manage server, domains, accounts, and other configurations. Please refer to section Carbonio Admin Panel for more information.

Carbonio CE Management and troubleshooting

The carbonio service integrates seamlessly with the various system tools like systemctl and journalctl, therefore allowing quicker analysis of the situation and check for any problem should arise.

The syntax is the standard used by systemctl, hence you can use

# systemctl start|stop|status carbonio*

to start, stop or verify the status of all the carbonio units and

# journalctl -u carbonio*

to access the logs produced by all the units.

To check, start, or stop a single carbonio unit, you can receive a list of all Carbonio-related units (and their status) with the command below, then use only the unit that you would like to access.

# systemctl list-units "carbonio*"