Installation

This section describes the Carbonio installation, which consists of several, connected Nodes (i.e., a Multi-Server installation), each playing one or more Roles.

Rather than giving fixed installation instructions, with some functionality installed on any node, we present an installation scenario that can be adapted to the different needs of Carbonio users, who use a different number of nodes. For this reason, we introduce the notion of Role: a Carbonio functionality that is considered atomic and consists of one or more packages.

A Role can be installed on any node of the cluster, therefore the scenario we describe below can be modified at will by installing a Role on a different node (or even on a dedicated node).

Five Nodes Scenario

Carbonio Multi-Server is the only supported method of installation in a production environment, especially for large production system, because it is more scalable in case of a growth of the infrastructure and the communication across all nodes is set up and secured automatically by Carbonio Mesh, which also adds fault detection and dynamic routing between components of the infrastructure.

In the suggested scenario we will set up a Carbonio Multi-Server environment, composed by five nodes (that we will denote as SRV1, …, SRV5) as follows:

1. SRV1 represents the core infrastructure of Carbonio and features Directory Server, Carbonio Mesh, DB connection, and Carbonio Monitoring

2. SRV2 is equipped with MTA, the mail server, Proxy, which allows web access to all components, and User Management

3. SRV3 hosts an AppServer and the Carbonio Advanced instance

4. SRV4 installs Carbonio Files & Carbonio Docs, that provide sharing and collaborative editing of documents, and Carbonio Preview, Carbonio's ability to preview snippets or thumbnails of a document

5. SRV5 features the Carbonio VideoServer and Video Recording

In our scenario, we start Carbonio installation from six nodes equipped with Ubuntu 20.04 LTS. The instructions are valid for six nodes which are installed with RHEL 8: the only difference is the command for the package installation, while the commands to configure the nodes are the same.

We also assume that the IP address of each node is 172.16.0.1X, with X the n-th node. In other words, IPs will be in the range 172.16.0.11 (SRV1) 172.16.0.15 (Carbonio VideoServer). These values will be used in configuration files that need to be manually modified during the installation or upgrade procedures.

In most Multi-Server scenarios, it proves useful to install a Replica Directory Server in a Master/Slave setup for improved reliability and load-balancing. We describe in a dedicated section the procedure to install the Replica on a dedicated node, SRV7 (which must be equipped with the same OS as the other Nodes). However, you can install the Replica on any node other than SRV1, following the same procedure.

Requirements

Carbonio can be installed in Multi-Server only. Each Node must satisfy the Hardware Requirements and Software Requirements below. On the contrary, Firewall Ports must be opened only on the Node that hosts the corresponding service. For example, port 6071 (secure access to the Admin Panel) must be opened only on the Node featuring the Carbonio Admin Panel. If a service is not installed, the corresponding port can be shut down, to prevent unwanted accesses. For example, if POP3/POPS access is not allowed, access to ports 110 and 995 can be disallowed.

Hardware Requirements

For each node, these are the hardware requirements to comply with. The Disk Space mentioned in the table refers only to the Operating System and not the data (e-mail quota and e-mail traffic, number of documents stored, and so on), because space requirements for the data may vary considerably.

Moreover, you must take into account the following:

• The Node that hosts Carbonio Advanced (SRV3) and therefore the emails, is the node requiring more disk space.

• The Carbonio Files service requires 4GB of RAM to start, so make sure that the node hosting it (SRV4) has at least 6GB of RAM

• The Video Recording feature requires additional storage, which is difficult to estimate in advance. Indeed, it depends on a number of factors, including: Number of participants and number of webcam active during the recording; length and dimension of the recording, screen sharing of the recording, and so on. As a general rule, a 1 hour recording at 1280x720 with 25 frames per second would occupy around 400MB of disk space in webm format.

Purely as an example, if you give a quota of 5GB to each of the 150 users, you need to assign 780GB of disk space (30GB for the OS and at 750 for user’s total quota) to SRV3.

Node	CPUs	RAM	Disk Space (OS)
SRV1	4vCPU	8GB	120GB
SRV2	4vCPU	10GB	30GB
SRV3	4vCPU	16GB	30GB
SRV4	4vCPU	8GB	30GB
SRV5	4vCPU	8GB	30GB

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.

The following requirements must be satisfied before attempting to install Carbonio.

1. The whole Carbonio infrastructure must have at least one public IP address. The IP address must have a domain name associated, that coincides with the A record in the DNS (e.g., A mail.example.com)

   Hint

   You can check a domain’s A record using the CLI utility host:

   # host -t A example.com
   

2. To allow the mail server to receive mail, it will be necessary to set up an MX record, which must correspond to the A record (e.g. MX: example.com = mail.example.com )

   Hint

   You can check a domain’s MX record using the CLI utility host:

   # host -t MX example.com
   

   If either of the A or MX records is not correctly configured, the installation will be temporarily suspended to allow the change of the hostname.

   See the dedicated box below for details and examples.

3. For improved security of sending emails, you should also define TXT records for SPF, DKIM and DMARC

4. Python 3, latest version available on the Operating System chosen

5. Perl, latest version available on the Operating System chosen

6. IPv6 must be disabled. Make also sure that the /etc/hosts does not contain any IPv6 entries.

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 for demo or test environment

Follow these simple steps to set up dnsmasq. These instructions are suitable for a demo or testing environment only.

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.

Ubuntu

# apt install dnsmasq

RHEL

# dnf install dnsmasq

To configure it, add the following lines to file /etc/dnsmasq.conf:

server=1.1.1.1
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 etc/resolv.conf contains the line:

nameserver 127.0.0.1

This will ensure that the local running dnsmasq is used for DNS resolution. Finally, restart the dnsmasq service

# systemctl restart dnsmasq

Support for other distributions will be announced in due course when it becomes available.

RHEL 8 Specific Requirements

If you plan to install Carbonio on RHEL 8, these tasks are required before attempting the installation.

Repositories

A subscription to the follow repositories must be active (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

SELinux and Firewall

SELinux

Must be set to disabled or permissive in file /etc/selinux/config. You can check the current profile using the command

# sestatus

Firewall

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

Additional Requirements

• Acquaintance with the use of CLI is necessary. All carbonio commands must be executed as the zextras user (these commands will feature a zextras$ prompt), while all other commands must be issued as the root user, unless stated otherwise.

  Note

  The zextras user is created during the Carbonio installation process, it is not necessary to create it beforehand.

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

• During the installation procedure, you will need to write down some configuration options and their value, because they will be needed in the setup of the next nodes. These information are summarised at the end of each node’s installation: copy them to a safe place and keep them at hand until the end of the installation. Example of values include: the IP address (public or private) of a node or the password of a database user.

• Depending on the Roles installed on each Node, you need to open in your firewall the ports listed in ref:fw-ports for all the services you will offer.

• If none of the nodes is exposed to the Internet, you need to forward two ports from the public IP: port 25/smtp to the Node featuring MTA (SRV2) to be able to receive mail, and port 443/https to the node installing the Proxy (SRV2) to allow users to access their webmail from a remote location

• If you plan to enable other protocols (e.g., POP, IMAP) you should forward also these ports accordingly. You can refer to section Firewall Ports for a list. Do not open these ports if you do not need these protocols!

• Also, for security reasons, port 6071, to access the Carbonio Admin Panel should never be exposed on the Internet, but reachable only from a VPN tunnel or similar mechanisms

• The same applies for SSH access to the Nodes: it should only be enabled from internal/management networks, while any remote access must be done via VPN tunnel or equivalent mechanism

• The hostname of each Node must be a FQDN that can be internally resolved to each other via DNS

Firewall Ports

For Carbonio to operate properly, it is necessary to allow network communication on specific ports.

The ports listed in the Internal Connections must be opened on all nodes, while those in the External Connections only on the node on which the corresponding Role is installed. For example, port 443 should be opened only on the node hosting the Proxy Role.

Furthermore, ports in Internal and External connections are grouped according to the Role that require them, so all ports listed in a table must be opened only on the Node on which the Role is installed.

TCP External Connections

MTA Role

Port	Protocol	Service
25	TCP	Postfix incoming mail
465	TCP	deprecated SMTP authentication relay [1]
587	TCP	Port for SMTP autenticated relay, requires STARTTLS (or opportunistic SSL/TLS)

[1]

This port is still used since in some cases it is considered safer than 587. It requires on-connection SSL.

Warning

These ports should be exposed only if really needed, and preferably only accessible from a VPN tunnel, if possible, to reduce the attack surface.

Proxy Role

Port	Service
80	TCP	unsecured connection to the Carbonio web client
110	TCP	external POP3 services
143	TCP	external IMAP services
443	TCP	secure connection to the Carbonio web client
993	TCP	external IMAP secure access
995	TCP	external POP3 secure access
6071	TCP	secure access to the Admin Panel
8636	TCP	access to LDAP address books
5222	TCP	XMMP protocol

Warning

The IMAP, POP3, and 6071 ports should be exposed only if really needed, and preferably only accessible from a VPN tunnel, if possible, to reduce the attack surface.

Carbonio VideoServer Role

Port	Protocol	Service
20000-40000	UDP	Client connections for the audio and video streams

TCP Internal Connections

Every Node

Port	Service
22	TCP	SSH access
8301	TCP and UDP	management of Gossip protocol [2] in the LAN
9100	TCP	Carbonio Monitoring Node exporter
9256	TCP	Carbonio Monitoring Process exporter

[2]

The Gossip protocol is an encrypted communication protocol used by Carbonio Mesh for message broadcasting and membership management.

Postgres Role

Port	Protocol	Service
5432	TCP	Postgres access
9187	TCP	Postgres data export to Carbonio Monitoring

Directory Server Role

Port	Protocol	Service
389	TCP	unsecure LDAP connection
636	TCP	secure LDAP connection
9330	TCP	LDAP data export to Carbonio Monitoring

MTA Role

Port	Protocol	Service
25	TCP	Postfix incoming mail
465	TCP	deprecated SMTP authentication relay [3]
587	TCP	Port for SMTP autenticated relay, requires STARTTLS (or opportunistic SSL/TLS)
7026	TCP	bind address of the Milter service

[3]

This port is still used since in some cases it is considered safer than 587. It requires on-connection SSL.

Advanced Role (AppServer)

Port	Protocol	Service
7025	TCP	local mail exchange using the LMTP protocol
7071	TCP	Port for SOAP services communication
7072	TCP	NGINX discovery and authentication
7073	TCP	SASL discovery and authentication
7110	TCP	internal POP3 services
7143	TCP	internal IMAP services
7993	TCP	internal IMAP secure access
7995	TCP	internal POP3 secure access
8080	TCP	internal HTTP services access
8443	TCP	internal HTTPS services
8735	TCP	Internal mailbox mailbox communication
8742	TCP	internal HTTP services, advanced module
8743	TCP	internal HTTPS services, advanced module

Carbonio VideoServer Role

Port	Protocol	Service
8188	TCP	Internal connection
8090	TCP	Servlet communication

Proxy Role

Port	Protocol	Service
9113	TCP	nginx data export to Carbonio Monitoring
11211	TCP	memcached access

Carbonio Mesh Role

Port	Protocol	Service
8300	TCP	management of incoming requests from other agents
8302	TCP and UDP	management of Gossip protocol [4] in the WAN
9107	TCP	Carbonio Mesh data export to Carbonio Monitoring

[4]

The Gossip protocol is an encrypted communication protocol used by Carbonio Mesh for message broadcasting and membership management.

Preliminary Tasks

Before starting with the actual installation, carry out the following two tasks on each of the six nodes.

Task 1. Configure repositories

Repository and Channels

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.

Hint

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.

FAQ

1. I want to help testing things, which channel should I use?

   RC channel.

2. I need to install Carbonio in a production environment which channel should I use?

   RELEASE channel.

3. How will we be informed about new RC packages?

   There will be no notification, because RC channel is updated continuously.

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

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

Task 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

then update /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 -f)"

Hint

Replace 172.16.0.10 with the actual management IP to be assigned to the server.

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.

Node Installation

The installation procedure follows the suggested order of nodes as described in the scenario. A few remarks:

While the overall procedure is the same for both Ubuntu and RHEL 8, the actual commands and file paths may differ on the two operating system, so pay attention that you execute the correct command on the correct files and operating system. The commands that differ are separated as follows. Click the Ubuntu or RHEL tab according to the Operating System on which you are installing Carbonio.

Ubuntu

# <command to be executed on Ubuntu systems>

RHEL

#  <command to be executed on Red Hat systems>

All the commands that are mentioned in this installation procedure must be executed as the root user.

When the installation process has successfully finished, you can access Carbonio's GUI using a browser: directions can be found in Section Access to the Web Interface.

SRV1: Postgres, Directory Server, DB connection, Carbonio Mesh, and Carbonio Monitoring

System requirements

CPU	4vCPU
RAM	8GB
Disk Space	110GB
IP Address	172.16.0.11
FQDN	srv1.example.com

Roles

• PostgreSQL

• DB connection, provided by pgpool

• Directory Server

• Carbonio Mesh

• Carbonio Monitoring

To install the first Node, follow the order of Roles presented in the above panel: start with the installation and configuration of PostgreSQL and DB connection, then bootstrap Carbonio, set up Carbonio Mesh, and finally prepare the Carbonio Files database.

Installation of PostgreSQL

Ubuntu

# apt install postgresql-12

RHEL

On a RHEL 8 installation, you need to install PostgreSQL 12 directly from the PostgreSQL repository, so install the repository information.

# dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

To make sure that Postresql 12 is installed, run commands

# dnf -qy module disable postgresql
# dnf -y install postgresql12 postgresql12-server

Once installed, initialise and enable the database

# /usr/pgsql-12/bin/postgresql-12-setup initdb
# systemctl enable --now postgresql-12

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

Note

If you are running Carbonio on RHEL 8, make sure you installed and configured PostgreSQL 12 according to the instruction in section Preliminary Tasks.

We start by defining a robust password for PostgreSQL’s administrative user.

# read -s -p "Password:" DB_ADM_PWD

Provide a password of your choice, which will be stored in a variable called DB_ADM_PWD and reusable throughout the whole procedure. It is important to notice that the password is accessible to the user (root) in the current terminal only. No one else can access it and it will be deleted upon logging out. You can also manually delete it with the appropriate command, but remember that you need it in the next step.

# unset $DB_ADM_PWD

# 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;\""

Finally, allow the other nodes to access the databases that will be stored on this node by running these commands.

Ubuntu

# su - postgres -c "psql --command=\"ALTER SYSTEM SET listen_addresses TO '*';\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET max_connections = 500;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET shared_buffers = 5000;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET port TO '5433';\""
# echo "host    all             all             0.0.0.0/0            md5" >> /etc/postgresql/12/main/pg_hba.conf
# systemctl restart postgresql

RHEL

# su - postgres -c "psql --command=\"ALTER SYSTEM SET listen_addresses TO '*';\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET max_connections = 500;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET shared_buffers = 5000;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET port TO '5433';\""
# echo "host    all             all             0.0.0.0/0            md5" >> /var/lib/pgsql/12/data/pg_hba.conf
# systemctl restart postgresql-12

Hint

You may replace the 0.0.0.0/0 network with the one within the cluster is installed (172.16.0.0) to prevent unwanted accesses.

Packages Installation

1. Install the following packages from main repository.

   Ubuntu

   # apt install service-discover-server \
     carbonio-directory-server carbonio-files-db \
     carbonio-mailbox-db carbonio-docs-connector-db \
     carbonio-prometheus
   

   RHEL

   # dnf install service-discover-server \
     carbonio-directory-server carbonio-files-db \
     carbonio-mailbox-db carbonio-docs-connector-db \
     carbonio-prometheus
   

   Note

   It is possible to install multiple instances of the service-discover service provided by Carbonio Mesh. Please refer to section Set up Multiple Carbonio Mesh Servers for details.

Install and configure pgpool

Carry out the following tasks to set up pgpool.

1. Install pgpool

   Ubuntu

   # apt install pgpool2
   

   RHEL

   # dnf install https://www.pgpool.net/yum/rpms/4.4/redhat/rhel-8-x86_64/pgpool-II-pg12-4.4.3-1pgdg.rhel8.x86_64.rpm
   

2. Configure Pgpool-II using the following command.

   Note

   backend_hostname0 is the IP of the Node on which PostgreSQL is installed. If you plan to install it on a different node or you want to use an existing PostgreSQL installation, replace the value localhost with the correct IP address or hostname, provided the hostname is resolvable by SRV1.

   Ubuntu

   # echo "backend_clustering_mode = 'raw'
   port = 5432
   backend_hostname0 = 'localhost'
   backend_port0 = 5433
   backend_flag0 = 'DISALLOW_TO_FAILOVER'
   num_init_children = 32
   max_pool=8
   reserved_connections=1" > /etc/pgpool2/pgpool.conf
   

   RHEL

   # echo "backend_clustering_mode = 'raw'
   port = 5432
   backend_hostname0 = 'localhost'
   backend_port0 = 5433
   backend_flag0 = 'DISALLOW_TO_FAILOVER'
   num_init_children = 32
   max_pool=8
   reserved_connections=1" > /etc/pgpool-II/pgpool.conf
   

3. Make sure the service is enabled and restart it using these commands

   Ubuntu

   # systemctl enable --now pgpool2
   # systemctl restart pgpool2.service
   

   RHEL

   # systemctl enable --now pgpool
   # systemctl restart pgpool.service
   

Bootstrap Carbonio

# carbonio-bootstrap

The bootstrap 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 all, you only need to click y for confirmation.

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

• ask for the Carbonio Mesh secret, which is used for setups, management, and to access the administration GUI. See section Carbonio Mesh Administration Interface for more information.

  Hint

  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.

  In case the password is lost or the credential file becomes corrupted and unusable, you can Regenerate Carbonio Mesh Secret.

• store the setup in file /etc/zextras/service-discover/cluster-credentials.tar.gpg

To complete Carbonio Mesh installation, run

# pending-setups -a

Hint

The secret needed to run the above command is stored in file /var/lib/service-discover/password, which is accessible only by the root user.

Bootstrap Carbonio Databases

You need to use the Postgres user created on SRV1 and the password defined in previous steps.

• Carbonio Advanced

  # PGPASSWORD=DB_ADM_PWD carbonio-mailbox-db-bootstrap carbonio_adm 127.0.0.1
  

• Carbonio Files

  # PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm 127.0.0.1
  

• Carbonio Docs

  # PGPASSWORD=DB_ADM_PWD carbonio-docs-connector-db-bootstrap carbonio_adm 127.0.0.1
  

Installation of SRV1 has now completed. To prevent anyone else reading the password of PostgreSQL’s administrator user, remove it from memory:

# unset $DB_ADM_PWD

SRV2: MTA, Proxy, and User Management

System requirements

CPU	4vCPU
RAM	10GB
Disk Space	30GB
IP Address	172.16.0.12
FQDN	srv2.example.com

Roles

• MTA, the mail server

• Proxy

• User management

Installation of Node 2 foresees the installation of MTA, Proxy, and user management Roles, the bootstrap of Carbonio, and the configuration of Carbonio Mesh and Memcached.

Ubuntu

# apt install service-discover-agent carbonio-mta \
carbonio-proxy carbonio-webui carbonio-files-ui \
carbonio-chats-ui carbonio-user-management

RHEL

# dnf install service-discover-agent carbonio-mta \
carbonio-proxy carbonio-webui carbonio-files-ui \
carbonio-chats-ui carbonio-user-management

The following tasks must be executed to configure the MTA.

Bootstrap Carbonio.

Launch the Carbonio bootstrap process

# carbonio-bootstrap

During the process, you need to provide these values, which you can retrieve from SRV1.

• Ldap master host is the FQDN of SRV1, srv1.example.com

• Ldap Admin password is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s zimbra_ldap_password"
  

• Bind password for postfix ldap user is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s ldap_postfix_password"
  

• Bind password for amavis ldap user is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s ldap_amavis_password"
  

• Bind password for nginx ldap user is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s ldap_nginx_password"
  

Set up Carbonio Mesh

Carbonio Mesh will install as an agent, that connects and communicates with the server. The configuration for the agent is created by launching command

# service-discover setup-wizard

This command will:

• ask for the IP address and netmask of the current Node

• ask for the Carbonio Mesh secret, which is stored in file /var/lib/service-discover/password on SRV1

After the configuration has completed successfully, run the following command, again using the secret.

# pending-setups -a

Enable Memcached

To enable Memcached access, use these commands as the zextras user:

zextras$ carbonio prov ms $(zmhostname) zimbraMemcachedBindAddress $(hostname -i)
zextras$ zmmemcachedctl restart
zextras$ zmproxyctl restart

Warning

Since Memcached does not support authentication, make sure that the Memcached port (11211) is accessible only from internal, trusted networks.

SRV3: Carbonio Advanced (AppServer)

System requirements

CPU	4vCPU
RAM	16GB
Disk Space	30GB
IP Address	172.16.0.13
FQDN	srv3.example.com

Note

Remember to allocate enough disk space for the user’s quota, which is around 750GB for 150 users with 5GB quota each.

Roles

• Carbonio Advanced (AppServer)

On the third node, the AppServer and the Carbonio Advanced instance are installed, and, like in the previous node, the bootstrap of Carbonio, and the configuration of Carbonio Mesh and Memcached are carried out.

Install Packages

Ubuntu

# apt install service-discover-agent carbonio-advanced

RHEL

Make sure to respect the order of installation.

# dnf install service-discover-agent
# dnf install carbonio-advanced

Bootstrap Carbonio.

Launch the Carbonio bootstrap process

# carbonio-bootstrap

During the process, you need to provide these values, which you can retrieve from SRV1.

• Ldap master host is the FQDN of SRV1, srv1.example.com

• Ldap Admin password is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s zimbra_ldap_password"
  

Set up Carbonio Mesh

Carbonio Mesh will install as an agent, that connects and communicates with the server. The configuration for the agent is created by launching command

# service-discover setup-wizard

This command will:

• ask for the IP address and netmask of the current Node

• ask for the Carbonio Mesh secret, which is stored in file /var/lib/service-discover/password on SRV1

After the configuration has completed successfully, run the following command, again using the secret.

# pending-setups -a

SRV4: Carbonio Preview, Carbonio Files, and Carbonio Docs

System requirements

CPU	4vCPU
RAM	4GB
Disk Space	30GB
IP Address	172.16.0.14
FQDN	srv4.example.com

Roles

• Carbonio Preview

• Carbonio Files

• Carbonio Docs

The fourth node requires the bootstrap of Carbonio and the configuration of Carbonio Mesh and Memcached.

Package installation

Ubuntu

# apt install service-discover-agent carbonio-preview \
carbonio-files carbonio-docs-connector \
carbonio-docs-editor

RHEL

# dnf install service-discover-agent carbonio-preview \
carbonio-files carbonio-docs-connector \
carbonio-docs-editor

Bootstrap Carbonio.

Launch the Carbonio bootstrap process

# carbonio-bootstrap

During the process, you need to provide these values, which you can retrieve from SRV1.

• Ldap master host is the FQDN of SRV1, srv1.example.com

• Ldap Admin password is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s zimbra_ldap_password"
  

Set up Carbonio Mesh

Carbonio Mesh will install as an agent, that connects and communicates with the server. The configuration for the agent is created by launching command

# service-discover setup-wizard

This command will:

• ask for the IP address and netmask of the current Node

• ask for the Carbonio Mesh secret, which is stored in file /var/lib/service-discover/password on SRV1

After the configuration has completed successfully, run the following command, again using the secret.

# pending-setups -a

Configure Memcached

To allow Carbonio Preview to operate correctly, you need to edit file /etc/carbonio/preview/config.ini and search for variables nginx_lookup_servers_full_path_urls and memcached_server_full_path_urls, which are one after the other, towards the end of the file.

nginx_lookup_server_full_path_urls = https://172.16.0.13:7072
memcached_server_full_path_urls = 172.16.0.12:11211

Make sure that:

• in line 1, protocol is https and the IP address is the address of the AppServer, which is SRV3’s 172.16.0.13

• in line 1, make also sure to specify the port used by Preview, 7072

• in line 2, SRV2’s IP (172.16.0.12) is written, to allow access to Memcached, which is installed on the Proxy Node

SRV5: Carbonio VideoServer and Video Recording

System requirements

CPU	4vCPU
RAM	8GB + ~1MB for each connected user
Disk Space	30GB
IP Address	172.16.0.15
FQDN	srv5.example.com

Roles

• Carbonio VideoServer

• Carbonio VideoServer Recording

Network

• A public IP address. This is either the IP address of Carbonio VideoServer, if it is directly accessible from remote clients on the Internet, or—​if there is a NAT-ting device in front of it (e.g., a firewall or router)–the IP address with which the Carbonio VideoServer is reachable.

• A publicly resolvable FQDN

• With the default settings, 200kb/s (0.2 mb/s) bandwidth for each connected user

• WebSockets support

Ports

• The mailbox server will establish a WebSocket on port 8188 (TCP) to communicate with the Carbonio VideoServer

• Connecting browsers will use a random UDP port between 20000 and 40000 on the public IP of the Carbonio VideoServer

Installation of Carbonio VideoServer

It is possible to install the Carbonio VideoServer without the Video Recording feature. If you wish to do so, follow the procedure below, but skip the last step, Installation of Video Recording. You can always install it at a later point by following the procedure in

First, install Carbonio VideoServer package

Ubuntu

# apt install service-discover-agent carbonio-videoserver

RHEL

Before starting the procedure, install Fedora’s epel-repository.

# dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

Then, install the packages.

# dnf install service-discover-agent carbonio-videoserver

After the installation, make sure that the Carbonio VideoServer public IP address (i.e., the one that will accept incoming connections to the Carbonio VideoServer) is present in the configuration file /etc/janus/janus.jcfg and add it if missing: find the variable nat_1_1_mapping and add it, for example: nat_1_1_mapping = "93.184.216.34"

Finally, enable and start the service with the commands

# systemctl enable videoserver.service
# systemctl start  videoserver.service

Installation of Video Recording

To implement this feature, install package

Ubuntu

# apt install carbonio-videoserver-recorder

RHEL

# dnf install carbonio-videoserver-recorder

The video-recording feature is enabled by default, and does not require configuration if installed together with the Carbonio VideoServer. It does however require some manual command if installed at a later point. Please refer to Section Recording a Video Meeting for directions.

The recorded sessions will be stored in directory /var/lib/videorecorder/ on SRV3, because the ability to record requires a Node which features the AppServer (i.e., on which the carbonio-advanced package is installed). Make sure that the directory has sufficient free space, otherwise recorded videos can not be stored.

Hint

You can mount on that location a dedicated disk or partition and keep it monitored for space usage.

Bootstrap Carbonio.

Launch the Carbonio bootstrap process

# carbonio-bootstrap

During the process, you need to provide these values, which you can retrieve from SRV1.

• Ldap master host is the FQDN of SRV1, srv1.example.com

• Ldap Admin password is obtained from SRV1 using the command

  # su - zextras -c "zmlocalconfig -s zimbra_ldap_password"
  

Set up Carbonio Mesh

Carbonio Mesh will install as an agent, that connects and communicates with the server. The configuration for the agent is created by launching command

# service-discover setup-wizard

This command will:

• ask for the IP address and netmask of the current Node

• ask for the Carbonio Mesh secret, which is stored in file /var/lib/service-discover/password on SRV1

After the configuration has completed successfully, run the following command, again using the secret.

# pending-setups -a

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

Activate license

The last task to complete before the installation is complete, is to activate Carbonio license: as the zextras user, issue the following command, replacing TOKEN with your licence token.

zextras$ carbonio 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.

You are also strongly advised to change the password of the Global Admin, a task explained in section Manage Global Administrators.

---

At this point the installation is complete. Before you can start using Carbonio, make sure to carry out all the tasks listed in section Post-Installation Tasks.

Post-Installation Tasks

The first task to carry out is to change the password of the zextras user. This is a very important task, because this user has full powers over all Carbonio functionalities, therefore its password must be robust. More details and the command to change the password can be found in section Manage Global Administrators.

After you change the password, log in to the Carbonio Admin Panel, using the Proxy Node’s IP or hostname, at https://srv2.example.com:6071/, with user zextras@example.com and password the one you just changed.

If the login is successful, go to Domains, select the domain example.com, and, under the General Settings and define:

• The Public Server Host Name, setting it as https://mail.example.com

• The Public Service Port, setting it as 443.

These two values combined represent the URL that users need to access to use the features of Carbonio.

Centralised Logging Configuration

The log system in Carbonio is rsyslog, which supports a centralised setup: in other words, all log files produced by Carbonio can be sent to a unique host server (we call it “Log Server”), that is appropriately configured to receive log files, which is particularly useful in a Multi-Server installation.

In the instructions below, we elect the Log Server to be SRV1.

Centralised Logging Setup

On SRV1, open file /etc/rsyslog.conf, find the following lines, and uncomment them (i.e., remove the # character at the beginning of the line).

$ModLoad imudp
$UDPServerRun 514

$ModLoad imtcp
$TCPServerRun 514

Then, restart the rsyslog service.

# systemctl restart rsyslog

Finally, specify the host server that will receive logs. Since this is the SRV1 node, we need its hostname.

zextras$ carbonio prov mcf zimbraLogHostname srv1_hostname

Note

Since zimbraLogHostname is a global attribute, this command must be run only once on one node.

Other Nodes Setup

Once the Log Server node has properly been initialised, on all other nodes, execute

# /opt/zextras/libexec/zmsyslogsetup  && service rsyslog restart

Manage Global Administrators

In order to change the password used by the zextras@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 -c "carbonio prov setpassword zextras@example.com mynewsecurepassword"

Make sure that newpassword meets good security criteria.

The zextras and zextras@example.com 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@example.com

This is the default administrator user to be used to access the Admin UI and manage Carbonio from the web interface.

A new Global Admin can be created from the Carbonio Admin Panel; please refer to section Create New Global Admin for directions.