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.
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 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.
The following requirements must be satisfied before attempting to install Carbonio.
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=184.108.40.206 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 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.
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 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
Instructions for setting up Carbonio repository will be provided by Zextras Sales Department.
The following are important information concerning the packages repository Carbonio 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 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 requires to run a few commands.
We start by updating and upgrading the system.
# apt clean &&apt update && apt upgrade
# dnf clean all && dnf upgrade
Next, we install all packages needed for Carbonio.
# 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-editor \ carbonio-docs-connector carbonio-docs-connector-db \ 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-user-management \ carbonio-files-ui carbonio-files \ carbonio-files-db \ carbonio-mta \ carbonio-logger \ carbonio-appserver \ carbonio-mailbox-db \ carbonio-advanced carbonio-zal \ carbonio-chats-ui \ carbonio-docs-editor \ carbonio-docs-connector carbonio-docs-connector-db \ carbonio-admin-ui carbonio-admin-console-ui \ carbonio-admin-login-ui carbonio-preview
Step 4: Bootstrap Carbonio
Once all packages have been installed, use the following command to configure and launch Carbonio.
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 components.
Step 5: Setup Carbonio Mesh
Carbonio Mesh is required to allow communication between Carbonio 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
Carbonio 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 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 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 databases of Carbonio using a few commands. First,
we bootstrap the databases.
# PGPASSWORD=DB_ADM_PWD carbonio-mailbox-db-bootstrap carbonio_adm 127.0.0.1
# PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm 127.0.0.1
# PGPASSWORD=DB_ADM_PWD carbonio-docs-connector-db-bootstrap carbonio_adm 127.0.0.1
Then restart the main mailbox process as the
zextras$ zmcontrol stop zextras$ zmcontrol start
Step 8: 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
Before starting the procedure, install Fedora’s epel-repository.
# yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
Then, install the packages.
# dnf install carbonio-videoserver carbonio-videoserver-recorder
During the installation, you will be asked for a command to be executed.
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
To complete the installation, first become the
# su - zextras
Execute the following command to configure video recording.
zextras$ carbonio chats video-server add VS_IP port 8188 servlet_port 8090 secret VIDEOSERVER_PWD
Finally, enable Carbonio VideoServer and the recording of meetings.
zextras$ carbonio config set global teamVideoServerRecordingEnabled true zextras$ carbonio config set cos default teamChatEnabled true
Here, port 8188 is the default port used by Carbonio VideoServer, while 8090
for recording. Change these values according to your needs or
preferences, but take into account that the value of the
servlet_port must match the one defined for Carbonio VideoServer in file
Remember also to replace
VS_IP with the public IP address of the Carbonio VideoServer.
In case you forget the password used for the video recording setup, (VIDEOSERVER_PWD), 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.
Final Steps: Complete Setup and Activate License
We are now on the last mile. To verify there is no dangling installation or configuration task, 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
Finally, as the
zextras user, activate Carbonio license,
replacing TOKEN with your licence token.
# carbonio core activate-license TOKEN
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.
(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 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 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 and introduction to the most common tasks