TLS configuration parameters for Consul agent configuration files

This page provides reference information for TLS configuration parameters in a Consul agent configuration file.

TLS configuration parameters

This section documents all of the configuration settings that apply to Agent TLS. Agent TLS is used by the HTTP API, internal RPC, and gRPC/xDS interfaces. Some of these settings may also be applied automatically by auto_config or auto_encrypt.

Security Note: The Certificate Authority (CA) configured on the internal RPC interface (either explicitly by tls.internal_rpc or implicitly by tls.defaults) should be a private CA, not a public one. We recommend using a dedicated CA which should not be used with any other systems. Any certificate signed by the CA will be allowed to communicate with the cluster and a specially crafted certificate signed by the CA can be used to gain full access to Consul.

tls Added in Consul 1.12, for previous versions see Deprecated Options.
- defaults Provides default settings that will be applied to every interface unless explicitly overridden by tls.grpc, tls.https, or tls.internal_rpc.
  - ca_file This provides a file path to a PEM-encoded certificate authority. The certificate authority is used to check the authenticity of client and server connections with the appropriate verify_incoming or verify_outgoing flags.
  - ca_path This provides a path to a directory of PEM-encoded certificate authority files. These certificate authorities are used to check the authenticity of client and server connections with the appropriate verify_incoming or verify_outgoing flags.
  - cert_file This provides a file path to a PEM-encoded certificate. The certificate is provided to clients or servers to verify the agent's authenticity. It must be provided along with key_file.
  - key_file This provides a the file path to a PEM-encoded private key. The key is used with the certificate to verify the agent's authenticity. This must be provided along with cert_file.
  - tls_min_version This specifies the minimum supported version of TLS. The following values are accepted:
    - TLSv1_0
    - TLSv1_1
    - TLSv1_2 (default)
    - TLSv1_3
  - verify_server_hostname When set to true, Consul verifies the TLS certificate presented by the servers match the hostname server.<datacenter>.<domain>. By default this is false, and Consul does not verify the hostname of the certificate, only that it is signed by a trusted CA.
    WARNING: TLS 1.1 and lower are generally considered less secure and should not be used if possible.
    The following values are also valid, but only when using the deprecated top-level tls_min_version config, and will be removed in a future release:
    A warning message will appear if a deprecated value is specified.
  - tls_cipher_suites This specifies the list of supported ciphersuites as a comma-separated-list. Applicable to TLS 1.2 and below only. The list of all ciphersuites supported by Consul is available in the TLS configuration source code.
    Note: The ordering of cipher suites will not be guaranteed from Consul 1.11 onwards. See this post for details.
  - verify_incoming - If set to true, Consul requires that all incoming connections make use of TLS and that the client provides a certificate signed by a Certificate Authority from the ca_file or ca_path. By default, this is false, and Consul will not enforce the use of TLS or verify a client's authenticity.
  - verify_outgoing - If set to true, Consul requires that all outgoing connections from this agent make use of TLS and that the server provides a certificate that is signed by a Certificate Authority from the ca_file or ca_path. By default, this is false, and Consul will not make use of TLS for outgoing connections. This applies to clients and servers as both will make outgoing connections. This setting does not apply to the gRPC interface as Consul makes no outgoing connections on this interface. When set to true for the HTTPS interface, this parameter applies to watches, which operate by making HTTPS requests to the local agent.
- grpc Provides settings for the gRPC/xDS interface. To enable the gRPC interface you must define a port via ports.grpc_tls.
  - ca_file Overrides tls.defaults.ca_file.
  - ca_path Overrides tls.defaults.ca_path.
  - cert_file Overrides tls.defaults.cert_file.
  - key_file Overrides tls.defaults.key_file.
  - tls_min_version Overrides tls.defaults.tls_min_version.
  - tls_cipher_suites Overrides tls.defaults.tls_cipher_suites.
  - verify_incoming - Overrides tls.defaults.verify_incoming.
  - use_auto_cert - (Defaults to false) Enables or disables TLS on gRPC servers. Set to true to allow auto_encrypt TLS settings to apply to gRPC listeners. We recommend disabling TLS on gRPC servers if you are using auto_encrypt for other TLS purposes, such as enabling HTTPS.
- https Provides settings for the HTTPS interface. To enable the HTTPS interface you must define a port via ports.https.
  - ca_file Overrides tls.defaults.ca_file.
  - ca_path Overrides tls.defaults.ca_path.
  - cert_file Overrides tls.defaults.cert_file.
  - key_file Overrides tls.defaults.key_file.
  - tls_min_version Overrides tls.defaults.tls_min_version.
  - tls_cipher_suites Overrides tls.defaults.tls_cipher_suites.
  - verify_incoming - Overrides tls.defaults.verify_incoming.
  - verify_outgoing - Overrides tls.defaults.verify_outgoing.
- internal_rpc Provides settings for the internal "server" RPC interface configured by ports.server.
  - ca_file Overrides tls.defaults.ca_file.
  - ca_path Overrides tls.defaults.ca_path.
  - cert_file Overrides tls.defaults.cert_file.
  - key_file Overrides tls.defaults.key_file.
  - tls_min_version Overrides tls.defaults.tls_min_version.
  - tls_cipher_suites Overrides tls.defaults.tls_cipher_suites.
  - verify_incoming - Overrides tls.defaults.verify_incoming.
    Security Note: verify_incoming must be set to true to prevent anyone with access to the internal RPC port from gaining full access to the Consul cluster.
  - verify_outgoing Overrides tls.defaults.verify_outgoing.
    Security Note: Servers that specify verify_outgoing = true will always talk to other servers over TLS, but they still accept non-TLS connections to allow for a transition of all clients to TLS. Currently the only way to enforce that no client can communicate with a server unencrypted is to also enable verify_incoming which requires client certificates too.
  - verify_server_hostname Overrides tls.defaults.verify_server_hostname. When set to true, Consul verifies the TLS certificate presented by the servers match the hostname server.<datacenter>.<domain>. By default this is false, and Consul does not verify the hostname of the certificate, only that it is signed by a trusted CA.
    Security Note: verify_server_hostname must be set to true to prevent a compromised client from gaining full read and write access to all cluster data including all ACL tokens and service mesh CA root keys.
server_name When provided, this overrides the node_name for the TLS certificate. It can be used to ensure that the certificate name matches the hostname we declare.

Deprecated Options

The following options were deprecated in Consul 1.12, please use the tls stanza instead.

ca_file See: tls.defaults.ca_file.
ca_path See: tls.defaults.ca_path.
cert_file See: tls.defaults.cert_file.
key_file See: tls.defaults.key_file.
tls_min_version Added in Consul 0.7.4. See: tls.defaults.tls_min_version.
tls_cipher_suites Added in Consul 0.8.2. See: tls.defaults.tls_cipher_suites.
tls_prefer_server_cipher_suites Added in Consul 0.8.2. This setting will be ignored (see this post for details).
verify_incoming See: tls.defaults.verify_incoming.
verify_incoming_rpc See: tls.internal_rpc.verify_incoming.
verify_incoming_https See: tls.https.verify_incoming.
verify_outgoing See: tls.defaults.verify_outgoing.
verify_server_hostname See: tls.internal_rpc.verify_server_hostname.

Examples

The following examples demonstrate common agent TLS configuration patterns.

Secure mTLS configuration

All three verify options should be set as true to enable secure mTLS communication, enabling both encryption and authentication. Failing to set verify_incoming or verify_outgoing either in the interface-specific stanza (e.g. tls.internal_rpc, tls.https) or in tls.defaults results in TLS not being enabled at all, even when specifying a ca_file, cert_file, and key_file.

Review, especially, the use of the ports setting in the highlighted code lines.

datacenter = "east-aws"
data_dir = "/opt/consul"
log_level = "INFO"
node_name = "foobar"
server = true

addresses = {
  https = "0.0.0.0"
}
ports {
  https = 8501
}

tls {
  defaults {
    key_file = "/etc/pki/tls/private/my.key"
    cert_file = "/etc/pki/tls/certs/my.crt"
    ca_file = "/etc/pki/tls/certs/ca-bundle.crt"
    verify_incoming = true
    verify_outgoing = true
    verify_server_hostname = true
  }
}

{
  "datacenter": "east-aws",
  "data_dir": "/opt/consul",
  "log_level": "INFO",
  "node_name": "foobar",
  "server": true,
  "addresses": {
    "https": "0.0.0.0"
  },
  "ports": {
    "https": 8501
  },
  "tls": {
    "defaults": {
      "key_file": "/etc/pki/tls/private/my.key",
      "cert_file": "/etc/pki/tls/certs/my.crt",
      "ca_file": "/etc/pki/tls/certs/ca-bundle.crt",
      "verify_incoming": true,
      "verify_outgoing": true,
      "verify_server_hostname": true
    }
  }
}

Consul does not enable TLS for the HTTP or gRPC API unless the https port has been assigned a port number > 0. We recommend using 8501 for https as this default automatically works with some tooling.