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.

Requirements

System Requirements

Hardware requirements

CPU

Intel/AMD 64-bit CPU 1.5 GHz

RAM

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

XenServer

KVM

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.

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)

Single-Server Installation

The installation on Ubuntu 20.04 is organised in steps, some of which are preliminary configuration tasks, and some is optional.

Pre-Installation Steps

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

    Hint

    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 /etc/netplan/01-netcfg.yaml:

    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

then update /etc/hosts

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

Hint

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

Example: Set up of dnsmasq

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

Warning

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:

server=1.1.1.1
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

# carbonio-bootstrap
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).

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

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.

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:

zextras

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

zextras@carbonio.local

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

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.*"

Multi-Server Installation

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.

Scenario

In this suggested scenario we will set up a Carbonio CE 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

    Note

    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.

Requirements

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

Warning

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 root user, unless stated otherwise.

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

Install packages

On each node, different packages should be installed.

Note

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 CE: the two tasks needed are to Update Multi-Server SSH keys and to setup Carbonio Mesh for Multi-Server Setup

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

Then either

  • upgrade Carbonio CE packages only

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

or

  • upgrade the whole system

    # apt upgrade
    
    # dnf upgrade
    

Hint

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.

Troubleshooting

Problem: Error in upgrading

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.

Solution:

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.