- `replication` ((#acl_tokens_replication)) - The ACL token used to
authorize secondary datacenters with the primary datacenter for replication
operations. This token is required for servers outside the [`primary_datacenter`](#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/api/agent#update-acl-tokens) on each server. This token must have at least "read" permissions on ACL data but if ACL token replication is enabled then it must have "write" permissions. This also enables Connect replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data.
~> **Warning:** When enabling ACL token replication on the secondary datacenter,
policies and roles already present in the secondary datacenter will be lost. For
production environments, consider configuring ACL replication in your initial
datacenter bootstrapping process.
- `managed_service_provider` ((#acl_tokens_managed_service_provider)) <EnterpriseAlert inline /> - An
array of ACL tokens used by Consul managed service providers for cluster operations.
- `acl_datacenter` - **This field is deprecated in Consul 1.4.0. See the [`primary_datacenter`](#primary_datacenter) field instead.**
This designates the datacenter which is authoritative for ACL information. It must be provided to enable ACLs. All servers and datacenters must agree on the ACL datacenter. Setting it on the servers is all you need for cluster-level enforcement, but for the APIs to forward properly from the clients,
it must be set on them too. In Consul 0.8 and later, this also enables agent-level enforcement
of ACLs. Please review the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details.
- `acl_default_policy` ((#acl_default_policy_legacy)) - **Deprecated in Consul 1.4.0. See the [`acl.default_policy`](#acl_default_policy) field instead.**
Either "allow" or "deny"; defaults to "allow". The default policy controls the
behavior of a token when there is no matching rule. In "allow" mode, ACLs are a
denylist: any operation not specifically prohibited is allowed. In "deny" mode,
ACLs are an allowlist: any operation not specifically allowed is blocked. **Note**:
this will not take effect until you've set `primary_datacenter` to enable ACL support.
- `acl_down_policy` ((#acl_down_policy_legacy)) - **Deprecated in Consul
1.4.0. See the [`acl.down_policy`](#acl_down_policy) field instead.** Either "allow",
"deny", "extend-cache" or "async-cache"; "extend-cache" is the default. In the
case that the policy for a token cannot be read from the [`primary_datacenter`](#primary_datacenter)
or leader node, the down policy is applied. In "allow" mode, all actions are permitted,
"deny" restricts all operations, and "extend-cache" allows any cached ACLs to be
used, ignoring their TTL values. If a non-cached ACL is used, "extend-cache" acts
like "deny". The value "async-cache" acts the same way as "extend-cache" but performs
updates asynchronously when ACL is present but its TTL is expired, thus, if latency
is bad between ACL authoritative and other datacenters, latency of operations is
in Consul 1.4.0. See the [`acl.tokens.replication`](#acl_tokens_replication) field
instead.** Only used for servers outside the [`primary_datacenter`](#primary_datacenter)
running Consul 0.7 or later. When provided, this will enable [ACL replication](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters)
using this ACL replication using this token to retrieve and replicate the ACLs
to the non-authoritative local datacenter. In Consul 0.9.1 and later you can enable
ACL replication using [`acl.enable_token_replication`](#acl_enable_token_replication) and then
set the token later using the [agent token API](/api/agent#update-acl-tokens)
on each server. If the `acl_replication_token` is set in the config, it will automatically
set [`acl.enable_token_replication`](#acl_enable_token_replication) to true for backward compatibility.
If there's a partition or other outage affecting the authoritative datacenter, and the
[`acl_down_policy`](/docs/agent/options#acl_down_policy) is set to "extend-cache", tokens not
in the cache can be resolved during the outage using the replicated set of ACLs.
- `acl_token` ((#acl_token_legacy)) - **Deprecated in Consul 1.4.0. See
the [`acl.tokens.default`](#acl_tokens_default) field instead.** When provided,
the agent will use this token when making requests to the Consul servers. Clients
can override this token on a per-request basis by providing the "?token" query
parameter. When not provided, the empty token, which maps to the 'anonymous' ACL
policy, is used.
- `acl_ttl` ((#acl_ttl_legacy)) - **Deprecated in Consul 1.4.0. See the
[`acl.token_ttl`](#acl_token_ttl) field instead.**Used to control Time-To-Live
caching of ACLs. By default, this is 30 seconds. This setting has a major performance
impact: reducing it will cause more frequent refreshes while increasing it reduces
the number of refreshes. However, because the caches are not actively invalidated,
ACL policy may be stale up to the TTL value.
- `addresses` - This is a nested object that allows setting
bind addresses. In Consul 1.0 and later these can be set to a space-separated list
of addresses to bind to, or a [go-sockaddr] template that can potentially resolve to multiple addresses.
`http`, `https` and `grpc` all support binding to a Unix domain socket. A
socket can be specified in the form `unix:///path/to/socket`. A new domain
socket will be created at the given path. If the specified file path already
exists, Consul will attempt to clear the file and create the domain socket
in its place. The permissions of the socket file are tunable via the
[`unix_sockets` config construct](#unix_sockets).
When running Consul agent commands against Unix socket interfaces, use the
`-http-addr` argument to specify the path to the socket. You can also place
the desired values in the `CONSUL_HTTP_ADDR` environment variable.
For TCP addresses, the environment variable value should be an IP address
_with the port_. For example: `10.0.0.1:8500` and not `10.0.0.1`. However,
ports are set separately in the [`ports`](#ports) structure when
defining them in a configuration file.
The following keys are valid:
- `dns` - The DNS server. Defaults to `client_addr`
- `http` - The HTTP API. Defaults to `client_addr`
- `https` - The HTTPS API. Defaults to `client_addr`
- `grpc` - The gRPC API. Defaults to `client_addr`
- `advertise_addr` Equivalent to the [`-advertise` command-line flag](#_advertise).
- `advertise_addr_ipv4` This was added together with [`advertise_addr_ipv6`](#advertise_addr_ipv6) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery.
- `advertise_addr_ipv6` This was added together with [`advertise_addr_ipv4`](#advertise_addr_ipv4) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery.
- `advertise_addr_wan` Equivalent to the [`-advertise-wan` command-line flag](#_advertise-wan).
- `advertise_addr_wan_ipv4` This was added together with [`advertise_addr_wan_ipv6`](#advertise_addr_wan_ipv6) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery.
- `advertise_addr_wan_ipv6` This was added together with [`advertise_addr_wan_ipv4`](#advertise_addr_wan_ipv4) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery.
- `advertise_reconnect_timeout` This is a per-agent setting of the [`reconnect_timeout`](#reconnect_timeout) parameter.
This agent will advertise to all other nodes in the cluster that after this timeout, the node may be completely
removed from the cluster. This may only be set on client agents and if unset then other nodes will use the main
`reconnect_timeout` setting when determining when this node may be removed from the cluster.
- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](#_alt_domain)
- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](#_serf_lan_bind).
This is an IP address, not to be confused with [`ports.serf_lan`](#serf_lan_port).
- `serf_lan_allowed_cidrs` ((#serf_lan_allowed_cidrs)) Equivalent to the [`-serf-lan-allowed-cidrs` command-line flag](#_serf_lan_allowed_cidrs).
- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](#_serf_wan_bind).
- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](#_serf_wan_allowed_cidrs).
- `audit` <EnterpriseAlert inline /> - Added in Consul 1.8, the audit object allow users to enable auditing
and configure a sink and filters for their audit logs. For more information, review the [audit log tutorial](https://learn.hashicorp.com/tutorials/consul/audit-logging).
```hcl
audit {
enabled = true
sink "My sink" {
type = "file"
format = "json"
path = "data/audit/audit.json"
delivery_guarantee = "best-effort"
rotate_duration = "24h"
rotate_max_files = 15
rotate_bytes = 25165824
}
}
```
The following sub-keys are available:
- `enabled` - Controls whether Consul logs out each time a user
performs an operation. ACLs must be enabled to use this feature. Defaults to `false`.
- `sink` - This object provides configuration for the destination to which
Consul will log auditing events. Sink is an object containing keys to sink objects, where the key is the name of the sink.
- `type` - Type specifies what kind of sink this is.
The following keys are valid:
- `file` - Currently only file sinks are available, they take the following keys.
- `format` - Format specifies what format the events will
be emitted with.
The following keys are valid:
- `json` - Currently only json events are offered.
- `path` - The directory and filename to write audit events to.
- `delivery_guarantee` - Specifies
the rules governing how audit events are written.
The following keys are valid:
- `best-effort` - Consul only supports `best-effort` event delivery.
- `mode` - The permissions to set on the audit log files.
- `rotate_duration` - Specifies the
interval by which the system rotates to a new log file. At least one of `rotate_duration` or `rotate_bytes`
must be configured to enable audit logging.
- `rotate_max_files` - Defines the
limit that Consul should follow before it deletes old log files.
- `rotate_bytes` - Specifies how large an
individual log file can grow before Consul rotates to a new file. At least one of `rotate_bytes` or
`rotate_duration` must be configured to enable audit logging.
- `autopilot` Added in Consul 0.8, this object allows a
number of sub-keys to be set which can configure operator-friendly settings for
Consul servers. When these keys are provided as configuration, they will only be
respected on bootstrapping. If they are not provided, the defaults will be used.
In order to change the value of these options after bootstrapping, you will need
to use the [Consul Operator Autopilot](/commands/operator/autopilot)
command. For more information about Autopilot, review the [Autopilot tutorial](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations).
The following sub-keys are available:
- `cleanup_dead_servers` - This controls the
automatic removal of dead server nodes periodically and whenever a new server
is added to the cluster. Defaults to `true`.
- `last_contact_threshold` - Controls the
maximum amount of time a server can go without contact from the leader before
being considered unhealthy. Must be a duration value such as `10s`. Defaults
to `200ms`.
- `max_trailing_logs` - Controls the maximum number
of log entries that a server can trail the leader by before being considered
unhealthy. Defaults to 250.
- `min_quorum` - Sets the minimum number of servers necessary
in a cluster before autopilot can prune dead servers. There is no default.
- `server_stabilization_time` - Controls
the minimum amount of time a server must be stable in the 'healthy' state before
being added to the cluster. Only takes effect if all servers are running Raft
protocol version 3 or higher. Must be a duration value such as `30s`. Defaults
corresponding to the NIST P-\* curves of the same name.
- `private_key_type = rsa`: `2048, 4096`
- `datacenter` Equivalent to the [`-datacenter` command-line flag](#_datacenter).
- `data_dir` Equivalent to the [`-data-dir` command-line flag](#_data_dir).
- `disable_anonymous_signature` Disables providing an anonymous
signature for de-duplication with the update check. See [`disable_update_check`](#disable_update_check).
- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](#_disable_host_node_id).
- `disable_http_unprintable_char_filter` Defaults to false. Consul 1.0.3 fixed a potential security vulnerability where malicious users could craft KV keys with unprintable chars that would confuse operators using the CLI or UI into taking wrong actions. Users who had data written in older versions of Consul that did not have this restriction will be unable to delete those values by default in 1.0.3 or later. This setting enables those users to **temporarily** disable the filter such that delete operations can work on those keys again to get back to a healthy state. It is strongly recommended that this filter is not disabled permanently as it exposes the original security vulnerability.
- `disable_remote_exec` Disables support for remote execution. When set to true, the agent will ignore
any incoming remote exec requests. In versions of Consul prior to 0.8, this defaulted
to false. In Consul 0.8 the default was changed to true, to make remote exec opt-in
instead of opt-out.
- `disable_update_check` Disables automatic checking for security bulletins and new version releases. This is disabled in Consul Enterprise.
- `discard_check_output` Discards the output of health checks before storing them. This reduces the number of writes to the Consul raft log in environments where health checks have volatile output like timestamps, process ids, ...
- `discovery_max_stale` - Enables stale requests for all service discovery HTTP endpoints. This is
equivalent to the [`max_stale`](#max_stale) configuration for DNS requests. If this value is zero (default), all service discovery HTTP endpoints are forwarded to the leader. If this value is greater than zero, any Consul server can handle the service discovery request. If a Consul server is behind the leader by more than `discovery_max_stale`, the query will be re-evaluated on the leader to get more up-to-date results. Consul agents also add a new `X-Consul-Effective-Consistency` response header which indicates if the agent did a stale read. `discover-max-stale` was introduced in Consul 1.0.7 as a way for Consul operators to force stale requests from clients at the agent level, and defaults to zero which matches default consistency behavior in earlier Consul versions.
- `dns_config` This object allows a number of sub-keys
to be set which can tune how DNS queries are serviced. Check the tutorial on [DNS caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) for more detail.
The following sub-keys are available:
- `allow_stale` - Enables a stale query for DNS information.
This allows any Consul server, rather than only the leader, to service the request.
The advantage of this is you get linear read scalability with Consul servers.
In versions of Consul prior to 0.7, this defaulted to false, meaning all requests
are serviced by the leader, providing stronger consistency but less throughput
and higher latency. In Consul 0.7 and later, this defaults to true for better
utilization of available servers.
- `max_stale` - When [`allow_stale`](#allow_stale) is
specified, this is used to limit how stale results are allowed to be. If a Consul
server is behind the leader by more than `max_stale`, the query will be re-evaluated
on the leader to get more up-to-date results. Prior to Consul 0.7.1 this defaulted
to 5 seconds; in Consul 0.7.1 and later this defaults to 10 years ("87600h")
which effectively allows DNS queries to be answered by any server, no matter
how stale. In practice, servers are usually only milliseconds behind the leader,
so this lets Consul continue serving requests in long outage scenarios where
no leader can be elected.
- `node_ttl` - By default, this is "0s", so all node lookups
are served with a 0 TTL value. DNS caching for node lookups can be enabled by
setting this value. This should be specified with the "s" suffix for second or
"m" for minute.
- `service_ttl` - This is a sub-object which allows
for setting a TTL on service lookups with a per-service policy. The "\*" wildcard
service can be used when there is no specific policy available for a service.
By default, all services are served with a 0 TTL value. DNS caching for service
lookups can be enabled by setting this value.
- `enable_truncate` - If set to true, a UDP DNS
query that would return more than 3 records, or more than would fit into a valid
UDP response, will set the truncated flag, indicating to clients that they should
re-query using TCP to get the full set of records.
- `only_passing` - If set to true, any nodes whose
health checks are warning or critical will be excluded from DNS results. If false,
the default, only nodes whose health checks are failing as critical will be excluded.
For service lookups, the health checks of the node itself, as well as the service-specific
checks are considered. For example, if a node has a health check that is critical
then all services on that node will be excluded because they are also considered
critical.
- `recursor_strategy` - If set to `sequential`, Consul will query recursors in the
order listed in the [`recursors`](#recursors) option. If set to `random`,
Consul will query an upstream DNS resolvers in a random order. Defaults to
`sequential`.
- `recursor_timeout` - Timeout used by Consul when
recursively querying an upstream DNS server. See [`recursors`](#recursors) for more details. Default is 2s. This is available in Consul 0.7 and later.
- `disable_compression` - If set to true, DNS
responses will not be compressed. Compression was added and enabled by default
in Consul 0.7.
- `udp_answer_limit` - Limit the number of resource
records contained in the answer section of a UDP-based DNS response. This parameter
applies only to UDP DNS queries that are less than 512 bytes. This setting is
deprecated and replaced in Consul 1.0.7 by [`a_record_limit`](#a_record_limit).
- `a_record_limit` - Limit the number of resource
records contained in the answer section of a A, AAAA or ANY DNS response (both
TCP and UDP). When answering a question, Consul will use the complete list of
matching hosts, shuffle the list randomly, and then limit the number of answers
to `a_record_limit` (default: no limit). This limit does not apply to SRV records.
In environments where [RFC 3484 Section 6](https://tools.ietf.org/html/rfc3484#section-6) Rule 9
is implemented and enforced (i.e. DNS answers are always sorted and
therefore never random), clients may need to set this value to `1` to
preserve the expected randomized distribution behavior (note:
[RFC 3484](https://tools.ietf.org/html/rfc3484) has been obsoleted by
[RFC 6724](https://tools.ietf.org/html/rfc6724) and as a result it should
be increasingly uncommon to need to change this value with modern
resolvers).
- `enable_additional_node_meta_txt` - When set to true, Consul
will add TXT records for Node metadata into the Additional section of the DNS responses for several query types such as SRV queries. When set to false those records are not emitted. This does not impact the behavior of those same TXT records when they would be added to the Answer section of the response like when querying with type TXT or ANY. This defaults to true.
- `soa` Allow to tune the setting set up in SOA. Non specified
values fallback to their default values, all values are integers and expressed
as seconds.
The following settings are available:
- `expire` ((#soa_expire)) - Configure SOA Expire duration in seconds,
default value is 86400, ie: 24 hours.
- `min_ttl` ((#soa_min_ttl)) - Configure SOA DNS minimum TTL. As explained
in [RFC-2308](https://tools.ietf.org/html/rfc2308) this also controls negative
cache TTL in most implementations. Default value is 0, ie: no minimum delay
or negative TTL.
- `refresh` ((#soa_refresh)) - Configure SOA Refresh duration in seconds,
default value is `3600`, ie: 1 hour.
- `retry` ((#soa_retry)) - Configures the Retry duration expressed
in seconds, default value is 600, ie: 10 minutes.
- `use_cache` ((#dns_use_cache)) - When set to true, DNS resolution will
use the agent cache described in [agent caching](/api/features/caching).
This setting affects all service and prepared queries DNS requests. Implies [`allow_stale`](#allow_stale)
- `cache_max_age` ((#dns_cache_max_age)) - When [use_cache](#dns_use_cache)
is enabled, the agent will attempt to re-fetch the result from the servers if
the cached value is older than this duration. See: [agent caching](/api/features/caching).
**Note** that unlike the `max-age` HTTP header, a value of 0 for this field is
equivalent to "no max age". To get a fresh value from the cache use a very small value
of `1ns` instead of 0.
- `prefer_namespace` ((#dns_prefer_namespace)) <EnterpriseAlert inline /> **Deprecated in
Consul 1.11. Use the [canonical DNS format](/docs/discovery/dns#namespaced-partitioned-services) instead.** -
When set to true, in a DNS query for a service, the label between the domain
and the `service` label will be treated as a namespace name instead of a datacenter.
When set to false, the default, the behavior will be the same as non-Enterprise
versions and will assume the label is the datacenter. See: [this section](/docs/discovery/dns#namespaced-services)
for more details.
- `domain` Equivalent to the [`-domain` command-line flag](#_domain).
- `enable_acl_replication` **Deprecated in Consul 1.11. Use the [`acl.enable_token_replication`](#acl_enable_token_replication) field instead.**
When set on a Consul server, enables ACL replication without having to set
the replication token via [`acl_replication_token`](#acl_replication_token). Instead, enable ACL replication
and then introduce the token using the [agent token API](/api/agent#update-acl-tokens) on each server.
See [`acl_replication_token`](#acl_replication_token) for more details.
~> **Warning:** When enabling ACL token replication on the secondary datacenter,
policies and roles already present in the secondary datacenter will be lost. For
production environments, consider configuring ACL replication in your initial
datacenter bootstrapping process.
- `enable_agent_tls_for_checks` When set, uses a subset of the agent's TLS configuration (`key_file`,
`cert_file`, `ca_file`, `ca_path`, and `server_name`) to set up the client for HTTP or gRPC health checks. This allows services requiring 2-way TLS to be checked using the agent's credentials. This was added in Consul 1.0.1 and defaults to false.
- `enable_central_service_config` When set, the Consul agent will look for any
[centralized service configuration](/docs/agent/config-entries)
that match a registering service instance. If it finds any, the agent will merge the centralized defaults with the service instance configuration. This allows for things like service protocol or proxy configuration to be defined centrally and inherited by any affected service registrations.
This defaults to `false` in versions of Consul prior to 1.9.0, and defaults to `true` in Consul 1.9.0 and later.
- `enable_debug` When set, enables some additional debugging features. Currently, this is only used to
access runtime profiling HTTP endpoints, which are available with an `operator:read` ACL regardless of the value of `enable_debug`.
- `enable_script_checks` Equivalent to the [`-enable-script-checks` command-line flag](#_enable_script_checks).
ACLs must be enabled for agents and the `enable_script_checks` option must be set to `true` to enable script checks in Consul 0.9.0 and later. See [Registering and Querying Node Information](/docs/security/acl/acl-rules#registering-and-querying-node-information) for related information.
~> **Security Warning:** Enabling script checks in some configurations may introduce a known remote execution vulnerability targeted by malware. We strongly recommend `enable_local_script_checks` instead. Refer to the following article for additional guidance: [_Protecting Consul from RCE Risk in Specific Configurations_](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations)
for more details.
- `enable_local_script_checks` Equivalent to the [`-enable-local-script-checks` command-line flag](#_enable_local_script_checks).
- `enable_syslog` Equivalent to the [`-syslog` command-line flag](#_syslog).
- `encrypt` Equivalent to the [`-encrypt` command-line flag](#_encrypt).
- `encrypt_verify_incoming` - This is an optional
parameter that can be used to disable enforcing encryption for incoming gossip
in order to upshift from unencrypted to encrypted gossip on a running cluster.
See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster)
for more information. Defaults to true.
- `encrypt_verify_outgoing` - This is an optional
parameter that can be used to disable enforcing encryption for outgoing gossip
in order to upshift from unencrypted to encrypted gossip on a running cluster.
See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster)
should be used, but this option is useful for removing access to HTTP API endpoints
completely, or on specific agents. This is available in Consul 0.9.0 and later.
- `response_headers` This object allows adding headers to the HTTP API and UI responses. For example, the following config can be used to enable [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) on the HTTP API endpoints:
```json
{
"http_config": {
"response_headers": {
"Access-Control-Allow-Origin": "*"
}
}
}
```
- `allow_write_http_from` This object is a list of networks in CIDR notation (eg "127.0.0.0/8") that are allowed to call the agent write endpoints. It defaults to an empty list, which means all networks are allowed. This is used to make the agent read-only, except for select ip ranges. - To block write calls from anywhere, use `[ "255.255.255.255/32" ]`. - To only allow write calls from localhost, use `[ "127.0.0.0/8" ]` - To only allow specific IPs, use `[ "10.0.0.1/32", "10.0.0.2/32" ]`
- `use_cache` ((#http_config_use_cache)) Defaults to true. If disabled, the agent won't be using [agent caching](/api/features/caching) to answer the request. Even when the url parameter is provided.
- `max_header_bytes` This setting controls the maximum number of bytes the consul http server will read parsing the request header's keys and values, including the request line. It does not limit the size of the request body. If zero, or negative, http.DefaultMaxHeaderBytes is used, which equates to 1 Megabyte.
- `leave_on_terminate` If enabled, when the agent receives a TERM signal, it will send a `Leave` message to the rest of the cluster and gracefully leave. The default behavior for this feature varies based on whether or not the agent is running as a client or a server (prior to Consul 0.7 the default value was unconditionally set to `false`). On agents in client-mode, this defaults to `true` and for agents in server-mode, this defaults to `false`.
- `license_path` <EnterpriseAlert inline /> This specifies the path to a file that contains the Consul Enterprise license. Alternatively the license may also be specified in either the `CONSUL_LICENSE` or `CONSUL_LICENSE_PATH` environment variables. See the [licensing documentation](/docs/enterprise/license/overview) for more information about Consul Enterprise license management. Added in versions 1.10.0, 1.9.7 and 1.8.13. Prior to version 1.10.0 the value may be set for all agents to facilitate forwards compatibility with 1.10 but will only actually be used by client agents.
- `limits` Available in Consul 0.9.3 and later, this is a nested
object that configures limits that are enforced by the agent. Prior to Consul 1.5.2,
this only applied to agents in client mode, not Consul servers. The following parameters
are available:
- `http_max_conns_per_client` - Configures a limit of how many concurrent TCP connections a single client IP address is allowed to open to the agent's HTTP(S) server. This affects the HTTP(S) servers in both client and server agents. Default value is `200`.
- `https_handshake_timeout` - Configures the limit for how long the HTTPS server in both client and server agents will wait for a client to complete a TLS handshake. This should be kept conservative as it limits how many connections an unauthenticated attacker can open if `verify_incoming` is being using to authenticate clients (strongly recommended in production). Default value is `5s`.
- `rpc_handshake_timeout` - Configures the limit for how long servers will wait after a client TCP connection is established before they complete the connection handshake. When TLS is used, the same timeout applies to the TLS handshake separately from the initial protocol negotiation. All Consul clients should perform this immediately on establishing a new connection. This should be kept conservative as it limits how many connections an unauthenticated attacker can open if `verify_incoming` is being using to authenticate clients (strongly recommended in production). When `verify_incoming` is true on servers, this limits how long the connection socket and associated goroutines will be held open before the client successfully authenticates. Default value is `5s`.
- `rpc_max_conns_per_client` - Configures a limit of how many concurrent TCP connections a single source IP address is allowed to open to a single server. It affects both clients connections and other server connections. In general Consul clients multiplex many RPC calls over a single TCP connection so this can typically be kept low. It needs to be more than one though since servers open at least one additional connection for raft RPC, possibly more for WAN federation when using network areas, and snapshot requests from clients run over a separate TCP conn. A reasonably low limit significantly reduces the ability of an unauthenticated attacker to consume unbounded resources by holding open many connections. You may need to increase this if WAN federated servers connect via proxies or NAT gateways or similar causing many legitimate connections from a single source IP. Default value is `100` which is designed to be extremely conservative to limit issues with certain deployment patterns. Most deployments can probably reduce this safely. 100 connections on modern server hardware should not cause a significant impact on resource usage from an unauthenticated attacker though.
- `rpc_rate` - Configures the RPC rate limiter on Consul _clients_ by setting the maximum request rate that this agent is allowed to make for RPC requests to Consul servers, in requests per second. Defaults to infinite, which disables rate limiting.
- `rpc_max_burst` - The size of the token bucket used to recharge the RPC rate limiter on Consul _clients_. Defaults to 1000 tokens, and each token is good for a single RPC call to a Consul server. See https://en.wikipedia.org/wiki/Token_bucket for more details about how token bucket rate limiters operate.
- `kv_max_value_size` - **(Advanced)** Configures the maximum number of bytes for a kv request body to the [`/v1/kv`](/api/kv) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. This option affects the txn endpoint too, but Consul 1.7.2 introduced `txn_max_req_len` which is the preferred way to set the limit for the txn endpoint. If both limits are set, the higher one takes precedence.
- `txn_max_req_len` - **(Advanced)** Configures the maximum number of bytes for a transaction request body to the [`/v1/txn`](/api/txn) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration.
- `log_file` Equivalent to the [`-log-file` command-line flag](#_log_file).
- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](#_log_rotate_duration).
- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](#_log_rotate_bytes).
- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](#_log_rotate_max_files).
- `log_level` Equivalent to the [`-log-level` command-line flag](#_log_level).
- `log_json` Equivalent to the [`-log-json` command-line flag](#_log_json).
- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](#_default_query_time).
- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](#_max_query_time).
- `node_id` Equivalent to the [`-node-id` command-line flag](#_node_id).
- `node_name` Equivalent to the [`-node` command-line flag](#_node).
- `node_meta` Available in Consul 0.7.3 and later, This object allows associating arbitrary metadata key/value pairs with the local node, which can then be used for filtering results from certain catalog endpoints. See the [`-node-meta` command-line flag](#_node_meta) for more information.
```json
{
"node_meta": {
"instance_type": "t2.medium"
}
}
```
- `partition` <EnterpriseAlert inline /> - This flag is used to set
the name of the admin partition the agent belongs to. An agent can only join
and communicate with other agents within its admin partition. Review the
[Admin Partitions documentation](/docs/enterprise/admin-partitions) for more
details. By default, this is an empty string, which is the `default` admin
partition. This cannot be set on a server agent.
~> **Warning:** The `partition` option cannot be used either the
[`segment`](#segment-2) option or [`-segment`](#_segment) flag.
- `performance` Available in Consul 0.7 and later, this is a nested object that allows tuning the performance of different subsystems in Consul. See the [Server Performance](/docs/install/performance) documentation for more details. The following parameters are available:
- `leave_drain_time` - A duration that a server will dwell during a graceful leave in order to allow requests to be retried against other Consul servers. Under normal circumstances, this can prevent clients from experiencing "no leader" errors when performing a rolling update of the Consul servers. This was added in Consul 1.0. Must be a duration value such as 10s. Defaults to 5s.
- `raft_multiplier` - An integer multiplier used by Consul servers to scale key Raft timing parameters. Omitting this value or setting it to 0 uses default timing described below. Lower values are used to tighten timing and increase sensitivity while higher values relax timings and reduce sensitivity. Tuning this affects the time it takes Consul to detect leader failures and to perform leader elections, at the expense of requiring more network and CPU resources for better performance.
By default, Consul will use a lower-performance timing that's suitable
for [minimal Consul servers](/docs/install/performance#minimum), currently equivalent
to setting this to a value of 5 (this default may be changed in future versions of Consul,
depending if the target minimum server profile changes). Setting this to a value of 1 will
configure Raft to its highest-performance mode, equivalent to the default timing of Consul
prior to 0.7, and is recommended for [production Consul servers](/docs/install/performance#production).
See the note on [last contact](/docs/install/performance#production-server-requirements) timing for more
details on tuning this parameter. The maximum allowed value is 10.
- `rpc_hold_timeout` - A duration that a client
or server will retry internal RPC requests during leader elections. Under normal
circumstances, this can prevent clients from experiencing "no leader" errors.
This was added in Consul 1.0. Must be a duration value such as 10s. Defaults
to 7s.
- `pid_file` Equivalent to the [`-pid-file` command line flag](#_pid_file).
- `ports` This is a nested object that allows setting the bind ports for the following keys:
- `dns` ((#dns_port)) - The DNS server, -1 to disable. Default 8600.
TCP and UDP.
- `http` ((#http_port)) - The HTTP API, -1 to disable. Default 8500.
TCP only.
- `https` ((#https_port)) - The HTTPS API, -1 to disable. Default -1
(disabled). **We recommend using `8501`** for `https` by convention as some tooling
will work automatically with this.
- `grpc` ((#grpc_port)) - The gRPC API, -1 to disable. Default -1 (disabled).
**We recommend using `8502`** for `grpc` by convention as some tooling will work
automatically with this. This is set to `8502` by default when the agent runs
in `-dev` mode. Currently gRPC is only used to expose Envoy xDS API to Envoy
proxies.
- `serf_lan` ((#serf_lan_port)) - The Serf LAN port. Default 8301. TCP
and UDP. Equivalent to the [`-serf-lan-port` command line flag](#_serf_lan_port).
- `serf_wan` ((#serf_wan_port)) - The Serf WAN port. Default 8302.
Equivalent to the [`-serf-wan-port` command line flag](#_serf_wan_port). Set
to -1 to disable. **Note**: this will disable WAN federation which is not recommended.
Various catalog and WAN related endpoints will return errors or empty results.
TCP and UDP.
- `server` ((#server_rpc_port)) - Server RPC address. Default 8300. TCP
only.
- `sidecar_min_port` ((#sidecar_min_port)) - Inclusive minimum port number
to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service).
Default 21000. Set to `0` to disable automatic port assignment.
- `sidecar_max_port` ((#sidecar_max_port)) - Inclusive maximum port number
to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service).
Default 21255. Set to `0` to disable automatic port assignment.
- `expose_min_port` ((#expose_min_port)) - Inclusive minimum port number
to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration#expose-paths-configuration-reference).
Default 21500. Set to `0` to disable automatic port assignment.
- `expose_max_port` ((#expose_max_port)) - Inclusive maximum port number
to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration#expose-paths-configuration-reference).
Default 21755. Set to `0` to disable automatic port assignment.
- `primary_datacenter` - This designates the datacenter
which is authoritative for ACL information, intentions and is the root Certificate
Authority for Connect. It must be provided to enable ACLs. All servers and datacenters
must agree on the primary datacenter. Setting it on the servers is all you need
for cluster-level enforcement, but for the APIs to forward properly from the clients,
it must be set on them too. In Consul 0.8 and later, this also enables agent-level
enforcement of ACLs.
- `primary_gateways` Equivalent to the [`-primary-gateway`
command-line flag](#_primary_gateway). Takes a list of addresses to use as the
mesh gateways for the primary datacenter when authoritative replicated catalog
data is not present. Discovery happens every [`primary_gateways_interval`](#primary_gateways_interval)
until at least one primary mesh gateway is discovered. This was added in Consul
1.8.0.
- `primary_gateways_interval` Time to wait
between [`primary_gateways`](#primary_gateways) discovery attempts. Defaults to
30s. This was added in Consul 1.8.0.
- `protocol` ((#protocol)) Equivalent to the [`-protocol` command-line
flag](#_protocol).
- `raft_boltdb` ((#raft_boltdb)) This is a nested object that allows configuring
options for Raft's BoltDB based log store.
- `NoFreelistSync` ((#NoFreelistSync)) Setting this to `true` will disable
syncing the BoltDB freelist to disk within the raft.db file. Not syncing
the freelist to disk will reduce disk IO required for write operations
at the expense of potentially increasing start up time due to needing
to scan the db to discover where the free space resides within the file.
- `raft_protocol` ((#raft_protocol)) Equivalent to the [`-raft-protocol`
command-line flag](#_raft_protocol).
- `raft_snapshot_threshold` ((#\_raft_snapshot_threshold)) This controls the
minimum number of raft commit entries between snapshots that are saved to
disk. This is a low-level parameter that should rarely need to be changed.
Very busy clusters experiencing excessive disk IO may increase this value to
reduce disk IO, and minimize the chances of all servers taking snapshots at
the same time. Increasing this trades off disk IO for disk space since the log
will grow much larger and the space in the raft.db file can't be reclaimed
till the next snapshot. Servers may take longer to recover from crashes or
failover if this is increased significantly as more logs will need to be
replayed. In Consul 1.1.0 and later this defaults to 16384, and in prior
versions it was set to 8192.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the
server a `SIGHUP` to allow tuning snapshot activity without a rolling restart
in emergencies.
- `raft_snapshot_interval` ((#\_raft_snapshot_interval)) This controls how often
servers check if they need to save a snapshot to disk. This is a low-level
parameter that should rarely need to be changed. Very busy clusters
experiencing excessive disk IO may increase this value to reduce disk IO, and
minimize the chances of all servers taking snapshots at the same time.
Increasing this trades off disk IO for disk space since the log will grow much
larger and the space in the raft.db file can't be reclaimed till the next
snapshot. Servers may take longer to recover from crashes or failover if this
is increased significantly as more logs will need to be replayed. In Consul
1.1.0 and later this defaults to `30s`, and in prior versions it was set to
`5s`.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the
server a `SIGHUP` to allow tuning snapshot activity without a rolling restart
in emergencies.
- `raft_trailing_logs` - This controls how many log entries are left in the log
store on disk after a snapshot is made. This should only be adjusted when
followers cannot catch up to the leader due to a very large snapshot size
and high write throughput causing log truncation before an snapshot can be
fully installed on a follower. If you need to use this to recover a cluster,
consider reducing write throughput or the amount of data stored on Consul as
it is likely under a load it is not designed to handle. The default value is
10000 which is suitable for all normal workloads. Added in Consul 1.5.3.
Since Consul 1.10.0 this can be reloaded using `consul reload` or sending the
server a `SIGHUP` to allow recovery without downtime when followers can't keep
up.
- `reap` This controls Consul's automatic reaping of child processes,
which is useful if Consul is running as PID 1 in a Docker container. If this isn't
specified, then Consul will automatically reap child processes if it detects it
is running as PID 1. If this is set to true or false, then it controls reaping
regardless of Consul's PID (forces reaping on or off, respectively). This option
was removed in Consul 0.7.1. For later versions of Consul, you will need to reap
processes using a wrapper, please see the [Consul Docker image entry point script](https://github.com/hashicorp/docker-consul/blob/master/0.X/docker-entrypoint.sh)
for an example. If you are using Docker 1.13.0 or later, you can use the new `--init`
option of the `docker run` command and docker will enable an init process with
PID 1 that reaps child processes for the container. More info on [Docker docs](https://docs.docker.com/engine/reference/commandline/run/#options).
- `reconnect_timeout` This controls how long it
takes for a failed node to be completely removed from the cluster. This defaults
to 72 hours and it is recommended that this is set to at least double the maximum
expected recoverable outage time for a node or network partition. WARNING: Setting
this time too low could cause Consul servers to be removed from quorum during an
extended node failure or partition, which could complicate recovery of the cluster.
The value is a time with a unit suffix, which can be "s", "m", "h" for seconds,
minutes, or hours. The value must be >= 8 hours.
- `reconnect_timeout_wan` This is the WAN equivalent
of the [`reconnect_timeout`](#reconnect_timeout) parameter, which controls
how long it takes for a failed server to be completely removed from the WAN pool.
This also defaults to 72 hours, and must be >= 8 hours.
- `recursors` This flag provides addresses of upstream DNS
servers that are used to recursively resolve queries if they are not inside the
service domain for Consul. For example, a node can use Consul directly as a DNS
server, and if the record is outside of the "consul." domain, the query will be
resolved upstream. As of Consul 1.0.1 recursors can be provided as IP addresses
or as go-sockaddr templates. IP addresses are resolved in order, and duplicates
are ignored.
- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](#_rejoin).
- `retry_join` - Equivalent to the [`-retry-join`](#retry-join) command-line flag.
- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](#_retry_interval).
- `retry_join_wan` Equivalent to the [`-retry-join-wan` command-line flag](#_retry_join_wan). Takes a list of addresses to attempt joining to WAN every [`retry_interval_wan`](#_retry_interval_wan) until at least one join works.
- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](#_retry_interval_wan).
- `rpc` configuration for Consul servers.
- `enable_streaming` ((#rpc_enable_streaming)) defaults to true. If set to false it will disable
the gRPC subscribe endpoint on a Consul Server. All
servers in all federated datacenters must have this enabled before any client can use
The base URL to use for contacting the Circonus API. By default, this is set
to "https://api.circonus.com/v2".
- `circonus_submission_interval` ((#telemetry-circonus_submission_interval)) The interval at which metrics are submitted to Circonus. By default, this is set to "10s" (ten seconds).
The Check ID (not **check bundle**) from a previously created HTTPTrap check.
The numeric portion of the `check._cid` field in the Check API object.
- `circonus_check_force_metric_activation` ((#telemetry-circonus_check_force_metric_activation)) Force activation of metrics which already exist and are not currently active.
If check management is enabled, the default behavior is to add new metrics as
they are encountered. If the metric already exists in the check, it will **not**
be activated. This setting overrides that behavior. By default, this is set to
false.
- `circonus_check_instance_id` ((#telemetry-circonus_check_instance_id)) Uniquely identifies the metrics coming from this **instance**. It can be used to
maintain metric continuity with transient or ephemeral instances as they move
around within an infrastructure. By default, this is set to hostname:application
name (e.g. "host123:consul").
- `circonus_check_search_tag` ((#telemetry-circonus_check_search_tag)) A special tag which, when coupled with the instance id, helps to narrow down
the search results when neither a Submission URL or Check ID is provided. By
default, this is set to service:application name (e.g. "service:consul").
- `circonus_check_display_name` ((#telemetry-circonus_check_display_name)) Specifies a name to give a check when it is created. This name is displayed in
the Circonus UI Checks list. Available in Consul 0.7.2 and later.
This allows users to disable metrics deprecated in 1.9 so they are no longer emitted, saving on performance and storage in large deployments. Defaults to false.
A leading "**+**" will enable any metrics with the given prefix, and a leading "**-**" will block them. If there is overlap between two rules, the more specific rule will take precedence. Blocking will take priority if the same prefix is listed multiple times.
- `prometheus_retention_time` ((#telemetry-prometheus_retention_time)) If the value is greater than `0s` (the default), this enables [Prometheus](https://prometheus.io/)
export of metrics. The duration can be expressed using the duration semantics
and will aggregates all counters for the duration specified (it might have an
impact on Consul's memory usage). A good value for this parameter is at least
2 times the interval of scrape of Prometheus, but you might also put a very high
retention time such as a few days (for instance 744h to enable retention to 31
days). Fetching the metrics using prometheus can then be performed using the
- `{{Service.Name}}` - Replaced with the current service's name.
- `{{Service.Namespace}}` - Replaced with the current service's namespace or empty if namespaces are not enabled.
- `{{Service.Partition}}` - Replaced with the current service's admin
partition or empty if admin partitions are not enabled.
- `{{Datacenter}}` - Replaced with the current service's datacenter.
- `ui_dir` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.dir`](#ui_config_dir) field instead.**
Equivalent to the [`-ui-dir`](#_ui_dir) command-line
flag. This configuration key is not required as of Consul version 0.7.0 and later.
Specifying this configuration key will enable the web UI. There is no need to specify
both ui-dir and ui. Specifying both will result in an error.
- `unix_sockets` - This allows tuning the ownership and
permissions of the Unix domain socket files created by Consul. Domain sockets are
only used if the HTTP address is configured with the `unix://` prefix.
It is important to note that this option may have different effects on
different operating systems. Linux generally observes socket file permissions
while many BSD variants ignore permissions on the socket file itself. It is
important to test this feature on your specific distribution. This feature is
currently not functional on Windows hosts.
The following options are valid within this construct and apply globally to all
sockets created by Consul:
- `user` - The name or ID of the user who will own the socket file.
- `group` - The group ID ownership of the socket file. This option
currently only supports numeric IDs.
- `mode` - The permission bits to set on the file.
- `use_streaming_backend` defaults to true. When enabled Consul client agents will use
streaming rpc, instead of the traditional blocking queries, for endpoints which support
streaming. All servers must have [`rpc.enable_streaming`](#rpc_enable_streaming)
enabled before any client can enable `use_streaming_backend`.
- `watches` - Watches is a list of watch specifications which
allow an external process to be automatically invoked when a particular data view
is updated. See the [watch documentation](/docs/agent/watches) for more detail.
Watches can be modified when the configuration is reloaded.
## TLS Configuration Reference
This section documents all of the configuration settings that apply to Agent TLS. Agent
TLS is used by the HTTP API, server RPC, and xDS interfaces. Some of these settings may also be
applied automatically by [auto_config](#auto_config) or [auto_encrypt](#auto_encrypt).
~> **Security Note:** The Certificate Authority (CA) specified by `ca_file` or `ca_path`
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.
- `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`](#verify_incoming)
or [`verify_outgoing`](#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`](#verify_incoming) or [`verify_outgoing`](#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).
- `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`](#cert_file).
- `server_name` When provided, this overrides the [`node_name`](#_node)
for the TLS certificate. It can be used to ensure that the certificate name matches
the hostname we declare.
- `tls_min_version` Added in Consul 0.7.4, this specifies
the minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12",
or "tls13". This defaults to "tls12". WARNING: TLS 1.1 and lower are generally
considered less secure; avoid using these if possible.
- `tls_cipher_suites` Added in Consul 0.8.2, this specifies the list of
supported ciphersuites as a comma-separated-list. Applicable to TLS 1.2 and below only.
The list of all supported ciphersuites is available through
