Common Operations#
This section shows a few important commands used when working with Carbonio Mesh clusters and services.
Whenever executing a command using Carbonio Mesh interface, consul, the bootstrap token is required. Refer to Section Retrieve Bootstrap Token to learn how to obtain it and how to deal with it.
Retrieve Bootstrap Token#
The token is encrypted and stored in file
/etc/zextras/service-discover/cluster-credentials.tar.gpg and
can be retrieved with this command, which will output the token on the CLI
# gpg -qdo - /etc/zextras/service-discover/cluster-credentials.tar.gpg | tar xOf - consul-acl-secret.json | jq .SecretID -r
For simplicity you can put the token in a local variable as follows
# export CONSUL_HTTP_TOKEN=$(gpg -qdo - /etc/zextras/service-discover/cluster-credentials.tar.gpg | tar xOf - consul-acl-secret.json | jq .SecretID -r)
You can then check the password with command
# echo $CONSUL_HTTP_TOKEN
The password will remain in memory until you exit the CLI session, but you can explicitly delete it using command
# unset CONSUL_HTTP_TOKEN
Cluster Commands#
The following commands are used to inspect a cluster:
# consul members
Node Address Status Type Build Protocol DC Segment
server-example-com 10.10.10.12:8301 alive server 1.10.12 2 dc1 <all>
agent1-example-com 10.10.10.24:8301 alive client 1.10.12 2 dc1 <default>
A similar command is consul catalog nodes -detailed, which outputs the node’s ID, used to run Consul on a given node.
# consul force-leave agent1-example-com
Service Commands#
These commands allow to retrieve a list of services registered to a Consul cluster and to manipulate them.
# consul catalog services
carbonio-address-book
carbonio-address-book-sidecar-proxy
carbonio-auth
[...]
To query all services running on a given node, use
consul catalog services -node 7ea9631e. As argument
to -node you can provide either the node’s ID or name.
# consul services register /etc/zextras/service-discover/carbonio-mta.hcl
The /etc/zextras/service-discover/carbonio-mta.hcl is a
JSON file that contains all information required to set up a
service. The file must be a valid JSON file and must conform to
Cunsul’s specification. Discussion about the format and syntax
of that file is outside the scope of this page, please refer to
the official upstream documentation
for more information.
# consul services deregister -id=my-service-id
This command assumes that there is a registered service namend my-service
To deregister a service which has a configuration file (which is the case for Carbonio), simply delete the file and reload the agent on all nodes.
Other Commands#
To reload the consul agent on a node, execute
# consul reload
This is useful when you modify any configuration; the changes are picked up by the agent running on the node and propagated to the server.
To check log files of Carbonio Mesh, use the command
# journalctl -u service-discover
Hint
To follow log files in real time while they are emitted, add
the -f option at the end of the command.
Generally speaking, an intention is a mechanism that allow to control
communication between objects managed by consul. The list of
available intentions in Carbonio can be see issuing the
following command as the root user.
# consul intention list
See also
Full CLI reference for Consul is available on the official documentation.
Active Replica#
When you set up Carbonio HA, the following commands can prove useful to verify the status of the service.
Verify Configuration
zextras$ carbonio config get global brokers
Verify Endpoint Availability
zextras$ carbonio ha test 10.0.10.11:9092,10.0.10.12:9092,10.0.10.13:9092
Restart the HA service
zextras$ carbonio ha doRestartService module