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.
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
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/hostsHint
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
# 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
# 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.
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).
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.
# apt install carbonio-videoserver carbonio-videoserver-recorder
# 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
Multi-Server Installation
This section describes a Carbonio 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 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
Note
The Logger node must be unique within a Carbonio 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 that both DNS resolution and the hostname are configured.
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'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
andpostfix
userProxy node: enter the password for
nginx
userStore 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: the two tasks needed are to Update Multi-Server SSH keys and to setup Carbonio Mesh, which is explained below.
Configure Carbonio Mesh
In order to configure Carbonio Mesh, execute the following command on the Directory-Server node.
# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!
Hint
Use a robust password of your choice.
The outcome of the previous command is a GPG key that you need to copy to all other nodes.
Assuming that you have nodes proxy
, mta
, store
, and
logger
(see the Multi-Server example installation
scenario, use the following commands,
provided you use the correct hostname or IP address of the nodes.
# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg proxy:/etc/zextras/service-discover/cluster-credentials.tar.gpg
# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg mta:/etc/zextras/service-discover/cluster-credentials.tar.gpg
# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg store:/etc/zextras/service-discover/cluster-credentials.tar.gpg
# scp /etc/zextras/service-discover/cluster-credentials.tar.gpg logger:/etc/zextras/service-discover/cluster-credentials.tar.gpg
Finally, log in to each nodes and run the command, making sure to use the same password used in the first step.
# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!
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‘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:
The WebClient, as well as other client protocols such as IMAP or POP, is available ONLY through the proxy: https://proxy.example.com/static/login/
The AdminClient is available ONLY through the proxy: https://proxy.example.com: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:
# apt update
# dnf update
Then either
-
upgrade Carbonio 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, remember that you should keep the whole system up to date, because new system packages may contain security fixes or bug fixes.
Troubleshooting
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.
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.