Carbonio Installation

This page provides hardware and software requirements for Carbonio 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 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 and requires valid DNS resolution for

the domain (MX and A record)
the FQDN (A record)

See the dedicated box below for details and examples.

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)

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.

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

We remark that, unless differently stated, all CLI commands must be run as the root user.

Step 1: 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.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.

Installation

Step 2: Repository Configuration and System Upgrade

Instructions for setting up Carbonio repository will be provided by Zextras Sales Department.

Step 3: Installation and Configuration of Carbonio

The installation of Carbonio requires to run the command

Ubuntu

# 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-connector-ce carbonio-docs-editor \
pgpool2 postgresql-12-pgpool2

RHEL

# dnf 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-connector-ce carbonio-docs-editor \
pgpool2 postgresql-12-pgpool2

Post Installation tasks

Step 4: Set up PostgreSQL and Pgpool-II

Note

This step is optional, but strongly suggested.

PostgreSQL database is used by Carbonio and, to improve connection efficiency and resource consumption, we set up Pgpool to work with PostgreSQL.

First, modify the port on which PostgreSQL listens for connections.

# vi /etc/postgresql/12/main/postgresql.conf
# port = 5433
# systemctl stop postgresql

Next, configure pgpool to use PostgreSQL’s port.

# echo "backend_clustering_mode = 'raw'
# port = 5432
# backend_hostname0 = '127.0.0.1'
# backend_port0 = 5433" > /etc/pgpool2/pgpool.conf

Finally, restart both services using this single command.

# systemctl restart pgpool2.service

Step 5: Bootstrap Carbonio

Once all packages have been installed and the PostgreSQL user and database for Carbonio Files have been setup, use the following command to configure and launch Carbonio.

# carbonio-bootstrap

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

Step 6: Setup Carbonio Mesh

Carbonio Mesh is required to allow communication between Carbonio and ts components. The configuration is automatically generated by command

# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!

Hint

Replace My_Mesh_Password£0! with a robust password of your choice.

This command will:

find the hostname IP address (hostname -i)
set the cluster credential password to My_Mesh_Password£0!, which is used for setups, management, and to access the administration GUI. See section Carbonio Mesh Administration Interface for more information.
store the setup in file /etc/zextras/service-discover/cluster-credentials.tar.gpg

Warning

Make sure to store the password in a safe place (like e.g., a password manager). In case the password is lost or the credential file becomes corrupted and unusable, you can Regenerate Carbonio Mesh Credentials.

Complete Carbonio Mesh and Carbonio setup by running

# pending setups

Step 7: Configure Carbonio Databases

Carbonio relies on a number of databases to store and keep track of all the objects it needs to manage, therefore it is necessary to create and configure all of them using these commands. First, become the postgres users and start psql.

# sudo -u postgres psql

Then run the following command in order to create roles, database, and grant appropriate access rights.

# CREATE ROLE "carbonio-files-adm" WITH LOGIN SUPERUSER encrypted password 'My-Files-pwd01$'
# CREATE DATABASE "carbonio-files-adm" owner "carbonio-files-adm"
# CREATE ROLE "powerstore" WITH LOGIN encrypted password 'My-PowerStore-pwd98%'
# CREATE DATABASE "powerstore" owner "powerstore"
# CREATE ROLE "activesync" WITH LOGIN encrypted password 'My-Sync-pass-_#4'
# CREATE DATABASE "activesync" owner "activesync"
# CREATE ROLE "abq" WITH LOGIN encrypted password 'My_AbQ-psw]4<'
# CREATE DATABASE "abq" owner "abq"
# \q

Hint

Make sure to use different passwords for each role.

Remember to replace all passwords with robust passwords of your choice and store them in a safe place (preferably using a password manager), as you might need them in the future.

Step 8: Bootstrap Database of Carbonio Files

The final steps is to bootstrap Carbonio Files's DB (replacing the example password My_Mesh_Password£0! with the chosen one):

# PGPASSWORD=My_Mesh_Password£0! carbonio-files-db-bootstrap carbonio-files-adm 127.0.0.1

Step 9: 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.

Ubuntu

# apt install carbonio-videoserver carbonio-videoserver-recorder

RHEL

# dnf install carbonio-videoserver carbonio-videoserver-recorder

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

Finally, the following commands enable video recording and must be executed as the zextras user.

# su - zextras
# zxsuite chats video-server add example.com port 8100 servlet 8090 secret MY_Video-ReC-pass7=6
# zxsuite config set global teamVideoServerRecordingEnabled true
# zxsuite config set cos default teamChatEnabled true

Here, port 8100 is the default port used by Carbonio VideoServer, while 8100 for recording. Change these values according to your needs or preferences. Remember also to replace example.com with your domain name.

In case you forget the password used for the video recording setup, (MY_Video-ReC-pass7=6), 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.

Step 10: JDBC Configuration

We are reaching the end of the installation. This is the last configuration step which will set up the JDBC connections with PostgreSQL.

# zxsuite config set global powerstoreMetadataDb '{"url":"jdbc:postgresql://127.0.0.1:20003/powerstore","user":"powerstore","password":"My-PowerStore-pwd98%"}'
# zxsuite config set global activeSyncDb '{"url":"jdbc:postgresql://127.0.0.1:20003/activesync","user":"activesync","password":"My-Sync-pass-_#4"}'
# zxsuite config set global abqMetadataDb '{"url":"jdbc:postgresql://127.0.0.1:20003/abq","user":"abq","password":"'My_AbQ-psw]4<"}'
# zxsuite mobile doRestartService module
# zxsuite powerstore doRestartService module

Step 8: Licence Activation

We are now on the last mile. To verify there is no dangling installation or configuration task, run:

# pending-setups

Finally, as the zextras user, activate Carbonio license, replacing TOKEN with your licence token.

# zxsuite core activate-license TOKEN

Installation Complete

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.

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

The WebClient (that is, the regular user access), as well as other client protocols such as IMAP or POP, is available at: https://mail.carbonio.local/
The AdminClient (for Administration access) is available at: https://mail.carbonio.local:6071/login

Carbonio upgrade

Carbonio 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, first check for new packages:

Ubuntu

# apt update

RHEL

# dnf update

Then either

upgrade Carbonio packages only

Ubuntu

# apt install "carbonio-*"

RHEL

# dnf install "carbonio-*"

or

upgrade the whole system
Ubuntu
# apt upgrade
RHEL
# dnf upgrade

Hint

Even if you choose to upgrade only Carbonio, 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 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.

Carbonio Installation

Requirements

System Requirements

Software Requirements

Single-Server Installation

Access to the Web Interface

Multi-Server Installation

Scenario

Requirements

Access to the Web Interface

Carbonio upgrade

Troubleshooting