In deep view
This section contains various rather advanced topics that are not required for a everyday use of Carbonio.
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. To have a look at the administration interface, for example to check out the configuration generated by Carbonio, you need first to create a new token, then to set up an SSH tunnel from the current workstation to the Carbonio 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
Zextras makes available to developers a couple of APIs to interact with Carbonio components. To read their documentation, follow the URLS:
Carbonio API is used to interact via SOAP with the main functions of Carbonio
Carbonio Files blob, for managing the uploading, downloading of BLOB files and links to them
Carbonio Files metadata metadata API
Deploy an SSL certificate
In this section we explain how to add an SSL/TLS certificate to a Carbonio installation, both a single server and a wildcard certificate.
This setup is mandatory if Carbonio 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 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
zextrasuser# 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.
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'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
zextrasuser# 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.
zmcontrol restart
Your certificate should now be installed: verify the certificate details by running this command:
zmcertmgr viewdeployedcrt
Add a DKIM record to Carbonio Installation
This section provides directions to add a DKIM record to the DNS of the domain managed by a Carbonio 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.
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
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.