HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul Home

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:

      • 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. Consul rejects an explicit tls_cipher_suites setting, including an empty string, when the same stanza has a TLS 1.3 minimum. Remove the setting before raising that stanza's minimum to TLS 1.3. Protocol stanzas with a TLS 1.3 minimum do not inherit cipher suites from tls.defaults. 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.

      • tls_ecdh_curves Specifies TLS key-exchange groups as a comma-separated string, not an array. Names are case-sensitive. Consul trims whitespace around each name. The supported values are:

        The Go-based agent TLS implementation supports all five groups. X25519MLKEM768 combines X25519 with ML-KEM-768 for hybrid post-quantum key exchange, which requires a TLS 1.3 handshake. Configuring groups accepts a minimum of TLSv1_2, TLSv1_3, TLS_AUTO, or an unspecified minimum, but not TLSv1_0 or TLSv1_1. An accepted configuration does not prove that a connection negotiates hybrid key exchange.

        Each protocol uses its explicit tls_ecdh_curves string when present. Otherwise, a protocol with a compatible minimum TLS version inherits a nonempty list from tls.defaults. Without an explicit or inherited list, an effective minimum of TLSv1_3 selects X25519MLKEM768,X25519. Otherwise, Go TLS defaults apply. An empty string in tls.defaults does not prevent this automatic selection.

        An explicitly empty per-protocol string overrides inheritance and skips Consul's automatic selection, leaving Go TLS defaults in effect. Those defaults can include hybrid groups. Do not use an empty string or remove this setting to disable post-quantum key exchange. Use an explicit classical list, such as "X25519", as described in Roll back post-quantum TLS.

        This setting does not enable TLS, replace certificate signatures with post-quantum signatures, or change certificate verification. Refer to Configure post-quantum TLS for component requirements and negotiated-group verification.

      • 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.

    • https Provides settings for the HTTPS interface. To enable the HTTPS interface you must define a port via ports.https.

    • internal_rpc Provides settings for the internal "server" RPC interface configured by ports.server.

  • 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.

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
  }
}

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.

Hybrid post-quantum key exchange

The following configuration fragments allow hybrid X25519MLKEM768 key exchange with classical X25519 fallback. A connection that selects X25519 does not use post-quantum key exchange. Both choices use TLS 1.3 in this example. Agent TLS exposes a minimum version setting, not a tls_max_version setting.

Merge these settings into your existing TLS configuration. Preserve your CA, certificate, private key, port, and certificate-verification settings, including verify_incoming, verify_outgoing, and verify_server_hostname. Remove explicit tls_cipher_suites settings in any stanza whose minimum you set to TLSv1_3: TLS 1.3 cipher suites are not configurable. Review protocol overrides because they take precedence over tls.defaults.

tls {
  defaults {
    tls_min_version = "TLSv1_3"
    tls_ecdh_curves  = "X25519MLKEM768,X25519"
  }
}

Use Consul binaries that support tls_ecdh_curves and TLS peers that support the selected groups and TLS version. Refer to Configure post-quantum TLS for requirements and verification, or Migrate to post-quantum TLS for staged adoption in an existing deployment.

Edit this page on GitHub