2020-04-07 18:55:19 +00:00
---
layout: docs
2022-09-16 15:28:32 +00:00
page_title: Agents - Configuration Explained
2020-04-07 18:55:19 +00:00
description: >-
2022-09-16 15:28:32 +00:00
Agent configuration is the process of defining server and client agent properties with CLI flags and configuration files. Learn what properties can be configured on reload and how Consul sets precedence for configuration settings.
2020-04-07 18:55:19 +00:00
---
2022-09-13 19:41:42 +00:00
# Agent Configuration
2020-04-07 18:55:19 +00:00
2022-03-15 23:13:58 +00:00
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.
2020-04-07 18:55:19 +00:00
2022-03-15 23:13:58 +00:00
Configuration precedence is evaluated in the following order:
2020-04-07 18:55:19 +00:00
2023-01-25 16:52:43 +00:00
1. [Command line arguments](/consul/docs/agent/config/cli-flags)
2. [Configuration files](/consul/docs/agent/config/config-files)
2020-04-07 18:55:19 +00:00
2022-03-15 23:13:58 +00:00
When loading configuration, the Consul agent 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.
The Consul agent 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
2023-01-25 16:52:43 +00:00
[reload command](/consul/commands/reload) can also be used to trigger a
2022-03-15 23:13:58 +00:00
configuration reload.
You can test the following configuration options by following the
2023-01-25 16:52:43 +00:00
[Get Started](/consul/tutorials/get-started-vms?utm_source=docs)
2022-10-11 20:01:29 +00:00
tutorials to install an agent in a VM.
2022-03-15 23:13:58 +00:00
## Ports Used
Consul requires up to 6 different ports to work properly, some on
TCP, UDP, or both protocols.
2023-01-25 16:52:43 +00:00
Review the [required ports](/consul/docs/install/ports) table for a list of
2022-03-15 23:13:58 +00:00
required ports and their default settings.
## Reloadable Configuration
2023-01-20 23:42:30 +00:00
Some agent configuration options are reloadable at runtime.
2023-01-25 16:52:43 +00:00
You can run the [`consul reload` command](/consul/commands/reload) to manually reload supported options from configuration files in the configuration directory.
2023-01-20 23:42:30 +00:00
To configure the agent to automatically reload configuration files updated on disk,
set the [`auto_reload_config` configuration option](/consul/docs/agent/config/config-files#auto_reload_config) parameter to `true`.
2022-03-15 23:13:58 +00:00
2023-01-20 23:42:30 +00:00
The following agent configuration options are reloadable at runtime:
2022-03-15 23:13:58 +00:00
- ACL Tokens
2023-01-25 16:52:43 +00:00
- [Configuration Entry Bootstrap](/consul/docs/agent/config/config-files#config_entries_bootstrap)
2022-03-15 23:13:58 +00:00
- Checks
2023-01-25 16:52:43 +00:00
- [Discard Check Output](/consul/docs/agent/config/config-files#discard_check_output)
2022-03-15 23:13:58 +00:00
- HTTP Client Address
- Log level
2023-01-25 16:52:43 +00:00
- [Metric Prefix Filter](/consul/docs/agent/config/config-files#telemetry-prefix_filter)
- [Node Metadata](/consul/docs/agent/config/config-files#node_meta)
2022-03-15 23:13:58 +00:00
- Some Raft options (since Consul 1.10.0)
2023-01-25 16:52:43 +00:00
- [`raft_snapshot_threshold`](/consul/docs/agent/config/config-files#_raft_snapshot_threshold)
- [`raft_snapshot_interval`](/consul/docs/agent/config/config-files#_raft_snapshot_interval)
- [`raft_trailing_logs`](/consul/docs/agent/config/config-files#_raft_trailing_logs)
2022-03-15 23:13:58 +00:00
- These can be important in certain outage situations so being able to control
them without a restart provides a recovery path that doesn't involve
downtime. They generally shouldn't be changed otherwise.
2023-01-25 16:52:43 +00:00
- [RPC rate limiting](/consul/docs/agent/config/config-files#limits)
- [HTTP Maximum Connections per Client](/consul/docs/agent/config/config-files#http_max_conns_per_client)
2022-03-15 23:13:58 +00:00
- Services
- 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.
2023-01-25 16:52:43 +00:00
- To avoid a potential security issue, the following TLS configuration parameters do not automatically reload when [-auto-reload-config](/consul/docs/agent/config/cli-flags#_auto_reload_config) is enabled:
- [encrypt_verify_incoming](/consul/docs/agent/config/config-files#encrypt_verify_incoming)
- [verify_incoming](/consul/docs/agent/config/config-files#verify_incoming)
- [verify_incoming_rpc](/consul/docs/agent/config/config-files#verify_incoming_rpc)
- [verify_incoming_https](/consul/docs/agent/config/config-files#verify_incoming_https)
- [verify_outgoing](/consul/docs/agent/config/config-files#verify_outgoing)
- [verify_server_hostname](/consul/docs/agent/config/config-files#verify_server_hostname)
- [ca_file](/consul/docs/agent/config/config-files#ca_file)
- [ca_path](/consul/docs/agent/config/config-files#ca_path)
2022-05-05 17:08:15 +00:00
2023-01-25 16:52:43 +00:00
If any of those configurations are changed while [-auto-reload-config](/consul/docs/agent/config/cli-flags#_auto_reload_config) is enabled,
2022-04-04 16:01:38 +00:00
Consul will issue the following warning, `Static Runtime config has changed and need a manual config reload to be applied`.
You must manually issue the `consul reload` command or send a `SIGHUP` to the Consul process to reload the new values.
2022-03-15 23:13:58 +00:00
- Watches
2023-01-25 16:52:43 +00:00
- [License](/consul/docs/enterprise/license/overview)
