Certificates for Carbonio Mesh


The file /etc/zextras/service-discover/cluster-credentials.tar.gpg, which is a tar archive that has been encrypted with GPG, contains the credentials used by Carbonio Mesh. What’s in the tar archive

  • Using a bootstrap token
  • The internal CA for Carbonio Mesh and the associated private key
  • The keys for encryption


If the file /etc/zextras/service-discover/cluster-credentials.tar.gpg becomes compromised, the security of the whole infrastructure will be compromised as well.

Various administrative actions, such as installing and upgrading Carbonio, conducting pending-setups, and doing other small tasks involving Carbonio components, need the presence of the file containing the Carbonio Mesh credentials.

The aforementioned file is GPG-encrypted using a secret, which is just another password, and is only available by the root user. The secret is saved in /var/lib/service-discover/password. The pending-setups command and the Service Discover installation procedure both require the secret.

In order to access the  /var/lib/service-discover/password  file on a Multi-Server Carbonio, log in to any Carbonio Mesh Server, and then log in as root to your Single-Server Carbonio if you cannot remember the password.

It is important to regenerate Carbonio Mesh Secret in the event that you wish to alter the secret or you are required to change it (for instance, because it has been hacked, shared with or communicated to the incorrect people, or if one of the system administrators has left your firm).

Secret to Regenerating Carbonio Mesh

The reset index value, which is always an integer, is crucial information to be aware of in advance in case the secret needs to be updated.

Retrieve the reset index

Simply execute the command

# consul acl bootstrap

The output will always be similar to:

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

The reset index value* is the last bit of the output (reset index: 908): in our case 908, which is the current index and is needed in the procedure below.

Before trying the recovery, be aware that the Carbonio Mesh service will be unavailable for the whole process.

The process is the same for Single-Server and Multi-Server, however there are additional stages to complete on the Multi-Server.

Preliminary Tasks

In case of a Single-Server node, log in to it and skip to Step 1 below.

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

# carbonio prov gas service-discover

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

# wget -qO -

The output will be an IP address and a port, for example If this IP is different from the Directory Server’s, log in to the latter on ( We will denote this IP with LEADER_IP.


Even if you have installed multiple Carbonio Mesh Servers, only one is the leader.

Step 1. Wipe Old Credentials

The first task, to be executed as the service-discover user on the leader node, is to write the current reset index to a file, to allow a new ACL token to be generated. As described in the Scenario above, the value is 908 (change it according to the output you receive), so we need to execute:

# 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

Remove the following two files:

# rm /etc/zextras/service-discover/config.json
# rm /etc/zextras/service-discover/main.json

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 LEADER_IP --first-instance --password=MESH_SECRET

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  alive   server  1.9.3  2

A Single-Server has completed the procedure. Ensure that the new credentials are stored safely!

Multi-Server Tasks

On a Multi-Server, you need to carry out all the steps below on each of the other nodes.

Login to one node, then copy the credentials from the LEADER_IP.

# scp root@[LEADER_IP]:/etc/zextras/service-discover/cluster-credentials.tar.gpg \

Stop the service-discover service.

# systemctl stop service-discover

Remove the following two files:

# rm /etc/zextras/service-discover/config.json
# rm /etc/zextras/service-discover/main.json

Remove also all certificates related to service-discover.

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

Finally, run the Carbonio Mesh setup.

# service-discover setup $(hostname -i) --password=MESH_SECRET