Carbonio Mesh Credentials#
The credentials used by Carbonio Mesh are stored in file
/etc/zextras/service-discover/cluster-credentials.tar.gpg
,
which is a tar archive that has been encrypted with GPG. The tar
archive contains:
The bootstrap token
The Carbonio Mesh internal CA and its corresponding private key
The encryption keys
Warning
If the file
/etc/zextras/service-discover/cluster-credentials.tar.gpg
becomes compromised, the security of the whole infrastructure will
be compromised as well.
The file with the Carbonio Mesh credentials must be present and accessible during various administration activities: Carbonio CE setup and upgrade, when running pending-setups, and while carrying out other minor tasks that involve Carbonio CE components.
The file mentioned above is GPG-encrypted using a secret (which is
nothing more than another password), that is stored in
/var/lib/service-discover/password
and is accessible only by
the root
user. The secret is needed when running the
pending-setups command and during the Service Discover
installation wizard.
Hence, if you do not remember the password, log in as root
to your
Single-Server Carbonio CE, while if you are on a Multi-Server, log in to
any Carbonio Mesh Server, then read the
/var/lib/service-discover/password
file.
In case you want to change the secret, or you need to change it (for example because it has been compromised, shared with or sent to the wrong persons, or if one of the system administrators has left your company), it is necessary to Reset Carbonio Mesh credentials: in the remainder, you can find step-by-step directions for Single-Server and for Multi-Server
Reset Carbonio Mesh Credentials on Single-Server#
Please take into account that the Carbonio Mesh service will be offline for the whole duration of the procedure.
Before starting the procedure, we need to know important information. Log in to the Single-Server and execute command
# consul acl bootstrap
The command allows to retrieve the reset index value, which is needed during the reset procedure. 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: copy it or write it down.
Wipe Old Credentials#
The first task, to be executed as the service-discover
user, 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
Generate New Credentials#
The first task to be done is to define a new, robust password, which we put in a temporary variable, for improved security. Remember to store the password in a safe place, in case you need it in the future.
# read -s -p "Insert Mesh Password:" MESH_SECRET
Note
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.
When prompted, enter a password of your choice, then 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.
If the command succeeds, you can manually unset the password
# unset MESH_SECRET
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
Reset Carbonio Mesh Credentials on Multi-Server#
On a Multi-Server, before starting the procedure it is necessary to identify the Leader Node, on which to carry out some preliminary tasks, then wipe the old secret, generate the new one, and finally set up the other nodes by copying the credentials on the remaining nodes and restart the service.
Find Leader Node’s IP Address#
You need to identify the Carbonio Mesh leader node node and log into
it. While this is usually the Node on which the Directory Server is
installed, the actual leader might be different. to find the
correct IP, log in to a Directory Server node and issue the
command as the zextras
user
zextras$ carbonio prov gas service-discover
This will output all Carbonio Mesh servers: to make sure you are on the leader node, 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 172.16.0.12:8300. If this IP is different from the Directory Server’s, log in to the latter on 172.16.0.12.
Note
Even if you have installed multiple Carbonio Mesh Servers, only one is the leader.
Wipe Old Credentials#
The first task, to be executed as the service-discover
user, 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
Generate New Credentials#
The first task to be done is to define a new, robust password, which we put in a temporary variable, for improved security. Remember to store the password in a safe place, in case you need it in the future.
# read -s -p "Insert Mesh Password:" MESH_SECRET
Note
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.
When prompted, enter a password of your choice, then 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.
If the command succeeds, you can manually unset the password
# unset MESH_SECRET
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
Set up Other Nodes#
To complete the procedure, repeat these tasks on each of the other Nodes.
Login to one node, then copy the credentials from the leader Node.
# scp root@[LEADER_IP]:/etc/zextras/service-discover/cluster-credentials.tar.gpg \
/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: take the MESH_SECRET
password
defined on the leader node and put it in a variable
# read -s -p "Insert Mesh Password:" MESH_SECRET
When prompted, enter a password of your choice, then run the setup
# service-discover setup $(hostname -i) --password=$MESH_SECRET
If the command succeeds, you can manually unset the password
# unset MESH_SECRET