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.
Intel/AMD 64-bit CPU 1.5 GHz
8 GB min, 16GB recommended
Disk space (Operating system and Carbonio)
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)
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.
valid DNS resolution for both the domain (
Arecords) and the FQDN (
Python 3, latest version available on the Operating System chosen
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.
Acquaintance with the use of CLI is necessary. All
carboniocommands must be executed as the
zextrasuser (these commands will feature a
zextras$prompt), while all other commands must be issued as the
rootuser, 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
Example: Set up of dnsmasq for demo or test environment
Follow these simple steps to set up
instructions are suitable for a demo or 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
server=126.96.36.199 mx-host=example.com,mail.example.com,50 host-record=example.com,172.16.0.10 host-record=mail.example.com,172.16.0.10
Remember to replace the 172.16.0.10 IP address with the one
of your server. Then, make sure that the
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 https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
SELinux and Firewall
Must be set to disabled or permissive in file
/etc/selinux/config. You can check the current profile using the command
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 127.0.0.1/32 ident
host if present and change it as follows:
# IPv4 local connections: host all all 127.0.0.1/32 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.
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.
I want to help testing things, which channel should I use?
I need to install Carbonio in a production environment which channel should I use?
How will we be informed about new RC packages?
There will be no notification, because RC channel is updated continuously.
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.
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 mail.example.com
/etc/hosts with IP and hostname
# echo "172.16.0.10 mail.example.com mail" >> /etc/hosts
You can also simply get the current IP and hostname and save them:
# echo "$(hostname -I) $HOSTNAME.$DOMAIN"
Replace 172.16.0.10 with the actual management IP to be assigned to the server.
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 \ carbonio-admin-login-ui
Step 4: Bootstrap Carbonio CE
Once all packages have been installed, use the following command to configure and launch Carbonio CE.
Before finalising the bootstrap, press y to apply the configuration. The process will continue until its completion: click Enter to continue.
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
The first part of the bootstrap enables all necessary services and creates a new administrator account (firstname.lastname@example.org), 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
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
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
/var/lib/service-discover/password which is accessible
only by the
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 127.0.0.1
Then restart the main mailbox process as the
zextras$ zmcontrol stop zextras$ zmcontrol start
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
email@example.com 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 firstname.lastname@example.org newpassword
Make sure that
newpassword meets good security criteria.
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..
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 https://mail.example.com/. 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 CE Management and troubleshooting
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
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*"