Consul on FreeBSD

This tutorial will walk you through the steps to install and configure a Consul Cluster running on FreeBSD 12.1. Consul is a distributed highly available solution used for service discovery and health checking, configuration management, and service mesh. Consul has a robust ecosystem with integrations into many other tools. FreeBSD is a Unix like operating system with many advanced features. I expect you already knew what Consul and FreeBSD are or you wouldn’t be reading this.

Please take a look at as they have great documentation on the use and design of Consul. Getting it running on FreeBSD is missing however.

Consul Architecture

Each host will need at minimum the following bind ports accessible

| Use | Default Port |
| DNS (TCP and UDP) | 8600 |
| HTTP (TCP) | 8500 |
| LAN Serf (TCP and UDP) | 8301 |
| WAN Serf (TCP and UDP) | 8302 |
| Server (TCP) | 8300 |

Consul uses a consensus protocol, based on Raft, to elect a leader for the cluster. It is recommended that you have three or five total servers per datacenter. Having an odd number helps the cluster form a consensus.

For this tutorial we will have three servers

| Hostname | IP |
| consul-01 | |
| consul-02 | |
| consul-03 | |

Step 1: Install Consul

This couldn’t be any easier

pkg install consul

You can verify the install by

# consul -v
Consul v1.7.2

Step 2: Configure rc.conf and config.json

Edit /etc/rc.conf to enable Consul at startup. Add the following line


Optional rc.conf settings include

consul_configtest (string): Set to yes to enable Consul config validation
Set to NO by default
consul_datadir (dir): Set dir to run consul in.
Default is "/var/db/consul"
consul_syslog_output_enable (bool): Set to YES to enable syslog output
Default is "NO". See daemon(8).
consul_syslog_output_tag (str): Set syslog tag if syslog enabled.
Default is "consul".
consul_syslog_output_priority (str): Set syslog priority if syslog enabled.
Default is "info".
consul_syslog_output_facility (str): Set to YES to enable syslog output

Now we need to make the directory where the Consul configuration file will live. On FreeBSD the Consul daemon expects the find the configuration file in /usr/local/etc/consul.d and the file to be named config.json

# mkdir /usr/local/etc/consul.d

Now create an encryption key for the cluster. Run consul keygen and save the output. We will use this in config.json as the value for the encrypt key.

Now edit /usr/local/etc/consul.d/config.json

On consul-01 my config file looks like

"dns_config": {
"enable_truncate": true,
"only_passing": true
"encrypt": "<mykey>",
"leave_on_terminate": true,
"rejoin_after_leave": true,
"server": true,
"ui": true,
"start_join": ["", "", "]

Save the file and run `consul validate /usr/local/etc/consul.d/config.json` to make sure everything looks good

Repeat this process on consul-02 and consul-03. Copy the config.json file makeing sure to edit the bind_addr and node_name for each server.

Step 3: Startup and Test

Time to start the server. Run the following on each server

service consul start

If all when well you can run

# service consul status
consul is running as pid 4324.

You can check the status of all members by running

# consul members
Node Address Status Type Build Protocol DC Segment
consul-01 alive server 1.7.2 2 dc1 <all>
consul-02 alive server 1.7.2 2 dc1 <all>
consul-03 alive server 1.7.2 2 dc1 <all>

You can also go to any of your servers via web browser and get to the Consul UI

That’s it for this tutorial. I just wanted to show how to get things up and running. There are a number of other tutorial out there on how to use Consul.

Thanks for reading



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store