In deep view

This section contains various rather advanced topics that are not required for a everyday use of Carbonio CE.

Regenerate Carbonio Mesh Credentials

Whenever the cluster credential password of file /etc/zextras/service-discover/cluster-credentials.tar.gpg are unaccessible, it is possible to generate a new file password and credentials file.

In those cases, the command consul acl bootstrap will terminate with an error message similar to:

Failed ACL bootstrapping: Unexpected response code: 403 (Permission denied: ACL bootstrap no longer allowed (reset index: 908))

Before attempting the recover, be prepared for a downtime of the Carbonio Mesh service for the whole duration of the procedure.

The procedure is the same for Single-Server and Multi-Server, but on the Multi-Server there are a few more steps to carry out.

Preliminary Tasks

In case of a Single-Server node, log in to it and skip to the next step.

On a Multi-Server, you need to identify the Carbonio Mesh leader node node and log into it. Most of the times, this is the Directory-Server node, whose IP address is retrieved using the command below.

# zmprov gas service-discover

To make sure you are on the leader, use the following command.

# wget http://127.0.0.1:8500/v1/status/leader -qO -

The output will be an IP address and a port, for example 192.168.56.101:8300. If this IP is different from the Directory Server’s, log in to the latter on (192.168.56.101).

Note

All the commands must be run on the leader node, unless differently specified.

Step 1. Wipe Old Credentials

The first task, to be executed as the service-discover user, is to write a reset index, to allow a new ACL token to be generated.

# sudo -u service-discover bash -c "echo 908 > /var/lib/service-discover/data/acl-bootstrap-reset"

Then stop the service discover service.

# systemctl stop service-discover

Finally, remove all certificates related to service discover.

# rm /var/lib/service-discover/*.pem

Step 2. Generate New Credentials

Run the setup as a first instance.

# service-discover setup 192.168.56.101 --first-instance --password=My_Mesh_Password£0!

This is essentially the same command as the one used during the configuration of Carbonio Mesh, the only difference being that in this case we use the explicit IP address and run it as first instance.

Optionally, verify the ACL token using the commands

# export CONSUL_HTTP_TOKEN=$(gpg -qdo - /etc/zextras/service-discover/cluster-credentials.tar.gpg | tar xOf - consul-acl-secret.json | jq .SecretID -r)
# consul members
       Node              Address              Status  Type    Build  Protocol  DC   Segment
       mail.example.com  192.168.56.101:8301  alive   server  1.9.3  2

On a Single-Server the procedure has been completed. Make sure to store the new credentials in a safe place!

Multi-Server Final Task

On a Multi-Server, you need to copy the credentials file on all other nodes, for example using scp, like explained during the installation.

Finally, log in to all other nodes and repeat on each of them the setup using the following commands

# rm /var/lib/service-discover/*pem
# service-discover setup $(hostname -i) --password=My_Mesh_Password£0!

Carbonio Mesh Administration Interface

It is usually not required to access the administration interface of Carbonio Mesh, because everything is managed under the hood by Carbonio CE. To have a look at the administration interface, for example to check out the configuration generated by Carbonio CE, you need first to create a new token, then to set up an SSH tunnel from the current workstation to the Carbonio CE server.

The latter step is mandatory because, For security reasons, Carbonio Mesh only listens on localhost.

Requirements

In order to successfully complete two tasks described below, you will need the cluster credential password that was defined during the Carbonio Mesh installation.

Step 2. Create Token

You need to create a bootstrap token that will be used to create any additional token.

# service-discover bootstrap-token

You need to provide the cluster credential password that you used in the previous step.

Warning

The bootstrap token is the most important building block of Carbonio Mesh and should only be used to create other tokens: if lost, all tokens must be regenerated, so keep it safe!

Step 3. Create tunnel

# ssh -N -f -L 8500:localhost:8500 root@<IP Address>

API for Carbonio CE

Zextras makes available to developers a couple of APIs to interact with Carbonio CE components. To read their documentation, follow the URLS:

Deploy an SSL certificate

In this section we explain how to add an SSL/TLS certificate to a Carbonio CE installation, both a single server and a wildcard certificate.

This setup is mandatory if Carbonio CE is used in conjunction with mobile apps; it is also suggested for any installation in order to avoid the client browser’s warning about an invalid certificate upon connection.

Commercial Certificate Installation

We will describe the procedure by taking into account the following scenario:

  • The server FQDN is mail.example.com

  • No SSL certificate is available for the domain.

In the remainder, replace mail.example.com with your actual server FQDN.

The procedure consists of a few steps and requires console access to the Carbonio CE server.

Step 1. Certificate Signing Request generation

We start by generating a CSR:

# /opt/zextras/bin/zmcertmgr createcsr comm -new -subject \
"/C=IT/ST=VR/L=Yourtown/O=YourCompany/OU=SampleDepartment/CN=mail.example.com" \
-subjectAltNames mail.example.com

Where the various elements in the subject are the standard fields of an SSL certificate:

  • C: the 2-digit country code

  • ST: State or Province

  • L: City

  • O: Organization Name

  • OU: Organization Unit (Department)

  • CN: Common Name

Note

You can optionally include more than one (alternative) name by simply adding to the end of the command one ore more -subjectAltNames options, followed by the name to add.

Once the command is executed these files will be generated:

/opt/zextras/ssl/carbonio/commercial/commercial.key
/opt/zextras/ssl/carbonio/commercial/commercial.csr

Step 2. Get the certificates from your SSL provider

To complete this step successfully, you need to submit the CSR to the SSL provider and get a commercial certificate in PEM format and save it as /opt/zextras/ssl/carbonio/commercial/commercial.crt.

Moreover, SSL providers supply also the intermediate certificate and the so-called Root CA in a bundled certificate file (“Full Chain CA”), that must be saved as /opt/zextras/ssl/carbonio/commercial/commercial_ca.crt.

How to create a Full Chain CA

However, in some cases, the SSL provider may only provide the intermediate certificate, in which case you need to create the Full CA Chain in order to install the certificate (for further information: https://knowledge.digicert.com/solution/SO16297.html)

If you don’t have a full CA chain bundle, download and save the root and the intermediate CA from your provider to temporary files, for example /tmp/ca_root.crt and /tmp/ca_intermediary.crt, then merge the two previously created temporary files into a single one:

# cat /tmp/ca_intermediary.crt /tmp/ca_root.crt > \
/opt/zextras/ssl/carbonio/commercial/commercial_ca.crt

Step 3. Verification and deploy

Issue the following commands to verify that the certificate and your private key match:

  • become the zextras user

    # su - zextras
    
  • go to the directory where the certificates are stored:

    # cd /opt/zextras/ssl/carbonio/commercial
    
  • verify the certificates

    # zmcertmgr verifycrt comm commercial.key commercial.crt commercial_ca.crt
    

If the verification is successful, you can deploy the SSL certificate.

zmcertmgr deploycrt comm commercial.crt commercial_ca.crt

Finally, restart Carbonio CE.

zmcontrol restart

Your certificate should now be installed: verify the certificate details by running this command:

zmcertmgr viewdeployedcrt

Wildcard Certificate Installation

To describe this procedure, we use the same server with FQDN mail.example.com, but in this case there is already a wildcard SSL certificate for domain *.example.com, that was generated on a server other than Carbonio CE's.

Therefore, you have all the necessary certificates and the procedure in this case is simpler

Step 1. Set up of certificates

The existing PEM certificate and its private key must be save as /opt/zextras/ssl/carbonio/commercial/commercial.crt and /opt/zextras/ssl/carbonio/commercial/commercial.key respectively.

Now, go to /opt/zextras/ssl/carbonio/commercial/ and merge the two certificates into a single one:

# cat commercial.crt commercial.key > commercial_ca.crt

Step 2. Verification and deploy

Issue the following commands to verify that the certificate and your private key match:

  • become the zextras user

    # su - zextras
    
  • go to the directory where the certificates are stored:

    # cd /opt/zextras/ssl/carbonio/commercial
    
  • verify the certificates

    # zmcertmgr verifycrt comm commercial.key commercial.crt commercial_ca.crt
    

If the verification is successful, you can deploy the SSL certificate.

zmcertmgr deploycrt comm commercial.crt commercial_ca.crt

Finally, restart Carbonio CE.

zmcontrol restart

Your certificate should now be installed: verify the certificate details by running this command:

zmcertmgr viewdeployedcrt

Add a DKIM record to Carbonio CE Installation

This section provides directions to add a DKIM record to the DNS of the domain managed by a Carbonio CE installation.

DKIM in a nutshell

The DomainKeys Identified Mail (DKIM) is a method to verify that an e-mail was sent from a legitimate mail server. Each e-mail is marked with a digital signature that can be verified by the receiver.

Technically, a TXT record that identifies the SMTP server must be added to the domain’s DNS configuration.

See also

DKIM is an Internet Standard first defined in RFC 6376, later updated in RFC 8301 and RFC 8463.

Create a DKIM record

In order to create a new DKIM record, two steps are necessary. As usual, we are using mail.example.com in our scenario: replace it with the actual domain name.

Step 1: Generate DKIM record

Execute the following command to generate a new DKIM record.

# /opt/zextras/libexec/zmdkimkeyutil -a -d mail.example.com

The output will be similar to the following:

DKIM Data added to LDAP for domain mail.example.com with selector D43CB080-8FE0-11EC-88DF-9958FFC5EFF5
Public signature to enter into DNS:
D43CB080-8FE0-11EC-88DF-9958FFC5EFF5._domainkey IN TXT ( "v=DKIM1; k=rsa; ""p=MIIBIjANBgkqhkiG9w0BAQEFA
AOCAQ8AMIIBCgKCAQEA6fn7z208Gj/UVAL29CeKxhyHrRnals/qs4kWxnWuPK+ogDQjZoD0aUIv6QkUX6Y/KSYUd9qHEy1I7pSNIlyS
ecqeq/YsP5zXzoKD7WmLfE0PGIx0CEtsn4h4MJucm+LNVKziSPVzkVZ0rku15BaBO1bpFd7bvkXMffei3cc2zwrFmFSDVB5P84k1na+
5p1o4NBq3SDn8fks9r6""CJ7dAZQ3LazNmAgenMldkWC7tv+/25CStiz3QQ4GqCn4tp0VW3hWOQm6tRSe1yHEG10XT2cSieFM1w0GzB
XZZEedCK1POmFoOKwgqraxJtqiPdM7i+mjUOy7w1uqJa4fyxjbVp0QIDAQAB" ) ; ----- DKIM key D43CB080-8FE0-11EC-88D
F-9958FFC5EFF5 for mail.example.com

Step 2: Add DKIM record to DNS settings

Edit the DNS settings of the domain and create a new record as follows, using the output of the previous command.

  • Create a new record of type TXT with name D43CB080-8FE0-11EC-88DF-9958FFC5EFF5._domainkey

  • As value of the new record, copy and paste the string within the ( braces ) and make sure that the value does not contain any newline (that is, the value is written on one line):

    v=DKIM1; k=rsa; ""p=MIIBIjANBgkqhkiG9w0BAQEFA
    AOCAQ8AMIIBCgKCAQEA6fn7z208Gj/UVAL29CeKxhyHrRnals/qs4kWxnWuPK+ogDQjZoD0aUIv6QkUX6Y/KSYUd9qHEy1I7pSNIlyS
    ecqeq/YsP5zXzoKD7WmLfE0PGIx0CEtsn4h4MJucm+LNVKziSPVzkVZ0rku15BaBO1bpFd7bvkXMffei3cc2zwrFmFSDVB5P84k1na+
    5p1o4NBq3SDn8fks9r6""CJ7dAZQ3LazNmAgenMldkWC7tv+/25CStiz3QQ4GqCn4tp0VW3hWOQm6tRSe1yHEG10XT2cSieFM1w0GzB
    XZZEedCK1POmFoOKwgqraxJtqiPdM7i+mjUOy7w1uqJa4fyxjbVp0QIDAQAB"
    

    Warning

    Depending on the DNS, it is possible that you need to remove the double quotes, the white spaces, or both!

Test and Verify

There are several tests that can be carried out to verify that the DKIM has been added correctly to the domain DNS and works correctly to sign the outgoing e-mails.

TXT record test

To check that the TXT record has been added to the DNS, issue the following command from any Linux box.

# nslookup -type=txt D43CB080-8FE0-11EC-88DF-9958FFC5EFF5._domainkey.mail.example.com

Make sure that you use the same name used when creating the TXT record.

If the DKIM record has been added correctly, the output contains the record, starting with v=DKIM1. Otherwise, if the DKIM record has not been set correctly, or if there was some issue in retrieving it, you will not see the string v=DKIM1 in the output.

DKIM service enabled

The openDkim service must be running on the Carbonio CE installation for the outgoing e-mails to be correctly signed. This can be verified in the output of the command

# zmprov gs $(zmhostname)|grep -i service

must contain the line:

zimbraServiceEnabled: opendkim

E-mail signature test

To verify that an outgoing e-mail has been correctly signed, the easiest way is to send an e-mail from the domain to a third-party address. The e-mail receiver can then look at the source code of the e-mail (The option is usually called View e-mail source code, Show original, Show e-mail headers or similar in any e-mail client).

In the source code, you should see a line similar to the following:

tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1 ... dkim=pass (2048-bit key) header.d=mail.example.com

Make sure the actual domain name is present instead of mail.example.com.