The agent has various configuration options that can be specified via the
command-line or via configuration files. All of the configuration options are
completely optional. Defaults are specified with their descriptions.
---
# Configuration
The agent has various configuration options that can be specified via
the command-line or via configuration files. All of the configuration
options are completely optional. Defaults are specified with their
descriptions.
Configuration precedence is evaluated in the following order:
1. Command line arguments
2. Configuration files
When loading configuration, Consul loads the configuration from files and
directories in lexical order. For example, configuration file
`basic_config.json` will be processed before `extra_config.json`. Configuration
can be in either [HCL](https://github.com/hashicorp/hcl#syntax) or JSON format.
Available in Consul 1.0 and later, the HCL support now requires an `.hcl` or
`.json` extension on all configuration files in order to specify their format.
Configuration specified later will be merged into configuration specified
earlier. In most cases, "merge" means that the later version will override the
earlier. In some cases, such as event handlers, merging appends the handlers to
the existing configuration. The exact merging behavior is specified for each
option below.
Consul also supports reloading configuration when it receives the
SIGHUP signal. Not all changes are respected, but those that are
documented below in the
[Reloadable Configuration](#reloadable-configuration) section. The
[reload command](/docs/commands/reload.html) can also be used to trigger a
configuration reload.
You can test the following configuration options by following the [Getting Started](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs) guides to install a local agent.
## Environment Variables
Environment variables **cannot** be used to configure the Consul client. They
_can_ be used when running other `consul` CLI commands that connect with a
running agent, e.g. `CONSUL_HTTP_ADDR=192.168.0.1:8500 consul members`.
See [Consul Commands](/docs/commands/index.html#environment-variables) for more
information.
## Command-line Options ((#commandline_options))
The options below are all specified on the command-line.
- `-advertise` ((#\_advertise)) - The advertise address is used to change
the address that we advertise to other nodes in the cluster. By default, the [`-bind`](#_bind)
address is advertised. However, in some cases, there may be a routable address
that cannot be bound. This flag enables gossiping a different address to support
this. If this address is not routable, the node will be in a constant flapping
state as other nodes will treat the non-routability as a failure. In Consul 1.0
and later this can be set to a [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template)
template.
- `-advertise-wan` ((#\_advertise-wan)) - The advertise WAN address is used
to change the address that we advertise to server nodes joining through the WAN.
This can also be set on client agents when used in combination with the [`translate_wan_addrs`](#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address
is advertised. However, in some cases all members of all datacenters cannot be
on the same physical or virtual network, especially on hybrid setups mixing cloud
and private datacenters. This flag enables server nodes gossiping through the public
network for the WAN while using private VLANs for gossiping to each other and their
client agents, and it allows client agents to be reached at this address when being
accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](#translate_wan_addrs). In Consul 1.0 and later this can be set to a [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template) template
- <a name="_bootstrap"></a>
<a href="#_bootstrap">`-bootstrap`</a> - This flag is used to control if a server
is in "bootstrap" mode. It is important that no more than one server _per_ datacenter
be running in this mode. Technically, a server in bootstrap mode is allowed to
self-elect as the Raft leader. It is important that only a single node is in this
mode; otherwise, consistency cannot be guaranteed as multiple nodes are able to
self-elect. It is not recommended to use this flag after a cluster has been bootstrapped.
- <a name="_bootstrap_expect"></a>
<a href="#_bootstrap_expect">`-bootstrap-expect`</a> - This flag provides the number
of expected servers in the datacenter. Either this value should not be provided
or the value must agree with other servers in the cluster. When provided, Consul
waits until the specified number of servers are available and then bootstraps the
cluster. This allows an initial leader to be elected automatically. This cannot
be used in conjunction with the legacy [`-bootstrap`](#_bootstrap) flag. This flag
requires [`-server`](#_server) mode.
- <a name="_bind"></a>
<a href="#_bind">`-bind`</a> - The address that should be bound to for internal
cluster communications. This is an IP address that should be reachable by all other
nodes in the cluster. By default, this is "0.0.0.0", meaning Consul will bind to
all addresses on the local machine and will [advertise](/docs/agent/options.html#_advertise)
the private IPv4 address to the rest of the cluster. If there are multiple private
IPv4 addresses available, Consul will exit with an error at startup. If you specify
`"[::]"`, Consul will [advertise](/docs/agent/options.html#_advertise) the public
IPv6 address. If there are multiple public IPv6 addresses available, Consul will
exit with an error at startup. Consul uses both TCP and UDP and the same port for
both. If you have any firewalls, be sure to allow both protocols. In Consul 1.0
and later this can be set to a [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template)
template that needs to resolve to a single address. Some example templates:
<a href="#acl_datacenter">`acl_datacenter`</a> - **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 see the [ACL Guide](https://learn.hashicorp.com/consul/security-networking/production-acls) for more details.
- <a name="acl_default_policy_legacy"></a>
<a href="#acl_default_policy_legacy">`acl_default_policy`</a> - **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
blacklist: any operation not specifically prohibited is allowed. In "deny" mode,
ACLs are a whitelist: any operation not specifically allowed is blocked. _Note_:
this will not take effect until you've set `primary_datacenter` to enable ACL support.
- <a name="acl_down_policy_legacy"></a>
<a href="#acl_down_policy_legacy">`acl_down_policy`</a> - **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
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, ...
- <a name="discovery_max_stale"></a>
<a href="#discovery_max_stale">`discovery_max_stale`</a> - 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.
- <a name="dns_config"></a>
<a href="#dns_config">`dns_config`</a> This object allows a number of sub-keys
to be set which can tune how DNS queries are serviced. See this guide on [DNS caching](https://learn.hashicorp.com/consul/security-networking/dns-caching)
for more detail.
The following sub-keys are available:
- <a name="allow_stale"></a>
<a href="#allow_stale">`allow_stale`</a> - 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.
- <a name="max_stale"></a>
<a href="#max_stale">`max_stale`</a> - 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.
- <a name="node_ttl"></a>
<a href="#node_ttl">`node_ttl`</a> - 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.
- <a name="service_ttl"></a>
<a href="#service_ttl">`service_ttl`</a> - 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.
- <a name="enable_truncate"></a>
<a href="#enable_truncate">`enable_truncate`</a> - 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.
- <a name="only_passing"></a>
<a href="#only_passing">`only_passing`</a> - 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 healthchecks 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.
- <a name="recursor_timeout"></a>
<a href="#recursor_timeout">`recursor_timeout`</a> - Timeout used by Consul when
recursively querying an upstream DNS server. See <a href="#recursors">
`recursors`
</a>
for more details. Default is 2s. This is available in Consul 0.7 and later.
- <a name="disable_compression"></a>
<a href="#disable_compression">`disable_compression`</a> - If set to true, DNS
responses will not be compressed. Compression was added and enabled by default
in Consul 0.7.
- <a name="udp_answer_limit"></a>
<a href="#udp_answer_limit">`udp_answer_limit`</a> - 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 href="#a_record_limit">
`a_record_limit`
</a>
.
- <a name="a_record_limit"></a>
<a href="#a_record_limit">`a_record_limit`</a> - 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).
- <a name="enable_additional_node_meta_txt"></a>
<a href="#enable_additional_node_meta_txt">
`enable_additional_node_meta_txt`
</a> - 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.
- <a name="soa"></a>
<a href="#soa">`soa`</a> 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.
<br />
<br />
The following settings are available:
- <a name="soa_expire"></a>
<a href="#soa_expire">`expire`</a> - Configure SOA Expire duration in seconds,
default value is 86400, ie: 24 hours.
- <a name="soa_min_ttl"></a>
<a href="#soa_min_ttl">`min_ttl`</a> - 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.
- <a name="soa_refresh"></a>
<a href="#soa_refresh">`refresh`</a> - Configure SOA Refresh duration in seconds,
default value is `3600`, ie: 1 hour.
- <a name="soa_retry"></a>
<a href="#soa_retry">`retry`</a> - Configures the Retry duration expressed
in seconds, default value is 600, ie: 10 minutes.
- <a name="dns_use_cache"></a>
<a href="#dns_use_cache">`use_cache`</a> - When set to true, DNS resolution will
use the agent cache described in [agent caching](/api/features/caching.html).
This setting affects all service and prepared queries DNS requests. Implies [`allow_stale`](#allow_stale)
- <a name="dns_cache_max_age"></a>
<a href="#dns_cache_max_age">`cache_max_age`</a> - 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.html).
Equivalent to the [`-default-query-time` command-line flag](#_default_query_time).
* <a name="max_query_time"></a>
<a href="#max_query_time">`max_query_time`</a>
Equivalent to the [`-max-query-time` command-line flag](#_max_query_time).
* <a name="node_id"></a>
<a href="#node_id">`node_id`</a> Equivalent to the [`-node-id` command-line flag](#_node_id).
* <a name="node_name"></a>
<a href="#node_name">`node_name`</a> Equivalent to the [`-node` command-line flag](#_node).
* <a name="node_meta"></a>
<a href="#node_meta">`node_meta`</a> 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.
```javascript
{
"node_meta": {
"instance_type": "t2.medium"
}
}
```
* <a name="performance"></a>
<a href="#performance">`performance`</a> 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.html) documentation
for more details. The following parameters are available:
- <a name="leave_drain_time"></a>
<a href="#leave_drain_time">`leave_drain_time`</a> - 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.
- <a name="raft_multiplier"></a>
<a href="#raft_multiplier">`raft_multiplier`</a> - 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.html#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.html#production).
See the note on [last contact](/docs/install/performance.html#last-contact) timing for more
details on tuning this parameter. The maximum allowed value is 10.
- <a name="rpc_hold_timeout"></a>
<a href="#rpc_hold_timeout">`rpc_hold_timeout`</a> - 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.
* <a name="ports"></a>
<a href="#ports">`ports`</a> This is a nested object that allows setting the bind
ports for the following keys:
- <a name="dns_port"></a>
<a href="#dns_port">`dns`</a> - The DNS server, -1 to disable. Default 8600.
TCP and UDP.
- <a name="http_port"></a>
<a href="#http_port">`http`</a> - The HTTP API, -1 to disable. Default 8500.
TCP only.
- <a name="https_port"></a>
<a href="#https_port">`https`</a> - 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.
- <a name="grpc_port"></a>
<a href="#grpc_port">`grpc`</a> - 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.
- <a name="serf_lan_port"></a>
<a href="#serf_lan_port">`serf_lan`</a> - The Serf LAN port. Default 8301. TCP
and UDP.
- <a name="serf_wan_port"></a>
<a href="#serf_wan_port">`serf_wan`</a> - The Serf WAN port. Default 8302. 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.
- <a name="server_rpc_port"></a>
<a href="#server_rpc_port">`server`</a> - Server RPC address. Default 8300. TCP
only.
- <a name="sidecar_min_port"></a>
<a href="#sidecar_min_port">`sidecar_min_port`</a> - Inclusive minimum port number
to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service.html).
Default 21000. Set to `0` to disable automatic port assignment.
- <a name="sidecar_max_port"></a>
<a href="#sidecar_max_port">`sidecar_max_port`</a> - Inclusive maximum port number
to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service.html).
Default 21255. Set to `0` to disable automatic port assignment.
- <a name="expose_min_port"></a>
<a href="#expose_min_port">`expose_min_port`</a> - Inclusive minimum port number
to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference).
Default 21500. Set to `0` to disable automatic port assignment.
- <a name="expose_max_port"></a>
<a href="#expose_max_port">`expose_max_port`</a> - Inclusive maximum port number
to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference).
Default 21755. Set to `0` to disable automatic port assignment.
* <a name="primary_datacenter"></a>
<a href="#primary_datacenter">`primary_datacenter`</a> - 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.
* <a name="primary_gateways"></a>
<a href="#primary_gateways">`primary_gateways`</a> 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.x **TODO(wanfed)**.
* <a name="primary_gateways_interval"></a>
<a href="#primary_gateways_interval">`primary_gateways_interval`</a> Time to wait
between [`primary_gateways`](#primary_gateways) discovery attempts. Defaults to
30s. This was added in Consul 1.8.x **TODO(wanfed)**.
* <a name="protocol"></a>
<a href="#protocol">`protocol`</a> Equivalent to the [`-protocol` command-line
flag](#_protocol).
* <a name="raft_protocol"></a>
<a href="#raft_protocol">`raft_protocol`</a> Equivalent to the [`-raft-protocol`
command-line flag](#_raft_protocol).
<!-- Note the extra _ anchors are here because we used to erroneously list these as
command line flags even though they are not actually defined as valid flags and can
only be set in config file. Duplicating the anchor preserves any existing external links
to the old fragment -->
- <a name="raft_snapshot_threshold"></a>
<a name="_raft_snapshot_threshold"></a>
<a href="#raft_snapshot_threshold">`raft_snapshot_threshold`</a> 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.
</a> This controls how often servers check if they need to save a snapshot to disk.
his 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
th e 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`.
- <a name="raft_trailing_logs"></a>
<a href="#raft_trailing_logs">`raft_trailing_logs`</a> - 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 that and high write throughput causing log truncation before an snapshot
can be fully installed. 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.
- <a name="reap"></a>
<a href="#reap">`reap`</a> 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).
- <a name="reconnect_timeout"></a>
<a href="#reconnect_timeout">`reconnect_timeout`</a> 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.
- <a name="reconnect_timeout_wan"></a>
<a href="#reconnect_timeout_wan">`reconnect_timeout_wan`</a> This is the WAN equivalent
of the <a href="#reconnect_timeout">`reconnect_timeout`</a> 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.
- <a name="recursors"></a>
<a href="#recursors">`recursors`</a> 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.
- <a name="rejoin_after_leave"></a>
<a href="#rejoin_after_leave">`rejoin_after_leave`</a> Equivalent to the [`-rejoin`
command-line flag](#_rejoin).
- `retry_join` - Equivalent to the [`-retry-join`](#retry-join) command-line flag.
- <a name="retry_interval"></a>
<a href="#retry_interval">`retry_interval`</a> Equivalent to the [`-retry-interval`
command-line flag](#_retry_interval).
- <a name="retry_join_wan"></a>
<a href="#retry_join_wan">`retry_join_wan`</a> 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.
- <a name="retry_interval_wan"></a>
<a href="#retry_interval_wan">`retry_interval_wan`</a> Equivalent to the [`-retry-interval-wan`
command-line flag](#_retry_interval_wan).
- <a name="segment"></a>
<a href="#segment">`segment`</a> (Enterprise-only) Equivalent to the [`-segment`
command-line flag](#_segment).
- <a name="segments"></a>
<a href="#segments">`segments`</a> (Enterprise-only) This is a list of nested objects
that allows setting the bind/advertise information for network segments. This can
only be set on servers. See the [Network Segments Guide](https://learn.hashicorp.com/consul/day-2-operations/network-segments)
for more details.
- <a name="segment_name"></a>
<a href="#segment_name">`name`</a> - The name of the segment. Must be a string
between 1 and 64 characters in length.
- <a name="segment_bind"></a>
<a href="#segment_bind">`bind`</a> - The bind address to use for the segment's
gossip layer. Defaults to the [`-bind`](#_bind) value if not provided.
- <a name="segment_port"></a>
<a href="#segment_port">`port`</a> - The port to use for the segment's gossip
layer (required).
- <a name="segment_advertise"></a>
<a href="#segment_advertise">`advertise`</a> - The advertise address to use for
the segment's gossip layer. Defaults to the [`-advertise`](#_advertise) value
if not provided.
- <a name="segment_rpc_listener"></a>
<a href="#segment_rpc_listener">`rpc_listener`</a> - If true, a separate RPC
listener will be started on this segment's [`-bind`](#_bind) address on the rpc
port. Only valid if the segment's bind address differs from the [`-bind`](#_bind)
address. Defaults to false.
- <a name="server"></a>
<a href="#server">`server`</a> Equivalent to the [`-server` command-line flag](#_server).
- <a name="non_voting_server"></a>
<a href="#non_voting_server">`non_voting_server`</a> - Equivalent to the [`-non-voting-server`
command-line flag](#_non_voting_server).
- <a name="server_name"></a>
<a href="#server_name">`server_name`</a> 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.
- <a name="session_ttl_min"></a>
<a href="#session_ttl_min">`session_ttl_min`</a>
The minimum allowed session TTL. This ensures sessions are not created with TTL's
shorter than the specified limit. It is recommended to keep this limit at or above
the default to encourage clients to send infrequent heartbeats. Defaults to 10s.
- <a name="skip_leave_on_interrupt"></a>
<a href="#skip_leave_on_interrupt">`skip_leave_on_interrupt`</a> This is similar
to [`leave_on_terminate`](#leave_on_terminate) but only affects interrupt handling.
When Consul receives an interrupt signal (such as hitting Control-C in a terminal),
Consul will gracefully leave the cluster. Setting this to `true` disables that
behavior. 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
`false` and for agents in server-mode, this defaults to `true` (i.e. Ctrl-C on
a server will keep the server in the cluster and therefore quorum, and Ctrl-C on
a client will gracefully leave).
- <a name="start_join"></a>
<a href="#start_join">`start_join`</a> An array of strings specifying addresses
of nodes to [`-join`](#_join) upon startup. Note that using
<a href="#retry_join">`retry_join`</a> could be more appropriate to help mitigate
node startup race conditions when automating a Consul cluster deployment.
- <a name="start_join_wan"></a>
<a href="#start_join_wan">`start_join_wan`</a> An array of strings specifying addresses
of WAN nodes to [`-join-wan`](#_join_wan) upon startup.
- <a name="telemetry"></a>
<a href="#telemetry">`telemetry`</a> This is a nested object that configures where
Consul sends its runtime telemetry, and contains the following keys:
- <a name="telemetry-circonus_api_token"></a>
<a href="#telemetry-circonus_api_token">`circonus_api_token`</a>A valid API
Token used to create/manage check. If provided, metric management is
enabled.
- <a name="telemetry-circonus_api_app"></a>
<a href="#telemetry-circonus_api_app">`circonus_api_app`</a>A valid app name
associated with the API token. By default, this is set to "consul".
for more details. For those versions you **must also set `verify_outgoing = true`** to ensure encrypted RPC connections.
* `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.html) for more detail.
Watches can be modified when the configuration is reloaded.
## Ports Used
Consul requires up to 6 different ports to work properly, some on
TCP, UDP, or both protocols.
Review the [required ports](/docs/install/ports.html) table for a list of
required ports and their default settings.
## Reloadable Configuration
Reloading configuration does not reload all configuration items. The
items which are reloaded include:
- Log level
- Checks
- Services
- Watches
- HTTP Client Address
- TLS Configuration
- Please be aware that this is currently limited to reload a configuration that is already TLS enabled. You cannot enable or disable TLS only with reloading.
