Carbonio CE Installation
This page provides hardware and software requirements for Carbonio CE and directions for its installation. Please review carefully this whole page before attempting to install.
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.
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)
The installation on Ubuntu 20.04 is organised in steps, some of which are preliminary configuration tasks, and some is optional.
Step 1: Interfaces
We suggest to set up two NICs on the server, and assigning to one a local IP address, that on the one side will be used as the management IP, and on the other side can always be used by Carbonio CE even if the main, public IP address changes. This setup is also useful for testing purposes or when setting up a demo.
Example: Assign an IP Address to a local NIC.
Assuming that a NIC identified as enp0s3 is free on your system, for example in Virtualbox use a Network adapter of type Internal Network, you can assign it an IP address in the preferred way:
use the CLI, for example ifconfig enp0s3 172.16.0.10 up
Replace 172.16.0.10 with the actual management IP to be assigned to the server.
Use netplan.io and add these lines to file
enp0s3: dhcp4: false dhcp6: false addresses: [172.16.0.10/24]
then issue the command netplan apply
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.carbonio.local
# echo "172.16.0.10 mail.carbonio.local mail" >> /etc/hosts
Replace 172.16.0.10 with the actual management IP to be assigned to the server.
Step 3: DNS Resolution
Carbonio CE needs valid DNS resolution for:
the domain (MX and A record)
the FQDN (A record)
So 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
Follow these simple steps to set up
dnsmasq on your testing
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=carbonio.local,mail.carbonio.local,50 host-record=carbonio.local,172.16.0.10 host-record=mail.carbonio.local,172.16.0.10
Finally, restart the dnsmasq service
# systemctl restart dnsmasq
Installation and Post-Installation
Step 4: Repository Configuration and System Upgrade
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, then upgrade the system
In order to upgrade the system, use your preferred package manager. As CLI utilities, you can use apt on Ubuntu operating systems and dnf or yum on RHEL 8 operating system.
Step 5: Installation and Configuration of Carbonio CE
The installation of Carbonio CE requires to run the command
# apt install carbonio-ce
# dnf install carbonio-ce
This command pulls all Carbonio CE packages; however, you can install only selected components according to your needs. To do so, install at least the following packages, which are required to provide the basic functionalities:
carbonio-directory-server carbonio-logger carbonio-mta carbonio-proxy carbonio-appserver carbonio-webui
Finally, in order to carry out the initial configuration and start Carbonio CE, execute
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
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).
Before finalising the bootstrap, press y to apply the configuration. The process will continue until its completion: click Enter to continue.
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.
Step 6. Change Password for System User (Optional)
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 # zmprov 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 Administration Console, point a supported browser to either of the URL below.
Since Carbonio CE 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.
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.*"
This section describes a Carbonio CE 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 CE multi-server environment, composed by five nodes as follows:
A Directory-Server node, used to manage the configuration of the infrastructure and provisioning of users and domains
An MTA node, that takes care of the transfer and forwarding of mail, including filtering and much more functions
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
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 CE 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 to configure the hostname and DNS resolution (See Single Server Installation’s Step 2 and Step 3 respectively).
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 CE'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
rootuser, unless stated otherwise.
Give meaningful names to the nodes. For example, call them proxy.example.com, mta.example.com, and so on. Replace
example.comwith your domain name.
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.
# apt install service-discover-server carbonio-directory-server
# dnf install service-discover-server carbonio-directory-server
# apt install service-discover-agent carbonio-mta
# dnf install service-discover-agent carbonio-mta
# apt install service-discover-agent carbonio-proxy carbonio-webui
# dnf install service-discover-agent carbonio-proxy carbonio-webui
# apt install service-discover-agent carbonio-appserver
# dnf install service-discover-agent carbonio-appserver
# apt install service-discover-agent carbonio-appserver carbonio-logger
# dnf install service-discover-agent carbonio-appserver carbonio-logger
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
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
Proxy node: enter the password for
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 CE: the two tasks needed are to Update Multi-Server SSH keys and to setup Carbonio Mesh for Multi-Server Setup
To complete the installation, execute the following command On each server, which will make sure that all services can operate flawlessly.
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 CE‘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 CE upgrade
Carbonio CE 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 CE, first check for new packages:
# apt update# dnf update
upgrade Carbonio CE packages only
# apt install "carbonio-*"
# dnf install "carbonio-*"
upgrade the whole system
# apt upgrade
# dnf upgrade
Even if you choose to upgrade only Carbonio CE, remember that you should keep the whole system up to date, because new system packages may contain security fixes or bug fixes.
In early Carbonio CE 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: /tmp/apt-dpkg-install-GOKoug/114-carbonio-core_4.0.5-1ubuntu1~focal_amd64.deb 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.