The default consul installation in XiVO uses the configuration file in /etc/consul/xivo/*.json. All files in this directory are installed with the package and should not be modified by the administrator. To use a different configuration, the adminstrator can add it’s own configuration file at another location and set the new configuration directory by creating a systemd unit drop-in file in the /etc/systemd/system/consul.service.d directory.

The default installation generates a master token that can be retrieved in /var/lib/consul/master_token. This master token will not be used if a new configuration is supplied.


The following environment variables can be overridden in a systemd unit drop-in file:

  • CONFIG_DIR: the consul configuration directory
  • WAIT_FOR_LEADER: should the “start” action wait for a leader ?

Example, in /etc/systemd/system/consul.service.d/custom.conf:


Agent mode

It is possible to run consul on another host and have the local consul node run as an agent only.

To get this kind of setup up and running, you will need to follow the following steps.

Downloading Consul

For a 32 bits system

wget --no-check-certificate

For a 64 bits system

wget --no-check-certificate

Installing Consul on a new host



mv consul /usr/bin/consul
mkdir -p /etc/consul/xivo
mkdir -p /var/lib/consul
adduser --quiet --system --group --no-create-home \
        --home /var/lib/consul consul

Copying the consul configuration from the XiVO to a new host

On the new consul host, modify /etc/consul/xivo/config.json to include to following lines.

"bind_addr": "",
"client_addr": "",
"advertise_addr": "<consul-host>"
# on the consul host
scp root@<xivo-host>:/lib/systemd/system/consul.service /lib/systemd/system
systemctl daemon-reload
scp -r root@<xivo-host>:/etc/consul /etc
scp -r root@<xivo-host>:/usr/share/xivo-certs /usr/share
consul agent -data-dir /var/lib/consul -config-dir /etc/consul/xivo/


To start consul with the systemd unit file, you may need to change owner and group (consul:consul) for all files inside /etc/consul, /usr/share/xivo-certs and /var/lib/consul

Adding the agent configuration

Create the file /etc/consul/agent/config.json with the following content

    "acl_datacenter": "<node_name>",
    "datacenter": "xivo",
    "server": false,
    "bind_addr": "",
    "advertise_addr": "<xivo_address>",
    "client_addr": "",
    "bootstrap": false,
    "rejoin_after_leave": true,
    "data_dir": "/var/lib/consul",
    "enable_syslog": true,
    "disable_update_check": true,
    "log_level": "INFO",
    "ports": {
        "dns": -1,
        "http": -1,
        "https": 8500
    "retry_join": [
    "cert_file": "/usr/share/xivo-certs/server.crt",
    "key_file": "/usr/share/xivo-certs/server.key"
  • node_name: Arbitrary name to give this node, xivo-paris for example.
  • remote_host: IP address of your new consul. Be sure the host is accessible from your XiVO and check the firewall. See the documentation here.
  • xivo_address: IP address of your xivo.

This file should be owned by consul user.

chown -R consul:consul /etc/consul/agent

Enabling the agent configuration

Add or modify /etc/systemd/system/consul.service.d/custom.conf to include the following lines:


Restart your consul server.

service consul restart

Updating the consul section of xivo-ctid

Add a file in /etc/xivo-ctid/conf.d/remote_consul.yml with the following content


  advertise_address: <xivo-ctid-host>
  check_url: http://<xivo-ctid-host>:9495/0.1/infos
  • xivo-ctid-host: Hostname to reach xivo-ctid