How-to: Consul Command-line Configuration Guide

Introduction

There are two ways to pass configuration into Consul Agents:

• via the command-line (CLI) arguments
• via configuration files

Expected Outcome

In this article, we will explore exclusively how to use the command line, in case the user cannot or does not want to use configuration files.

Prerequisites

• Consul v1.0+

Overview

In order to configure Consul, you can use either configuration stored in files, or you can provide it inline as command-line arguments. Command-line arguments take precedence over configuration files, so this is a handy way of overriding defaults stored in a text config.

Procedures

Passing specific command-line options

For most configuration parameters, there are specific command-line options that allow for setting the wanted value. For example, to change the number of expected Consul servers before a bootstrap starts, you can pass -bootstrap-expect <NUMBER>.

Passing configuration file key-value pairs

You can also pass configuration fragments as command-line arguments. For example, instead of having an HCL config file that contains the following:

bootstrap_expect = 3

You can pass that configuration fragment via the -hcl parameter (more info here) in the following way:

-hcl='bootstrap_expect = 3'

You can pass as many fragments as needed. If a parameter is passed twice, the last occurrence takes precedence.

Note: if you wish to pass environment variables within these configuration fragments, make sure that you are using the correct combination of single quotes, double quotes and special character escaping. Specifics on that will depend on the shell from which you are launching the Consul binary.

Passing nested blocks of configuration file key-value pairs

Sometimes there are configuration entries that can only be passed as a configuration key-value pair. For example, auto_encrypt is such a configuration entry. If you wish to pass this as a command-line argument instead of a config file, you will need to use -hcl, and sometimes you will have to nest multiple configuration blocks.

In a standard HCL configuration file, nested configuration blocks are constructed around curly braces like this:

auto_encrypt {

    tls = true

    dns_san = ["agent1.domain.tld", "agent1.subdomain.somedomain.domain.tld"]

    ip_san = ["192.168.123.4", "10.23.45.67"]

}

There are two ways to translate this configuration block into command-line parameters. First option is to use just one argument for all nested parameters like so:

-hcl='auto_encrypt = {tls = true, dns_san = ["agent1.domain.tld", "agent1.subdomain.somedomain.domain.tld"], ip_san = ["192.168.123.4", "10.23.45.67"]
}'

The second way is to break down each nested element into a different command-line parameter like so:

-hcl='auto_encrypt = {tls = true}'
-hcl='auto_encrypt = {dns_san = ["agent1.domain.tld", "agent1.subdomain.somedomain.domain.tld"]
}'
-hcl='auto_encrypt = {ip_san = ["192.168.123.4", "10.23.45.67"]
}'

Additional Information: 

• Official Consul configuration documentation