From 57eecbbc144ffbfff1a31c326340e926e7e1ac91 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 10:46:47 -0800 Subject: [PATCH 01/10] docs: move agent/options.mdx into agent/config/index.mdx and add placeholder .mdx files for cli/files Also update nav data --- .../docs/agent/config/agent-config-cli.mdx | 0 .../docs/agent/config/agent-config-files.mdx | 0 .../docs/agent/{options.mdx => config/index.mdx} | 0 website/data/docs-nav-data.json | 15 ++++++++++++++- 4 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 website/content/docs/agent/config/agent-config-cli.mdx create mode 100644 website/content/docs/agent/config/agent-config-files.mdx rename website/content/docs/agent/{options.mdx => config/index.mdx} (100%) diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/agent-config-cli.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/config/index.mdx similarity index 100% rename from website/content/docs/agent/options.mdx rename to website/content/docs/agent/config/index.mdx diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index fcfe7f9073..9e25b99bfc 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -771,7 +771,20 @@ }, { "title": "Configuration", - "path": "agent/options" + "routes": [ + { + "title": "General", + "path": "agent/config" + }, + { + "title": "CLI Reference", + "path": "agent/config/agent-config-cli" + }, + { + "title": "Configuration Reference", + "path": "agent/config/agent-config-files" + } + ] }, { "title": "Configuration Entries", From b0818abad4cd29b779b5008509125174315d9a67 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 10:50:16 -0800 Subject: [PATCH 02/10] docs: move cli content from agent/config/index to agent/config/agent-config-cli And add sections for logical groupings of options --- .../docs/agent/config/agent-config-cli.mdx | 517 ++++++++++++++++++ website/content/docs/agent/config/index.mdx | 487 ----------------- 2 files changed, 517 insertions(+), 487 deletions(-) diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/agent-config-cli.mdx index e69de29bb2..ff19b147fd 100644 --- a/website/content/docs/agent/config/agent-config-cli.mdx +++ b/website/content/docs/agent/config/agent-config-cli.mdx @@ -0,0 +1,517 @@ +--- +layout: docs +page_title: Consul Agent CLI Reference +description: >- + This topic describes the supported options for configuring Consul agents on the command line. +--- + +# Command-line Options ((#commandline_options)) + +-> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](#config_key_reference) for equivalent HCL Keys. + +The options below are all specified on the command-line. + +## 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#environment-variables) for more +information. + +## General + +- `-check_output_max_size` - Override the default + limit of 4k for maximum size of checks, this is a positive value. By limiting this + size, it allows to put less pressure on Consul servers when many checks are having + a very large output in their checks. In order to completely disable check output + capture, it is possible to use [`discard_check_output`](#discard_check_output). + +- `-client` ((#\_client)) - The address to which Consul will bind client + interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", + allowing only loopback connections. In Consul 1.0 and later this 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. + +- `-data-dir` ((#\_data_dir)) - This flag provides a data directory for + the agent to store state. This is required for all agents. The directory should + be durable across reboots. This is especially critical for agents that are running + in server mode as they must be able to persist cluster state. Additionally, the + directory must support the use of filesystem locking, meaning some types of mounted + folders (e.g. VirtualBox shared folders) may not be suitable. + + **Note:** both server and non-server agents may store ACL tokens in the state in this directory so read access may grant access to any tokens on servers and to any tokens used during service registration on non-servers. On Unix-based platforms the files are written with 0600 permissions so you should ensure only trusted processes can execute as the same user as Consul. On Windows, you should ensure the directory has suitable permissions configured as these will be inherited. + +- `-datacenter` ((#\_datacenter)) - This flag controls the datacenter in + which the agent is running. If not provided, it defaults to "dc1". Consul has first-class + support for multiple datacenters, but it relies on proper configuration. Nodes + in the same datacenter should be on a single LAN. + +- `-dev` ((#\_dev)) - Enable development server mode. This is useful for + quickly starting a Consul agent with all persistence options turned off, enabling + an in-memory server which can be used for rapid prototyping or developing against + the API. In this mode, [Connect is enabled](/docs/connect/configuration) and + will by default create a new root CA certificate on startup. This mode is **not** + intended for production use as it does not write any data to disk. The gRPC port + is also defaulted to `8502` in this mode. + +- `-disable-host-node-id` ((#\_disable_host_node_id)) - Setting this to + true will prevent Consul from using information from the host to generate a deterministic + node ID, and will instead generate a random node ID which will be persisted in + the data directory. This is useful when running multiple Consul agents on the same + host for testing. This defaults to false in Consul prior to version 0.8.5 and in + 0.8.5 and later defaults to true, so you must opt-in for host-based IDs. Host-based + IDs are generated using [gopsutil](https://github.com/shirou/gopsutil/tree/master/v3/host), which + is shared with HashiCorp's [Nomad](https://www.nomadproject.io/), so if you opt-in + to host-based IDs then Consul and Nomad will use information on the host to automatically + assign the same ID in both systems. + +- `-disable-keyring-file` ((#\_disable_keyring_file)) - If set, the keyring + will not be persisted to a file. Any installed keys will be lost on shutdown, and + only the given `-encrypt` key will be available on startup. This defaults to false. + +- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether + [health checks that execute scripts](/docs/agent/checks) are enabled on this + agent, and defaults to `false` so operators must opt-in to allowing these. This + was added in Consul 0.9.0. + + ~> **Security Warning:** Enabling script checks in some configurations may + introduce a remote execution vulnerability which is known to be targeted by + malware. We strongly recommend `-enable-local-script-checks` instead. See [this + blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations) + for more details. + +- `-enable-local-script-checks` ((#\_enable_local_script_checks)) + Like [`enable_script_checks`](#_enable_script_checks), but only enable them when + they are defined in the local configuration files. Script checks defined in HTTP + API registrations will still not be allowed. + + +- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption + of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The + easiest way to create an encryption key is to use [`consul keygen`](/commands/keygen). + All nodes within a cluster must share the same encryption key to communicate. The + provided key is automatically persisted to the data directory and loaded automatically + whenever the agent is restarted. This means that to encrypt Consul's gossip protocol, + this option only needs to be provided once on each agent's initial startup sequence. + If it is provided after Consul has been initialized with an encryption key, then + the provided key is ignored and a warning will be displayed. + +- `-grpc-port` ((#\_grpc_port)) - the gRPC API port to listen on. Default + -1 (gRPC disabled). See [ports](#ports) documentation for more detail. + +- `-hcl` ((#\_hcl)) - A HCL configuration fragment. This HCL configuration + fragment is appended to the configuration and allows to specify the full range + of options of a config file on the command line. This option can be specified multiple + times. This was added in Consul 1.0. + +- `-http-port` ((#\_http_port)) - the HTTP API port to listen on. This overrides + the default port 8500. This option is very useful when deploying Consul to an environment + which communicates the HTTP port through the environment e.g. PaaS like CloudFoundry, + allowing you to set the port directly via a Procfile. + +- `-https-port` ((#\_https_port)) - the HTTPS API port to listen on. Default + -1 (https disabled). See [ports](#ports) documentation for more detail. + +- `-default-query-time` ((#\_default_query_time)) - This flag controls the + amount of time a blocking query will wait before Consul will force a response. + This value can be overridden by the `wait` query parameter. Note that Consul applies + some jitter on top of this time. Defaults to 300s. + +- `-max-query-time` ((#\_max_query_time)) - this flag controls the maximum + amount of time a blocking query can wait before Consul will force a response. Consul + applies jitter to the wait time. The jittered time will be capped to this time. + Defaults to 600s. + +- `-pid-file` ((#\_pid_file)) - This flag provides the file path for the + agent to store its PID. This is useful for sending signals (for example, `SIGINT` + to close the agent or `SIGHUP` to update check definitions) to the agent. + +- `-protocol` ((#\_protocol)) - The Consul protocol version to use. Consul + agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/docs/upgrading). You can view the protocol versions supported by Consul by running `consul -v`. + +- `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version + of the Raft consensus protocol used for server communications. This must be set + to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details. + +- `-segment` ((#\_segment)) - This flag is used to set + the name of the network segment the agent belongs to. An agent can only join and + communicate with other agents within its network segment. Ensure the [join + operation uses the correct port for this segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). + Review the [Network Segments documentation](/docs/enterprise/network-segments) + for more details. By default, this is an empty string, which is the `` + network segment. + + ~> **Warning:** The `segment` flag cannot be used with the [`partition`](#partition-1) option. + +## Advertise Address Options + +- `-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.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that is resolved at runtime. + +- `-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.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that is resolved at runtime. + +## Bind Options + +- `-bind` ((#\_bind)) - 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#_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#_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.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that must resolve at runtime to a single address. Some example templates: + + ```shell + # Using address within a specific CIDR + $ consul agent -bind '{{ GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address" }}' + ``` + + ```shell + # Using a static network interface name + $ consul agent -bind '{{ GetInterfaceIP "eth0" }}' + ``` + + ```shell + # Using regular expression matching for network interface name that is forwardable and up + $ consul agent -bind '{{ GetAllInterfaces | include "name" "^eth" | include "flags" "forwardable|up" | attr "address" }}' + ``` + +- `-serf-wan-bind` ((#\_serf_wan_bind)) - The address that should be bound + to for Serf WAN gossip communications. By default, the value follows the same rules + as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind` + option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that is resolved at runtime. + +- `-serf-lan-bind` ((#\_serf_lan_bind)) - The address that should be bound + to for Serf LAN gossip communications. This is an IP address that should be reachable + by all other LAN nodes in the cluster. By default, the value follows the same rules + as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind` + option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that is resolved at runtime. + +## Bootstrap Options + +- `-bootstrap` ((#\_bootstrap)) - 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. + +- `-bootstrap-expect` ((#\_bootstrap_expect)) - 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. + +## Configuration File Options + +- `-config-file` ((#\_config_file)) - A configuration file to load. For + more information on the format of this file, read the [Configuration Files](#configuration_files) + section. This option can be specified multiple times to load multiple configuration + files. If it is specified multiple times, configuration files loaded later will + merge with configuration files loaded earlier. During a config merge, single-value + keys (string, int, bool) will simply have their values replaced while list types + will be appended together. + +- `-config-dir` ((#\_config_dir)) - A directory of configuration files to + load. Consul will load all files in this directory with the suffix ".json" or ".hcl". + The load order is alphabetical, and the the same merge routine is used as with + the [`config-file`](#_config_file) option above. This option can be specified multiple + times to load multiple directories. Sub-directories of the config directory are + not loaded. For more information on the format of the configuration files, see + the [Configuration Files](#configuration_files) section. + +- `-config-format` ((#\_config_format)) - The format of the configuration + files to load. Normally, Consul detects the format of the config files from the + ".json" or ".hcl" extension. Setting this option to either "json" or "hcl" forces + Consul to interpret any file with or without extension to be interpreted in that + format. + +## DNS and Domain Options + +- `-dns-port` ((#\_dns_port)) - the DNS port to listen on. This overrides + the default port 8600. This is available in Consul 0.7 and later. + +- `-domain` ((#\_domain)) - By default, Consul responds to DNS queries in + the "consul." domain. This flag can be used to change that domain. All queries + in this domain are assumed to be handled by Consul and will not be recursively + resolved. + +- `-alt-domain` ((#\_alt_domain)) - This flag allows Consul to respond to + DNS queries in an alternate domain, in addition to the primary domain. If unset, + no alternate domain is used. + + In Consul 1.10.4 and later, Consul DNS responses will use the same domain as in the query (`-domain` or `-alt-domain`) where applicable. + PTR query responses will always use `-domain`, since the desired domain cannot be included in the query. + +- `-recursor` ((#\_recursor)) - Specifies the address of an upstream DNS + server. This option may be provided multiple times, and is functionally equivalent + to the [`recursors` configuration option](#recursors). + +## Join Options + +- `-join` ((#\_join)) - Address of another agent to join upon starting up. + This can be specified multiple times to specify multiple agents to join. If Consul + is unable to join with any of the specified addresses, agent startup will fail. + By default, the agent won't join any nodes when it starts up. Note that using [`retry_join`](#retry_join) could be more appropriate to help mitigate node startup race conditions when automating + a Consul cluster deployment. + + In Consul 1.1.0 and later this can be dynamically defined with a + [go-sockaddr] + template that is resolved at runtime. + + If using Enterprise network segments, see [additional documentation on + joining a client to a segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). + +- `-retry-join` ((#\_retry_join)) - Similar to [`-join`](#_join) but allows retrying a join until + it is successful. Once it joins successfully to a member in a list of members + it will never attempt to join again. Agents will then solely maintain their + membership via gossip. This is useful for cases where you know the address will + eventually be available. This option can be specified multiple times to + specify multiple agents to join. The value can contain IPv4, IPv6, or DNS + addresses. IPv6 must use the "bracketed" syntax. If multiple values + are given, they are tried and retried in the order listed until the first + succeeds. + + In Consul 1.1.0 and later this can be dynamically defined with a + [go-sockaddr] + template that is resolved at runtime. + + If Consul is running on the non-default Serf LAN port, the port must + be specified in the join address, or configured as the agent's default Serf port + using the [`ports.serf_lan`](#serf_lan_port) configuration option or + [`-serf-lan-port`](#_serf_lan_port) command line flag. + + If using network segments (Enterprise), see [additional documentation on + joining a client to a segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). + + Here are some examples of using `-retry-join`: + + ```shell + # Using a DNS entry + $ consul agent -retry-join "consul.domain.internal" + ``` + + ```shell + # Using IPv4 + $ consul agent -retry-join "10.0.4.67" + ``` + + ```shell + # Using a non-default Serf LAN port + $ consul agent -retry-join "192.0.2.10:8304" + ``` + + ```shell + # Using IPv6 + $ consul agent -retry-join "[::1]:8301" + ``` + + ```shell + # Using multiple addresses + $ consul agent -retry-join "consul.domain.internal" -retry-join "10.0.4.67" + ``` + + ### Cloud Auto-Joining + + As of Consul 0.9.1, `retry-join` accepts a unified interface using the + [go-discover](https://github.com/hashicorp/go-discover) library for doing + automatic cluster joining using cloud metadata. For more information, see + the [Cloud Auto-join page](/docs/agent/cloud-auto-join). + + ```shell + # Using Cloud Auto-Joining + $ consul agent -retry-join "provider=aws tag_key=..." + ``` + +- `-retry-interval` ((#\_retry_interval)) - Time to wait between join attempts. + Defaults to 30s. + +- `-retry-max` ((#\_retry_max)) - The maximum number of [`-join`](#_join) + attempts to be made before exiting with return code 1. By default, this is set + to 0 which is interpreted as infinite retries. + +- `-join-wan` ((#\_join_wan)) - Address of another wan agent to join upon + starting up. This can be specified multiple times to specify multiple WAN agents + to join. If Consul is unable to join with any of the specified addresses, agent + startup will fail. By default, the agent won't [`-join-wan`](#_join_wan) any nodes + when it starts up. + + In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that is resolved at runtime. + +- `-retry-join-wan` ((#\_retry_join_wan)) - Similar to [`retry-join`](#_retry_join) + but allows retrying a wan join if the first attempt fails. This is useful for cases + where we know the address will become available eventually. As of Consul 0.9.3 + [Cloud Auto-Joining](#cloud-auto-joining) is supported as well. + + In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] + template that is resolved at runtime. + +- `-primary-gateway` ((#\_primary_gateway)) - Similar to [`retry-join-wan`](#_retry_join_wan) + but allows retrying discovery of fallback addresses for the mesh gateways in the + primary datacenter if the first attempt fails. This is useful for cases where we + know the address will become available eventually. [Cloud Auto-Joining](#cloud-auto-joining) + is supported as well as [go-sockaddr] + templates. This was added in Consul 1.8.0. + +- `-retry-interval-wan` ((#\_retry_interval_wan)) - Time to wait between + [`-join-wan`](#_join_wan) attempts. Defaults to 30s. + +- `-retry-max-wan` ((#\_retry_max_wan)) - The maximum number of [`-join-wan`](#_join_wan) + attempts to be made before exiting with return code 1. By default, this is set + to 0 which is interpreted as infinite retries. + +- `-rejoin` ((#\_rejoin)) - When provided, Consul will ignore a previous + leave and attempt to rejoin the cluster when starting. By default, Consul treats + leave as a permanent intent and does not attempt to join the cluster again when + starting. This flag allows the previous state to be used to rejoin the cluster. + +## Log Options + +- `-log-file` ((#\_log_file)) - writes all the Consul agent log messages + to a file. This value is used as a prefix for the log file name. The current timestamp + is appended to the file name. If the value ends in a path separator, `consul-` + will be appended to the value. If the file name is missing an extension, `.log` + is appended. For example, setting `log-file` to `/var/log/` would result in a log + file path of `/var/log/consul-{timestamp}.log`. `log-file` can be combined with + [`-log-rotate-bytes`](#_log_rotate_bytes) and [-log-rotate-duration](#_log_rotate_duration) + for a fine-grained log rotation experience. + +- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of + bytes that should be written to a log before it needs to be rotated. Unless specified, + there is no limit to the number of bytes that can be written to a log file. + +- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum + duration a log should be written to before it needs to be rotated. Must be a duration + value such as 30s. Defaults to 24h. + +- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum + number of older log file archives to keep. Defaults to 0 (no files are ever deleted). + Set to -1 to discard old log files when a new one is created. + +- `-log-level` ((#\_log_level)) - The level of logging to show after the + Consul agent has started. This defaults to "info". The available log levels are + "trace", "debug", "info", "warn", and "err". You can always connect to an agent + via [`consul monitor`](/commands/monitor) and use any log level. Also, + the log level can be changed during a config reload. + +- `-log-json` ((#\_log_json)) - This flag enables the agent to output logs + in a JSON format. By default this is false. + +- `-syslog` ((#\_syslog)) - This flag enables logging to syslog. This is + only supported on Linux and OSX. It will result in an error if provided on Windows. + +## Node Options + +- `-node` ((#\_node)) - The name of this node in the cluster. This must + be unique within the cluster. By default this is the hostname of the machine. + +- `-node-id` ((#\_node_id)) - Available in Consul 0.7.3 and later, this + is a unique identifier for this node across all time, even if the name of the node + or address changes. This must be in the form of a hex string, 36 characters long, + such as `adf4238a-882b-9ddc-4a9d-5b6758e4159e`. If this isn't supplied, which is + the most common case, then the agent will generate an identifier at startup and + persist it in the [data directory](#_data_dir) so that it will remain the same + across agent restarts. Information from the host will be used to generate a deterministic + node ID if possible, unless [`-disable-host-node-id`](#_disable_host_node_id) is + set to true. + +- `-node-meta` ((#\_node_meta)) - Available in Consul 0.7.3 and later, this + specifies an arbitrary metadata key/value pair to associate with the node, of the + form `key:value`. This can be specified multiple times. Node metadata pairs have + the following restrictions: + + - A maximum of 64 key/value pairs can be registered per node. + - Metadata keys must be between 1 and 128 characters (inclusive) in length + - Metadata keys must contain only alphanumeric, `-`, and `_` characters. + - Metadata keys must not begin with the `consul-` prefix; that is reserved for internal use by Consul. + - Metadata values must be between 0 and 512 (inclusive) characters in length. + - Metadata values for keys beginning with `rfc1035-` are encoded verbatim in DNS TXT requests, otherwise + the metadata kv-pair is encoded according [RFC1464](https://www.ietf.org/rfc/rfc1464.txt). + +## Serf Options + +- `-serf-lan-allowed-cidrs` ((#\_serf_lan_allowed_cidrs)) - The Serf LAN allowed CIDRs allow to accept incoming + connections for Serf only from several networks (multiple values are supported). + Those networks are specified with CIDR notation (eg: 192.168.1.0/24). + This is available in Consul 1.8 and later. + +- `-serf-lan-port` ((#\_serf_lan_port)) - the Serf LAN port to listen on. + This overrides the default Serf LAN port 8301. This is available in Consul 1.2.2 + and later. + +- `-serf-wan-allowed-cidrs` ((#\_serf_wan_allowed_cidrs)) - The Serf WAN allowed CIDRs allow to accept incoming + connections for Serf only from several networks (multiple values are supported). + Those networks are specified with CIDR notation (eg: 192.168.1.0/24). + This is available in Consul 1.8 and later. + +- `-serf-wan-port` ((#\_serf_wan_port)) - the Serf WAN port to listen on. + This overrides the default Serf WAN port 8302. This is available in Consul 1.2.2 + and later. + +## Server Options + +- `-server` ((#\_server)) - This flag is used to control if an agent is + in server or client mode. When provided, an agent will act as a Consul server. + Each Consul cluster must have at least one server and ideally no more than 5 per + datacenter. All servers participate in the Raft consensus algorithm to ensure that + transactions occur in a consistent, linearizable manner. Transactions modify cluster + state, which is maintained on all server nodes to ensure availability in the case + of node failure. Server nodes also participate in a WAN gossip pool with server + nodes in other datacenters. Servers act as gateways to other datacenters and forward + traffic as appropriate. + +- `-server-port` ((#\_server_port)) - the server RPC port to listen on. + This overrides the default server RPC port 8300. This is available in Consul 1.2.2 + and later. + +- `-non-voting-server` ((#\_non_voting_server)) - **This field + is deprecated in Consul 1.9.1. See the [`-read-replica`](#_read_replica) flag instead.** + +- `-read-replica` ((#\_read_replica)) - This + flag is used to make the server not participate in the Raft quorum, and have it + only receive the data replication stream. This can be used to add read scalability + to a cluster in cases where a high volume of reads to servers are needed. + +## UI Options + +- `-ui` ((#\_ui)) - Enables the built-in web UI server and the required + HTTP routes. This eliminates the need to maintain the Consul web UI files separately + from the binary. + +- `-ui-dir` ((#\_ui_dir)) - This flag provides the directory containing + the Web UI resources for Consul. This will automatically enable the Web UI. The + directory must be readable to the agent. Starting with Consul version 0.7.0 and + later, the Web UI assets are included in the binary so this flag is no longer necessary; + specifying only the `-ui` flag is enough to enable the Web UI. Specifying both + the '-ui' and '-ui-dir' flags will result in an error. + + +- `-ui-content-path` ((#\_ui\_content\_path)) - This flag provides the option + to change the path the Consul UI loads from and will be displayed in the browser. + By default, the path is `/ui/`, for example `http://localhost:8500/ui/`. Only alphanumerics, + `-`, and `_` are allowed in a custom path.`/v1/` is not allowed as it would overwrite + the API endpoint. \ No newline at end of file diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx index 78149a43fb..78c4cb5b2e 100644 --- a/website/content/docs/agent/config/index.mdx +++ b/website/content/docs/agent/config/index.mdx @@ -43,493 +43,6 @@ You can test the following configuration options by following the [Getting Started](https://learn.hashicorp.com/tutorials/consul/get-started-install?utm_source=consul.io&utm_medium=docs) tutorials 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#environment-variables) for more -information. - -## Command-line Options ((#commandline_options)) - --> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](#config_key_reference) for equivalent HCL Keys. - -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.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. - -- `-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.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. - -- `-bootstrap` ((#\_bootstrap)) - 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. - -- `-bootstrap-expect` ((#\_bootstrap_expect)) - 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. - -- `-bind` ((#\_bind)) - 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#_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#_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.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that must resolve at runtime to a single address. Some example templates: - - ```shell - # Using address within a specific CIDR - $ consul agent -bind '{{ GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address" }}' - ``` - - ```shell - # Using a static network interface name - $ consul agent -bind '{{ GetInterfaceIP "eth0" }}' - ``` - - ```shell - # Using regular expression matching for network interface name that is forwardable and up - $ consul agent -bind '{{ GetAllInterfaces | include "name" "^eth" | include "flags" "forwardable|up" | attr "address" }}' - ``` - -- `-serf-wan-bind` ((#\_serf_wan_bind)) - The address that should be bound - to for Serf WAN gossip communications. By default, the value follows the same rules - as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind` - option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. - -- `-serf-lan-bind` ((#\_serf_lan_bind)) - The address that should be bound - to for Serf LAN gossip communications. This is an IP address that should be reachable - by all other LAN nodes in the cluster. By default, the value follows the same rules - as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind` - option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. - -- `-check_output_max_size` - Override the default - limit of 4k for maximum size of checks, this is a positive value. By limiting this - size, it allows to put less pressure on Consul servers when many checks are having - a very large output in their checks. In order to completely disable check output - capture, it is possible to use [`discard_check_output`](#discard_check_output). - -- `-client` ((#\_client)) - The address to which Consul will bind client - interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", - allowing only loopback connections. In Consul 1.0 and later this 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. - -- `-config-file` ((#\_config_file)) - A configuration file to load. For - more information on the format of this file, read the [Configuration Files](#configuration_files) - section. This option can be specified multiple times to load multiple configuration - files. If it is specified multiple times, configuration files loaded later will - merge with configuration files loaded earlier. During a config merge, single-value - keys (string, int, bool) will simply have their values replaced while list types - will be appended together. - -- `-config-dir` ((#\_config_dir)) - A directory of configuration files to - load. Consul will load all files in this directory with the suffix ".json" or ".hcl". - The load order is alphabetical, and the the same merge routine is used as with - the [`config-file`](#_config_file) option above. This option can be specified multiple - times to load multiple directories. Sub-directories of the config directory are - not loaded. For more information on the format of the configuration files, see - the [Configuration Files](#configuration_files) section. - -- `-config-format` ((#\_config_format)) - The format of the configuration - files to load. Normally, Consul detects the format of the config files from the - ".json" or ".hcl" extension. Setting this option to either "json" or "hcl" forces - Consul to interpret any file with or without extension to be interpreted in that - format. - -- `-data-dir` ((#\_data_dir)) - This flag provides a data directory for - the agent to store state. This is required for all agents. The directory should - be durable across reboots. This is especially critical for agents that are running - in server mode as they must be able to persist cluster state. Additionally, the - directory must support the use of filesystem locking, meaning some types of mounted - folders (e.g. VirtualBox shared folders) may not be suitable. - - **Note:** both server and non-server agents may store ACL tokens in the state in this directory so read access may grant access to any tokens on servers and to any tokens used during service registration on non-servers. On Unix-based platforms the files are written with 0600 permissions so you should ensure only trusted processes can execute as the same user as Consul. On Windows, you should ensure the directory has suitable permissions configured as these will be inherited. - -- `-datacenter` ((#\_datacenter)) - This flag controls the datacenter in - which the agent is running. If not provided, it defaults to "dc1". Consul has first-class - support for multiple datacenters, but it relies on proper configuration. Nodes - in the same datacenter should be on a single LAN. - -- `-dev` ((#\_dev)) - Enable development server mode. This is useful for - quickly starting a Consul agent with all persistence options turned off, enabling - an in-memory server which can be used for rapid prototyping or developing against - the API. In this mode, [Connect is enabled](/docs/connect/configuration) and - will by default create a new root CA certificate on startup. This mode is **not** - intended for production use as it does not write any data to disk. The gRPC port - is also defaulted to `8502` in this mode. - -- `-disable-host-node-id` ((#\_disable_host_node_id)) - Setting this to - true will prevent Consul from using information from the host to generate a deterministic - node ID, and will instead generate a random node ID which will be persisted in - the data directory. This is useful when running multiple Consul agents on the same - host for testing. This defaults to false in Consul prior to version 0.8.5 and in - 0.8.5 and later defaults to true, so you must opt-in for host-based IDs. Host-based - IDs are generated using [gopsutil](https://github.com/shirou/gopsutil/tree/master/v3/host), which - is shared with HashiCorp's [Nomad](https://www.nomadproject.io/), so if you opt-in - to host-based IDs then Consul and Nomad will use information on the host to automatically - assign the same ID in both systems. - -- `-disable-keyring-file` ((#\_disable_keyring_file)) - If set, the keyring - will not be persisted to a file. Any installed keys will be lost on shutdown, and - only the given `-encrypt` key will be available on startup. This defaults to false. - -- `-dns-port` ((#\_dns_port)) - the DNS port to listen on. This overrides - the default port 8600. This is available in Consul 0.7 and later. - -- `-domain` ((#\_domain)) - By default, Consul responds to DNS queries in - the "consul." domain. This flag can be used to change that domain. All queries - in this domain are assumed to be handled by Consul and will not be recursively - resolved. - -- `-alt-domain` ((#\_alt_domain)) - This flag allows Consul to respond to - DNS queries in an alternate domain, in addition to the primary domain. If unset, - no alternate domain is used. - - In Consul 1.10.4 and later, Consul DNS responses will use the same domain as in the query (`-domain` or `-alt-domain`) where applicable. - PTR query responses will always use `-domain`, since the desired domain cannot be included in the query. - -- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether - [health checks that execute scripts](/docs/agent/checks) are enabled on this - agent, and defaults to `false` so operators must opt-in to allowing these. This - was added in Consul 0.9.0. - - ~> **Security Warning:** Enabling script checks in some configurations may - introduce a remote execution vulnerability which is known to be targeted by - malware. We strongly recommend `-enable-local-script-checks` instead. See [this - blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations) - for more details. - -- `-enable-local-script-checks` ((#\_enable_local_script_checks)) - Like [`enable_script_checks`](#_enable_script_checks), but only enable them when - they are defined in the local configuration files. Script checks defined in HTTP - API registrations will still not be allowed. - - -- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption - of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The - easiest way to create an encryption key is to use [`consul keygen`](/commands/keygen). - All nodes within a cluster must share the same encryption key to communicate. The - provided key is automatically persisted to the data directory and loaded automatically - whenever the agent is restarted. This means that to encrypt Consul's gossip protocol, - this option only needs to be provided once on each agent's initial startup sequence. - If it is provided after Consul has been initialized with an encryption key, then - the provided key is ignored and a warning will be displayed. - -- `-grpc-port` ((#\_grpc_port)) - the gRPC API port to listen on. Default - -1 (gRPC disabled). See [ports](#ports) documentation for more detail. - -- `-hcl` ((#\_hcl)) - A HCL configuration fragment. This HCL configuration - fragment is appended to the configuration and allows to specify the full range - of options of a config file on the command line. This option can be specified multiple - times. This was added in Consul 1.0. - -- `-http-port` ((#\_http_port)) - the HTTP API port to listen on. This overrides - the default port 8500. This option is very useful when deploying Consul to an environment - which communicates the HTTP port through the environment e.g. PaaS like CloudFoundry, - allowing you to set the port directly via a Procfile. - -- `-https-port` ((#\_https_port)) - the HTTPS API port to listen on. Default - -1 (https disabled). See [ports](#ports) documentation for more detail. - -- `-log-file` ((#\_log_file)) - writes all the Consul agent log messages - to a file. This value is used as a prefix for the log file name. The current timestamp - is appended to the file name. If the value ends in a path separator, `consul-` - will be appended to the value. If the file name is missing an extension, `.log` - is appended. For example, setting `log-file` to `/var/log/` would result in a log - file path of `/var/log/consul-{timestamp}.log`. `log-file` can be combined with - [`-log-rotate-bytes`](#_log_rotate_bytes) and [-log-rotate-duration](#_log_rotate_duration) - for a fine-grained log rotation experience. - -- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of - bytes that should be written to a log before it needs to be rotated. Unless specified, - there is no limit to the number of bytes that can be written to a log file. - -- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum - duration a log should be written to before it needs to be rotated. Must be a duration - value such as 30s. Defaults to 24h. - -- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum - number of older log file archives to keep. Defaults to 0 (no files are ever deleted). - Set to -1 to discard old log files when a new one is created. - -- `-default-query-time` ((#\_default_query_time)) - This flag controls the - amount of time a blocking query will wait before Consul will force a response. - This value can be overridden by the `wait` query parameter. Note that Consul applies - some jitter on top of this time. Defaults to 300s. - -- `-max-query-time` ((#\_max_query_time)) - this flag controls the maximum - amount of time a blocking query can wait before Consul will force a response. Consul - applies jitter to the wait time. The jittered time will be capped to this time. - Defaults to 600s. - -- `-join` ((#\_join)) - Address of another agent to join upon starting up. - This can be specified multiple times to specify multiple agents to join. If Consul - is unable to join with any of the specified addresses, agent startup will fail. - By default, the agent won't join any nodes when it starts up. Note that using [`retry_join`](#retry_join) could be more appropriate to help mitigate node startup race conditions when automating - a Consul cluster deployment. - - In Consul 1.1.0 and later this can be dynamically defined with a - [go-sockaddr] - template that is resolved at runtime. - - If using Enterprise network segments, see [additional documentation on - joining a client to a segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). - -- `-retry-join` ((#\_retry_join)) - Similar to [`-join`](#_join) but allows retrying a join until - it is successful. Once it joins successfully to a member in a list of members - it will never attempt to join again. Agents will then solely maintain their - membership via gossip. This is useful for cases where you know the address will - eventually be available. This option can be specified multiple times to - specify multiple agents to join. The value can contain IPv4, IPv6, or DNS - addresses. IPv6 must use the "bracketed" syntax. If multiple values - are given, they are tried and retried in the order listed until the first - succeeds. - - In Consul 1.1.0 and later this can be dynamically defined with a - [go-sockaddr] - template that is resolved at runtime. - - If Consul is running on the non-default Serf LAN port, the port must - be specified in the join address, or configured as the agent's default Serf port - using the [`ports.serf_lan`](#serf_lan_port) configuration option or - [`-serf-lan-port`](#_serf_lan_port) command line flag. - - If using network segments (Enterprise), see [additional documentation on - joining a client to a segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). - - Here are some examples of using `-retry-join`: - - ```shell - # Using a DNS entry - $ consul agent -retry-join "consul.domain.internal" - ``` - - ```shell - # Using IPv4 - $ consul agent -retry-join "10.0.4.67" - ``` - - ```shell - # Using a non-default Serf LAN port - $ consul agent -retry-join "192.0.2.10:8304" - ``` - - ```shell - # Using IPv6 - $ consul agent -retry-join "[::1]:8301" - ``` - - ```shell - # Using multiple addresses - $ consul agent -retry-join "consul.domain.internal" -retry-join "10.0.4.67" - ``` - - ### Cloud Auto-Joining - - As of Consul 0.9.1, `retry-join` accepts a unified interface using the - [go-discover](https://github.com/hashicorp/go-discover) library for doing - automatic cluster joining using cloud metadata. For more information, see - the [Cloud Auto-join page](/docs/agent/cloud-auto-join). - - ```shell - # Using Cloud Auto-Joining - $ consul agent -retry-join "provider=aws tag_key=..." - ``` - -- `-retry-interval` ((#\_retry_interval)) - Time to wait between join attempts. - Defaults to 30s. - -- `-retry-max` ((#\_retry_max)) - The maximum number of [`-join`](#_join) - attempts to be made before exiting with return code 1. By default, this is set - to 0 which is interpreted as infinite retries. - -- `-join-wan` ((#\_join_wan)) - Address of another wan agent to join upon - starting up. This can be specified multiple times to specify multiple WAN agents - to join. If Consul is unable to join with any of the specified addresses, agent - startup will fail. By default, the agent won't [`-join-wan`](#_join_wan) any nodes - when it starts up. - - In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. - -- `-retry-join-wan` ((#\_retry_join_wan)) - Similar to [`retry-join`](#_retry_join) - but allows retrying a wan join if the first attempt fails. This is useful for cases - where we know the address will become available eventually. As of Consul 0.9.3 - [Cloud Auto-Joining](#cloud-auto-joining) is supported as well. - - In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. - -- `-retry-interval-wan` ((#\_retry_interval_wan)) - Time to wait between - [`-join-wan`](#_join_wan) attempts. Defaults to 30s. - -- `-retry-max-wan` ((#\_retry_max_wan)) - The maximum number of [`-join-wan`](#_join_wan) - attempts to be made before exiting with return code 1. By default, this is set - to 0 which is interpreted as infinite retries. - -- `-log-level` ((#\_log_level)) - The level of logging to show after the - Consul agent has started. This defaults to "info". The available log levels are - "trace", "debug", "info", "warn", and "err". You can always connect to an agent - via [`consul monitor`](/commands/monitor) and use any log level. Also, - the log level can be changed during a config reload. - -- `-log-json` ((#\_log_json)) - This flag enables the agent to output logs - in a JSON format. By default this is false. - -- `-node` ((#\_node)) - The name of this node in the cluster. This must - be unique within the cluster. By default this is the hostname of the machine. - -- `-node-id` ((#\_node_id)) - Available in Consul 0.7.3 and later, this - is a unique identifier for this node across all time, even if the name of the node - or address changes. This must be in the form of a hex string, 36 characters long, - such as `adf4238a-882b-9ddc-4a9d-5b6758e4159e`. If this isn't supplied, which is - the most common case, then the agent will generate an identifier at startup and - persist it in the [data directory](#_data_dir) so that it will remain the same - across agent restarts. Information from the host will be used to generate a deterministic - node ID if possible, unless [`-disable-host-node-id`](#_disable_host_node_id) is - set to true. - -- `-node-meta` ((#\_node_meta)) - Available in Consul 0.7.3 and later, this - specifies an arbitrary metadata key/value pair to associate with the node, of the - form `key:value`. This can be specified multiple times. Node metadata pairs have - the following restrictions: - - - A maximum of 64 key/value pairs can be registered per node. - - Metadata keys must be between 1 and 128 characters (inclusive) in length - - Metadata keys must contain only alphanumeric, `-`, and `_` characters. - - Metadata keys must not begin with the `consul-` prefix; that is reserved for internal use by Consul. - - Metadata values must be between 0 and 512 (inclusive) characters in length. - - Metadata values for keys beginning with `rfc1035-` are encoded verbatim in DNS TXT requests, otherwise - the metadata kv-pair is encoded according [RFC1464](https://www.ietf.org/rfc/rfc1464.txt). - -- `-pid-file` ((#\_pid_file)) - This flag provides the file path for the - agent to store its PID. This is useful for sending signals (for example, `SIGINT` - to close the agent or `SIGHUP` to update check definitions) to the agent. - -- `-protocol` ((#\_protocol)) - The Consul protocol version to use. Consul - agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/docs/upgrading). You can view the protocol versions supported by Consul by running `consul -v`. - -- `-primary-gateway` ((#\_primary_gateway)) - Similar to [`retry-join-wan`](#_retry_join_wan) - but allows retrying discovery of fallback addresses for the mesh gateways in the - primary datacenter if the first attempt fails. This is useful for cases where we - know the address will become available eventually. [Cloud Auto-Joining](#cloud-auto-joining) - is supported as well as [go-sockaddr] - templates. This was added in Consul 1.8.0. - -- `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version - of the Raft consensus protocol used for server communications. This must be set - to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details. - -- `-recursor` ((#\_recursor)) - Specifies the address of an upstream DNS - server. This option may be provided multiple times, and is functionally equivalent - to the [`recursors` configuration option](#recursors). - -- `-rejoin` ((#\_rejoin)) - When provided, Consul will ignore a previous - leave and attempt to rejoin the cluster when starting. By default, Consul treats - leave as a permanent intent and does not attempt to join the cluster again when - starting. This flag allows the previous state to be used to rejoin the cluster. - -- `-segment` ((#\_segment)) - This flag is used to set - the name of the network segment the agent belongs to. An agent can only join and - communicate with other agents within its network segment. Ensure the [join - operation uses the correct port for this segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). - Review the [Network Segments documentation](/docs/enterprise/network-segments) - for more details. By default, this is an empty string, which is the `` - network segment. - - ~> **Warning:** The `segment` flag cannot be used with the [`partition`](#partition-1) option. - -- `-serf-lan-allowed-cidrs` ((#\_serf_lan_allowed_cidrs)) - The Serf LAN allowed CIDRs allow to accept incoming - connections for Serf only from several networks (multiple values are supported). - Those networks are specified with CIDR notation (eg: 192.168.1.0/24). - This is available in Consul 1.8 and later. - -- `-serf-lan-port` ((#\_serf_lan_port)) - the Serf LAN port to listen on. - This overrides the default Serf LAN port 8301. This is available in Consul 1.2.2 - and later. - -- `-serf-wan-allowed-cidrs` ((#\_serf_wan_allowed_cidrs)) - The Serf WAN allowed CIDRs allow to accept incoming - connections for Serf only from several networks (multiple values are supported). - Those networks are specified with CIDR notation (eg: 192.168.1.0/24). - This is available in Consul 1.8 and later. - -- `-serf-wan-port` ((#\_serf_wan_port)) - the Serf WAN port to listen on. - This overrides the default Serf WAN port 8302. This is available in Consul 1.2.2 - and later. - -- `-server` ((#\_server)) - This flag is used to control if an agent is - in server or client mode. When provided, an agent will act as a Consul server. - Each Consul cluster must have at least one server and ideally no more than 5 per - datacenter. All servers participate in the Raft consensus algorithm to ensure that - transactions occur in a consistent, linearizable manner. Transactions modify cluster - state, which is maintained on all server nodes to ensure availability in the case - of node failure. Server nodes also participate in a WAN gossip pool with server - nodes in other datacenters. Servers act as gateways to other datacenters and forward - traffic as appropriate. - -- `-server-port` ((#\_server_port)) - the server RPC port to listen on. - This overrides the default server RPC port 8300. This is available in Consul 1.2.2 - and later. - -- `-non-voting-server` ((#\_non_voting_server)) - **This field - is deprecated in Consul 1.9.1. See the [`-read-replica`](#_read_replica) flag instead.** - -- `-read-replica` ((#\_read_replica)) - This - flag is used to make the server not participate in the Raft quorum, and have it - only receive the data replication stream. This can be used to add read scalability - to a cluster in cases where a high volume of reads to servers are needed. - -- `-syslog` ((#\_syslog)) - This flag enables logging to syslog. This is - only supported on Linux and OSX. It will result in an error if provided on Windows. - -- `-ui` ((#\_ui)) - Enables the built-in web UI server and the required - HTTP routes. This eliminates the need to maintain the Consul web UI files separately - from the binary. - -- `-ui-dir` ((#\_ui_dir)) - This flag provides the directory containing - the Web UI resources for Consul. This will automatically enable the Web UI. The - directory must be readable to the agent. Starting with Consul version 0.7.0 and - later, the Web UI assets are included in the binary so this flag is no longer necessary; - specifying only the `-ui` flag is enough to enable the Web UI. Specifying both - the '-ui' and '-ui-dir' flags will result in an error. - - -- `-ui-content-path` ((#\_ui\_content\_path)) - This flag provides the option - to change the path the Consul UI loads from and will be displayed in the browser. - By default, the path is `/ui/`, for example `http://localhost:8500/ui/`. Only alphanumerics, - `-`, and `_` are allowed in a custom path.`/v1/` is not allowed as it would overwrite - the API endpoint. - ## Configuration Files ((#configuration_files)) In addition to the command-line options, configuration can be put into From d07b7a529218a67988037960e176ea40628f4312 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 10:59:51 -0800 Subject: [PATCH 03/10] docs: move configuration files content from agent/config/index to agent/config/agent-config-files --- .../docs/agent/config/agent-config-files.mdx | 1884 +++++++++++++++++ website/content/docs/agent/config/index.mdx | 1878 ---------------- 2 files changed, 1884 insertions(+), 1878 deletions(-) diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx index e69de29bb2..a454adb0e5 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/agent-config-files.mdx @@ -0,0 +1,1884 @@ +--- +layout: docs +page_title: Consul Agent Configuration Reference +description: >- + This topic describes the supported parameters for configuring Consul agents in HCL and JSON configuration files. +--- + +# Configuration Files ((#configuration_files)) + +In addition to the command-line options, configuration can be put into +files. This may be easier in certain situations, for example when Consul is +being configured using a configuration management system. + +The configuration files are JSON formatted, making them easily readable +and editable by both humans and computers. The configuration is formatted +as a single JSON object with configuration within it. + +Configuration files are used for more than just setting up the agent, +they are also used to provide check and service definitions. These are used +to announce the availability of system servers to the rest of the cluster. +They are documented separately under [check configuration](/docs/agent/checks) and +[service configuration](/docs/agent/services) respectively. The service and check +definitions support being updated during a reload. + +#### Example Configuration File + +```json +{ + "datacenter": "east-aws", + "data_dir": "/opt/consul", + "log_level": "INFO", + "node_name": "foobar", + "server": true, + "watches": [ + { + "type": "checks", + "handler": "/usr/bin/health-check-handler.sh" + } + ], + "telemetry": { + "statsite_address": "127.0.0.1:2180" + } +} +``` + +#### Configuration Key Reference + +-> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following +[formatting specification](https://golang.org/pkg/time/#ParseDuration): "A +duration string is a possibly signed sequence of decimal numbers, each with +optional fraction and a unit suffix, such as '300ms', '-1.5h' or '2h45m'. +Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." + +- `acl` ((#acl)) - This object allows a number of sub-keys to be set which + controls the ACL system. Configuring the ACL system within the ACL stanza was added + in Consul 1.4.0 + + The following sub-keys are available: + + - `enabled` ((#acl_enabled)) - Enables ACLs. + + - `policy_ttl` ((#acl_policy_ttl)) - Used to control Time-To-Live caching + of ACL policies. 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. + + - `role_ttl` ((#acl_role_ttl)) - Used to control Time-To-Live caching + of ACL roles. 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 role may be stale up to the TTL value. + + - `token_ttl` ((#acl_token_ttl)) - Used to control Time-To-Live caching + of ACL tokens. 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 token may be stale up to the TTL value. + + - `down_policy` ((#acl_down_policy)) - Either "allow", "deny", "extend-cache" + or "async-cache"; "extend-cache" is the default. In the case that a policy or + 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 objects + to be used, ignoring the expiry time of the cached entry. If the request uses an + ACL that is not in the cache, "extend-cache" falls back to the behaviour of + `default_policy`. + 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 the primary and secondary datacenters, latency + of operations is not impacted. + + - `default_policy` ((#acl_default_policy)) - Either "allow" or "deny"; + defaults to "allow" but this will be changed in a future major release. 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 enabled ACLs. + + - `enable_key_list_policy` ((#acl_enable_key_list_policy)) - Boolean value, defaults to false. + When true, the `list` permission will be required on the prefix being recursively read from the KV store. + Regardless of being enabled, the full set of KV entries under the prefix will be filtered + to remove any entries that the request's ACL token does not grant at least read + permissions. This option is only available in Consul 1.0 and newer. + + - `enable_token_replication` ((#acl_enable_token_replication)) - By default + secondary Consul datacenters will perform replication of only ACL policies and + roles. Setting this configuration will will enable ACL token replication and + allow for the creation of both [local tokens](/api/acl/tokens#local) and + [auth methods](/docs/acl/auth-methods) in connected secondary datacenters. + + ~> **Warning:** When enabling ACL token replication on the secondary datacenter, + global tokens already present in the secondary datacenter will be lost. For + production environments, consider configuring ACL replication in your initial + datacenter bootstrapping process. + + - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either + `true` or `false`. When `true` tokens set using the API will be persisted to + disk and reloaded when an agent restarts. + + - `tokens` ((#acl_tokens)) - This object holds all of the configured + ACL tokens for the agents usage. + + - `initial_management` ((#acl_tokens_initial_management)) - This is available in + Consul 1.11 and later. In prior versions, use [`acl.tokens.master`](#acl_tokens_master). + + Only used for servers in the [`primary_datacenter`](#primary_datacenter). + This token will be created with management-level permissions if it does not exist. + It allows operators to bootstrap the ACL system with a token Secret ID that is + well-known. + + The `initial_management` token is only installed when a server acquires cluster + leadership. If you would like to install or change it, set the new value for + `initial_management` in the configuration for all servers. Once this is done, + restart the current leader to force a leader election. If the `initial_management` + token is not supplied, then the servers do not create an initial management token. + When you provide a value, it should be a UUID. To maintain backwards compatibility + and an upgrade path this restriction is not currently enforced but will be in a + future major Consul release. + + - `master` ((#acl_tokens_master)) **Renamed in Consul 1.11 to + [`acl.tokens.initial_management`](#acl_tokens_initial_management).** + + - `default` ((#acl_tokens_default)) - 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 token, + is used. + + - `agent` ((#acl_tokens_agent)) - Used for clients and servers to perform + internal operations. If this isn't specified, then the + [`default`](#acl_tokens_default) will be used. + + This token must at least have write access to the node name it will + register as in order to set any of the node-level information in the + catalog such as metadata, or the node's tagged addresses. + + - `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11 + and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master). + + Used to access [agent endpoints](/api/agent) that require agent read or write privileges, + or node read privileges, even if Consul servers aren't present to validate any tokens. + This should only be used by operators during outages, regular ACL tokens should normally + be used by applications. + + - `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to + [`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).** + + - `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)) - An + array of ACL tokens used by Consul managed service providers for cluster operations. + + ```json + "managed_service_provider": [ + { + "accessor_id": "ed22003b-0832-4e48-ac65-31de64e5c2ff", + "secret_id": "cb6be010-bba8-4f30-a9ed-d347128dde17" + } + ] + ``` + +- `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 + not impacted. + +- `acl_agent_master_token` ((#acl_agent_master_token_legacy)) - **Deprecated + in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master) + field instead.** Used to access [agent endpoints](/api/agent) that + require agent read or write privileges, or node read privileges, even if Consul + servers aren't present to validate any tokens. This should only be used by operators + during outages, regular ACL tokens should normally be used by applications. This + was added in Consul 0.7.2 and is only used when [`acl_enforce_version_8`](#acl_enforce_version_8) is set to true. + +- `acl_agent_token` ((#acl_agent_token_legacy)) - **Deprecated in Consul + 1.4.0. See the [`acl.tokens.agent`](#acl_tokens_agent) field instead.** Used for + clients and servers to perform internal operations. If this isn't specified, then + the [`acl_token`](#acl_token) will be used. This was added in Consul 0.7.2. + + This token must at least have write access to the node name it will register as in order to set any + of the node-level information in the catalog such as metadata, or the node's tagged addresses. + +- `acl_enforce_version_8` - **Deprecated in + Consul 1.4.0 and removed in 1.8.0.** Used for clients and servers to determine if enforcement should + occur for new ACL policies being previewed before Consul 0.8. Added in Consul 0.7.2, + this defaults to false in versions of Consul prior to 0.8, and defaults to true + in Consul 0.8 and later. This helps ease the transition to the new ACL features + by allowing policies to be in place before enforcement begins. + +- `acl_master_token` ((#acl_master_token_legacy)) - **Deprecated in Consul + 1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.** + +- `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated + 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` - 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 + to `10s`. + + - `redundancy_zone_tag` - + This controls the [`-node-meta`](#_node_meta) key to use when Autopilot is separating + servers into zones for redundancy. Only one server in each zone can be a voting + member at one time. If left blank (the default), this feature will be disabled. + + - `disable_upgrade_migration` - + If set to `true`, this setting will disable Autopilot's upgrade migration strategy + in Consul Enterprise of waiting until enough newer-versioned servers have been + added to the cluster before promoting any of them to voters. Defaults to `false`. + + - `upgrade_version_tag` - + The node_meta tag to use for version info when performing upgrade migrations. + If this is not set, the Consul version will be used. + +- `auto_config` This object allows setting options for the `auto_config` feature. + + The following sub-keys are available: + + - `enabled` (Defaults to `false`) This option enables `auto_config` on a client + agent. When starting up but before joining the cluster, the client agent will + make an RPC to the configured server addresses to request configuration settings, + such as its `agent` ACL token, TLS certificates, Gossip encryption key as well + as other configuration settings. These configurations get merged in as defaults + with any user-supplied configuration on the client agent able to override them. + The initial RPC uses a JWT specified with either `intro_token`, + `intro_token_file` or the `CONSUL_INTRO_TOKEN` environment variable to authorize + the request. How the JWT token is verified is controlled by the `auto_config.authorizer` + object available for use on Consul servers. Enabling this option also turns + on Connect because it is vital for `auto_config`, more specifically the CA + and certificates infrastructure. + + ~> **Warning:** Enabling `auto_config` conflicts with the [`auto_encrypt.tls`](#tls) feature. + Only one option may be specified. + + - `intro_token` (Defaults to `""`) This specifies the JWT to use for the initial + `auto_config` RPC to the Consul servers. This can be overridden with the + `CONSUL_INTRO_TOKEN` environment variable + + - `intro_token_file` (Defaults to `""`) This specifies a file containing the JWT + to use for the initial `auto_config` RPC to the Consul servers. This token + from this file is only loaded if the `intro_token` configuration is unset as + well as the `CONSUL_INTRO_TOKEN` environment variable + + - `server_addresses` (Defaults to `[]`) This specifies the addresses of servers in + the local datacenter to use for the initial RPC. These addresses support + [Cloud Auto-Joining](#cloud-auto-joining) and can optionally include a port to + use when making the outbound connection. If not port is provided the `server_port` + will be used. + + - `dns_sans` (Defaults to `[]`) This is a list of extra DNS SANs to request in the + client agent's TLS certificate. The `localhost` DNS SAN is always requested. + + - `ip_sans` (Defaults to `[]`) This is a list of extra IP SANs to request in the + client agent's TLS certificate. The `::1` and `127.0.0.1` IP SANs are always requested. + + - `authorization` This object controls how a Consul server will authorize `auto_config` + requests and in particular how to verify the JWT intro token. + + - `enabled` (Defaults to `false`) This option enables `auto_config` authorization + capabilities on the server. + + - `static` This object controls configuring the static authorizer setup in the Consul + configuration file. Almost all sub-keys are identical to those provided by the [JWT + Auth Method](/docs/acl/auth-methods/jwt). + + - `jwt_validation_pub_keys` (Defaults to `[]`) A list of PEM-encoded public keys + to use to authenticate signatures locally. + + Exactly one of `jwks_url` `jwt_validation_pub_keys`, or `oidc_discovery_url` is required. + + - `oidc_discovery_url` (Defaults to `""`) The OIDC Discovery URL, without any + .well-known component (base path). + + Exactly one of `jwks_url` `jwt_validation_pub_keys`, or `oidc_discovery_url` is required. + + - `oidc_discovery_ca_cert` (Defaults to `""`) PEM encoded CA cert for use by the TLS + client used to talk with the OIDC Discovery URL. NOTE: Every line must end + with a newline (`\n`). If not set, system certificates are used. + + - `jwks_url` (Defaults to `""`) The JWKS URL to use to authenticate signatures. + + Exactly one of `jwks_url` `jwt_validation_pub_keys`, or `oidc_discovery_url` is required. + + - `jwks_ca_cert` (Defaults to `""`) PEM encoded CA cert for use by the TLS client + used to talk with the JWKS URL. NOTE: Every line must end with a newline + (`\n`). If not set, system certificates are used. + + - `claim_mappings` (Defaults to `(map[string]string)` Mappings of claims (key) that + will be copied to a metadata field (value). Use this if the claim you are capturing + is singular (such as an attribute). + + When mapped, the values can be any of a number, string, or boolean and will + all be stringified when returned. + + - `list_claim_mappings` (Defaults to `(map[string]string)`) Mappings of claims (key) + will be copied to a metadata field (value). Use this if the claim you are capturing + is list-like (such as groups). + + When mapped, the values in each list can be any of a number, string, or + boolean and will all be stringified when returned. + + - `jwt_supported_algs` (Defaults to `["RS256"]`) JWTSupportedAlgs is a list of + supported signing algorithms. + + - `bound_audiences` (Defaults to `[]`) List of `aud` claims that are valid for + login; any match is sufficient. + + - `bound_issuer` (Defaults to `""`) The value against which to match the `iss` + claim in a JWT. + + - `expiration_leeway` (Defaults to `"0s"`) Duration of leeway when + validating expiration of a token to account for clock skew. Defaults to 150s + (2.5 minutes) if set to 0s and can be disabled if set to -1ns. + + - `not_before_leeway` (Defaults to `"0s"`) Duration of leeway when + validating not before values of a token to account for clock skew. Defaults + to 150s (2.5 minutes) if set to 0s and can be disabled if set to -1. + + - `clock_skew_leeway` (Defaults to `"0s"`) Duration of leeway when + validating all claims to account for clock skew. Defaults to 60s (1 minute) + if set to 0s and can be disabled if set to -1ns. + + - `claim_assertions` (Defaults to []) List of assertions about the mapped + claims required to authorize the incoming RPC request. The syntax uses + github.com/hashicorp/go-bexpr which is shared with the + [API filtering feature](/api/features/filtering). For example, the following + configurations when combined will ensure that the JWT `sub` matches the node + name requested by the client. + + ``` + claim_mappings { + sub = "node_name" + } + claim_assertions = [ + "value.node_name == \"${node}\"" + ] + ``` + + The assertions are lightly templated using [HIL syntax](https://github.com/hashicorp/hil) + to interpolate some values from the RPC request. The list of variables that can be interpolated + are: + + - `node` - The node name the client agent is requesting. + + - `segment` - The network segment name the client is requesting. + + - `partition` - The admin partition name the client is requesting. + +- `auto_encrypt` This object allows setting options for the `auto_encrypt` feature. + + The following sub-keys are available: + + - `allow_tls` (Defaults to `false`) This option enables + `auto_encrypt` on the servers and allows them to automatically distribute certificates + from the Connect CA to the clients. If enabled, the server can accept incoming + connections from both the built-in CA and the Connect CA, as well as their certificates. + Note, the server will only present the built-in CA and certificate, which the + client can verify using the CA it received from `auto_encrypt` endpoint. If disabled, + a client configured with `auto_encrypt.tls` will be unable to start. + + - `tls` (Defaults to `false`) Allows the client to request the + Connect CA and certificates from the servers, for encrypting RPC communication. + The client will make the request to any servers listed in the `-join` or `-retry-join` + option. This requires that every server to have `auto_encrypt.allow_tls` enabled. + When both `auto_encrypt` options are used, it allows clients to receive certificates + that are generated on the servers. If the `-server-port` is not the default one, + it has to be provided to the client as well. Usually this is discovered through + LAN gossip, but `auto_encrypt` provision happens before the information can be + distributed through gossip. The most secure `auto_encrypt` setup is when the + client is provided with the built-in CA, `verify_server_hostname` is turned on, + and when an ACL token with `node.write` permissions is setup. It is also possible + to use `auto_encrypt` with a CA and ACL, but without `verify_server_hostname`, + or only with a ACL enabled, or only with CA and `verify_server_hostname`, or + only with a CA, or finally without a CA and without ACL enabled. In any case, + the communication to the `auto_encrypt` endpoint is always TLS encrypted. + + ~> **Warning:** Enabling `auto_encrypt.tls` conflicts with the [`auto_config`](#auto_config) feature. + Only one option may be specified. + + - `dns_san` (Defaults to `[]`) When this option is being + used, the certificates requested by `auto_encrypt` from the server have these + `dns_san` set as DNS SAN. + + - `ip_san` (Defaults to `[]`) When this option is being used, + the certificates requested by `auto_encrypt` from the server have these `ip_san` + set as IP SAN. + +- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](#_bootstrap). + +- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](#_bootstrap_expect). + +- `bind_addr` Equivalent to the [`-bind` command-line flag](#_bind). + + This parameter can be set to a go-sockaddr template that resolves to a single + address. Special characters such as backslashes `\` or double quotes `"` + within a double quoted string value must be escaped with a backslash `\`. + Some example templates: + + + +```hcl +bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}" +``` + +```json +{ + "bind_addr": "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}" +} +``` + + + +- `cache` configuration for client agents. The configurable values are the following: + + - `entry_fetch_max_burst` The size of the token bucket used to recharge the rate-limit per + cache entry. The default value is 2 and means that when cache has not been updated + for a long time, 2 successive queries can be made as long as the rate-limit is not + reached. + + - `entry_fetch_rate` configures the rate-limit at which the cache may refresh a single + entry. On a cluster with many changes/s, watching changes in the cache might put high + pressure on the servers. This ensures the number of requests for a single cache entry + will never go beyond this limit, even when a given service changes every 1/100s. + Since this is a per cache entry limit, having a highly unstable service will only rate + limit the watched on this service, but not the other services/entries. + The value is strictly positive, expressed in queries per second as a float, + 1 means 1 query per second, 0.1 mean 1 request every 10s maximum. + The default value is "No limit" and should be tuned on large + clusters to avoid performing too many RPCs on entries changing a lot. + +- `check_update_interval` ((#check_update_interval)) + This interval controls how often check output from checks in a steady state is + synchronized with the server. By default, this is set to 5 minutes ("5m"). Many + checks which are in a steady state produce slightly different output per run (timestamps, + etc) which cause constant writes. This configuration allows deferring the sync + of check output for a given interval to reduce write pressure. If a check ever + changes state, the new state and associated output is synchronized immediately. + To disable this behavior, set the value to "0s". + +- `client_addr` Equivalent to the [`-client` command-line flag](#_client). + +- `config_entries` This object allows setting options for centralized config entries. + + The following sub-keys are available: + + - `bootstrap` ((#config_entries_bootstrap)) + This is a list of inlined config entries to insert into the state store when + the Consul server gains leadership. This option is only applicable to server + nodes. Each bootstrap entry will be created only if it does not exist. When reloading, + any new entries that have been added to the configuration will be processed. + See the [configuration entry docs](/docs/agent/config-entries) for more + details about the contents of each entry. + +- `connect` This object allows setting options for the Connect feature. + + The following sub-keys are available: + + - `enabled` ((#connect_enabled)) Controls whether Connect features are + enabled on this agent. Should be enabled on all servers in the cluster + in order for Connect to function properly. Defaults to false. + + - `enable_mesh_gateway_wan_federation` ((#connect_enable_mesh_gateway_wan_federation)) Controls whether cross-datacenter federation traffic between servers is funneled + through mesh gateways. Defaults to false. This was added in Consul 1.8.0. + + - `ca_provider` ((#connect_ca_provider)) Controls which CA provider to + use for Connect's CA. Currently only the `aws-pca`, `consul`, and `vault` providers are supported. + This is only used when initially bootstrapping the cluster. For an existing cluster, + use the [Update CA Configuration Endpoint](/api/connect/ca#update-ca-configuration). + + - `ca_config` ((#connect_ca_config)) An object which allows setting different + config options based on the CA provider chosen. This is only used when initially + bootstrapping the cluster. For an existing cluster, use the [Update CA Configuration + Endpoint](/api/connect/ca#update-ca-configuration). + + The following providers are supported: + + #### AWS ACM Private CA Provider (`ca_provider = "aws-pca"`) + + - `existing_arn` ((#aws_ca_existing_arn)) The Amazon Resource Name (ARN) of + an existing private CA in your ACM account. If specified, Consul will + attempt to use the existing CA to issue certificates. + + #### Consul CA Provider (`ca_provider = "consul"`) + + - `private_key` ((#consul_ca_private_key)) The PEM contents of the + private key to use for the CA. + + - `root_cert` ((#consul_ca_root_cert)) The PEM contents of the root + certificate to use for the CA. + + #### Vault CA Provider (`ca_provider = "vault"`) + + - `address` ((#vault_ca_address)) The address of the Vault server to + connect to. + + - `token` ((#vault_ca_token)) The Vault token to use. In Consul 1.8.5 and later, if + the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable) + flag set, Consul will attempt to renew its lease periodically after half the + duration has expired. + + - `root_pki_path` ((#vault_ca_root_pki)) The path to use for the root + CA pki backend in Vault. This can be an existing backend with a CA already + configured, or a blank/unmounted backend in which case Connect will automatically + mount/generate the CA. The Vault token given above must have `sudo` access + to this backend, as well as permission to mount the backend at this path if + it is not already mounted. + + - `intermediate_pki_path` ((#vault_ca_intermediate_pki)) + The path to use for the temporary intermediate CA pki backend in Vault. **Connect + will overwrite any data at this path in order to generate a temporary intermediate + CA**. The Vault token given above must have `write` access to this backend, + as well as permission to mount the backend at this path if it is not already + mounted. + + #### Common CA Config Options + + There are also a number of common configuration options supported by all providers: + + - `csr_max_concurrent` ((#ca_csr_max_concurrent)) Sets a limit on the number + of Certificate Signing Requests that can be processed concurrently. Defaults + to 0 (disabled). This is useful when you want to limit the number of CPU cores + available to the server for certificate signing operations. For example, on an + 8 core server, setting this to 1 will ensure that no more than one CPU core + will be consumed when generating or rotating certificates. Setting this is + recommended **instead** of `csr_max_per_second` when you want to limit the + number of cores consumed since it is simpler to reason about limiting CSR + resources this way without artificially slowing down rotations. Added in 1.4.1. + + - `csr_max_per_second` ((#ca_csr_max_per_second)) Sets a rate limit + on the maximum number of Certificate Signing Requests (CSRs) the servers will + accept. This is used to prevent CA rotation from causing unbounded CPU usage + on servers. It defaults to 50 which is conservative – a 2017 Macbook can process + about 100 per second using only ~40% of one CPU core – but sufficient for deployments + up to ~1500 service instances before the time it takes to rotate is impacted. + For larger deployments we recommend increasing this based on the expected number + of server instances and server resources, or use `csr_max_concurrent` instead + if servers have more than one CPU core. Setting this to zero disables rate limiting. + Added in 1.4.1. + + - `leaf_cert_ttl` ((#ca_leaf_cert_ttl)) The upper bound on the lease + duration of a leaf certificate issued for a service. In most cases a new leaf + certificate will be requested by a proxy before this limit is reached. This + is also the effective limit on how long a server outage can last (with no leader) + before network connections will start being rejected. Defaults to `72h`. + This value cannot be lower than 1 hour or higher than 1 year. + + This value is also used when rotating out old root certificates from + the cluster. When a root certificate has been inactive (rotated out) + for more than twice the _current_ `leaf_cert_ttl`, it will be removed + from the trusted list. + + - `root_cert_ttl` ((#ca_root_cert_ttl)) The time to live (TTL) for a root certificate. + Defaults to 10 years as `87600h`. This value, if provided, needs to be higher than the + intermediate certificate TTL. + + This setting applies to all Consul CA providers. + + For the Vault provider, this value is only used if the backend is not initialized at first. + + This value is also applied on the `ca set-config` command. + + - `private_key_type` ((#ca_private_key_type)) The type of key to generate + for this CA. This is only used when the provider is generating a new key. If + `private_key` is set for the Consul provider, or existing root or intermediate + PKI paths given for Vault then this will be ignored. Currently supported options + are `ec` or `rsa`. Default is `ec`. + + It is required that all servers in a datacenter have + the same config for the CA. It is recommended that servers in + different datacenters use the same key type and size, + although the built-in CA and Vault provider will both allow mixed CA + key types. + + Some CA providers (currently Vault) will not allow cross-signing a + new CA certificate with a different key type. This means that if you + migrate from an RSA-keyed Vault CA to an EC-keyed CA from any + provider, you may have to proceed without cross-signing which risks + temporary connection issues for workloads during the new certificate + rollout. We highly recommend testing this outside of production to + understand the impact and suggest sticking to same key type where + possible. + + Note that this only affects _CA_ keys generated by the provider. + Leaf certificate keys are always EC 256 regardless of the CA + configuration. + + - `private_key_bits` ((#ca_private_key_bits)) The length of key to + generate for this CA. This is only used when the provider is generating a new + key. If `private_key` is set for the Consul provider, or existing root or intermediate + PKI paths given for Vault then this will be ignored. + + Currently supported values are: + + - `private_key_type = ec` (default): `224, 256, 384, 521` + 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)) **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) + for more information. Defaults to true. + +- `disable_keyring_file` - Equivalent to the + [`-disable-keyring-file` command-line flag](#_disable_keyring_file). + +- `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). + When network coordinates are disabled the `near` query param will not work to sort the nodes, + and the [`consul rtt`](/commands/rtt) command will not be able to provide round trip time between nodes. + +- `gossip_lan` - **(Advanced)** This object contains a + number of sub-keys which can be set to tune the LAN gossip communications. These + are only provided for users running especially large clusters that need fine tuning + and are prepared to spend significant effort correctly tuning them for their environment + and workload. **Tuning these improperly can cause Consul to fail in unexpected + ways**. The default values are appropriate in almost all deployments. + + - `gossip_nodes` - The number of random nodes to send + gossip messages to per gossip_interval. Increasing this number causes the gossip + messages to propagate across the cluster more quickly at the expense of increased + bandwidth. The default is 3. + + - `gossip_interval` - The interval between sending + messages that need to be gossiped that haven't been able to piggyback on probing + messages. If this is set to zero, non-piggyback gossip is disabled. By lowering + this value (more frequent) gossip messages are propagated across the cluster + more quickly at the expense of increased bandwidth. The default is 200ms. + + - `probe_interval` - The interval between random + node probes. Setting this lower (more frequent) will cause the cluster to detect + failed nodes more quickly at the expense of increased bandwidth usage. The default + is 1s. + + - `probe_timeout` - The timeout to wait for an ack + from a probed node before assuming it is unhealthy. This should be at least the + 99-percentile of RTT (round-trip time) on your network. The default is 500ms + and is a conservative value suitable for almost all realistic deployments. + + - `retransmit_mult` - The multiplier for the number + of retransmissions that are attempted for messages broadcasted over gossip. The + number of retransmits is scaled using this multiplier and the cluster size. The + higher the multiplier, the more likely a failed broadcast is to converge at the + expense of increased bandwidth. The default is 4. + + - `suspicion_mult` - The multiplier for determining + the time an inaccessible node is considered suspect before declaring it dead. + The timeout is scaled with the cluster size and the probe_interval. This allows + the timeout to scale properly with expected propagation delay with a larger cluster + size. The higher the multiplier, the longer an inaccessible node is considered + part of the cluster before declaring it dead, giving that suspect node more time + to refute if it is indeed still alive. The default is 4. + +- `gossip_wan` - **(Advanced)** This object contains a + number of sub-keys which can be set to tune the WAN gossip communications. These + are only provided for users running especially large clusters that need fine tuning + and are prepared to spend significant effort correctly tuning them for their environment + and workload. **Tuning these improperly can cause Consul to fail in unexpected + ways**. The default values are appropriate in almost all deployments. + + - `gossip_nodes` - The number of random nodes to send + gossip messages to per gossip_interval. Increasing this number causes the gossip + messages to propagate across the cluster more quickly at the expense of increased + bandwidth. The default is 4. + + - `gossip_interval` - The interval between sending + messages that need to be gossiped that haven't been able to piggyback on probing + messages. If this is set to zero, non-piggyback gossip is disabled. By lowering + this value (more frequent) gossip messages are propagated across the cluster + more quickly at the expense of increased bandwidth. The default is 500ms. + + - `probe_interval` - The interval between random + node probes. Setting this lower (more frequent) will cause the cluster to detect + failed nodes more quickly at the expense of increased bandwidth usage. The default + is 5s. + + - `probe_timeout` - The timeout to wait for an ack + from a probed node before assuming it is unhealthy. This should be at least the + 99-percentile of RTT (round-trip time) on your network. The default is 3s + and is a conservative value suitable for almost all realistic deployments. + + - `retransmit_mult` - The multiplier for the number + of retransmissions that are attempted for messages broadcasted over gossip. The + number of retransmits is scaled using this multiplier and the cluster size. The + higher the multiplier, the more likely a failed broadcast is to converge at the + expense of increased bandwidth. The default is 4. + + - `suspicion_mult` - The multiplier for determining + the time an inaccessible node is considered suspect before declaring it dead. + The timeout is scaled with the cluster size and the probe_interval. This allows + the timeout to scale properly with expected propagation delay with a larger cluster + size. The higher the multiplier, the longer an inaccessible node is considered + part of the cluster before declaring it dead, giving that suspect node more time + to refute if it is indeed still alive. The default is 6. + +- `http_config` This object allows setting options for the HTTP API and UI. + + The following sub-keys are available: + + - `block_endpoints` + This object is a list of HTTP API endpoint prefixes to block on the agent, and + defaults to an empty list, meaning all endpoints are enabled. Any endpoint that + has a common prefix with one of the entries on this list will be blocked and + will return a 403 response code when accessed. For example, to block all of the + V1 ACL endpoints, set this to `["/v1/acl"]`, which will block `/v1/acl/create`, + `/v1/acl/update`, and the other ACL endpoints that begin with `/v1/acl`. This + only works with API endpoints, not `/ui` or `/debug`, those must be disabled + with their respective configuration options. Any CLI commands that use disabled + endpoints will no longer function as well. For more general access control, Consul's + [ACL system](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) + 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` 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` - 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 + [`use_streaming_backend`](#use_streaming_backend). + +- `segment` - Equivalent to the [`-segment` command-line flag](#_segment). + + ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. + +- `segments` - (Server agents only) This is a list of nested objects + that specifies user-defined network segments, not including the `` segment, which is + created automatically. Review the [Network Segments documentation](/docs/enterprise/network-segments) + for more details. + + - `name` ((#segment_name)) - The name of the segment. Must be a string + between 1 and 64 characters in length. + - `bind` ((#segment_bind)) - The bind address to use for the segment's + gossip layer. Defaults to the [`-bind`](#_bind) value if not provided. + - `port` ((#segment_port)) - The port to use for the segment's gossip + layer (required). + - `advertise` ((#segment_advertise)) - The advertise address to use for + the segment's gossip layer. Defaults to the [`-advertise`](#_advertise) value + if not provided. + - `rpc_listener` ((#segment_rpc_listener)) - 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. + +- `server` Equivalent to the [`-server` command-line flag](#_server). + +- `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** + +- `read_replica` - Equivalent to the [`-read-replica` command-line flag](#_read_replica). + +- `session_ttl_min` 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. + +- `skip_leave_on_interrupt` 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). + +- `start_join` An array of strings specifying addresses + of nodes to [`-join`](#_join) upon startup. Note that using + `retry_join` could be more appropriate to help mitigate + node startup race conditions when automating a Consul cluster deployment. + +- `start_join_wan` An array of strings specifying addresses + of WAN nodes to [`-join-wan`](#_join_wan) upon startup. + +- `telemetry` This is a nested object that configures where + Consul sends its runtime telemetry, and contains the following keys: + + - `circonus_api_token` ((#telemetry-circonus_api_token)) A valid API + Token used to create/manage check. If provided, metric management is + enabled. + + - `circonus_api_app` ((#telemetry-circonus_api_app)) A valid app name + associated with the API token. By default, this is set to "consul". + + - `circonus_api_url` ((#telemetry-circonus_api_url)) + 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). + + - `circonus_submission_url` ((#telemetry-circonus_submission_url)) + The `check.config.submission_url` field, of a Check API object, from a previously + created HTTPTrap check. + + - `circonus_check_id` ((#telemetry-circonus_check_id)) + 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. + + - `circonus_check_tags` ((#telemetry-circonus_check_tags)) + Comma separated list of additional tags to add to a check when it is created. + Available in Consul 0.7.2 and later. + + - `circonus_broker_id` ((#telemetry-circonus_broker_id)) + The ID of a specific Circonus Broker to use when creating a new check. The numeric + portion of `broker._cid` field in a Broker API object. If metric management is + enabled and neither a Submission URL nor Check ID is provided, an attempt will + be made to search for an existing check using Instance ID and Search Tag. If + one is not found, a new HTTPTrap check will be created. By default, this is not + used and a random Enterprise Broker is selected, or the default Circonus Public + Broker. + + - `circonus_broker_select_tag` ((#telemetry-circonus_broker_select_tag)) A special tag which will be used to select a Circonus Broker when a Broker ID + is not provided. The best use of this is to as a hint for which broker should + be used based on **where** this particular instance is running (e.g. a specific + geo location or datacenter, dc:sfo). By default, this is left blank and not used. + + - `disable_compat_1.9` ((#telemetry-disable_compat_1.9)) + 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. + + - `disable_hostname` ((#telemetry-disable_hostname)) + This controls whether or not to prepend runtime telemetry with the machine's + hostname, defaults to false. + + - `dogstatsd_addr` ((#telemetry-dogstatsd_addr)) This provides the address + of a DogStatsD instance in the format `host:port`. DogStatsD is a protocol-compatible + flavor of statsd, with the added ability to decorate metrics with tags and event + information. If provided, Consul will send various telemetry information to that + instance for aggregation. This can be used to capture runtime information. + + - `dogstatsd_tags` ((#telemetry-dogstatsd_tags)) This provides a list + of global tags that will be added to all telemetry packets sent to DogStatsD. + It is a list of strings, where each string looks like "my_tag_name:my_tag_value". + + - `filter_default` ((#telemetry-filter_default)) + This controls whether to allow metrics that have not been specified by the filter. + Defaults to `true`, which will allow all metrics when no filters are provided. + When set to `false` with no filters, no metrics will be sent. + + - `metrics_prefix` ((#telemetry-metrics_prefix)) + The prefix used while writing all telemetry data. By default, this is set to + "consul". This was added in Consul 1.0. For previous versions of Consul, use + the config option `statsite_prefix` in this same structure. This was renamed + in Consul 1.0 since this prefix applied to all telemetry providers, not just + statsite. + + - `prefix_filter` ((#telemetry-prefix_filter)) + This is a list of filter rules to apply for allowing/blocking metrics by + prefix in the following format: + + ```json + ["+consul.raft.apply", "-consul.http", "+consul.http.GET"] + ``` + + 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 + [`/v1/agent/metrics?format=prometheus`](/api/agent#view-metrics) endpoint. + The format is compatible natively with prometheus. When running in this mode, + it is recommended to also enable the option [`disable_hostname`](#telemetry-disable_hostname) + to avoid having prefixed metrics with hostname. Consul does not use the default + Prometheus path, so Prometheus must be configured as follows. Note that using + ?format=prometheus in the path won't work as ? will be escaped, so it must be + specified as a parameter. + + ```yaml + metrics_path: '/v1/agent/metrics' + params: + format: ['prometheus'] + ``` + + - `statsd_address` ((#telemetry-statsd_address)) This provides the address + of a statsd instance in the format `host:port`. If provided, Consul will send + various telemetry information to that instance for aggregation. This can be used + to capture runtime information. This sends UDP packets only and can be used with + statsd or statsite. + + - `statsite_address` ((#telemetry-statsite_address)) This provides the + address of a statsite instance in the format `host:port`. If provided, Consul + will stream various telemetry information to that instance for aggregation. This + can be used to capture runtime information. This streams via TCP and can only + be used with statsite. + +- `syslog_facility` When [`enable_syslog`](#enable_syslog) + is provided, this controls to which facility messages are sent. By default, `LOCAL0` + will be used. + +- `translate_wan_addrs` If set to true, Consul + will prefer a node's configured [WAN address](#_advertise-wan) + when servicing DNS and HTTP requests for a node in a remote datacenter. This allows + the node to be reached within its own datacenter using its local address, and reached + from other datacenters using its WAN address, which is useful in hybrid setups + with mixed networks. This is disabled by default. + + Starting in Consul 0.7 and later, node addresses in responses to HTTP requests will also prefer a + node's configured [WAN address](#_advertise-wan) when querying for a node in a remote + datacenter. An [`X-Consul-Translate-Addresses`](/api#translated-addresses) header + will be present on all responses when translation is enabled to help clients know that the addresses + may be translated. The `TaggedAddresses` field in responses also have a `lan` address for clients that + need knowledge of that address, regardless of translation. + + The following endpoints translate addresses: + + - [`/v1/catalog/nodes`](/api/catalog#list-nodes) + - [`/v1/catalog/node/`](/api/catalog#retrieve-map-of-services-for-a-node) + - [`/v1/catalog/service/`](/api/catalog#list-nodes-for-service) + - [`/v1/health/service/`](/api/health#list-nodes-for-service) + - [`/v1/query//execute`](/api/query#execute-prepared-query) + +- `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** + Equivalent to the [`-ui`](#_ui) command-line flag. + +- `ui_config` - This object allows a number of sub-keys to be set which controls + the display or features available in the UI. Configuring the UI with this + stanza was added in Consul 1.9.0. + + The following sub-keys are available: + + - `enabled` ((#ui_config_enabled)) - This enables the service of the web UI + from this agent. Boolean value, defaults to false. In `-dev` mode this + defaults to true. Replaces `ui` from before 1.9.0. Equivalent to the + [`-ui`](#_ui) command-line flag. + + - `dir` ((#ui_config_dir)) - This specifies that the web UI should be served + from an external dir rather than the build in one. This allows for + customization or development. Replaces `ui_dir` from before 1.9.0. + Equivalent to the [`-ui-dir`](#_ui_dir) command-line flag. + + - `content_path` ((#ui_config_content_path)) - This specifies the HTTP path + that the web UI should be served from. Defaults to `/ui/`. Equivalent to the + [`-ui-content-path`](#_ui_content_path) flag. + + - `metrics_provider` ((#ui_config_metrics_provider)) - Specifies a named + metrics provider implementation the UI should use to fetch service metrics. + By default metrics are disabled. Consul 1.9.0 includes a built-in provider + named `prometheus` that can be enabled explicitly here. It also requires the + `metrics_proxy` to be configured below and direct queries to a Prometheus + instance that has Envoy metrics for all services in the datacenter. + + - `metrics_provider_files` ((#ui_config_metrics_provider_files)) - An optional array + of absolute paths to javascript files on the Agent's disk which will be + served as part of the UI. These files should contain metrics provider + implementations and registration enabling UI metric queries to be customized + or implemented for an alternative time-series backend. + + ~> **Security Note:** These javascript files are included in the UI with no + further validation or sand-boxing. By configuring them here the operator is + fully trusting anyone able to write to them as well as the original authors + not to include malicious code in the UI being served. + + - `metrics_provider_options_json` ((#ui_config_metrics_provider_options_json)) - + This is an optional raw JSON object as a string which is passed to the + provider implementation's `init` method at startup to allow arbitrary + configuration to be passed through. + + - `metrics_proxy` ((#ui_config_metrics_proxy)) - This object configures an + internal agent API endpoint that will proxy GET requests to a metrics + backend to allow querying metrics data in the UI. This simplifies deployment + where the metrics backend is not exposed externally to UI users' browsers. + It may also be used to augment requests with API credentials to allow + serving graphs to UI users without them needing individual access tokens for + the metrics backend. + + ~> **Security Note:** Exposing your metrics backend via Consul in this way + should be carefully considered in production. As Consul doesn't understand + the requests, it can't limit access to only specific resources. For example + **this might make it possible for a malicious user on the network to query + for arbitrary metrics about any server or workload in your infrastructure, + or overload the metrics infrastructure with queries**. See [Metrics Proxy + Security](/docs/connect/observability/ui-visualization#metrics-proxy-security) + for more details. + + The following sub-keys are available: + + - `base_url` ((#ui_config_metrics_provider_base_url)) - This is required to + enable the proxy. It should be set to the base URL that the Consul agent + should proxy requests for metrics too. For example a value of + `http://prometheus-server` would target a Prometheus instance with local + DNS name "prometheus-server" on port 80. This may include a path prefix + which will then not be necessary in provider requests to the backend and + the proxy will prevent any access to paths without that prefix on the + backend. + + - `path_allowlist` ((#ui_config_metrics_provider_path_allowlist)) - This + specifies the paths that may be proxies to when appended to the + `base_url`. It defaults to `["/api/v1/query_range", "/api/v1/query"]` + which are the endpoints required for the built-in Prometheus provider. If + a [custom + provider](/docs/connect/observability/ui-visualization#custom-metrics-providers) + is used that requires the metrics proxy, the correct allowlist must be + specified to enable proxying to necessary endpoints. See [Path + Allowlist](/docs/connect/observability/ui-visualization#path-allowlist) + for more information. + + - `add_headers` ((#ui_config_metrics_proxy_add_headers)) - This is an + optional list if headers to add to requests that are proxied to the + metrics backend. It may be used to inject Authorization tokens within the + agent without exposing those to UI users. + + Each item in the list is an object with the following keys: + + - `name` ((#ui_config_metrics_proxy_add_headers_name)) - Specifies the + HTTP header name to inject into proxied requests. + + - `value` ((#ui_config_metrics_proxy_add_headers_value)) - Specifies the + value in inject into proxied requests. + + - `dashboard_url_templates` ((#ui_config_dashboard_url_templates)) - This map + specifies URL templates that may be used to render links to external + dashboards in various contexts in the UI. It is a map with the name of the + template as a key. The value is a string URL with optional placeholders. + + Each template may contain placeholders which will be substituted for the + correct values in content when rendered in the UI. The placeholders + available are listed for each template. + + For more information and examples see [UI + Visualization](/docs/connect/observability/ui-visualization#configuring-dashboard-urls) + + The following named templates are defined: + + - `service` ((#ui_config_dashboard_url_templates_service)) - This is the URL + to use when linking to the dashboard for a specific service. It is shown + as part of the [Topology + Visualization](/docs/connect/observability/ui-visualization). + + The placeholders available are: + + - `{{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 + [this search](https://github.com/hashicorp/consul/search?q=cipherMap+%3A%3D+map&unscoped_q=cipherMap+%3A%3D+map). + + ~> **Note:** The ordering of cipher suites will not be guaranteed from Consul 1.11 onwards. See this + [post](https://go.dev/blog/tls-cipher-suites) for details. + +- `tls_prefer_server_cipher_suites` Added in Consul 0.8.2, this + will cause Consul to prefer the server's ciphersuite over the client ciphersuites. + + ~> **Note:** This config will be deprecated in Consul 1.11. See this + [post](https://go.dev/blog/tls-cipher-suites) for details. + +- `verify_incoming` - If set to true, Consul + requires that all incoming connections make use of TLS and that the client + provides a certificate signed by a Certificate Authority from the + [`ca_file`](#ca_file) or [`ca_path`](#ca_path). This applies to both server + RPC and to the HTTPS API. By default, this is false, and Consul will not + enforce the use of TLS or verify a client's authenticity. Turning on + `verify_incoming` on consul clients protects the HTTPS endpoint, by ensuring + that the certificate that is presented by a 3rd party tool to the HTTPS + endpoint was created by the CA that the consul client was setup with. If the + UI is served, the same checks are performed. + +- `verify_incoming_rpc` - When set to true, Consul + requires that all incoming RPC connections use TLS and that the client + provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file) + or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce + the use of TLS or verify a client's authenticity. + + ~> **Security Note:** `verify_incoming_rpc` _must_ be set to true to prevent anyone + with access to the RPC port from gaining full access to the Consul cluster. + +- `verify_incoming_https` - If set to true, + Consul requires that all incoming HTTPS connections make use of TLS and that the + client provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file) + or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce + the use of TLS or verify a client's authenticity. To enable the HTTPS API, you + must define an HTTPS port via the [`ports`](#ports) configuration. By default, + HTTPS is disabled. + +- `verify_outgoing` - If set to true, Consul requires + that all outgoing connections from this agent make use of TLS and that the server + provides a certificate that is signed by a Certificate Authority from the [`ca_file`](#ca_file) + or [`ca_path`](#ca_path). By default, this is false, and Consul will not make use + of TLS for outgoing connections. This applies to clients and servers as both will + make outgoing connections. + + ~> **Security Note:** Note that servers that specify `verify_outgoing = true` will always talk to other servers over TLS, but they still _accept_ + non-TLS connections to allow for a transition of all clients to TLS. + Currently the only way to enforce that no client can communicate with a + server unencrypted is to also enable `verify_incoming` which requires client + certificates too. + +- `verify_server_hostname` - When set to true, Consul verifies the TLS certificate + presented by the servers match the hostname `server..`. + By default this is false, and Consul does not verify the hostname + of the certificate, only that it is signed by a trusted CA. This setting _must_ be enabled + to prevent a compromised client from gaining full read and write access to all + cluster data _including all ACL tokens and Connect CA root keys_. This is new in 0.5.1. + + ~> **Security Note:** From versions 0.5.1 to 1.4.0, due to a bug, setting + this flag alone _does not_ imply `verify_outgoing` and leaves client to server + and server to server RPCs unencrypted despite the documentation stating otherwise. See + [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) + for more details. For those versions you **must also set `verify_outgoing = true`** to ensure encrypted RPC connections. + +### Example Configuration File, with TLS + +~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both +encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) +will result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file). + +```json +{ + "datacenter": "east-aws", + "data_dir": "/opt/consul", + "log_level": "INFO", + "node_name": "foobar", + "server": true, + "addresses": { + "https": "0.0.0.0" + }, + "ports": { + "https": 8501 + }, + "key_file": "/etc/pki/tls/private/my.key", + "cert_file": "/etc/pki/tls/certs/my.crt", + "ca_file": "/etc/pki/tls/certs/ca-bundle.crt", + "verify_incoming": true, + "verify_outgoing": true, + "verify_server_hostname": true +} +``` + +See, especially, the use of the `ports` setting: + +```json +"ports": { + "https": 8501 +} +``` + +Consul will not enable TLS for the HTTP API unless the `https` port has been +assigned a port number `> 0`. We recommend using `8501` for `https` as this +default will automatically work with some tooling. \ No newline at end of file diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx index 78c4cb5b2e..adc5577cdf 100644 --- a/website/content/docs/agent/config/index.mdx +++ b/website/content/docs/agent/config/index.mdx @@ -43,1884 +43,6 @@ You can test the following configuration options by following the [Getting Started](https://learn.hashicorp.com/tutorials/consul/get-started-install?utm_source=consul.io&utm_medium=docs) tutorials to install a local agent. -## Configuration Files ((#configuration_files)) - -In addition to the command-line options, configuration can be put into -files. This may be easier in certain situations, for example when Consul is -being configured using a configuration management system. - -The configuration files are JSON formatted, making them easily readable -and editable by both humans and computers. The configuration is formatted -as a single JSON object with configuration within it. - -Configuration files are used for more than just setting up the agent, -they are also used to provide check and service definitions. These are used -to announce the availability of system servers to the rest of the cluster. -They are documented separately under [check configuration](/docs/agent/checks) and -[service configuration](/docs/agent/services) respectively. The service and check -definitions support being updated during a reload. - -#### Example Configuration File - -```json -{ - "datacenter": "east-aws", - "data_dir": "/opt/consul", - "log_level": "INFO", - "node_name": "foobar", - "server": true, - "watches": [ - { - "type": "checks", - "handler": "/usr/bin/health-check-handler.sh" - } - ], - "telemetry": { - "statsite_address": "127.0.0.1:2180" - } -} -``` - -#### Configuration Key Reference ((#config_key_reference)) - --> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following -[formatting specification](https://golang.org/pkg/time/#ParseDuration): "A -duration string is a possibly signed sequence of decimal numbers, each with -optional fraction and a unit suffix, such as '300ms', '-1.5h' or '2h45m'. -Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - -- `acl` ((#acl)) - This object allows a number of sub-keys to be set which - controls the ACL system. Configuring the ACL system within the ACL stanza was added - in Consul 1.4.0 - - The following sub-keys are available: - - - `enabled` ((#acl_enabled)) - Enables ACLs. - - - `policy_ttl` ((#acl_policy_ttl)) - Used to control Time-To-Live caching - of ACL policies. 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. - - - `role_ttl` ((#acl_role_ttl)) - Used to control Time-To-Live caching - of ACL roles. 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 role may be stale up to the TTL value. - - - `token_ttl` ((#acl_token_ttl)) - Used to control Time-To-Live caching - of ACL tokens. 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 token may be stale up to the TTL value. - - - `down_policy` ((#acl_down_policy)) - Either "allow", "deny", "extend-cache" - or "async-cache"; "extend-cache" is the default. In the case that a policy or - 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 objects - to be used, ignoring the expiry time of the cached entry. If the request uses an - ACL that is not in the cache, "extend-cache" falls back to the behaviour of - `default_policy`. - 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 the primary and secondary datacenters, latency - of operations is not impacted. - - - `default_policy` ((#acl_default_policy)) - Either "allow" or "deny"; - defaults to "allow" but this will be changed in a future major release. 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 enabled ACLs. - - - `enable_key_list_policy` ((#acl_enable_key_list_policy)) - Boolean value, defaults to false. - When true, the `list` permission will be required on the prefix being recursively read from the KV store. - Regardless of being enabled, the full set of KV entries under the prefix will be filtered - to remove any entries that the request's ACL token does not grant at least read - permissions. This option is only available in Consul 1.0 and newer. - - - `enable_token_replication` ((#acl_enable_token_replication)) - By default - secondary Consul datacenters will perform replication of only ACL policies and - roles. Setting this configuration will will enable ACL token replication and - allow for the creation of both [local tokens](/api/acl/tokens#local) and - [auth methods](/docs/acl/auth-methods) in connected secondary datacenters. - - ~> **Warning:** When enabling ACL token replication on the secondary datacenter, - global tokens already present in the secondary datacenter will be lost. For - production environments, consider configuring ACL replication in your initial - datacenter bootstrapping process. - - - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either - `true` or `false`. When `true` tokens set using the API will be persisted to - disk and reloaded when an agent restarts. - - - `tokens` ((#acl_tokens)) - This object holds all of the configured - ACL tokens for the agents usage. - - - `initial_management` ((#acl_tokens_initial_management)) - This is available in - Consul 1.11 and later. In prior versions, use [`acl.tokens.master`](#acl_tokens_master). - - Only used for servers in the [`primary_datacenter`](#primary_datacenter). - This token will be created with management-level permissions if it does not exist. - It allows operators to bootstrap the ACL system with a token Secret ID that is - well-known. - - The `initial_management` token is only installed when a server acquires cluster - leadership. If you would like to install or change it, set the new value for - `initial_management` in the configuration for all servers. Once this is done, - restart the current leader to force a leader election. If the `initial_management` - token is not supplied, then the servers do not create an initial management token. - When you provide a value, it should be a UUID. To maintain backwards compatibility - and an upgrade path this restriction is not currently enforced but will be in a - future major Consul release. - - - `master` ((#acl_tokens_master)) **Renamed in Consul 1.11 to - [`acl.tokens.initial_management`](#acl_tokens_initial_management).** - - - `default` ((#acl_tokens_default)) - 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 token, - is used. - - - `agent` ((#acl_tokens_agent)) - Used for clients and servers to perform - internal operations. If this isn't specified, then the - [`default`](#acl_tokens_default) will be used. - - This token must at least have write access to the node name it will - register as in order to set any of the node-level information in the - catalog such as metadata, or the node's tagged addresses. - - - `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11 - and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master). - - Used to access [agent endpoints](/api/agent) that require agent read or write privileges, - or node read privileges, even if Consul servers aren't present to validate any tokens. - This should only be used by operators during outages, regular ACL tokens should normally - be used by applications. - - - `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to - [`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).** - - - `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)) - An - array of ACL tokens used by Consul managed service providers for cluster operations. - - ```json - "managed_service_provider": [ - { - "accessor_id": "ed22003b-0832-4e48-ac65-31de64e5c2ff", - "secret_id": "cb6be010-bba8-4f30-a9ed-d347128dde17" - } - ] - ``` - -- `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 - not impacted. - -- `acl_agent_master_token` ((#acl_agent_master_token_legacy)) - **Deprecated - in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master) - field instead.** Used to access [agent endpoints](/api/agent) that - require agent read or write privileges, or node read privileges, even if Consul - servers aren't present to validate any tokens. This should only be used by operators - during outages, regular ACL tokens should normally be used by applications. This - was added in Consul 0.7.2 and is only used when [`acl_enforce_version_8`](#acl_enforce_version_8) is set to true. - -- `acl_agent_token` ((#acl_agent_token_legacy)) - **Deprecated in Consul - 1.4.0. See the [`acl.tokens.agent`](#acl_tokens_agent) field instead.** Used for - clients and servers to perform internal operations. If this isn't specified, then - the [`acl_token`](#acl_token) will be used. This was added in Consul 0.7.2. - - This token must at least have write access to the node name it will register as in order to set any - of the node-level information in the catalog such as metadata, or the node's tagged addresses. - -- `acl_enforce_version_8` - **Deprecated in - Consul 1.4.0 and removed in 1.8.0.** Used for clients and servers to determine if enforcement should - occur for new ACL policies being previewed before Consul 0.8. Added in Consul 0.7.2, - this defaults to false in versions of Consul prior to 0.8, and defaults to true - in Consul 0.8 and later. This helps ease the transition to the new ACL features - by allowing policies to be in place before enforcement begins. - -- `acl_master_token` ((#acl_master_token_legacy)) - **Deprecated in Consul - 1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.** - -- `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated - 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` - 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 - to `10s`. - - - `redundancy_zone_tag` - - This controls the [`-node-meta`](#_node_meta) key to use when Autopilot is separating - servers into zones for redundancy. Only one server in each zone can be a voting - member at one time. If left blank (the default), this feature will be disabled. - - - `disable_upgrade_migration` - - If set to `true`, this setting will disable Autopilot's upgrade migration strategy - in Consul Enterprise of waiting until enough newer-versioned servers have been - added to the cluster before promoting any of them to voters. Defaults to `false`. - - - `upgrade_version_tag` - - The node_meta tag to use for version info when performing upgrade migrations. - If this is not set, the Consul version will be used. - -- `auto_config` This object allows setting options for the `auto_config` feature. - - The following sub-keys are available: - - - `enabled` (Defaults to `false`) This option enables `auto_config` on a client - agent. When starting up but before joining the cluster, the client agent will - make an RPC to the configured server addresses to request configuration settings, - such as its `agent` ACL token, TLS certificates, Gossip encryption key as well - as other configuration settings. These configurations get merged in as defaults - with any user-supplied configuration on the client agent able to override them. - The initial RPC uses a JWT specified with either `intro_token`, - `intro_token_file` or the `CONSUL_INTRO_TOKEN` environment variable to authorize - the request. How the JWT token is verified is controlled by the `auto_config.authorizer` - object available for use on Consul servers. Enabling this option also turns - on Connect because it is vital for `auto_config`, more specifically the CA - and certificates infrastructure. - - ~> **Warning:** Enabling `auto_config` conflicts with the [`auto_encrypt.tls`](#tls) feature. - Only one option may be specified. - - - `intro_token` (Defaults to `""`) This specifies the JWT to use for the initial - `auto_config` RPC to the Consul servers. This can be overridden with the - `CONSUL_INTRO_TOKEN` environment variable - - - `intro_token_file` (Defaults to `""`) This specifies a file containing the JWT - to use for the initial `auto_config` RPC to the Consul servers. This token - from this file is only loaded if the `intro_token` configuration is unset as - well as the `CONSUL_INTRO_TOKEN` environment variable - - - `server_addresses` (Defaults to `[]`) This specifies the addresses of servers in - the local datacenter to use for the initial RPC. These addresses support - [Cloud Auto-Joining](#cloud-auto-joining) and can optionally include a port to - use when making the outbound connection. If not port is provided the `server_port` - will be used. - - - `dns_sans` (Defaults to `[]`) This is a list of extra DNS SANs to request in the - client agent's TLS certificate. The `localhost` DNS SAN is always requested. - - - `ip_sans` (Defaults to `[]`) This is a list of extra IP SANs to request in the - client agent's TLS certificate. The `::1` and `127.0.0.1` IP SANs are always requested. - - - `authorization` This object controls how a Consul server will authorize `auto_config` - requests and in particular how to verify the JWT intro token. - - - `enabled` (Defaults to `false`) This option enables `auto_config` authorization - capabilities on the server. - - - `static` This object controls configuring the static authorizer setup in the Consul - configuration file. Almost all sub-keys are identical to those provided by the [JWT - Auth Method](/docs/acl/auth-methods/jwt). - - - `jwt_validation_pub_keys` (Defaults to `[]`) A list of PEM-encoded public keys - to use to authenticate signatures locally. - - Exactly one of `jwks_url` `jwt_validation_pub_keys`, or `oidc_discovery_url` is required. - - - `oidc_discovery_url` (Defaults to `""`) The OIDC Discovery URL, without any - .well-known component (base path). - - Exactly one of `jwks_url` `jwt_validation_pub_keys`, or `oidc_discovery_url` is required. - - - `oidc_discovery_ca_cert` (Defaults to `""`) PEM encoded CA cert for use by the TLS - client used to talk with the OIDC Discovery URL. NOTE: Every line must end - with a newline (`\n`). If not set, system certificates are used. - - - `jwks_url` (Defaults to `""`) The JWKS URL to use to authenticate signatures. - - Exactly one of `jwks_url` `jwt_validation_pub_keys`, or `oidc_discovery_url` is required. - - - `jwks_ca_cert` (Defaults to `""`) PEM encoded CA cert for use by the TLS client - used to talk with the JWKS URL. NOTE: Every line must end with a newline - (`\n`). If not set, system certificates are used. - - - `claim_mappings` (Defaults to `(map[string]string)` Mappings of claims (key) that - will be copied to a metadata field (value). Use this if the claim you are capturing - is singular (such as an attribute). - - When mapped, the values can be any of a number, string, or boolean and will - all be stringified when returned. - - - `list_claim_mappings` (Defaults to `(map[string]string)`) Mappings of claims (key) - will be copied to a metadata field (value). Use this if the claim you are capturing - is list-like (such as groups). - - When mapped, the values in each list can be any of a number, string, or - boolean and will all be stringified when returned. - - - `jwt_supported_algs` (Defaults to `["RS256"]`) JWTSupportedAlgs is a list of - supported signing algorithms. - - - `bound_audiences` (Defaults to `[]`) List of `aud` claims that are valid for - login; any match is sufficient. - - - `bound_issuer` (Defaults to `""`) The value against which to match the `iss` - claim in a JWT. - - - `expiration_leeway` (Defaults to `"0s"`) Duration of leeway when - validating expiration of a token to account for clock skew. Defaults to 150s - (2.5 minutes) if set to 0s and can be disabled if set to -1ns. - - - `not_before_leeway` (Defaults to `"0s"`) Duration of leeway when - validating not before values of a token to account for clock skew. Defaults - to 150s (2.5 minutes) if set to 0s and can be disabled if set to -1. - - - `clock_skew_leeway` (Defaults to `"0s"`) Duration of leeway when - validating all claims to account for clock skew. Defaults to 60s (1 minute) - if set to 0s and can be disabled if set to -1ns. - - - `claim_assertions` (Defaults to []) List of assertions about the mapped - claims required to authorize the incoming RPC request. The syntax uses - github.com/hashicorp/go-bexpr which is shared with the - [API filtering feature](/api/features/filtering). For example, the following - configurations when combined will ensure that the JWT `sub` matches the node - name requested by the client. - - ``` - claim_mappings { - sub = "node_name" - } - claim_assertions = [ - "value.node_name == \"${node}\"" - ] - ``` - - The assertions are lightly templated using [HIL syntax](https://github.com/hashicorp/hil) - to interpolate some values from the RPC request. The list of variables that can be interpolated - are: - - - `node` - The node name the client agent is requesting. - - - `segment` - The network segment name the client is requesting. - - - `partition` - The admin partition name the client is requesting. - -- `auto_encrypt` This object allows setting options for the `auto_encrypt` feature. - - The following sub-keys are available: - - - `allow_tls` (Defaults to `false`) This option enables - `auto_encrypt` on the servers and allows them to automatically distribute certificates - from the Connect CA to the clients. If enabled, the server can accept incoming - connections from both the built-in CA and the Connect CA, as well as their certificates. - Note, the server will only present the built-in CA and certificate, which the - client can verify using the CA it received from `auto_encrypt` endpoint. If disabled, - a client configured with `auto_encrypt.tls` will be unable to start. - - - `tls` (Defaults to `false`) Allows the client to request the - Connect CA and certificates from the servers, for encrypting RPC communication. - The client will make the request to any servers listed in the `-join` or `-retry-join` - option. This requires that every server to have `auto_encrypt.allow_tls` enabled. - When both `auto_encrypt` options are used, it allows clients to receive certificates - that are generated on the servers. If the `-server-port` is not the default one, - it has to be provided to the client as well. Usually this is discovered through - LAN gossip, but `auto_encrypt` provision happens before the information can be - distributed through gossip. The most secure `auto_encrypt` setup is when the - client is provided with the built-in CA, `verify_server_hostname` is turned on, - and when an ACL token with `node.write` permissions is setup. It is also possible - to use `auto_encrypt` with a CA and ACL, but without `verify_server_hostname`, - or only with a ACL enabled, or only with CA and `verify_server_hostname`, or - only with a CA, or finally without a CA and without ACL enabled. In any case, - the communication to the `auto_encrypt` endpoint is always TLS encrypted. - - ~> **Warning:** Enabling `auto_encrypt.tls` conflicts with the [`auto_config`](#auto_config) feature. - Only one option may be specified. - - - `dns_san` (Defaults to `[]`) When this option is being - used, the certificates requested by `auto_encrypt` from the server have these - `dns_san` set as DNS SAN. - - - `ip_san` (Defaults to `[]`) When this option is being used, - the certificates requested by `auto_encrypt` from the server have these `ip_san` - set as IP SAN. - -- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](#_bootstrap). - -- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](#_bootstrap_expect). - -- `bind_addr` Equivalent to the [`-bind` command-line flag](#_bind). - - This parameter can be set to a go-sockaddr template that resolves to a single - address. Special characters such as backslashes `\` or double quotes `"` - within a double quoted string value must be escaped with a backslash `\`. - Some example templates: - - - -```hcl -bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}" -``` - -```json -{ - "bind_addr": "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}" -} -``` - - - -- `cache` configuration for client agents. The configurable values are the following: - - - `entry_fetch_max_burst` The size of the token bucket used to recharge the rate-limit per - cache entry. The default value is 2 and means that when cache has not been updated - for a long time, 2 successive queries can be made as long as the rate-limit is not - reached. - - - `entry_fetch_rate` configures the rate-limit at which the cache may refresh a single - entry. On a cluster with many changes/s, watching changes in the cache might put high - pressure on the servers. This ensures the number of requests for a single cache entry - will never go beyond this limit, even when a given service changes every 1/100s. - Since this is a per cache entry limit, having a highly unstable service will only rate - limit the watched on this service, but not the other services/entries. - The value is strictly positive, expressed in queries per second as a float, - 1 means 1 query per second, 0.1 mean 1 request every 10s maximum. - The default value is "No limit" and should be tuned on large - clusters to avoid performing too many RPCs on entries changing a lot. - -- `check_update_interval` ((#check_update_interval)) - This interval controls how often check output from checks in a steady state is - synchronized with the server. By default, this is set to 5 minutes ("5m"). Many - checks which are in a steady state produce slightly different output per run (timestamps, - etc) which cause constant writes. This configuration allows deferring the sync - of check output for a given interval to reduce write pressure. If a check ever - changes state, the new state and associated output is synchronized immediately. - To disable this behavior, set the value to "0s". - -- `client_addr` Equivalent to the [`-client` command-line flag](#_client). - -- `config_entries` This object allows setting options for centralized config entries. - - The following sub-keys are available: - - - `bootstrap` ((#config_entries_bootstrap)) - This is a list of inlined config entries to insert into the state store when - the Consul server gains leadership. This option is only applicable to server - nodes. Each bootstrap entry will be created only if it does not exist. When reloading, - any new entries that have been added to the configuration will be processed. - See the [configuration entry docs](/docs/agent/config-entries) for more - details about the contents of each entry. - -- `connect` This object allows setting options for the Connect feature. - - The following sub-keys are available: - - - `enabled` ((#connect_enabled)) Controls whether Connect features are - enabled on this agent. Should be enabled on all servers in the cluster - in order for Connect to function properly. Defaults to false. - - - `enable_mesh_gateway_wan_federation` ((#connect_enable_mesh_gateway_wan_federation)) Controls whether cross-datacenter federation traffic between servers is funneled - through mesh gateways. Defaults to false. This was added in Consul 1.8.0. - - - `ca_provider` ((#connect_ca_provider)) Controls which CA provider to - use for Connect's CA. Currently only the `aws-pca`, `consul`, and `vault` providers are supported. - This is only used when initially bootstrapping the cluster. For an existing cluster, - use the [Update CA Configuration Endpoint](/api/connect/ca#update-ca-configuration). - - - `ca_config` ((#connect_ca_config)) An object which allows setting different - config options based on the CA provider chosen. This is only used when initially - bootstrapping the cluster. For an existing cluster, use the [Update CA Configuration - Endpoint](/api/connect/ca#update-ca-configuration). - - The following providers are supported: - - #### AWS ACM Private CA Provider (`ca_provider = "aws-pca"`) - - - `existing_arn` ((#aws_ca_existing_arn)) The Amazon Resource Name (ARN) of - an existing private CA in your ACM account. If specified, Consul will - attempt to use the existing CA to issue certificates. - - #### Consul CA Provider (`ca_provider = "consul"`) - - - `private_key` ((#consul_ca_private_key)) The PEM contents of the - private key to use for the CA. - - - `root_cert` ((#consul_ca_root_cert)) The PEM contents of the root - certificate to use for the CA. - - #### Vault CA Provider (`ca_provider = "vault"`) - - - `address` ((#vault_ca_address)) The address of the Vault server to - connect to. - - - `token` ((#vault_ca_token)) The Vault token to use. In Consul 1.8.5 and later, if - the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable) - flag set, Consul will attempt to renew its lease periodically after half the - duration has expired. - - - `root_pki_path` ((#vault_ca_root_pki)) The path to use for the root - CA pki backend in Vault. This can be an existing backend with a CA already - configured, or a blank/unmounted backend in which case Connect will automatically - mount/generate the CA. The Vault token given above must have `sudo` access - to this backend, as well as permission to mount the backend at this path if - it is not already mounted. - - - `intermediate_pki_path` ((#vault_ca_intermediate_pki)) - The path to use for the temporary intermediate CA pki backend in Vault. **Connect - will overwrite any data at this path in order to generate a temporary intermediate - CA**. The Vault token given above must have `write` access to this backend, - as well as permission to mount the backend at this path if it is not already - mounted. - - #### Common CA Config Options - - There are also a number of common configuration options supported by all providers: - - - `csr_max_concurrent` ((#ca_csr_max_concurrent)) Sets a limit on the number - of Certificate Signing Requests that can be processed concurrently. Defaults - to 0 (disabled). This is useful when you want to limit the number of CPU cores - available to the server for certificate signing operations. For example, on an - 8 core server, setting this to 1 will ensure that no more than one CPU core - will be consumed when generating or rotating certificates. Setting this is - recommended **instead** of `csr_max_per_second` when you want to limit the - number of cores consumed since it is simpler to reason about limiting CSR - resources this way without artificially slowing down rotations. Added in 1.4.1. - - - `csr_max_per_second` ((#ca_csr_max_per_second)) Sets a rate limit - on the maximum number of Certificate Signing Requests (CSRs) the servers will - accept. This is used to prevent CA rotation from causing unbounded CPU usage - on servers. It defaults to 50 which is conservative – a 2017 Macbook can process - about 100 per second using only ~40% of one CPU core – but sufficient for deployments - up to ~1500 service instances before the time it takes to rotate is impacted. - For larger deployments we recommend increasing this based on the expected number - of server instances and server resources, or use `csr_max_concurrent` instead - if servers have more than one CPU core. Setting this to zero disables rate limiting. - Added in 1.4.1. - - - `leaf_cert_ttl` ((#ca_leaf_cert_ttl)) The upper bound on the lease - duration of a leaf certificate issued for a service. In most cases a new leaf - certificate will be requested by a proxy before this limit is reached. This - is also the effective limit on how long a server outage can last (with no leader) - before network connections will start being rejected. Defaults to `72h`. - This value cannot be lower than 1 hour or higher than 1 year. - - This value is also used when rotating out old root certificates from - the cluster. When a root certificate has been inactive (rotated out) - for more than twice the _current_ `leaf_cert_ttl`, it will be removed - from the trusted list. - - - `root_cert_ttl` ((#ca_root_cert_ttl)) The time to live (TTL) for a root certificate. - Defaults to 10 years as `87600h`. This value, if provided, needs to be higher than the - intermediate certificate TTL. - - This setting applies to all Consul CA providers. - - For the Vault provider, this value is only used if the backend is not initialized at first. - - This value is also applied on the `ca set-config` command. - - - `private_key_type` ((#ca_private_key_type)) The type of key to generate - for this CA. This is only used when the provider is generating a new key. If - `private_key` is set for the Consul provider, or existing root or intermediate - PKI paths given for Vault then this will be ignored. Currently supported options - are `ec` or `rsa`. Default is `ec`. - - It is required that all servers in a datacenter have - the same config for the CA. It is recommended that servers in - different datacenters use the same key type and size, - although the built-in CA and Vault provider will both allow mixed CA - key types. - - Some CA providers (currently Vault) will not allow cross-signing a - new CA certificate with a different key type. This means that if you - migrate from an RSA-keyed Vault CA to an EC-keyed CA from any - provider, you may have to proceed without cross-signing which risks - temporary connection issues for workloads during the new certificate - rollout. We highly recommend testing this outside of production to - understand the impact and suggest sticking to same key type where - possible. - - Note that this only affects _CA_ keys generated by the provider. - Leaf certificate keys are always EC 256 regardless of the CA - configuration. - - - `private_key_bits` ((#ca_private_key_bits)) The length of key to - generate for this CA. This is only used when the provider is generating a new - key. If `private_key` is set for the Consul provider, or existing root or intermediate - PKI paths given for Vault then this will be ignored. - - Currently supported values are: - - - `private_key_type = ec` (default): `224, 256, 384, 521` - 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)) **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) - for more information. Defaults to true. - -- `disable_keyring_file` - Equivalent to the - [`-disable-keyring-file` command-line flag](#_disable_keyring_file). - -- `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). - When network coordinates are disabled the `near` query param will not work to sort the nodes, - and the [`consul rtt`](/commands/rtt) command will not be able to provide round trip time between nodes. - -- `gossip_lan` - **(Advanced)** This object contains a - number of sub-keys which can be set to tune the LAN gossip communications. These - are only provided for users running especially large clusters that need fine tuning - and are prepared to spend significant effort correctly tuning them for their environment - and workload. **Tuning these improperly can cause Consul to fail in unexpected - ways**. The default values are appropriate in almost all deployments. - - - `gossip_nodes` - The number of random nodes to send - gossip messages to per gossip_interval. Increasing this number causes the gossip - messages to propagate across the cluster more quickly at the expense of increased - bandwidth. The default is 3. - - - `gossip_interval` - The interval between sending - messages that need to be gossiped that haven't been able to piggyback on probing - messages. If this is set to zero, non-piggyback gossip is disabled. By lowering - this value (more frequent) gossip messages are propagated across the cluster - more quickly at the expense of increased bandwidth. The default is 200ms. - - - `probe_interval` - The interval between random - node probes. Setting this lower (more frequent) will cause the cluster to detect - failed nodes more quickly at the expense of increased bandwidth usage. The default - is 1s. - - - `probe_timeout` - The timeout to wait for an ack - from a probed node before assuming it is unhealthy. This should be at least the - 99-percentile of RTT (round-trip time) on your network. The default is 500ms - and is a conservative value suitable for almost all realistic deployments. - - - `retransmit_mult` - The multiplier for the number - of retransmissions that are attempted for messages broadcasted over gossip. The - number of retransmits is scaled using this multiplier and the cluster size. The - higher the multiplier, the more likely a failed broadcast is to converge at the - expense of increased bandwidth. The default is 4. - - - `suspicion_mult` - The multiplier for determining - the time an inaccessible node is considered suspect before declaring it dead. - The timeout is scaled with the cluster size and the probe_interval. This allows - the timeout to scale properly with expected propagation delay with a larger cluster - size. The higher the multiplier, the longer an inaccessible node is considered - part of the cluster before declaring it dead, giving that suspect node more time - to refute if it is indeed still alive. The default is 4. - -- `gossip_wan` - **(Advanced)** This object contains a - number of sub-keys which can be set to tune the WAN gossip communications. These - are only provided for users running especially large clusters that need fine tuning - and are prepared to spend significant effort correctly tuning them for their environment - and workload. **Tuning these improperly can cause Consul to fail in unexpected - ways**. The default values are appropriate in almost all deployments. - - - `gossip_nodes` - The number of random nodes to send - gossip messages to per gossip_interval. Increasing this number causes the gossip - messages to propagate across the cluster more quickly at the expense of increased - bandwidth. The default is 4. - - - `gossip_interval` - The interval between sending - messages that need to be gossiped that haven't been able to piggyback on probing - messages. If this is set to zero, non-piggyback gossip is disabled. By lowering - this value (more frequent) gossip messages are propagated across the cluster - more quickly at the expense of increased bandwidth. The default is 500ms. - - - `probe_interval` - The interval between random - node probes. Setting this lower (more frequent) will cause the cluster to detect - failed nodes more quickly at the expense of increased bandwidth usage. The default - is 5s. - - - `probe_timeout` - The timeout to wait for an ack - from a probed node before assuming it is unhealthy. This should be at least the - 99-percentile of RTT (round-trip time) on your network. The default is 3s - and is a conservative value suitable for almost all realistic deployments. - - - `retransmit_mult` - The multiplier for the number - of retransmissions that are attempted for messages broadcasted over gossip. The - number of retransmits is scaled using this multiplier and the cluster size. The - higher the multiplier, the more likely a failed broadcast is to converge at the - expense of increased bandwidth. The default is 4. - - - `suspicion_mult` - The multiplier for determining - the time an inaccessible node is considered suspect before declaring it dead. - The timeout is scaled with the cluster size and the probe_interval. This allows - the timeout to scale properly with expected propagation delay with a larger cluster - size. The higher the multiplier, the longer an inaccessible node is considered - part of the cluster before declaring it dead, giving that suspect node more time - to refute if it is indeed still alive. The default is 6. - -- `http_config` This object allows setting options for the HTTP API and UI. - - The following sub-keys are available: - - - `block_endpoints` - This object is a list of HTTP API endpoint prefixes to block on the agent, and - defaults to an empty list, meaning all endpoints are enabled. Any endpoint that - has a common prefix with one of the entries on this list will be blocked and - will return a 403 response code when accessed. For example, to block all of the - V1 ACL endpoints, set this to `["/v1/acl"]`, which will block `/v1/acl/create`, - `/v1/acl/update`, and the other ACL endpoints that begin with `/v1/acl`. This - only works with API endpoints, not `/ui` or `/debug`, those must be disabled - with their respective configuration options. Any CLI commands that use disabled - endpoints will no longer function as well. For more general access control, Consul's - [ACL system](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) - 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` 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` - 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 - [`use_streaming_backend`](#use_streaming_backend). - -- `segment` - Equivalent to the [`-segment` command-line flag](#_segment). - - ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. - -- `segments` - (Server agents only) This is a list of nested objects - that specifies user-defined network segments, not including the `` segment, which is - created automatically. Review the [Network Segments documentation](/docs/enterprise/network-segments) - for more details. - - - `name` ((#segment_name)) - The name of the segment. Must be a string - between 1 and 64 characters in length. - - `bind` ((#segment_bind)) - The bind address to use for the segment's - gossip layer. Defaults to the [`-bind`](#_bind) value if not provided. - - `port` ((#segment_port)) - The port to use for the segment's gossip - layer (required). - - `advertise` ((#segment_advertise)) - The advertise address to use for - the segment's gossip layer. Defaults to the [`-advertise`](#_advertise) value - if not provided. - - `rpc_listener` ((#segment_rpc_listener)) - 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. - -- `server` Equivalent to the [`-server` command-line flag](#_server). - -- `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** - -- `read_replica` - Equivalent to the [`-read-replica` command-line flag](#_read_replica). - -- `session_ttl_min` 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. - -- `skip_leave_on_interrupt` 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). - -- `start_join` An array of strings specifying addresses - of nodes to [`-join`](#_join) upon startup. Note that using - `retry_join` could be more appropriate to help mitigate - node startup race conditions when automating a Consul cluster deployment. - -- `start_join_wan` An array of strings specifying addresses - of WAN nodes to [`-join-wan`](#_join_wan) upon startup. - -- `telemetry` This is a nested object that configures where - Consul sends its runtime telemetry, and contains the following keys: - - - `circonus_api_token` ((#telemetry-circonus_api_token)) A valid API - Token used to create/manage check. If provided, metric management is - enabled. - - - `circonus_api_app` ((#telemetry-circonus_api_app)) A valid app name - associated with the API token. By default, this is set to "consul". - - - `circonus_api_url` ((#telemetry-circonus_api_url)) - 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). - - - `circonus_submission_url` ((#telemetry-circonus_submission_url)) - The `check.config.submission_url` field, of a Check API object, from a previously - created HTTPTrap check. - - - `circonus_check_id` ((#telemetry-circonus_check_id)) - 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. - - - `circonus_check_tags` ((#telemetry-circonus_check_tags)) - Comma separated list of additional tags to add to a check when it is created. - Available in Consul 0.7.2 and later. - - - `circonus_broker_id` ((#telemetry-circonus_broker_id)) - The ID of a specific Circonus Broker to use when creating a new check. The numeric - portion of `broker._cid` field in a Broker API object. If metric management is - enabled and neither a Submission URL nor Check ID is provided, an attempt will - be made to search for an existing check using Instance ID and Search Tag. If - one is not found, a new HTTPTrap check will be created. By default, this is not - used and a random Enterprise Broker is selected, or the default Circonus Public - Broker. - - - `circonus_broker_select_tag` ((#telemetry-circonus_broker_select_tag)) A special tag which will be used to select a Circonus Broker when a Broker ID - is not provided. The best use of this is to as a hint for which broker should - be used based on **where** this particular instance is running (e.g. a specific - geo location or datacenter, dc:sfo). By default, this is left blank and not used. - - - `disable_compat_1.9` ((#telemetry-disable_compat_1.9)) - 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. - - - `disable_hostname` ((#telemetry-disable_hostname)) - This controls whether or not to prepend runtime telemetry with the machine's - hostname, defaults to false. - - - `dogstatsd_addr` ((#telemetry-dogstatsd_addr)) This provides the address - of a DogStatsD instance in the format `host:port`. DogStatsD is a protocol-compatible - flavor of statsd, with the added ability to decorate metrics with tags and event - information. If provided, Consul will send various telemetry information to that - instance for aggregation. This can be used to capture runtime information. - - - `dogstatsd_tags` ((#telemetry-dogstatsd_tags)) This provides a list - of global tags that will be added to all telemetry packets sent to DogStatsD. - It is a list of strings, where each string looks like "my_tag_name:my_tag_value". - - - `filter_default` ((#telemetry-filter_default)) - This controls whether to allow metrics that have not been specified by the filter. - Defaults to `true`, which will allow all metrics when no filters are provided. - When set to `false` with no filters, no metrics will be sent. - - - `metrics_prefix` ((#telemetry-metrics_prefix)) - The prefix used while writing all telemetry data. By default, this is set to - "consul". This was added in Consul 1.0. For previous versions of Consul, use - the config option `statsite_prefix` in this same structure. This was renamed - in Consul 1.0 since this prefix applied to all telemetry providers, not just - statsite. - - - `prefix_filter` ((#telemetry-prefix_filter)) - This is a list of filter rules to apply for allowing/blocking metrics by - prefix in the following format: - - ```json - ["+consul.raft.apply", "-consul.http", "+consul.http.GET"] - ``` - - 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 - [`/v1/agent/metrics?format=prometheus`](/api/agent#view-metrics) endpoint. - The format is compatible natively with prometheus. When running in this mode, - it is recommended to also enable the option [`disable_hostname`](#telemetry-disable_hostname) - to avoid having prefixed metrics with hostname. Consul does not use the default - Prometheus path, so Prometheus must be configured as follows. Note that using - ?format=prometheus in the path won't work as ? will be escaped, so it must be - specified as a parameter. - - ```yaml - metrics_path: '/v1/agent/metrics' - params: - format: ['prometheus'] - ``` - - - `statsd_address` ((#telemetry-statsd_address)) This provides the address - of a statsd instance in the format `host:port`. If provided, Consul will send - various telemetry information to that instance for aggregation. This can be used - to capture runtime information. This sends UDP packets only and can be used with - statsd or statsite. - - - `statsite_address` ((#telemetry-statsite_address)) This provides the - address of a statsite instance in the format `host:port`. If provided, Consul - will stream various telemetry information to that instance for aggregation. This - can be used to capture runtime information. This streams via TCP and can only - be used with statsite. - -- `syslog_facility` When [`enable_syslog`](#enable_syslog) - is provided, this controls to which facility messages are sent. By default, `LOCAL0` - will be used. - -- `translate_wan_addrs` If set to true, Consul - will prefer a node's configured [WAN address](#_advertise-wan) - when servicing DNS and HTTP requests for a node in a remote datacenter. This allows - the node to be reached within its own datacenter using its local address, and reached - from other datacenters using its WAN address, which is useful in hybrid setups - with mixed networks. This is disabled by default. - - Starting in Consul 0.7 and later, node addresses in responses to HTTP requests will also prefer a - node's configured [WAN address](#_advertise-wan) when querying for a node in a remote - datacenter. An [`X-Consul-Translate-Addresses`](/api#translated-addresses) header - will be present on all responses when translation is enabled to help clients know that the addresses - may be translated. The `TaggedAddresses` field in responses also have a `lan` address for clients that - need knowledge of that address, regardless of translation. - - The following endpoints translate addresses: - - - [`/v1/catalog/nodes`](/api/catalog#list-nodes) - - [`/v1/catalog/node/`](/api/catalog#retrieve-map-of-services-for-a-node) - - [`/v1/catalog/service/`](/api/catalog#list-nodes-for-service) - - [`/v1/health/service/`](/api/health#list-nodes-for-service) - - [`/v1/query//execute`](/api/query#execute-prepared-query) - -- `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** - Equivalent to the [`-ui`](#_ui) command-line flag. - -- `ui_config` - This object allows a number of sub-keys to be set which controls - the display or features available in the UI. Configuring the UI with this - stanza was added in Consul 1.9.0. - - The following sub-keys are available: - - - `enabled` ((#ui_config_enabled)) - This enables the service of the web UI - from this agent. Boolean value, defaults to false. In `-dev` mode this - defaults to true. Replaces `ui` from before 1.9.0. Equivalent to the - [`-ui`](#_ui) command-line flag. - - - `dir` ((#ui_config_dir)) - This specifies that the web UI should be served - from an external dir rather than the build in one. This allows for - customization or development. Replaces `ui_dir` from before 1.9.0. - Equivalent to the [`-ui-dir`](#_ui_dir) command-line flag. - - - `content_path` ((#ui_config_content_path)) - This specifies the HTTP path - that the web UI should be served from. Defaults to `/ui/`. Equivalent to the - [`-ui-content-path`](#_ui_content_path) flag. - - - `metrics_provider` ((#ui_config_metrics_provider)) - Specifies a named - metrics provider implementation the UI should use to fetch service metrics. - By default metrics are disabled. Consul 1.9.0 includes a built-in provider - named `prometheus` that can be enabled explicitly here. It also requires the - `metrics_proxy` to be configured below and direct queries to a Prometheus - instance that has Envoy metrics for all services in the datacenter. - - - `metrics_provider_files` ((#ui_config_metrics_provider_files)) - An optional array - of absolute paths to javascript files on the Agent's disk which will be - served as part of the UI. These files should contain metrics provider - implementations and registration enabling UI metric queries to be customized - or implemented for an alternative time-series backend. - - ~> **Security Note:** These javascript files are included in the UI with no - further validation or sand-boxing. By configuring them here the operator is - fully trusting anyone able to write to them as well as the original authors - not to include malicious code in the UI being served. - - - `metrics_provider_options_json` ((#ui_config_metrics_provider_options_json)) - - This is an optional raw JSON object as a string which is passed to the - provider implementation's `init` method at startup to allow arbitrary - configuration to be passed through. - - - `metrics_proxy` ((#ui_config_metrics_proxy)) - This object configures an - internal agent API endpoint that will proxy GET requests to a metrics - backend to allow querying metrics data in the UI. This simplifies deployment - where the metrics backend is not exposed externally to UI users' browsers. - It may also be used to augment requests with API credentials to allow - serving graphs to UI users without them needing individual access tokens for - the metrics backend. - - ~> **Security Note:** Exposing your metrics backend via Consul in this way - should be carefully considered in production. As Consul doesn't understand - the requests, it can't limit access to only specific resources. For example - **this might make it possible for a malicious user on the network to query - for arbitrary metrics about any server or workload in your infrastructure, - or overload the metrics infrastructure with queries**. See [Metrics Proxy - Security](/docs/connect/observability/ui-visualization#metrics-proxy-security) - for more details. - - The following sub-keys are available: - - - `base_url` ((#ui_config_metrics_provider_base_url)) - This is required to - enable the proxy. It should be set to the base URL that the Consul agent - should proxy requests for metrics too. For example a value of - `http://prometheus-server` would target a Prometheus instance with local - DNS name "prometheus-server" on port 80. This may include a path prefix - which will then not be necessary in provider requests to the backend and - the proxy will prevent any access to paths without that prefix on the - backend. - - - `path_allowlist` ((#ui_config_metrics_provider_path_allowlist)) - This - specifies the paths that may be proxies to when appended to the - `base_url`. It defaults to `["/api/v1/query_range", "/api/v1/query"]` - which are the endpoints required for the built-in Prometheus provider. If - a [custom - provider](/docs/connect/observability/ui-visualization#custom-metrics-providers) - is used that requires the metrics proxy, the correct allowlist must be - specified to enable proxying to necessary endpoints. See [Path - Allowlist](/docs/connect/observability/ui-visualization#path-allowlist) - for more information. - - - `add_headers` ((#ui_config_metrics_proxy_add_headers)) - This is an - optional list if headers to add to requests that are proxied to the - metrics backend. It may be used to inject Authorization tokens within the - agent without exposing those to UI users. - - Each item in the list is an object with the following keys: - - - `name` ((#ui_config_metrics_proxy_add_headers_name)) - Specifies the - HTTP header name to inject into proxied requests. - - - `value` ((#ui_config_metrics_proxy_add_headers_value)) - Specifies the - value in inject into proxied requests. - - - `dashboard_url_templates` ((#ui_config_dashboard_url_templates)) - This map - specifies URL templates that may be used to render links to external - dashboards in various contexts in the UI. It is a map with the name of the - template as a key. The value is a string URL with optional placeholders. - - Each template may contain placeholders which will be substituted for the - correct values in content when rendered in the UI. The placeholders - available are listed for each template. - - For more information and examples see [UI - Visualization](/docs/connect/observability/ui-visualization#configuring-dashboard-urls) - - The following named templates are defined: - - - `service` ((#ui_config_dashboard_url_templates_service)) - This is the URL - to use when linking to the dashboard for a specific service. It is shown - as part of the [Topology - Visualization](/docs/connect/observability/ui-visualization). - - The placeholders available are: - - - `{{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 - [this search](https://github.com/hashicorp/consul/search?q=cipherMap+%3A%3D+map&unscoped_q=cipherMap+%3A%3D+map). - - ~> **Note:** The ordering of cipher suites will not be guaranteed from Consul 1.11 onwards. See this - [post](https://go.dev/blog/tls-cipher-suites) for details. - -- `tls_prefer_server_cipher_suites` Added in Consul 0.8.2, this - will cause Consul to prefer the server's ciphersuite over the client ciphersuites. - - ~> **Note:** This config will be deprecated in Consul 1.11. See this - [post](https://go.dev/blog/tls-cipher-suites) for details. - -- `verify_incoming` - If set to true, Consul - requires that all incoming connections make use of TLS and that the client - provides a certificate signed by a Certificate Authority from the - [`ca_file`](#ca_file) or [`ca_path`](#ca_path). This applies to both server - RPC and to the HTTPS API. By default, this is false, and Consul will not - enforce the use of TLS or verify a client's authenticity. Turning on - `verify_incoming` on consul clients protects the HTTPS endpoint, by ensuring - that the certificate that is presented by a 3rd party tool to the HTTPS - endpoint was created by the CA that the consul client was setup with. If the - UI is served, the same checks are performed. - -- `verify_incoming_rpc` - When set to true, Consul - requires that all incoming RPC connections use TLS and that the client - provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file) - or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce - the use of TLS or verify a client's authenticity. - - ~> **Security Note:** `verify_incoming_rpc` _must_ be set to true to prevent anyone - with access to the RPC port from gaining full access to the Consul cluster. - -- `verify_incoming_https` - If set to true, - Consul requires that all incoming HTTPS connections make use of TLS and that the - client provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file) - or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce - the use of TLS or verify a client's authenticity. To enable the HTTPS API, you - must define an HTTPS port via the [`ports`](#ports) configuration. By default, - HTTPS is disabled. - -- `verify_outgoing` - If set to true, Consul requires - that all outgoing connections from this agent make use of TLS and that the server - provides a certificate that is signed by a Certificate Authority from the [`ca_file`](#ca_file) - or [`ca_path`](#ca_path). By default, this is false, and Consul will not make use - of TLS for outgoing connections. This applies to clients and servers as both will - make outgoing connections. - - ~> **Security Note:** Note that servers that specify `verify_outgoing = true` will always talk to other servers over TLS, but they still _accept_ - non-TLS connections to allow for a transition of all clients to TLS. - Currently the only way to enforce that no client can communicate with a - server unencrypted is to also enable `verify_incoming` which requires client - certificates too. - -- `verify_server_hostname` - When set to true, Consul verifies the TLS certificate - presented by the servers match the hostname `server..`. - By default this is false, and Consul does not verify the hostname - of the certificate, only that it is signed by a trusted CA. This setting _must_ be enabled - to prevent a compromised client from gaining full read and write access to all - cluster data _including all ACL tokens and Connect CA root keys_. This is new in 0.5.1. - - ~> **Security Note:** From versions 0.5.1 to 1.4.0, due to a bug, setting - this flag alone _does not_ imply `verify_outgoing` and leaves client to server - and server to server RPCs unencrypted despite the documentation stating otherwise. See - [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) - for more details. For those versions you **must also set `verify_outgoing = true`** to ensure encrypted RPC connections. - -### Example Configuration File, with TLS - -~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both -encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) -will result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file). - -```json -{ - "datacenter": "east-aws", - "data_dir": "/opt/consul", - "log_level": "INFO", - "node_name": "foobar", - "server": true, - "addresses": { - "https": "0.0.0.0" - }, - "ports": { - "https": 8501 - }, - "key_file": "/etc/pki/tls/private/my.key", - "cert_file": "/etc/pki/tls/certs/my.crt", - "ca_file": "/etc/pki/tls/certs/ca-bundle.crt", - "verify_incoming": true, - "verify_outgoing": true, - "verify_server_hostname": true -} -``` - -See, especially, the use of the `ports` setting: - -```json -"ports": { - "https": 8501 -} -``` - -Consul will not enable TLS for the HTTP API unless the `https` port has been -assigned a port number `> 0`. We recommend using `8501` for `https` as this -default will automatically work with some tooling. - ## Ports Used Consul requires up to 6 different ports to work properly, some on From 1ec8b58f7b35626df8881324fa913cafa206273e Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 11:30:56 -0800 Subject: [PATCH 04/10] docs: arrange agent configuration file parameters into logical groups --- .../docs/agent/config/agent-config-cli.mdx | 24 +- .../docs/agent/config/agent-config-files.mdx | 1278 +++++++++-------- 2 files changed, 666 insertions(+), 636 deletions(-) diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/agent-config-cli.mdx index ff19b147fd..8daeebcc18 100644 --- a/website/content/docs/agent/config/agent-config-cli.mdx +++ b/website/content/docs/agent/config/agent-config-cli.mdx @@ -56,17 +56,6 @@ information. intended for production use as it does not write any data to disk. The gRPC port is also defaulted to `8502` in this mode. -- `-disable-host-node-id` ((#\_disable_host_node_id)) - Setting this to - true will prevent Consul from using information from the host to generate a deterministic - node ID, and will instead generate a random node ID which will be persisted in - the data directory. This is useful when running multiple Consul agents on the same - host for testing. This defaults to false in Consul prior to version 0.8.5 and in - 0.8.5 and later defaults to true, so you must opt-in for host-based IDs. Host-based - IDs are generated using [gopsutil](https://github.com/shirou/gopsutil/tree/master/v3/host), which - is shared with HashiCorp's [Nomad](https://www.nomadproject.io/), so if you opt-in - to host-based IDs then Consul and Nomad will use information on the host to automatically - assign the same ID in both systems. - - `-disable-keyring-file` ((#\_disable_keyring_file)) - If set, the keyring will not be persisted to a file. Any installed keys will be lost on shutdown, and only the given `-encrypt` key will be available on startup. This defaults to false. @@ -166,7 +155,7 @@ information. accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. -## Bind Options +## Address Bind Options - `-bind` ((#\_bind)) - The address that should be bound to for internal cluster communications. This is an IP address that should be reachable by all other @@ -452,6 +441,17 @@ information. - Metadata values for keys beginning with `rfc1035-` are encoded verbatim in DNS TXT requests, otherwise the metadata kv-pair is encoded according [RFC1464](https://www.ietf.org/rfc/rfc1464.txt). +- `-disable-host-node-id` ((#\_disable_host_node_id)) - Setting this to + true will prevent Consul from using information from the host to generate a deterministic + node ID, and will instead generate a random node ID which will be persisted in + the data directory. This is useful when running multiple Consul agents on the same + host for testing. This defaults to false in Consul prior to version 0.8.5 and in + 0.8.5 and later defaults to true, so you must opt-in for host-based IDs. Host-based + IDs are generated using [gopsutil](https://github.com/shirou/gopsutil/tree/master/v3/host), which + is shared with HashiCorp's [Nomad](https://www.nomadproject.io/), so if you opt-in + to host-based IDs then Consul and Nomad will use information on the host to automatically + assign the same ID in both systems. + ## Serf Options - `-serf-lan-allowed-cidrs` ((#\_serf_lan_allowed_cidrs)) - The Serf LAN allowed CIDRs allow to accept incoming diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx index a454adb0e5..f22a1eb69a 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/agent-config-files.mdx @@ -43,7 +43,7 @@ definitions support being updated during a reload. } ``` -#### Configuration Key Reference +# Configuration Key Reference -> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following [formatting specification](https://golang.org/pkg/time/#ParseDuration): "A @@ -51,221 +51,7 @@ duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as '300ms', '-1.5h' or '2h45m'. Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." -- `acl` ((#acl)) - This object allows a number of sub-keys to be set which - controls the ACL system. Configuring the ACL system within the ACL stanza was added - in Consul 1.4.0 - - The following sub-keys are available: - - - `enabled` ((#acl_enabled)) - Enables ACLs. - - - `policy_ttl` ((#acl_policy_ttl)) - Used to control Time-To-Live caching - of ACL policies. 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. - - - `role_ttl` ((#acl_role_ttl)) - Used to control Time-To-Live caching - of ACL roles. 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 role may be stale up to the TTL value. - - - `token_ttl` ((#acl_token_ttl)) - Used to control Time-To-Live caching - of ACL tokens. 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 token may be stale up to the TTL value. - - - `down_policy` ((#acl_down_policy)) - Either "allow", "deny", "extend-cache" - or "async-cache"; "extend-cache" is the default. In the case that a policy or - 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 objects - to be used, ignoring the expiry time of the cached entry. If the request uses an - ACL that is not in the cache, "extend-cache" falls back to the behaviour of - `default_policy`. - 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 the primary and secondary datacenters, latency - of operations is not impacted. - - - `default_policy` ((#acl_default_policy)) - Either "allow" or "deny"; - defaults to "allow" but this will be changed in a future major release. 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 enabled ACLs. - - - `enable_key_list_policy` ((#acl_enable_key_list_policy)) - Boolean value, defaults to false. - When true, the `list` permission will be required on the prefix being recursively read from the KV store. - Regardless of being enabled, the full set of KV entries under the prefix will be filtered - to remove any entries that the request's ACL token does not grant at least read - permissions. This option is only available in Consul 1.0 and newer. - - - `enable_token_replication` ((#acl_enable_token_replication)) - By default - secondary Consul datacenters will perform replication of only ACL policies and - roles. Setting this configuration will will enable ACL token replication and - allow for the creation of both [local tokens](/api/acl/tokens#local) and - [auth methods](/docs/acl/auth-methods) in connected secondary datacenters. - - ~> **Warning:** When enabling ACL token replication on the secondary datacenter, - global tokens already present in the secondary datacenter will be lost. For - production environments, consider configuring ACL replication in your initial - datacenter bootstrapping process. - - - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either - `true` or `false`. When `true` tokens set using the API will be persisted to - disk and reloaded when an agent restarts. - - - `tokens` ((#acl_tokens)) - This object holds all of the configured - ACL tokens for the agents usage. - - - `initial_management` ((#acl_tokens_initial_management)) - This is available in - Consul 1.11 and later. In prior versions, use [`acl.tokens.master`](#acl_tokens_master). - - Only used for servers in the [`primary_datacenter`](#primary_datacenter). - This token will be created with management-level permissions if it does not exist. - It allows operators to bootstrap the ACL system with a token Secret ID that is - well-known. - - The `initial_management` token is only installed when a server acquires cluster - leadership. If you would like to install or change it, set the new value for - `initial_management` in the configuration for all servers. Once this is done, - restart the current leader to force a leader election. If the `initial_management` - token is not supplied, then the servers do not create an initial management token. - When you provide a value, it should be a UUID. To maintain backwards compatibility - and an upgrade path this restriction is not currently enforced but will be in a - future major Consul release. - - - `master` ((#acl_tokens_master)) **Renamed in Consul 1.11 to - [`acl.tokens.initial_management`](#acl_tokens_initial_management).** - - - `default` ((#acl_tokens_default)) - 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 token, - is used. - - - `agent` ((#acl_tokens_agent)) - Used for clients and servers to perform - internal operations. If this isn't specified, then the - [`default`](#acl_tokens_default) will be used. - - This token must at least have write access to the node name it will - register as in order to set any of the node-level information in the - catalog such as metadata, or the node's tagged addresses. - - - `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11 - and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master). - - Used to access [agent endpoints](/api/agent) that require agent read or write privileges, - or node read privileges, even if Consul servers aren't present to validate any tokens. - This should only be used by operators during outages, regular ACL tokens should normally - be used by applications. - - - `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to - [`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).** - - - `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)) - An - array of ACL tokens used by Consul managed service providers for cluster operations. - - ```json - "managed_service_provider": [ - { - "accessor_id": "ed22003b-0832-4e48-ac65-31de64e5c2ff", - "secret_id": "cb6be010-bba8-4f30-a9ed-d347128dde17" - } - ] - ``` - -- `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 - not impacted. - -- `acl_agent_master_token` ((#acl_agent_master_token_legacy)) - **Deprecated - in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master) - field instead.** Used to access [agent endpoints](/api/agent) that - require agent read or write privileges, or node read privileges, even if Consul - servers aren't present to validate any tokens. This should only be used by operators - during outages, regular ACL tokens should normally be used by applications. This - was added in Consul 0.7.2 and is only used when [`acl_enforce_version_8`](#acl_enforce_version_8) is set to true. - -- `acl_agent_token` ((#acl_agent_token_legacy)) - **Deprecated in Consul - 1.4.0. See the [`acl.tokens.agent`](#acl_tokens_agent) field instead.** Used for - clients and servers to perform internal operations. If this isn't specified, then - the [`acl_token`](#acl_token) will be used. This was added in Consul 0.7.2. - - This token must at least have write access to the node name it will register as in order to set any - of the node-level information in the catalog such as metadata, or the node's tagged addresses. - -- `acl_enforce_version_8` - **Deprecated in - Consul 1.4.0 and removed in 1.8.0.** Used for clients and servers to determine if enforcement should - occur for new ACL policies being previewed before Consul 0.8. Added in Consul 0.7.2, - this defaults to false in versions of Consul prior to 0.8, and defaults to true - in Consul 0.8 and later. This helps ease the transition to the new ACL features - by allowing policies to be in place before enforcement begins. - -- `acl_master_token` ((#acl_master_token_legacy)) - **Deprecated in Consul - 1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.** - -- `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated - 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. +## General - `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 @@ -294,34 +80,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `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` - 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). @@ -550,49 +310,6 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `partition` - The admin partition name the client is requesting. -- `auto_encrypt` This object allows setting options for the `auto_encrypt` feature. - - The following sub-keys are available: - - - `allow_tls` (Defaults to `false`) This option enables - `auto_encrypt` on the servers and allows them to automatically distribute certificates - from the Connect CA to the clients. If enabled, the server can accept incoming - connections from both the built-in CA and the Connect CA, as well as their certificates. - Note, the server will only present the built-in CA and certificate, which the - client can verify using the CA it received from `auto_encrypt` endpoint. If disabled, - a client configured with `auto_encrypt.tls` will be unable to start. - - - `tls` (Defaults to `false`) Allows the client to request the - Connect CA and certificates from the servers, for encrypting RPC communication. - The client will make the request to any servers listed in the `-join` or `-retry-join` - option. This requires that every server to have `auto_encrypt.allow_tls` enabled. - When both `auto_encrypt` options are used, it allows clients to receive certificates - that are generated on the servers. If the `-server-port` is not the default one, - it has to be provided to the client as well. Usually this is discovered through - LAN gossip, but `auto_encrypt` provision happens before the information can be - distributed through gossip. The most secure `auto_encrypt` setup is when the - client is provided with the built-in CA, `verify_server_hostname` is turned on, - and when an ACL token with `node.write` permissions is setup. It is also possible - to use `auto_encrypt` with a CA and ACL, but without `verify_server_hostname`, - or only with a ACL enabled, or only with CA and `verify_server_hostname`, or - only with a CA, or finally without a CA and without ACL enabled. In any case, - the communication to the `auto_encrypt` endpoint is always TLS encrypted. - - ~> **Warning:** Enabling `auto_encrypt.tls` conflicts with the [`auto_config`](#auto_config) feature. - Only one option may be specified. - - - `dns_san` (Defaults to `[]`) When this option is being - used, the certificates requested by `auto_encrypt` from the server have these - `dns_san` set as DNS SAN. - - - `ip_san` (Defaults to `[]`) When this option is being used, - the certificates requested by `auto_encrypt` from the server have these `ip_san` - set as IP SAN. - -- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](#_bootstrap). - -- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](#_bootstrap_expect). - - `bind_addr` Equivalent to the [`-bind` command-line flag](#_bind). This parameter can be set to a go-sockaddr template that resolves to a single @@ -655,6 +372,594 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr See the [configuration entry docs](/docs/agent/config-entries) for more details about the contents of each entry. +- `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_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. + +- `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). + +- `disable_keyring_file` - Equivalent to the + [`-disable-keyring-file` command-line flag](#_disable_keyring_file). + +- `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). + When network coordinates are disabled the `near` query param will not work to sort the nodes, + and the [`consul rtt`](/commands/rtt) command will not be able to provide round trip time between nodes. + +- `http_config` This object allows setting options for the HTTP API and UI. + + The following sub-keys are available: + + - `block_endpoints` + This object is a list of HTTP API endpoint prefixes to block on the agent, and + defaults to an empty list, meaning all endpoints are enabled. Any endpoint that + has a common prefix with one of the entries on this list will be blocked and + will return a 403 response code when accessed. For example, to block all of the + V1 ACL endpoints, set this to `["/v1/acl"]`, which will block `/v1/acl/create`, + `/v1/acl/update`, and the other ACL endpoints that begin with `/v1/acl`. This + only works with API endpoints, not `/ui` or `/debug`, those must be disabled + with their respective configuration options. Any CLI commands that use disabled + endpoints will no longer function as well. For more general access control, Consul's + [ACL system](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) + 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` 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. + +- `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). + +- `partition` - 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). + +- `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. + +- `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 + [`use_streaming_backend`](#use_streaming_backend). + +- `segment` - Equivalent to the [`-segment` command-line flag](#_segment). + + ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. + +- `segments` - (Server agents only) This is a list of nested objects + that specifies user-defined network segments, not including the `` segment, which is + created automatically. Review the [Network Segments documentation](/docs/enterprise/network-segments) + for more details. + + - `name` ((#segment_name)) - The name of the segment. Must be a string + between 1 and 64 characters in length. + - `bind` ((#segment_bind)) - The bind address to use for the segment's + gossip layer. Defaults to the [`-bind`](#_bind) value if not provided. + - `port` ((#segment_port)) - The port to use for the segment's gossip + layer (required). + - `advertise` ((#segment_advertise)) - The advertise address to use for + the segment's gossip layer. Defaults to the [`-advertise`](#_advertise) value + if not provided. + - `rpc_listener` ((#segment_rpc_listener)) - 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. + +- `server` Equivalent to the [`-server` command-line flag](#_server). + +- `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** + +- `read_replica` - Equivalent to the [`-read-replica` command-line flag](#_read_replica). + +- `session_ttl_min` 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. + +- `skip_leave_on_interrupt` 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). + +- `translate_wan_addrs` If set to true, Consul + will prefer a node's configured [WAN address](#_advertise-wan) + when servicing DNS and HTTP requests for a node in a remote datacenter. This allows + the node to be reached within its own datacenter using its local address, and reached + from other datacenters using its WAN address, which is useful in hybrid setups + with mixed networks. This is disabled by default. + + Starting in Consul 0.7 and later, node addresses in responses to HTTP requests will also prefer a + node's configured [WAN address](#_advertise-wan) when querying for a node in a remote + datacenter. An [`X-Consul-Translate-Addresses`](/api#translated-addresses) header + will be present on all responses when translation is enabled to help clients know that the addresses + may be translated. The `TaggedAddresses` field in responses also have a `lan` address for clients that + need knowledge of that address, regardless of translation. + + The following endpoints translate addresses: + + - [`/v1/catalog/nodes`](/api/catalog#list-nodes) + - [`/v1/catalog/node/`](/api/catalog#retrieve-map-of-services-for-a-node) + - [`/v1/catalog/service/`](/api/catalog#list-nodes-for-service) + - [`/v1/health/service/`](/api/health#list-nodes-for-service) + - [`/v1/query//execute`](/api/query#execute-prepared-query) + +- `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. + +## ACL Paramters + +- `acl` ((#acl)) - This object allows a number of sub-keys to be set which + controls the ACL system. Configuring the ACL system within the ACL stanza was added + in Consul 1.4.0 + + The following sub-keys are available: + + - `enabled` ((#acl_enabled)) - Enables ACLs. + + - `policy_ttl` ((#acl_policy_ttl)) - Used to control Time-To-Live caching + of ACL policies. 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. + + - `role_ttl` ((#acl_role_ttl)) - Used to control Time-To-Live caching + of ACL roles. 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 role may be stale up to the TTL value. + + - `token_ttl` ((#acl_token_ttl)) - Used to control Time-To-Live caching + of ACL tokens. 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 token may be stale up to the TTL value. + + - `down_policy` ((#acl_down_policy)) - Either "allow", "deny", "extend-cache" + or "async-cache"; "extend-cache" is the default. In the case that a policy or + 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 objects + to be used, ignoring the expiry time of the cached entry. If the request uses an + ACL that is not in the cache, "extend-cache" falls back to the behaviour of + `default_policy`. + 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 the primary and secondary datacenters, latency + of operations is not impacted. + + - `default_policy` ((#acl_default_policy)) - Either "allow" or "deny"; + defaults to "allow" but this will be changed in a future major release. 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 enabled ACLs. + + - `enable_key_list_policy` ((#acl_enable_key_list_policy)) - Boolean value, defaults to false. + When true, the `list` permission will be required on the prefix being recursively read from the KV store. + Regardless of being enabled, the full set of KV entries under the prefix will be filtered + to remove any entries that the request's ACL token does not grant at least read + permissions. This option is only available in Consul 1.0 and newer. + + - `enable_token_replication` ((#acl_enable_token_replication)) - By default + secondary Consul datacenters will perform replication of only ACL policies and + roles. Setting this configuration will will enable ACL token replication and + allow for the creation of both [local tokens](/api/acl/tokens#local) and + [auth methods](/docs/acl/auth-methods) in connected secondary datacenters. + + ~> **Warning:** When enabling ACL token replication on the secondary datacenter, + global tokens already present in the secondary datacenter will be lost. For + production environments, consider configuring ACL replication in your initial + datacenter bootstrapping process. + + - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either + `true` or `false`. When `true` tokens set using the API will be persisted to + disk and reloaded when an agent restarts. + + - `tokens` ((#acl_tokens)) - This object holds all of the configured + ACL tokens for the agents usage. + + - `initial_management` ((#acl_tokens_initial_management)) - This is available in + Consul 1.11 and later. In prior versions, use [`acl.tokens.master`](#acl_tokens_master). + + Only used for servers in the [`primary_datacenter`](#primary_datacenter). + This token will be created with management-level permissions if it does not exist. + It allows operators to bootstrap the ACL system with a token Secret ID that is + well-known. + + The `initial_management` token is only installed when a server acquires cluster + leadership. If you would like to install or change it, set the new value for + `initial_management` in the configuration for all servers. Once this is done, + restart the current leader to force a leader election. If the `initial_management` + token is not supplied, then the servers do not create an initial management token. + When you provide a value, it should be a UUID. To maintain backwards compatibility + and an upgrade path this restriction is not currently enforced but will be in a + future major Consul release. + + - `master` ((#acl_tokens_master)) **Renamed in Consul 1.11 to + [`acl.tokens.initial_management`](#acl_tokens_initial_management).** + + - `default` ((#acl_tokens_default)) - 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 token, + is used. + + - `agent` ((#acl_tokens_agent)) - Used for clients and servers to perform + internal operations. If this isn't specified, then the + [`default`](#acl_tokens_default) will be used. + + This token must at least have write access to the node name it will + register as in order to set any of the node-level information in the + catalog such as metadata, or the node's tagged addresses. + + - `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11 + and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master). + + Used to access [agent endpoints](/api/agent) that require agent read or write privileges, + or node read privileges, even if Consul servers aren't present to validate any tokens. + This should only be used by operators during outages, regular ACL tokens should normally + be used by applications. + + - `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to + [`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).** + + - `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)) - An + array of ACL tokens used by Consul managed service providers for cluster operations. + + ```json + "managed_service_provider": [ + { + "accessor_id": "ed22003b-0832-4e48-ac65-31de64e5c2ff", + "secret_id": "cb6be010-bba8-4f30-a9ed-d347128dde17" + } + ] + ``` + +- `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 + not impacted. + +- `acl_agent_master_token` ((#acl_agent_master_token_legacy)) - **Deprecated + in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master) + field instead.** Used to access [agent endpoints](/api/agent) that + require agent read or write privileges, or node read privileges, even if Consul + servers aren't present to validate any tokens. This should only be used by operators + during outages, regular ACL tokens should normally be used by applications. This + was added in Consul 0.7.2 and is only used when [`acl_enforce_version_8`](#acl_enforce_version_8) is set to true. + +- `acl_agent_token` ((#acl_agent_token_legacy)) - **Deprecated in Consul + 1.4.0. See the [`acl.tokens.agent`](#acl_tokens_agent) field instead.** Used for + clients and servers to perform internal operations. If this isn't specified, then + the [`acl_token`](#acl_token) will be used. This was added in Consul 0.7.2. + + This token must at least have write access to the node name it will register as in order to set any + of the node-level information in the catalog such as metadata, or the node's tagged addresses. + +- `acl_enforce_version_8` - **Deprecated in + Consul 1.4.0 and removed in 1.8.0.** Used for clients and servers to determine if enforcement should + occur for new ACL policies being previewed before Consul 0.8. Added in Consul 0.7.2, + this defaults to false in versions of Consul prior to 0.8, and defaults to true + in Consul 0.8 and later. This helps ease the transition to the new ACL features + by allowing policies to be in place before enforcement begins. + +- `acl_master_token` ((#acl_master_token_legacy)) - **Deprecated in Consul + 1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.** + +- `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated + 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. + +- `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. + +## Advertise Address Parameters + +- `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. + +## Bootstrap Parameters + +- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](#_bootstrap). + +- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](#_bootstrap_expect). + +## Connect Parameters + - `connect` This object allows setting options for the Connect feature. The following sub-keys are available: @@ -799,28 +1104,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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 and Domain Parameters - `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. @@ -946,38 +1230,46 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `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. +## Encryption Parameters - ~> **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. +- `auto_encrypt` This object allows setting options for the `auto_encrypt` feature. -- `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. + The following sub-keys are available: -- `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. + - `allow_tls` (Defaults to `false`) This option enables + `auto_encrypt` on the servers and allows them to automatically distribute certificates + from the Connect CA to the clients. If enabled, the server can accept incoming + connections from both the built-in CA and the Connect CA, as well as their certificates. + Note, the server will only present the built-in CA and certificate, which the + client can verify using the CA it received from `auto_encrypt` endpoint. If disabled, + a client configured with `auto_encrypt.tls` will be unable to start. -- `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`. + - `tls` (Defaults to `false`) Allows the client to request the + Connect CA and certificates from the servers, for encrypting RPC communication. + The client will make the request to any servers listed in the `-join` or `-retry-join` + option. This requires that every server to have `auto_encrypt.allow_tls` enabled. + When both `auto_encrypt` options are used, it allows clients to receive certificates + that are generated on the servers. If the `-server-port` is not the default one, + it has to be provided to the client as well. Usually this is discovered through + LAN gossip, but `auto_encrypt` provision happens before the information can be + distributed through gossip. The most secure `auto_encrypt` setup is when the + client is provided with the built-in CA, `verify_server_hostname` is turned on, + and when an ACL token with `node.write` permissions is setup. It is also possible + to use `auto_encrypt` with a CA and ACL, but without `verify_server_hostname`, + or only with a ACL enabled, or only with CA and `verify_server_hostname`, or + only with a CA, or finally without a CA and without ACL enabled. In any case, + the communication to the `auto_encrypt` endpoint is always TLS encrypted. -- `enable_script_checks` Equivalent to the [`-enable-script-checks` command-line flag](#_enable_script_checks). + ~> **Warning:** Enabling `auto_encrypt.tls` conflicts with the [`auto_config`](#auto_config) feature. + Only one option may be specified. - 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. + - `dns_san` (Defaults to `[]`) When this option is being + used, the certificates requested by `auto_encrypt` from the server have these + `dns_san` set as DNS SAN. - ~> **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). + - `ip_san` (Defaults to `[]`) When this option is being used, + the certificates requested by `auto_encrypt` from the server have these `ip_san` + set as IP SAN. - `encrypt` Equivalent to the [`-encrypt` command-line flag](#_encrypt). @@ -993,12 +1285,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster) for more information. Defaults to true. -- `disable_keyring_file` - Equivalent to the - [`-disable-keyring-file` command-line flag](#_disable_keyring_file). - -- `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). - When network coordinates are disabled the `near` query param will not work to sort the nodes, - and the [`consul rtt`](/commands/rtt) command will not be able to provide round trip time between nodes. +## Gossip Parameters - `gossip_lan` - **(Advanced)** This object contains a number of sub-keys which can be set to tune the LAN gossip communications. These @@ -1084,59 +1371,27 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr part of the cluster before declaring it dead, giving that suspect node more time to refute if it is indeed still alive. The default is 6. -- `http_config` This object allows setting options for the HTTP API and UI. +## Join Parameters - The following sub-keys are available: +- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](#_rejoin). - - `block_endpoints` - This object is a list of HTTP API endpoint prefixes to block on the agent, and - defaults to an empty list, meaning all endpoints are enabled. Any endpoint that - has a common prefix with one of the entries on this list will be blocked and - will return a 403 response code when accessed. For example, to block all of the - V1 ACL endpoints, set this to `["/v1/acl"]`, which will block `/v1/acl/create`, - `/v1/acl/update`, and the other ACL endpoints that begin with `/v1/acl`. This - only works with API endpoints, not `/ui` or `/debug`, those must be disabled - with their respective configuration options. Any CLI commands that use disabled - endpoints will no longer function as well. For more general access control, Consul's - [ACL system](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) - 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. +- `retry_join` - Equivalent to the [`-retry-join`](#retry-join) command-line flag. - - `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: +- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](#_retry_interval). - ```json - { - "http_config": { - "response_headers": { - "Access-Control-Allow-Origin": "*" - } - } - } - ``` +- `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. - - `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" ]` +- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](#_retry_interval_wan). - - `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. +- `start_join` An array of strings specifying addresses + of nodes to [`-join`](#_join) upon startup. Note that using + `retry_join` could be more appropriate to help mitigate + node startup race conditions when automating a Consul cluster deployment. - - `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. +- `start_join_wan` An array of strings specifying addresses + of WAN nodes to [`-join-wan`](#_join_wan) upon startup. -- `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` 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 Parameters - `log_file` Equivalent to the [`-log-file` command-line flag](#_log_file). @@ -1150,9 +1405,13 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `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). +- `enable_syslog` Equivalent to the [`-syslog` command-line flag](#_syslog). -- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](#_max_query_time). +- `syslog_facility` When [`enable_syslog`](#enable_syslog) + is provided, this controls to which facility messages are sent. By default, `LOCAL0` + will be used. + +## Node Parameters - `node_id` Equivalent to the [`-node-id` command-line flag](#_node_id). @@ -1168,97 +1427,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr } ``` -- `partition` - 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. +- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](#_disable_host_node_id). - ~> **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 Parameters - `raft_boltdb` ((#raft_boltdb)) This is a nested object that allows configuring options for Raft's BoltDB based log store. @@ -1318,107 +1489,18 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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). +## Serf Parameters -- `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. +- `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). -- `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. +- `serf_lan_allowed_cidrs` ((#serf_lan_allowed_cidrs)) Equivalent to the [`-serf-lan-allowed-cidrs` command-line flag](#_serf_lan_allowed_cidrs). -- `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. +- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](#_serf_wan_bind). -- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](#_rejoin). +- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](#_serf_wan_allowed_cidrs). -- `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 - [`use_streaming_backend`](#use_streaming_backend). - -- `segment` - Equivalent to the [`-segment` command-line flag](#_segment). - - ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. - -- `segments` - (Server agents only) This is a list of nested objects - that specifies user-defined network segments, not including the `` segment, which is - created automatically. Review the [Network Segments documentation](/docs/enterprise/network-segments) - for more details. - - - `name` ((#segment_name)) - The name of the segment. Must be a string - between 1 and 64 characters in length. - - `bind` ((#segment_bind)) - The bind address to use for the segment's - gossip layer. Defaults to the [`-bind`](#_bind) value if not provided. - - `port` ((#segment_port)) - The port to use for the segment's gossip - layer (required). - - `advertise` ((#segment_advertise)) - The advertise address to use for - the segment's gossip layer. Defaults to the [`-advertise`](#_advertise) value - if not provided. - - `rpc_listener` ((#segment_rpc_listener)) - 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. - -- `server` Equivalent to the [`-server` command-line flag](#_server). - -- `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** - -- `read_replica` - Equivalent to the [`-read-replica` command-line flag](#_read_replica). - -- `session_ttl_min` 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. - -- `skip_leave_on_interrupt` 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). - -- `start_join` An array of strings specifying addresses - of nodes to [`-join`](#_join) upon startup. Note that using - `retry_join` could be more appropriate to help mitigate - node startup race conditions when automating a Consul cluster deployment. - -- `start_join_wan` An array of strings specifying addresses - of WAN nodes to [`-join-wan`](#_join_wan) upon startup. +## Telemetry Paramters - `telemetry` This is a nested object that configures where Consul sends its runtime telemetry, and contains the following keys: @@ -1552,31 +1634,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr can be used to capture runtime information. This streams via TCP and can only be used with statsite. -- `syslog_facility` When [`enable_syslog`](#enable_syslog) - is provided, this controls to which facility messages are sent. By default, `LOCAL0` - will be used. - -- `translate_wan_addrs` If set to true, Consul - will prefer a node's configured [WAN address](#_advertise-wan) - when servicing DNS and HTTP requests for a node in a remote datacenter. This allows - the node to be reached within its own datacenter using its local address, and reached - from other datacenters using its WAN address, which is useful in hybrid setups - with mixed networks. This is disabled by default. - - Starting in Consul 0.7 and later, node addresses in responses to HTTP requests will also prefer a - node's configured [WAN address](#_advertise-wan) when querying for a node in a remote - datacenter. An [`X-Consul-Translate-Addresses`](/api#translated-addresses) header - will be present on all responses when translation is enabled to help clients know that the addresses - may be translated. The `TaggedAddresses` field in responses also have a `lan` address for clients that - need knowledge of that address, regardless of translation. - - The following endpoints translate addresses: - - - [`/v1/catalog/nodes`](/api/catalog#list-nodes) - - [`/v1/catalog/node/`](/api/catalog#retrieve-map-of-services-for-a-node) - - [`/v1/catalog/service/`](/api/catalog#list-nodes-for-service) - - [`/v1/health/service/`](/api/health#list-nodes-for-service) - - [`/v1/query//execute`](/api/query#execute-prepared-query) +## UI Parameters - `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** Equivalent to the [`-ui`](#_ui) command-line flag. @@ -1709,34 +1767,6 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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 From b0c6d5b02a941c590520219a89720dfe88ef58b8 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 12:06:21 -0800 Subject: [PATCH 05/10] docs: fix agent config links --- .../docs/agent/config/agent-config-cli.mdx | 14 +-- .../docs/agent/config/agent-config-files.mdx | 94 +++++++++---------- website/content/docs/agent/config/index.mdx | 4 +- 3 files changed, 56 insertions(+), 56 deletions(-) diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/agent-config-cli.mdx index 8daeebcc18..82d6608034 100644 --- a/website/content/docs/agent/config/agent-config-cli.mdx +++ b/website/content/docs/agent/config/agent-config-cli.mdx @@ -26,7 +26,7 @@ information. limit of 4k for maximum size of checks, this is a positive value. By limiting this size, it allows to put less pressure on Consul servers when many checks are having a very large output in their checks. In order to completely disable check output - capture, it is possible to use [`discard_check_output`](#discard_check_output). + capture, it is possible to use [`discard_check_output`](/docs/agent/config/agent-config-files#discard_check_output). - `-client` ((#\_client)) - The address to which Consul will bind client interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", @@ -122,7 +122,7 @@ information. - `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version of the Raft consensus protocol used for server communications. This must be set - to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details. + to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](/docs/agent/config/agent-config-files#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details. - `-segment` ((#\_segment)) - This flag is used to set the name of the network segment the agent belongs to. An agent can only join and @@ -146,13 +146,13 @@ information. - `-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 + This can also be set on client agents when used in combination with the [`translate_wan_addrs`](/docs/agent/config/agent-config-files#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.1.0 and later this can be dynamically defined with a [go-sockaddr] + accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. ## Address Bind Options @@ -160,10 +160,10 @@ information. - `-bind` ((#\_bind)) - 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#_advertise) + all addresses on the local machine and will [advertise](#_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#_advertise) the public + `"[::]"`, Consul will [advertise](#_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.1.0 and later this can be dynamically defined with a [go-sockaddr] @@ -290,7 +290,7 @@ information. If Consul is running on the non-default Serf LAN port, the port must be specified in the join address, or configured as the agent's default Serf port - using the [`ports.serf_lan`](#serf_lan_port) configuration option or + using the [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port) configuration option or [`-serf-lan-port`](#_serf_lan_port) command line flag. If using network segments (Enterprise), see [additional documentation on diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx index f22a1eb69a..40dae78782 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/agent-config-files.mdx @@ -80,7 +80,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `https` - The HTTPS API. Defaults to `client_addr` - `grpc` - The gRPC API. Defaults to `client_addr` -- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](#_alt_domain) +- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](/docs/agent/config/agent-config-cli#_alt_domain) - `audit` - 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). @@ -207,7 +207,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `server_addresses` (Defaults to `[]`) This specifies the addresses of servers in the local datacenter to use for the initial RPC. These addresses support - [Cloud Auto-Joining](#cloud-auto-joining) and can optionally include a port to + [Cloud Auto-Joining](/docs/agent/config/agent-config-cli#cloud-auto-joining) and can optionally include a port to use when making the outbound connection. If not port is provided the `server_port` will be used. @@ -310,7 +310,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `partition` - The admin partition name the client is requesting. -- `bind_addr` Equivalent to the [`-bind` command-line flag](#_bind). +- `bind_addr` Equivalent to the [`-bind` command-line flag](/docs/agent/config/agent-config-cli#_bind). This parameter can be set to a go-sockaddr template that resolves to a single address. Special characters such as backslashes `\` or double quotes `"` @@ -358,7 +358,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr changes state, the new state and associated output is synchronized immediately. To disable this behavior, set the value to "0s". -- `client_addr` Equivalent to the [`-client` command-line flag](#_client). +- `client_addr` Equivalent to the [`-client` command-line flag](/docs/agent/config/agent-config-cli#_client). - `config_entries` This object allows setting options for centralized config entries. @@ -372,9 +372,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr See the [configuration entry docs](/docs/agent/config-entries) for more details about the contents of each entry. -- `datacenter` Equivalent to the [`-datacenter` command-line flag](#_datacenter). +- `datacenter` Equivalent to the [`-datacenter` command-line flag](/docs/agent/config/agent-config-cli#_datacenter). -- `data_dir` Equivalent to the [`-data-dir` command-line flag](#_data_dir). +- `data_dir` Equivalent to the [`-data-dir` command-line flag](/docs/agent/config/agent-config-cli#_data_dir). - `disable_anonymous_signature` Disables providing an anonymous signature for de-duplication with the update check. See [`disable_update_check`](#disable_update_check). @@ -404,17 +404,17 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `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). +- `enable_script_checks` Equivalent to the [`-enable-script-checks` command-line flag](/docs/agent/config/agent-config-cli#_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_local_script_checks` Equivalent to the [`-enable-local-script-checks` command-line flag](/docs/agent/config/agent-config-cli#_enable_local_script_checks). - `disable_keyring_file` - Equivalent to the - [`-disable-keyring-file` command-line flag](#_disable_keyring_file). + [`-disable-keyring-file` command-line flag](/docs/agent/config/agent-config-cli#_disable_keyring_file). - `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). When network coordinates are disabled the `near` query param will not work to sort the nodes, @@ -474,9 +474,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `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. -- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](#_default_query_time). +- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](/docs/agent/config/agent-config-cli#_default_query_time). -- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](#_max_query_time). +- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](/docs/agent/config/agent-config-cli#_max_query_time). - `partition` - This flag is used to set the name of the admin partition the agent belongs to. An agent can only join @@ -557,7 +557,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr enforcement of ACLs. - `primary_gateways` Equivalent to the [`-primary-gateway` - command-line flag](#_primary_gateway). Takes a list of addresses to use as the + command-line flag](/docs/agent/config/agent-config-cli#_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 @@ -568,7 +568,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 30s. This was added in Consul 1.8.0. - `protocol` ((#protocol)) Equivalent to the [`-protocol` command-line - flag](#_protocol). + flag](/docs/agent/config/agent-config-cli#_protocol). - `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 @@ -610,7 +610,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr servers in all federated datacenters must have this enabled before any client can use [`use_streaming_backend`](#use_streaming_backend). -- `segment` - Equivalent to the [`-segment` command-line flag](#_segment). +- `segment` - Equivalent to the [`-segment` command-line flag](/docs/agent/config/agent-config-cli#_segment). ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. @@ -633,11 +633,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr port. Only valid if the segment's bind address differs from the [`-bind`](#_bind) address. Defaults to false. -- `server` Equivalent to the [`-server` command-line flag](#_server). +- `server` Equivalent to the [`-server` command-line flag](/docs/agent/config/agent-config-cli#_server). - `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** -- `read_replica` - Equivalent to the [`-read-replica` command-line flag](#_read_replica). +- `read_replica` - Equivalent to the [`-read-replica` command-line flag](/docs/agent/config/agent-config-cli#_read_replica). - `session_ttl_min` 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 @@ -935,13 +935,13 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Advertise Address Parameters -- `advertise_addr` Equivalent to the [`-advertise` command-line flag](#_advertise). +- `advertise_addr` Equivalent to the [`-advertise` command-line flag](/docs/agent/config/agent-config-cli#_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` Equivalent to the [`-advertise-wan` command-line flag](/docs/agent/config/agent-config-cli#_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. @@ -954,9 +954,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Bootstrap Parameters -- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](#_bootstrap). +- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](/docs/agent/config/agent-config-cli#_bootstrap). -- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](#_bootstrap_expect). +- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](/docs/agent/config/agent-config-cli#_bootstrap_expect). ## Connect Parameters @@ -1228,7 +1228,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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). +- `domain` Equivalent to the [`-domain` command-line flag](/docs/agent/config/agent-config-cli#_domain). ## Encryption Parameters @@ -1271,7 +1271,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr the certificates requested by `auto_encrypt` from the server have these `ip_san` set as IP SAN. -- `encrypt` Equivalent to the [`-encrypt` command-line flag](#_encrypt). +- `encrypt` Equivalent to the [`-encrypt` command-line flag](/docs/agent/config/agent-config-cli#_encrypt). - `encrypt_verify_incoming` - This is an optional parameter that can be used to disable enforcing encryption for incoming gossip @@ -1373,15 +1373,15 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Join Parameters -- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](#_rejoin). +- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](/docs/agent/config/agent-config-cli#_rejoin). -- `retry_join` - Equivalent to the [`-retry-join`](#retry-join) command-line flag. +- `retry_join` - Equivalent to the [`-retry-join`](/docs/agent/config/agent-config-cli#retry-join) command-line flag. -- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](#_retry_interval). +- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](/docs/agent/config/agent-config-cli#_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_join_wan` Equivalent to the [`-retry-join-wan` command-line flag](/docs/agent/config/agent-config-cli#_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). +- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](/docs/agent/config/agent-config-cli#_retry_interval_wan). - `start_join` An array of strings specifying addresses of nodes to [`-join`](#_join) upon startup. Note that using @@ -1393,19 +1393,19 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Log Parameters -- `log_file` Equivalent to the [`-log-file` command-line flag](#_log_file). +- `log_file` Equivalent to the [`-log-file` command-line flag](/docs/agent/config/agent-config-cli#_log_file). -- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](#_log_rotate_duration). +- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](/docs/agent/config/agent-config-cli#_log_rotate_duration). -- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](#_log_rotate_bytes). +- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](/docs/agent/config/agent-config-cli#_log_rotate_bytes). -- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](#_log_rotate_max_files). +- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](/docs/agent/config/agent-config-cli#_log_rotate_max_files). -- `log_level` Equivalent to the [`-log-level` command-line flag](#_log_level). +- `log_level` Equivalent to the [`-log-level` command-line flag](/docs/agent/config/agent-config-cli#_log_level). -- `log_json` Equivalent to the [`-log-json` command-line flag](#_log_json). +- `log_json` Equivalent to the [`-log-json` command-line flag](/docs/agent/config/agent-config-cli#_log_json). -- `enable_syslog` Equivalent to the [`-syslog` command-line flag](#_syslog). +- `enable_syslog` Equivalent to the [`-syslog` command-line flag](/docs/agent/config/agent-config-cli#_syslog). - `syslog_facility` When [`enable_syslog`](#enable_syslog) is provided, this controls to which facility messages are sent. By default, `LOCAL0` @@ -1413,11 +1413,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Node Parameters -- `node_id` Equivalent to the [`-node-id` command-line flag](#_node_id). +- `node_id` Equivalent to the [`-node-id` command-line flag](/docs/agent/config/agent-config-cli#_node_id). -- `node_name` Equivalent to the [`-node` command-line flag](#_node). +- `node_name` Equivalent to the [`-node` command-line flag](/docs/agent/config/agent-config-cli#_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. +- `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](/docs/agent/config/agent-config-cli#_node_meta) for more information. ```json { @@ -1427,7 +1427,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr } ``` -- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](#_disable_host_node_id). +- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/docs/agent/config/agent-config-cli#_disable_host_node_id). ## Raft Parameters @@ -1442,7 +1442,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `raft_protocol` ((#raft_protocol)) Equivalent to the [`-raft-protocol` - command-line flag](#_raft_protocol). + command-line flag](/docs/agent/config/agent-config-cli#_raft_protocol). - `raft_snapshot_threshold` ((#\_raft_snapshot_threshold)) This controls the minimum number of raft commit entries between snapshots that are saved to @@ -1491,14 +1491,14 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Serf Parameters -- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](#_serf_lan_bind). +- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](/docs/agent/config/agent-config-cli#_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_lan_allowed_cidrs` ((#serf_lan_allowed_cidrs)) Equivalent to the [`-serf-lan-allowed-cidrs` command-line flag](/docs/agent/config/agent-config-cli#_serf_lan_allowed_cidrs). -- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](#_serf_wan_bind). +- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](/docs/agent/config/agent-config-cli#_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). +- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](/docs/agent/config/agent-config-cli#_serf_wan_allowed_cidrs). ## Telemetry Paramters @@ -1637,7 +1637,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## UI Parameters - `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** - Equivalent to the [`-ui`](#_ui) command-line flag. + Equivalent to the [`-ui`](/docs/agent/config/agent-config-cli#_ui) command-line flag. - `ui_config` - This object allows a number of sub-keys to be set which controls the display or features available in the UI. Configuring the UI with this @@ -1648,12 +1648,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `enabled` ((#ui_config_enabled)) - This enables the service of the web UI from this agent. Boolean value, defaults to false. In `-dev` mode this defaults to true. Replaces `ui` from before 1.9.0. Equivalent to the - [`-ui`](#_ui) command-line flag. + [`-ui`](/docs/agent/config/agent-config-cli#_ui) command-line flag. - `dir` ((#ui_config_dir)) - This specifies that the web UI should be served from an external dir rather than the build in one. This allows for customization or development. Replaces `ui_dir` from before 1.9.0. - Equivalent to the [`-ui-dir`](#_ui_dir) command-line flag. + Equivalent to the [`-ui-dir`](/docs/agent/config/agent-config-cli#_ui_dir) command-line flag. - `content_path` ((#ui_config_content_path)) - This specifies the HTTP path that the web UI should be served from. Defaults to `/ui/`. Equivalent to the @@ -1762,7 +1762,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `{{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 + Equivalent to the [`-ui-dir`](/docs/agent/config/agent-config-cli#_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. diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx index adc5577cdf..d846ebb739 100644 --- a/website/content/docs/agent/config/index.mdx +++ b/website/content/docs/agent/config/index.mdx @@ -16,8 +16,8 @@ descriptions. Configuration precedence is evaluated in the following order: -1. Command line arguments -2. Configuration files +1. [Command line arguments](/docs/agent/config/agent-config-cli) +2. [Configuration files](/docs/agent/config/agent-config-files) When loading configuration, Consul loads the configuration from files and directories in lexical order. For example, configuration file From 00c2444cfce645c516074688ecfedf6fa99ab5aa Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 13:13:13 -0800 Subject: [PATCH 06/10] docs: fix external links to agent config pages --- .../network-areas/README.md | 2 +- docs/config/README.md | 6 +- docs/config/checklist-adding-config-fields.md | 4 +- docs/rpc/README.md | 2 +- website/content/api-docs/acl/index.mdx | 10 +- website/content/api-docs/agent/index.mdx | 20 ++-- website/content/api-docs/config.mdx | 2 +- .../content/api-docs/connect/intentions.mdx | 2 +- website/content/api-docs/health.mdx | 2 +- website/content/api-docs/index.mdx | 4 +- .../content/api-docs/operator/autopilot.mdx | 2 +- .../content/commands/acl/set-agent-token.mdx | 2 +- website/content/commands/config/index.mdx | 2 +- website/content/commands/connect/envoy.mdx | 2 +- website/content/commands/debug.mdx | 2 +- website/content/commands/index.mdx | 2 +- .../content/commands/operator/autopilot.mdx | 4 +- website/content/commands/reload.mdx | 2 +- website/content/commands/validate.mdx | 2 +- website/content/docs/agent/config-entries.mdx | 4 +- .../docs/agent/config/agent-config-files.mdx | 2 +- website/content/docs/agent/config/index.mdx | 18 +-- website/content/docs/agent/index.mdx | 30 ++--- website/content/docs/agent/telemetry.mdx | 20 ++-- website/content/docs/connect/ca/aws.mdx | 6 +- website/content/docs/connect/ca/consul.mdx | 2 +- website/content/docs/connect/ca/index.mdx | 2 +- website/content/docs/connect/ca/vault.mdx | 4 +- .../config-entries/exported-services.mdx | 2 +- .../docs/connect/config-entries/index.mdx | 2 +- .../connect/config-entries/proxy-defaults.mdx | 4 +- .../config-entries/service-defaults.mdx | 4 +- .../config-entries/service-intentions.mdx | 4 +- .../content/docs/connect/configuration.mdx | 14 +-- .../docs/connect/connect-internals.mdx | 4 +- .../docs/connect/gateways/ingress-gateway.mdx | 4 +- ...service-to-service-traffic-datacenters.mdx | 10 +- .../service-to-service-traffic-partitions.mdx | 4 +- .../wan-federation-via-mesh-gateways.mdx | 2 +- .../connect/gateways/terminating-gateway.mdx | 4 +- .../docs/connect/intentions-legacy.mdx | 2 +- website/content/docs/connect/intentions.mdx | 2 +- .../docs/connect/observability/index.mdx | 6 +- .../observability/ui-visualization.mdx | 14 +-- .../content/docs/connect/proxies/built-in.mdx | 2 +- .../content/docs/connect/proxies/envoy.mdx | 2 +- .../connect/proxies/managed-deprecated.mdx | 6 +- .../registration/service-registration.mdx | 4 +- .../connect/registration/sidecar-service.mdx | 2 +- website/content/docs/discovery/checks.mdx | 10 +- website/content/docs/discovery/dns.mdx | 26 ++--- .../content/docs/dynamic-app-config/kv.mdx | 4 +- .../docs/dynamic-app-config/watches.mdx | 2 +- .../content/docs/ecs/get-started/install.mdx | 2 +- .../content/docs/enterprise/audit-logging.mdx | 4 +- .../docs/enterprise/license/overview.mdx | 8 +- .../docs/enterprise/network-segments.mdx | 32 ++--- .../content/docs/enterprise/read-scale.mdx | 4 +- website/content/docs/index.mdx | 2 +- .../content/docs/install/bootstrapping.mdx | 14 +-- .../content/docs/install/cloud-auto-join.mdx | 4 +- .../content/docs/install/manual-bootstrap.mdx | 2 +- website/content/docs/install/performance.mdx | 20 ++-- website/content/docs/install/ports.mdx | 2 +- .../docs/k8s/connect/connect-ca-provider.mdx | 4 +- website/content/docs/k8s/helm.mdx | 16 +-- website/content/docs/k8s/index.mdx | 2 +- .../servers-outside-kubernetes.mdx | 2 +- .../installation/multi-cluster/kubernetes.mdx | 4 +- .../multi-cluster/vms-and-kubernetes.mdx | 2 +- website/content/docs/nia/configuration.mdx | 6 +- .../docs/nia/installation/requirements.mdx | 2 +- website/content/docs/release-notes/1-9-0.mdx | 2 +- .../content/docs/security/acl/acl-legacy.mdx | 98 ++++++++-------- .../content/docs/security/acl/acl-rules.mdx | 22 ++-- .../content/docs/security/acl/acl-system.mdx | 36 +++--- .../docs/security/acl/auth-methods/index.mdx | 2 +- website/content/docs/security/encryption.mdx | 22 ++-- .../docs/security/security-models/core.mdx | 56 ++++----- .../docs/troubleshoot/common-errors.mdx | 6 +- website/content/docs/troubleshoot/faq.mdx | 8 +- .../instructions/general-process.mdx | 4 +- .../instructions/upgrade-to-1-6-x.mdx | 8 +- .../docs/upgrading/upgrade-specific.mdx | 110 +++++++++--------- .../partials/http_api_options_client.mdx | 2 +- 85 files changed, 405 insertions(+), 405 deletions(-) diff --git a/docs/cluster-federation/network-areas/README.md b/docs/cluster-federation/network-areas/README.md index 0b62162e47..efe10aa069 100644 --- a/docs/cluster-federation/network-areas/README.md +++ b/docs/cluster-federation/network-areas/README.md @@ -35,7 +35,7 @@ Every Consul Enterprise server maintains a reconciliation routine where every 30 Joining a network area pool involves: 1. Setting memberlist and Serf configuration. - * Prior to Consul `v1.8.11` and `v1.9.5`, network areas were configured with memberlist's [DefaultWANConfig](https://github.com/hashicorp/memberlist/blob/838073fef1a4e1f6cb702a57a8075304098b1c31/config.go#L315). This was then updated to instead use the server's [gossip_wan](https://www.consul.io/docs/agent/options#gossip_wan) configuration, which falls back to the DefaultWANConfig if it was not specified. + * Prior to Consul `v1.8.11` and `v1.9.5`, network areas were configured with memberlist's [DefaultWANConfig](https://github.com/hashicorp/memberlist/blob/838073fef1a4e1f6cb702a57a8075304098b1c31/config.go#L315). This was then updated to instead use the server's [gossip_wan](https://www.consul.io/docs/agent/config/agent-config-files#gossip_wan) configuration, which falls back to the DefaultWANConfig if it was not specified. * As of Consul `v1.8.11`/`v1.9.5` it is not possible to tune gossip communication on a per-area basis. 2. Update the server's gossip network, which keeps track of network areas that the server is a part of. This gossip network is also used to dispatch incoming **gossip** connections to handlers for the appropriate area. diff --git a/docs/config/README.md b/docs/config/README.md index 49f8014cf7..fe38011b9b 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -10,10 +10,10 @@ specified using command line flags, and some can be loaded with [Auto-Config]. See also the [checklist for adding a new field] to the configuration. [hcl]: https://github.com/hashicorp/hcl/tree/hcl1 -[Agent Configuration]: https://www.consul.io/docs/agent/options +[Agent Configuration]: https://www.consul.io/docs/agent/config [checklist for adding a new field]: ./checklist-adding-config-fields.md [Auto-Config]: #auto-config -[Config Entries]: https://www.consul.io/docs/agent/options#config_entries +[Config Entries]: https://www.consul.io/docs/agent/config/agent-config-files#config_entries [Services]: https://www.consul.io/docs/discovery/services [Checks]: https://www.consul.io/docs/discovery/checks @@ -53,6 +53,6 @@ implemented in a couple packages. * the server RPC endpoint is in [agent/consul/auto_config_endpoint.go] * the client that receives and applies the config is implemented in [agent/auto-config] -[auto_config]: https://www.consul.io/docs/agent/options#auto_config +[auto_config]: https://www.consul.io/docs/agent/config/agent-config-files#auto_config [agent/consul/auto_config_endpoint.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/auto_config_endpoint.go [agent/auto-config]: https://github.com/hashicorp/consul/tree/main/agent/auto-config diff --git a/docs/config/checklist-adding-config-fields.md b/docs/config/checklist-adding-config-fields.md index fff3fba368..66807c0721 100644 --- a/docs/config/checklist-adding-config-fields.md +++ b/docs/config/checklist-adding-config-fields.md @@ -55,7 +55,7 @@ There are four specific cases covered with increasing complexity: state for client agent's RPC client. - [ ] Add a test to `agent/agent_test.go` similar to others with prefix `TestAgent_reloadConfig*`. - - [ ] Add documentation to `website/content/docs/agent/options.mdx`. + - [ ] Add documentation to `website/content/docs/agent/config/agent-config-files.mdx`. Done! You can now use your new field in a client agent by accessing `s.agent.Config.`. @@ -75,7 +75,7 @@ If the config field also needs a CLI flag, then follow these steps. `TestLoad_IntegrationWithFlags` in `agent/config/runtime_test.go` to ensure setting the flag works. - [ ] Add flag (as well as config file) documentation to - `website/source/docs/agent/options.html.md`. + `website/source/docs/agent/config/agent-config-files.mdx` and `website/source/docs/agent/config/agent-config-cli.mdx`. ## Adding a Simple Config Field for Servers Consul servers have a separate Config struct for reasons. Note that Consul diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 8a5236d4a1..7d8a75cad2 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -22,7 +22,7 @@ The "RPC Server" accepts requests to the [server port] and routes the requests b configuration of the Server and the the first byte in the request. The diagram below shows all the possible routing flows. -[server port]: https://www.consul.io/docs/agent/options#server_rpc_port +[server port]: https://www.consul.io/docs/agent/config/agent-config-files#server_rpc_port ![RPC Routing](./routing.svg) diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx index cd7a20fc6a..ee663be92e 100644 --- a/website/content/api-docs/acl/index.mdx +++ b/website/content/api-docs/acl/index.mdx @@ -16,7 +16,7 @@ the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-s ## Bootstrap ACLs This endpoint does a special one-time bootstrap of the ACL system, making the first -management token if the [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) +management token if the [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management) configuration entry is not specified in the Consul server configuration and if the cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all Consul servers to be upgraded in order to operate. @@ -141,7 +141,7 @@ $ curl \ - `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being replicated from and will match the - [`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration. + [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) configuration. - `ReplicationType` - The type of replication that is currently in use. @@ -289,7 +289,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/options#acl_enable_token_replication) must be +replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. @@ -415,7 +415,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/options#acl_enable_token_replication) must be +replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. @@ -495,7 +495,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/options#acl_enable_token_replication) must be +replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. diff --git a/website/content/api-docs/agent/index.mdx b/website/content/api-docs/agent/index.mdx index 5bcd4f2dae..6ed7603896 100644 --- a/website/content/api-docs/agent/index.mdx +++ b/website/content/api-docs/agent/index.mdx @@ -356,7 +356,7 @@ This endpoint instructs the agent to reload its configuration. Any errors encountered during this process are returned. Not all configuration options are reloadable. See the -[Reloadable Configuration](/docs/agent/options#reloadable-configuration) +[Reloadable Configuration](/docs/agent/config#reloadable-configuration) section on the agent options page for details on which options are supported. | Method | Path | Produces | @@ -432,7 +432,7 @@ page. In order to enable [Prometheus](https://prometheus.io/) support, you need to use the configuration directive -[`prometheus_retention_time`](/docs/agent/options#telemetry-prometheus_retention_time). +[`prometheus_retention_time`](/docs/agent/config/agent-config-files#telemetry-prometheus_retention_time). Since Consul 1.7.2 this endpoint will also automatically switch output format if the request contains an `Accept` header with a compatible MIME type such as @@ -731,7 +731,7 @@ $ curl \ This endpoint updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens will be persisted -only if the [`acl.enable_token_persistence`](/docs/agent/options#acl_enable_token_persistence) +only if the [`acl.enable_token_persistence`](/docs/agent/config/agent-config-files#acl_enable_token_persistence) configuration is `true`. When not being persisted, they will need to be reset if the agent is restarted. @@ -743,9 +743,9 @@ is restarted. | `PUT` | `/agent/token/replication` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`default`](/docs/agent/options#acl_tokens_default), [`agent`](/docs/agent/options#acl_tokens_agent), -[`agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery), and -[`replication`](/docs/agent/options#acl_tokens_replication). +[`default`](/docs/agent/config/agent-config-files#acl_tokens_default), [`agent`](/docs/agent/config/agent-config-files#acl_tokens_agent), +[`agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery), and +[`replication`](/docs/agent/config/agent-config-files#acl_tokens_replication). -> **Deprecation Note:** The following paths were deprecated in version 1.11 @@ -754,7 +754,7 @@ The paths above correspond to the token names as found in the agent configuratio | `PUT` | `/agent/token/agent_master` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`agent_master`](/docs/agent/options#acl_tokens_agent_master). +[`agent_master`](/docs/agent/config/agent-config-files#acl_tokens_agent_master). -> **Deprecation Note:** The following paths were deprecated in version 1.4.3 @@ -766,9 +766,9 @@ The paths above correspond to the token names as found in the agent configuratio | `PUT` | `/agent/token/acl_replication_token` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`acl_token`](/docs/agent/options#acl_token_legacy), [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy), -[`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy), and -[`acl_replication_token`](/docs/agent/options#acl_replication_token_legacy). +[`acl_token`](/docs/agent/config/agent-config-files#acl_token_legacy), [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token_legacy), +[`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy), and +[`acl_replication_token`](/docs/agent/config/agent-config-files#acl_replication_token_legacy). The table below shows this endpoint's support for [blocking queries](/api/features/blocking), diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx index 7587e14b3d..96303beab6 100644 --- a/website/content/api-docs/config.mdx +++ b/website/content/api-docs/config.mdx @@ -10,7 +10,7 @@ description: |- The `/config` endpoints create, update, delete and query central configuration entries registered with Consul. See the -[agent configuration](/docs/agent/options#enable_central_service_config) +[agent configuration](/docs/agent/config/agent-config-files#enable_central_service_config) for more information on how to enable this functionality for centrally configuring services and [configuration entries docs](/docs/agent/config-entries) for a description of the configuration entries content. diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index 39912a9b18..bc7652548e 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -94,7 +94,7 @@ The table below shows this endpoint's support for evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default intention behavior is defined by the default [ACL - policy](/docs/agent/options#acl_default_policy). + policy](/docs/agent/config/agent-config-files#acl_default_policy). This should be omitted for an L4 intention as it is mutually exclusive with the `Action` field. diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index 77721a7cbc..602e991ae7 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -235,7 +235,7 @@ The table below shows this endpoint's support for ascending order based on the estimated round trip time from that node. Passing `?near=_agent` will use the agent's node for the sort. This is specified as part of the URL as a query parameter. **Note** that using `near` will ignore - [`use_streaming_backend`](/docs/agent/options#use_streaming_backend) and always + [`use_streaming_backend`](/docs/agent/config/agent-config-files#use_streaming_backend) and always use blocking queries, because the data required to sort the results is not available to the streaming backend. diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index d57d86b18a..5810d50c76 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -79,7 +79,7 @@ $ curl \ Consul 0.7 added the ability to translate addresses in HTTP response based on the configuration setting for -[`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs). In order +[`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs). In order to allow clients to know if address translation is in effect, the `X-Consul-Translate-Addresses` header will be added if translation is enabled, and will have a value of `true`. If translation is not enabled then this header @@ -90,7 +90,7 @@ will not be present. All API responses for Consul versions after 1.9 will include an HTTP response header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which mirrors the current value of the agent's -[`acl.default_policy`](/docs/agent/options#acl_default_policy) option. +[`acl.default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) option. This is also the default [intention](/docs/connect/intentions) enforcement action if no intention matches. diff --git a/website/content/api-docs/operator/autopilot.mdx b/website/content/api-docs/operator/autopilot.mdx index ed568e6484..a3a1f9923b 100644 --- a/website/content/api-docs/operator/autopilot.mdx +++ b/website/content/api-docs/operator/autopilot.mdx @@ -67,7 +67,7 @@ $ curl \ ``` For more information about the Autopilot configuration options, see the -[agent configuration section](/docs/agent/options#autopilot). +[agent configuration section](/docs/agent/config/agent-config-files#autopilot). ## Update Configuration diff --git a/website/content/commands/acl/set-agent-token.mdx b/website/content/commands/acl/set-agent-token.mdx index d5caa308c1..fca77f61c4 100644 --- a/website/content/commands/acl/set-agent-token.mdx +++ b/website/content/commands/acl/set-agent-token.mdx @@ -10,7 +10,7 @@ Command: `consul acl set-agent-token` This command updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens are not persisted unless -[`acl.enable_token_persistence`](/docs/agent/options#acl_enable_token_persistence) +[`acl.enable_token_persistence`](/docs/agent/config/agent-config-files#acl_enable_token_persistence) is `true`, so tokens will need to be updated again if that option is `false` and the agent is restarted. diff --git a/website/content/commands/config/index.mdx b/website/content/commands/config/index.mdx index 1d3abe7c46..5b22e51153 100644 --- a/website/content/commands/config/index.mdx +++ b/website/content/commands/config/index.mdx @@ -10,7 +10,7 @@ Command: `consul config` The `config` command is used to interact with Consul's central configuration system. It exposes commands for creating, updating, reading, and deleting different kinds of config entries. See the -[agent configuration](/docs/agent/options#enable_central_service_config) +[agent configuration](/docs/agent/config/agent-config-files#enable_central_service_config) for more information on how to enable this functionality for centrally configuring services and [configuration entries docs](/docs/agent/config-entries) for a description of the configuration entries content. diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index 468ed8210f..4c8b701ac6 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -42,7 +42,7 @@ proxy configuration needed. be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using `unix:///path/to/socket` if the [agent is configured to - listen](/docs/agent/options#addresses) that way. + listen](/docs/agent/config/agent-config-files#addresses) that way. -> **Note:** gRPC uses the same TLS settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS diff --git a/website/content/commands/debug.mdx b/website/content/commands/debug.mdx index ded40e58e6..23ff3d0da9 100644 --- a/website/content/commands/debug.mdx +++ b/website/content/commands/debug.mdx @@ -78,7 +78,7 @@ information when `debug` is running. By default, it captures all information. | `members` | A list of all the WAN and LAN members in the cluster. | | `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. | | `logs` | `DEBUG` level logs for the target agent, captured for the duration. | -| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/options#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. | +| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/config/agent-config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. | ## Examples diff --git a/website/content/commands/index.mdx b/website/content/commands/index.mdx index 2ecd76563b..eb225022d6 100644 --- a/website/content/commands/index.mdx +++ b/website/content/commands/index.mdx @@ -226,7 +226,7 @@ CONSUL_TLS_SERVER_NAME=consulserver.domain Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the local agent is listening for gRPC requests. Currently gRPC is only used for integrating [Envoy proxy](/docs/connect/proxies/envoy) and must be [enabled -explicitly](/docs/agent/options#grpc_port) in agent configuration. +explicitly](/docs/agent/config/agent-config-files#grpc_port) in agent configuration. ``` CONSUL_GRPC_ADDR=127.0.0.1:8502 diff --git a/website/content/commands/operator/autopilot.mdx b/website/content/commands/operator/autopilot.mdx index a0949b9bcb..26a3cdb7b9 100644 --- a/website/content/commands/operator/autopilot.mdx +++ b/website/content/commands/operator/autopilot.mdx @@ -84,10 +84,10 @@ Usage: `consul operator autopilot set-config [options]` - `-disable-upgrade-migration` - Controls whether Consul will avoid promoting new servers until it can perform a migration. Must be one of `[true|false]`. -- `-redundancy-zone-tag` - Controls the [`-node-meta`](/docs/agent/options#_node_meta) +- `-redundancy-zone-tag` - Controls the [`-node-meta`](/docs/agent/config/agent-config-cli#_node_meta) key name used for separating servers into different redundancy zones. -- `-upgrade-version-tag` - Controls the [`-node-meta`](/docs/agent/options#_node_meta) +- `-upgrade-version-tag` - Controls the [`-node-meta`](/docs/agent/config/agent-config-cli#_node_meta) tag to use for version info when performing upgrade migrations. If left blank, the Consul version will be used. ### Command Output diff --git a/website/content/commands/reload.mdx b/website/content/commands/reload.mdx index 930dc87467..dd8a24f1a0 100644 --- a/website/content/commands/reload.mdx +++ b/website/content/commands/reload.mdx @@ -20,7 +20,7 @@ reload will be present in the agent logs and not in the output of this command. **NOTE** Not all configuration options are reloadable. See the -[Reloadable Configuration](/docs/agent/options#reloadable-configuration) +[Reloadable Configuration](/docs/agent/config#reloadable-configuration) section on the agent options page for details on which options are supported. ## Usage diff --git a/website/content/commands/validate.mdx b/website/content/commands/validate.mdx index cb3d02e079..ade1339282 100644 --- a/website/content/commands/validate.mdx +++ b/website/content/commands/validate.mdx @@ -21,7 +21,7 @@ to be loaded by the agent. This command cannot operate on partial configuration fragments since those won't pass the full agent validation. For more information on the format of Consul's configuration files, read the -consul agent [Configuration Files](/docs/agent/options#configuration-files) +consul agent [Configuration Files](/docs/agent/config/agent-config-files) section. ## Usage diff --git a/website/content/docs/agent/config-entries.mdx b/website/content/docs/agent/config-entries.mdx index e95ea16f29..6548dd6496 100644 --- a/website/content/docs/agent/config-entries.mdx +++ b/website/content/docs/agent/config-entries.mdx @@ -52,7 +52,7 @@ Configuration entries outside of Kubernetes should be managed with the Consul [CLI](/commands/config) or [API](/api/config). Additionally, as a convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's -[configuration files](/docs/agent/options#config_entries_bootstrap) +[configuration files](/docs/agent/config/agent-config-files#config_entries_bootstrap) ### Managing Configuration Entries with the CLI @@ -156,7 +156,7 @@ api ### Bootstrapping From A Configuration File Configuration entries can be bootstrapped by adding them [inline to each Consul -server's configuration file](/docs/agent/options#config_entries). When a +server's configuration file](/docs/agent/config/agent-config-files#config_entries). When a server gains leadership, it will attempt to initialize the configuration entries. If a configuration entry does not already exist outside of the servers configuration, then it will create it. If a configuration entry does exist, that diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx index 40dae78782..08a9f43980 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/agent-config-files.mdx @@ -905,7 +905,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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 + [`acl_down_policy`](/docs/agent/config/agent-config-files#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 diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx index d846ebb739..7928be877c 100644 --- a/website/content/docs/agent/config/index.mdx +++ b/website/content/docs/agent/config/index.mdx @@ -57,22 +57,22 @@ Reloading configuration does not reload all configuration items. The items which are reloaded include: - ACL Tokens -- [Configuration Entry Bootstrap](#config_entries_bootstrap) +- [Configuration Entry Bootstrap](/docs/agent/config/agent-config-files#config_entries_bootstrap) - Checks -- [Discard Check Output](#discard_check_output) +- [Discard Check Output](/docs/agent/config/agent-config-files#discard_check_output) - HTTP Client Address - Log level -- [Metric Prefix Filter](#telemetry-prefix_filter) -- [Node Metadata](#node_meta) +- [Metric Prefix Filter](/docs/agent/config/agent-config-files#telemetry-prefix_filter) +- [Node Metadata](/docs/agent/config/agent-config-files#node_meta) - Some Raft options (since Consul 1.10.0) - - [`raft_snapshot_threshold`](#_raft_snapshot_threshold) - - [`raft_snapshot_interval`](#_raft_snapshot_interval) - - [`raft_trailing_logs`](#_raft_trailing_logs) + - [`raft_snapshot_threshold`](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) + - [`raft_snapshot_interval`](/docs/agent/config/agent-config-files#_raft_snapshot_interval) + - [`raft_trailing_logs`](/docs/agent/config/agent-config-files#_raft_trailing_logs) - 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. -- [RPC rate limiting](#limits) -- [HTTP Maximum Connections per Client](#http_max_conns_per_client) +- [RPC rate limiting](/docs/agent/config/agent-config-files#limits) +- [HTTP Maximum Connections per Client](/docs/agent/config/agent-config-files#http_max_conns_per_client) - 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. diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index 8e67dbca1e..09d396bde0 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -102,7 +102,7 @@ The following example starts an agent in dev mode and stores agent state data in consul agent -data-dir=tmp/consul -dev ``` -Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/docs/agent/options) topic for a complete list of configuration options. +Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/docs/agent/config) topic for a complete list of configuration options. ### Understanding the Agent Startup Output @@ -127,16 +127,16 @@ $ consul agent -data-dir=/tmp/consul - **Node name**: This is a unique name for the agent. By default, this is the hostname of the machine, but you may customize it using the - [`-node`](/docs/agent/options#_node) flag. + [`-node`](/docs/agent/config/agent-config-cli#_node) flag. - **Datacenter**: This is the datacenter in which the agent is configured to - run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/options#_datacenter) flag. + run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/config/agent-config-cli#_datacenter) flag. Consul has first-class support for multiple datacenters, but configuring each node to report its datacenter improves agent efficiency. - **Server**: This indicates whether the agent is running in server or client mode. Running an agent in server mode requires additional overhead. This is because they participate in the consensus quorum, store cluster state, and handle queries. A server may also be - in ["bootstrap"](/docs/agent/options#_bootstrap_expect) mode, which enables the server to elect itselft as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. + in ["bootstrap"](/docs/agent/config/agent-config-cli#_bootstrap_expect) mode, which enables the server to elect itselft as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. - **Client Addr**: This is the address used for client interfaces to the agent. This includes the ports for the HTTP and DNS interfaces. By default, this @@ -179,18 +179,18 @@ The following settings are commonly used in the configuration file (also called | Parameter | Description | Default | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `node_name` | String value that specifies a name for the agent node.
See [`-node-id`](/docs/agent/options#_node_id) for details. | Hostname of the machine | -| `server` | Boolean value that determines if the agent runs in server mode.
See [`-server`](/docs/agent/options#_server) for details. | `false` | -| `datacenter` | String value that specifies which datacenter the agent runs in.
See [-datacenter](/docs/agent/options#_datacenter) for details. | `dc1` | -| `data_dir` | String value that specifies a directory for storing agent state data.
See [`-data-dir`](/docs/agent/options#_data_dir) for details. | none | -| `log_level` | String value that specifies the level of logging the agent reports.
See [`-log-level`](docs/agent/options#_log_level) for details. | `info` | -| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member.
See [`-retry-join`](/docs/agent/options#_retry_join) for details. | none | -| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/options#addresses) | -| `ports` | Block of nested objects that define ports bound to agent addresses.
See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/options#ports) | +| `node_name` | String value that specifies a name for the agent node.
See [`-node-id`](/docs/agent/config/agent-config-cli#_node_id) for details. | Hostname of the machine | +| `server` | Boolean value that determines if the agent runs in server mode.
See [`-server`](/docs/agent/config/agent-config-cli#_server) for details. | `false` | +| `datacenter` | String value that specifies which datacenter the agent runs in.
See [-datacenter](/docs/agent/config/agent-config-cli#_datacenter) for details. | `dc1` | +| `data_dir` | String value that specifies a directory for storing agent state data.
See [`-data-dir`](/docs/agent/config/agent-config-cli#_data_dir) for details. | none | +| `log_level` | String value that specifies the level of logging the agent reports.
See [`-log-level`](/docs/agent/config/agent-config-cli#_log_level) for details. | `info` | +| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member.
See [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) for details. | none | +| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/config/agent-config-files#addresses) | +| `ports` | Block of nested objects that define ports bound to agent addresses.
See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/config/agent-config-files#ports) | ### Server Node in a Service Mesh -The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/options#_bootstrap) and the Consul GUI is enabled. +The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/config/agent-config-cli#_bootstrap) and the Consul GUI is enabled. The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/docs/connect) for details. @@ -399,6 +399,6 @@ may not be important for your use case. For example, for a web server and load balancer setup, both result in the same outcome: the web node is removed from the load balancer pool. -The [`skip_leave_on_interrupt`](/docs/agent/options#skip_leave_on_interrupt) and -[`leave_on_terminate`](/docs/agent/options#leave_on_terminate) configuration +The [`skip_leave_on_interrupt`](/docs/agent/config/agent-config-files#skip_leave_on_interrupt) and +[`leave_on_terminate`](/docs/agent/config/agent-config-files#leave_on_terminate) configuration options allow you to adjust this behavior. diff --git a/website/content/docs/agent/telemetry.mdx b/website/content/docs/agent/telemetry.mdx index 076c21105b..634583e213 100644 --- a/website/content/docs/agent/telemetry.mdx +++ b/website/content/docs/agent/telemetry.mdx @@ -29,7 +29,7 @@ This telemetry information can be used for debugging or otherwise getting a better view of what Consul is doing. Review the [Monitoring and Metrics tutorial](https://learn.hashicorp.com/tutorials/consul/monitor-datacenter-health?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data. -Additionally, if the [`telemetry` configuration options](/docs/agent/options#telemetry) +Additionally, if the [`telemetry` configuration options](/docs/agent/config/agent-config-files#telemetry) are provided, the telemetry information will be streamed to a [statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where it can be aggregated and flushed to Graphite or any other metrics store. @@ -138,7 +138,7 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference() | Metric Name | Description | Unit | Type | | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server | requests | counter | -| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. | requests | counter | +| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/agent-config-files#limits) configuration. | requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | **Why they're important:** These measurements indicate the current load created from a Consul agent, including when the load becomes high enough to be rate limited. A high RPC count, especially from `consul.client.rpcexceeded` meaning that the requests are being rate-limited, could imply a misconfigured Consul agent. @@ -170,7 +170,7 @@ Under these conditions, a follower after a restart may be unable to catch up on replication and become a voter again since it takes longer to restore from disk or the leader than the leader takes to write a new snapshot and truncate its logs. Servers retain -[`raft_trailing_logs`](/docs/agent/options#_raft_trailing_logs) (default +[`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) (default `10240`) log entries even if their snapshot was more recent. On a leader processing 500 commits/second, that is only about 20 seconds worth of logs. Assuming the leader is able to write out a snapshot and truncate the logs in @@ -195,7 +195,7 @@ repeatedly as well as reduce the fault tolerance and serving capacity of the cluster. Since Consul 1.5.3 -[`raft_trailing_logs`](/docs/agent/options#_raft_trailing_logs) has been +[`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) has been configurable. Increasing it allows the leader to retain more logs and give followers more time to restore and catch up. The tradeoff is potentially slower appends which eventually might affect write throughput and latency @@ -206,7 +206,7 @@ mean loosing cluster availability and needing to recover the cluster from a loss of quorum. Since Consul 1.10.0 -[`raft_trailing_logs`](/docs/agent/options#_raft_trailing_logs) is now +[`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) is now reloadable with `consul reload` or `SIGHUP` allowing operators to increase this without the leader restarting or loosing leadership allowing the cluster to be recovered gracefully. @@ -277,7 +277,7 @@ This is a full list of metrics emitted by Consul. | `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter | | `consul.api.http` | Migrated from consul.http.. this samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter | -| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | +| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/agent-config-files#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.api.catalog_register.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter | | `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter | @@ -375,7 +375,7 @@ These metrics are used to monitor the health of the Consul servers. | `consul.raft.last_index` | Represents the raft applied index. | index | gauge | | `consul.raft.leader.dispatchLog` | Measures the time it takes for the leader to write log entries to disk. | ms | timer | | `consul.raft.leader.dispatchNumLogs` | Measures the number of logs committed to disk in a batch. | logs | gauge | -| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/options#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance) guide for more details. | ms | timer | +| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/config/agent-config-files#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance) guide for more details. | ms | timer | | `consul.raft.leader.oldestLogAge` | The number of milliseconds since the _oldest_ log in the leader's log store was written. This can be important for replication health where write rate is high and the snapshot is large as followers may be unable to recover from a restart if restoring takes longer than the minimum value for the current leader. Compare this with `consul.raft.fsm.lastRestoreDuration` and `consul.raft.rpc.installSnapshot` to monitor. In normal usage this gauge value will grow linearly over time until a snapshot completes on the leader and the log is truncated. Note: this metric won't be emitted until the leader writes a snapshot. After an upgrade to Consul 1.10.0 it won't be emitted until the oldest log was written after the upgrade. | ms | gauge | | `consul.raft.replication.heartbeat` | Measures the time taken to invoke appendEntries on a peer, so that it doesn’t timeout on a periodic basis. | ms | timer | | `consul.raft.replication.appendEntries` | Measures the time it takes to replicate log entries to followers. This is a general indicator of the load pressure on the Consul servers, as well as the performance of the communication between the servers. | ms | timer | @@ -473,7 +473,7 @@ These metrics give insight into the health of the cluster as a whole. | `consul.memberlist.degraded.timeout` | Counts the number of times an agent was marked as a dead node, whilst not getting enough confirmations from a randomly selected list of agent nodes in an agent's membership. | occurrence / interval | counter | | `consul.memberlist.msg.dead` | Counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter | | `consul.memberlist.health.score` | Describes a node's perception of its own health based on how well it is meeting the soft real-time requirements of the protocol. This metric ranges from 0 to 8, where 0 indicates "totally healthy". This health score is used to scale the time between outgoing probes, and higher scores translate into longer probing intervals. For more details see section IV of the Lifeguard paper: https://arxiv.org/pdf/1707.00788.pdf | score | gauge | -| `consul.memberlist.msg.suspect` | Increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/options#ports). | suspect messages received / interval | counter | +| `consul.memberlist.msg.suspect` | Increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/config/agent-config-files#ports). | suspect messages received / interval | counter | | `consul.memberlist.tcp.accept` | Counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter | | `consul.memberlist.udp.sent/received` | Measures the total number of bytes sent/received by an agent through the UDP protocol. | bytes sent or bytes received / interval | counter | | `consul.memberlist.tcp.connect` | Counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter | @@ -484,8 +484,8 @@ These metrics give insight into the health of the cluster as a whole. | `consul.memberlist.msg_suspect` | The number of suspect messages that the agent has processed so far, based on the message information given by the network layer. | messages / Interval | counter | | `consul.memberlist.probeNode` | Measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter | | `consul.memberlist.pushPullNode` | Measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter | -| `consul.serf.member.failed` | Increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | failures / interval | counter | -| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | flaps / interval | counter | +| `consul.serf.member.failed` | Increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/agent-config-files#ports). | failures / interval | counter | +| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/agent-config-files#ports). | flaps / interval | counter | | `consul.serf.member.join` | Increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter | | `consul.serf.member.left` | Increments when an agent leaves the cluster. | leaves / interval | counter | | `consul.serf.events` | Increments when an agent processes an [event](/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter | diff --git a/website/content/docs/connect/ca/aws.mdx b/website/content/docs/connect/ca/aws.mdx index 46e215f87c..3b4ed80b90 100644 --- a/website/content/docs/connect/ca/aws.mdx +++ b/website/content/docs/connect/ca/aws.mdx @@ -173,11 +173,11 @@ So monthly cost would be calculated as: - 500 ⨉ 13.3 = 6,650 certificates issued in dc3 The number of certificates issued could be reduced by increasing -[`leaf_cert_ttl`](/docs/agent/options#ca_leaf_cert_ttl) in the CA Provider +[`leaf_cert_ttl`](/docs/agent/config/agent-config-files#ca_leaf_cert_ttl) in the CA Provider configuration if the longer lived credentials are an acceptable risk tradeoff against the cost. -[`ca_config`]: /docs/agent/options#connect_ca_config -[`ca_provider`]: /docs/agent/options#connect_ca_provider +[`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config +[`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider [`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration diff --git a/website/content/docs/connect/ca/consul.mdx b/website/content/docs/connect/ca/consul.mdx index bad7effbb0..69778d0667 100644 --- a/website/content/docs/connect/ca/consul.mdx +++ b/website/content/docs/connect/ca/consul.mdx @@ -92,7 +92,7 @@ Connect is enabled - the PrivateKey and RootCert fields have not been set, so th been generated (as seen above in the roots list). There are two ways to have the Consul CA use a custom private key and root certificate: -either through the `ca_config` section of the [Agent configuration](/docs/agent/options#connect_ca_config) (which can only be used during the cluster's +either through the `ca_config` section of the [Agent configuration](/docs/agent/config/agent-config-files#connect_ca_config) (which can only be used during the cluster's initial bootstrap) or through the [Update CA Configuration endpoint](/api/connect/ca#update-ca-configuration). Currently Consul requires that root certificates are valid [SPIFFE SVID Signing certificates](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded diff --git a/website/content/docs/connect/ca/index.mdx b/website/content/docs/connect/ca/index.mdx index 94d7bf3946..4fd96a79bf 100644 --- a/website/content/docs/connect/ca/index.mdx +++ b/website/content/docs/connect/ca/index.mdx @@ -30,7 +30,7 @@ will generate the initial root certificates and setup the internal Consul server state. For the initial bootstrap, the CA provider can be configured through the -[Agent configuration](/docs/agent/options#connect_ca_config). After +[Agent configuration](/docs/agent/config/agent-config-files#connect_ca_config). After initialization, the CA can only be updated through the [Update CA Configuration API endpoint](/api/connect/ca#update-ca-configuration). If a CA is already initialized, any changes to the CA configuration in the diff --git a/website/content/docs/connect/ca/vault.mdx b/website/content/docs/connect/ca/vault.mdx index 3929c43ee0..514fb4544a 100644 --- a/website/content/docs/connect/ca/vault.mdx +++ b/website/content/docs/connect/ca/vault.mdx @@ -271,6 +271,6 @@ path "/connect_inter/*" { -[`ca_config`]: /docs/agent/options#connect_ca_config -[`ca_provider`]: /docs/agent/options#connect_ca_provider +[`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config +[`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider [`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index def7a2040d..9e13659002 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -28,7 +28,7 @@ You can configure the settings defined in the `exported-services` configuration ## Usage 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). -1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/options#config_entries)) as described in [Configuration](#configuration). +1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/config/agent-config-files#config_entries)) as described in [Configuration](#configuration). 1. Apply the configuration using one of the following methods: - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. diff --git a/website/content/docs/connect/config-entries/index.mdx b/website/content/docs/connect/config-entries/index.mdx index d7d11797c7..2ff6142fa8 100644 --- a/website/content/docs/connect/config-entries/index.mdx +++ b/website/content/docs/connect/config-entries/index.mdx @@ -49,7 +49,7 @@ See [Agent - Config Entries](/docs/agent/config-entries). ## Using Configuration Entries For Service Defaults Outside of Kubernetes, when the agent is -[configured](/docs/agent/options#enable_central_service_config) to enable +[configured](/docs/agent/config/agent-config-files#enable_central_service_config) to enable central service configurations, it will look for service configuration defaults that match a registering service instance. If it finds any, the agent will merge those defaults with the service instance configuration. This allows for things diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 74bfb70385..83e9721eb1 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -300,8 +300,8 @@ spec: type: 'bool: false', description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). + [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost.`, }, { diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index 8a5b647797..b2764273c6 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -649,8 +649,8 @@ spec: type: 'bool: false', description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). + [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running Consul on Kubernetes, and Consul agents run in their own pods.`, }, diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index b3bc3981c2..51a6ae79de 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -468,7 +468,7 @@ spec: first permission to match in the list is terminal and stops further evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default - intention behavior is defined by the default [ACL policy](/docs/agent/options#acl_default_policy).

+ intention behavior is defined by the default [ACL policy](/docs/agent/config/agent-config-files#acl_default_policy).

This should be omitted for an L4 intention as it is mutually exclusive with the \`Action\` field.

Setting \`Permissions\` is not valid if a wildcard is used for the \`Name\` or \`Namespace\` because they can only be @@ -478,7 +478,7 @@ spec: first permission to match in the list is terminal and stops further evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default - intention behavior is defined by the default [ACL policy](/docs/agent/options#acl_default_policy).

+ intention behavior is defined by the default [ACL policy](/docs/agent/config/agent-config-files#acl_default_policy).

This should be omitted for an L4 intention as it is mutually exclusive with the \`action\` field.

Setting \`permissions\` is not valid if a wildcard is used for the \`spec.destination.name\` or \`spec.destination.namespace\` diff --git a/website/content/docs/connect/configuration.mdx b/website/content/docs/connect/configuration.mdx index a60ddf78f1..ca0f6a1cdf 100644 --- a/website/content/docs/connect/configuration.mdx +++ b/website/content/docs/connect/configuration.mdx @@ -22,7 +22,7 @@ The first step to use Connect is to enable Connect for your Consul cluster. By default, Connect is disabled. Enabling Connect requires changing the configuration of only your Consul _servers_ (not client agents). To enable Connect, add the following to a new or existing -[server configuration file](/docs/agent/options). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: +[server configuration file](/docs/agent/config/agent-config-files). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: ```hcl connect { @@ -43,20 +43,20 @@ connection attempts to fail until Connect is enabled on the server agents. Other optional Connect configurations that you can set in the server configuration file include: -- [certificate authority settings](/docs/agent/options#connect) -- [token replication](/docs/agent/options#acl_tokens_replication) -- [dev mode](/docs/agent/options#_dev) -- [server host name verification](/docs/agent/options#verify_server_hostname) +- [certificate authority settings](/docs/agent/config/agent-config-files#connect) +- [token replication](/docs/agent/config/agent-config-files#acl_tokens_replication) +- [dev mode](/docs/agent/config/agent-config-cli#_dev) +- [server host name verification](/docs/agent/config/agent-config-files#verify_server_hostname) If you would like to use Envoy as your Connect proxy you will need to [enable -gRPC](/docs/agent/options#grpc_port). +gRPC](/docs/agent/config/agent-config-files#grpc_port). Additionally if you plan on using the observability features of Connect, it can be convenient to configure your proxies and services using [configuration entries](/docs/agent/config-entries) which you can interact with using the CLI or API, or by creating configuration entry files. You will want to enable [centralized service -configuration](/docs/agent/options#enable_central_service_config) on +configuration](/docs/agent/config/agent-config-files#enable_central_service_config) on clients, which allows each service's proxy configuration to be managed centrally via API. diff --git a/website/content/docs/connect/connect-internals.mdx b/website/content/docs/connect/connect-internals.mdx index c55ab29423..c4f30ae12d 100644 --- a/website/content/docs/connect/connect-internals.mdx +++ b/website/content/docs/connect/connect-internals.mdx @@ -109,10 +109,10 @@ externally routable IPs at the service level. ## Intention Replication Intention replication happens automatically but requires the -[`primary_datacenter`](/docs/agent/options#primary_datacenter) +[`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) configuration to be set to specify a datacenter that is authoritative for intentions. In production setups with ACLs enabled, the -[replication token](/docs/agent/options#acl_tokens_replication) must also +[replication token](/docs/agent/config/agent-config-files#acl_tokens_replication) must also be set in the secondary datacenter server's configuration. ## Certificate Authority Federation diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx index 72c98125e2..8e02b22d57 100644 --- a/website/content/docs/connect/gateways/ingress-gateway.mdx +++ b/website/content/docs/connect/gateways/ingress-gateway.mdx @@ -40,8 +40,8 @@ the [hosts](/docs/connect/config-entries/ingress-gateway#hosts) field. Ingress gateways also require that your Consul datacenters are configured correctly: - You'll need to use Consul version 1.8.0 or newer. -- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents. +- Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled on all client agents. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx index 6add2cee0a..f970753182 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx @@ -30,12 +30,12 @@ Ensure that your Consul environment meets the following requirements. * Consul version 1.6.0 or newer. * A local Consul agent is required to manage its configuration. -* Consul [Connect](/docs/agent/options#connect) must be enabled in both datacenters. -* Each [datacenter](/docs/agent/options#datacenter) must have a unique name. +* Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled in both datacenters. +* Each [datacenter](/docs/agent/config/agent-config-files#datacenter) must have a unique name. * Each datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan). -* The [primary datacenter](/docs/agent/options#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. -* [gRPC](/docs/agent/options#grpc_port) must be enabled. -* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#enable_central_service_config). +* The [primary datacenter](/docs/agent/config/agent-config-files#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. +* [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled. +* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/agent-config-files#enable_central_service_config). ### Network diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx index bc529496fa..278d504efd 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx @@ -24,9 +24,9 @@ Ensure that your Consul environment meets the following requirements. * Consul Enterprise version 1.11.0 or newer. * A local Consul agent is required to manage its configuration. -* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/options#connect) for details. +* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/config/agent-config-files#connect) for details. * Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enteprise/admin-partitions) for details. -* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#enable_central_service_config). +* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/agent-config-files#enable_central_service_config). ### Proxy diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index eca396d927..126c50ead0 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -124,7 +124,7 @@ connect { } ``` -Any references to [`start_join_wan`](/docs/agent/options#start_join_wan) or [`retry_join_wan`](/docs/agent/options#retry_join_wan) should be omitted. +Any references to [`start_join_wan`](/docs/agent/config/agent-config-files#start_join_wan) or [`retry_join_wan`](/docs/agent/config/agent-config-files#retry_join_wan) should be omitted. -> The `primary_gateways` configuration can also use `go-discover` syntax just like `retry_join_wan`. diff --git a/website/content/docs/connect/gateways/terminating-gateway.mdx b/website/content/docs/connect/gateways/terminating-gateway.mdx index fe5c700e79..064e5ed070 100644 --- a/website/content/docs/connect/gateways/terminating-gateway.mdx +++ b/website/content/docs/connect/gateways/terminating-gateway.mdx @@ -59,8 +59,8 @@ Each terminating gateway needs: Terminating gateways also require that your Consul datacenters are configured correctly: - You'll need to use Consul version 1.8.0 or newer. -- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents. +- Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled on all client agents. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul. diff --git a/website/content/docs/connect/intentions-legacy.mdx b/website/content/docs/connect/intentions-legacy.mdx index 240f0aea83..6061a867ea 100644 --- a/website/content/docs/connect/intentions-legacy.mdx +++ b/website/content/docs/connect/intentions-legacy.mdx @@ -25,7 +25,7 @@ is allowed by testing the intentions. If authorize returns false the connection must be terminated. The default intention behavior is defined by the default [ACL -policy](/docs/agent/options#acl_default_policy). If the default ACL policy is +policy](/docs/agent/config/agent-config-files#acl_default_policy). If the default ACL policy is "allow all", then all Connect connections are allowed by default. If the default ACL policy is "deny all", then all Connect connections are denied by default. diff --git a/website/content/docs/connect/intentions.mdx b/website/content/docs/connect/intentions.mdx index 198fa0d289..95aef154cf 100644 --- a/website/content/docs/connect/intentions.mdx +++ b/website/content/docs/connect/intentions.mdx @@ -49,7 +49,7 @@ target destination. After verifying the TLS client certificate, the cached intentions should be consulted for each incoming connection/request to determine if it should be accepted or rejected. -The default intention behavior is defined by the [`default_policy`](/docs/agent/options#acl_default_policy) configuration. +The default intention behavior is defined by the [`default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) configuration. If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. If is set to `deny`, then all connections or requests will be denied by default. diff --git a/website/content/docs/connect/observability/index.mdx b/website/content/docs/connect/observability/index.mdx index dda5e782e3..0aa3026ba0 100644 --- a/website/content/docs/connect/observability/index.mdx +++ b/website/content/docs/connect/observability/index.mdx @@ -18,10 +18,10 @@ to: - Define the upstreams for each of your services. If you are using Envoy as your sidecar proxy, you will need to [enable -gRPC](/docs/agent/options#grpc_port) on your client agents. To define the +gRPC](/docs/agent/config/agent-config-files#grpc_port) on your client agents. To define the metrics destination and service protocol you may want to enable [configuration -entries](/docs/agent/options#config_entries) and [centralized service -configuration](/docs/agent/options#enable_central_service_config). +entries](/docs/agent/config/agent-config-files#config_entries) and [centralized service +configuration](/docs/agent/config/agent-config-files#enable_central_service_config). ### Kubernetes If you are using Kubernetes, the Helm chart can simplify much of the configuration needed to enable observability. See diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx index 2102846a0e..9477b77ec7 100644 --- a/website/content/docs/connect/observability/ui-visualization.mdx +++ b/website/content/docs/connect/observability/ui-visualization.mdx @@ -47,11 +47,11 @@ UI. If there are multiple clients with the UI enabled in a datacenter for redundancy these configurations must be added to all of them. We assume that the UI is already enabled by setting -[`ui_config.enabled`](/docs/agent/options#ui_config_enabled) to `true` in the +[`ui_config.enabled`](/docs/agent/config/agent-config-files#ui_config_enabled) to `true` in the agent's configuration file. To use the built-in Prometheus provider -[`ui_config.metrics_provider`](/docs/agent/options#ui_config_metrics_provider) +[`ui_config.metrics_provider`](/docs/agent/config/agent-config-files#ui_config_metrics_provider) must be set to `prometheus`. The UI must query the metrics provider through a proxy endpoint. This simplifies @@ -59,7 +59,7 @@ deployment where Prometheus is not exposed externally to UI user's browsers. To set this up, provide the URL that the _Consul agent_ should use to reach the Prometheus server in -[`ui_config.metrics_proxy.base_url`](/docs/agent/options#ui_config_metrics_proxy_base_url). +[`ui_config.metrics_proxy.base_url`](/docs/agent/config/agent-config-files#ui_config_metrics_proxy_base_url). For example in Kubernetes, the Prometheus helm chart by default installs a service named `prometheus-server` so each Consul agent can reach it on `http://prometheus-server` (using Kubernetes' DNS resolution). @@ -87,7 +87,7 @@ service-specific dashboard in an external tool like [Grafana](https://grafana.com) or a hosted provider. To configure this, you must provide a URL template in the [agent configuration -file](/docs/agent/options#ui_config_dashboard_url_templates) for all agents that +file](/docs/agent/config/agent-config-files#ui_config_dashboard_url_templates) for all agents that have the UI enabled. The template is essentially the URL to the external dashboard, but can have placeholder values which will be replaced with the service name, namespace and datacenter where appropriate to allow deep-linking @@ -498,12 +498,12 @@ ui_config { ``` More than one JavaScript file may be specified in -[`metrics_provider_files`](/docs/agent/options#ui_config_metrics_provider_files) +[`metrics_provider_files`](/docs/agent/config/agent-config-files#ui_config_metrics_provider_files) and all we be served allowing flexibility if needed to include dependencies. Only one metrics provider can be configured and used at one time. The -[`metrics_provider_options_json`](/docs/agent/options#ui_config_metrics_provider_options_json) +[`metrics_provider_options_json`](/docs/agent/config/agent-config-files#ui_config_metrics_provider_options_json) field is an optional literal JSON object which is passed to the provider's `init` method at startup time. This allows configuring arbitrary parameters for the provider in config rather than hard coding them into the provider itself to @@ -512,7 +512,7 @@ make providers more reusable. The provider may fetch metrics directly from another source although in this case the agent will probably need to serve the correct CORS headers to prevent browsers from blocking these requests. These may be configured with -[`http_config.response_headers`](/docs/agent/options#response_headers). +[`http_config.response_headers`](/docs/agent/config/agent-config-files#response_headers). Alternatively, the provider may choose to use the [built-in metrics proxy](#metrics-proxy) to avoid cross domain issues or to inject additional diff --git a/website/content/docs/connect/proxies/built-in.mdx b/website/content/docs/connect/proxies/built-in.mdx index c37c0e94fa..f66a6747d7 100644 --- a/website/content/docs/connect/proxies/built-in.mdx +++ b/website/content/docs/connect/proxies/built-in.mdx @@ -58,7 +58,7 @@ All fields are optional with a reasonable default. - `bind_port` - The port the proxy will bind its _public_ mTLS listener to. If not provided, the agent will attempt to assign one from its - [configured proxy port range](/docs/agent/options#sidecar_min_port) if available. + [configured proxy port range](/docs/agent/config/agent-config-files#sidecar_min_port) if available. By default the range is [20000, 20255] and the port is selected at random from that range. diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index c5e29b24c7..8e6cde206f 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -188,7 +188,7 @@ the upstream listeners of any downstream service. One example is how users can define a service's protocol in a [`service-defaults` configuration entry](/docs/connect/config-entries/service-defaults). Agents with -[`enable_central_service_config`](/docs/agent/options#enable_central_service_config) +[`enable_central_service_config`](/docs/agent/config/agent-config-files#enable_central_service_config) set to true will automatically discover the protocol when configuring a proxy for a service. The proxy will discover the main protocol of the service it represents and use this to configure its main public listener. It will also diff --git a/website/content/docs/connect/proxies/managed-deprecated.mdx b/website/content/docs/connect/proxies/managed-deprecated.mdx index 1fd49ff023..7d14ce8c09 100644 --- a/website/content/docs/connect/proxies/managed-deprecated.mdx +++ b/website/content/docs/connect/proxies/managed-deprecated.mdx @@ -24,7 +24,7 @@ Managed proxies have been deprecated since Consul 1.3 and have been fully remove in Consul 1.6. Anyone using Managed Proxies should aim to change their workflow as soon as possible to avoid issues with a later upgrade. -After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/options#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. +After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/config/agent-config-cli#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. **new and known issues will not be fixed**. @@ -79,7 +79,7 @@ via agent configuration files. They _cannot_ be registered via the HTTP API. And 2.) Managed proxies are not started at all if Consul is running as root. Both of these default configurations help prevent arbitrary process execution or privilege escalation. This behavior can be configured -[per-agent](/docs/agent/options). +[per-agent](/docs/agent/config). ### Lifecycle @@ -275,6 +275,6 @@ level logs showing service discovery, certificate and authorization information. ~> **Note:** In `-dev` mode there is no `data_dir` unless one is explicitly configured so logging is disabled. You can access logs by providing the -[`-data-dir`](/docs/agent/options#_data_dir) CLI option. If a data dir is +[`-data-dir`](/docs/agent/config/agent-config-cli#_data_dir) CLI option. If a data dir is configured, this will also cause proxy processes to stay running when the agent terminates as described in [Lifecycle](#lifecycle). diff --git a/website/content/docs/connect/registration/service-registration.mdx b/website/content/docs/connect/registration/service-registration.mdx index 92bcb1a93e..bef0ff0ea2 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/registration/service-registration.mdx @@ -437,8 +437,8 @@ registrations](/docs/agent/services#service-definition-parameter-case). - `checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). + [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running Consul on Kubernetes, and Consul agents run in their own pods. - `paths` `array: []` - A list of paths to expose through Envoy. diff --git a/website/content/docs/connect/registration/sidecar-service.mdx b/website/content/docs/connect/registration/sidecar-service.mdx index 88bf58d62f..ffa5f5e699 100644 --- a/website/content/docs/connect/registration/sidecar-service.mdx +++ b/website/content/docs/connect/registration/sidecar-service.mdx @@ -131,7 +131,7 @@ proxy. - `tags` - Defaults to the tags of the parent service. - `meta` - Defaults to the service metadata of the parent service. - `port` - Defaults to being auto-assigned from a [configurable - range](/docs/agent/options#sidecar_min_port) that is + range](/docs/agent/config/agent-config-files#sidecar_min_port) that is by default `[21000, 21255]`. - `kind` - Defaults to `connect-proxy`. This can't be overridden currently. - `check`, `checks` - By default we add a TCP check on the local address and diff --git a/website/content/docs/discovery/checks.mdx b/website/content/docs/discovery/checks.mdx index 02ef1c2846..29095d32e5 100644 --- a/website/content/docs/discovery/checks.mdx +++ b/website/content/docs/discovery/checks.mdx @@ -34,10 +34,10 @@ There are several different kinds of checks: In Consul 0.9.0 and later, script checks are not enabled by default. To use them you can either use : - - [`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks): + - [`enable_local_script_checks`](/docs/agent/config/agent-config-cli#_enable_local_script_checks): enable script checks defined in local config files. Script checks defined via the HTTP API will not be allowed. - - [`enable_script_checks`](/docs/agent/options#_enable_script_checks): enable + - [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks): enable script checks regardless of how they are defined. ~> **Security Warning:** Enabling script checks in some configurations may @@ -105,7 +105,7 @@ There are several different kinds of checks: has to be performed is configurable which makes it possible to run containers which have different shells on the same host. Check output for Docker is limited to 4KB. Any output larger than this will be truncated. In Consul 0.9.0 and later, the agent - must be configured with [`enable_script_checks`](/docs/agent/options#_enable_script_checks) + must be configured with [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks) set to `true` in order to enable Docker health checks. - `gRPC + Interval` - These checks are intended for applications that support the standard @@ -462,7 +462,7 @@ This is the only convention that Consul depends on. Any output of the script will be captured and stored in the `output` field. In Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/options#_enable_script_checks) set to `true` +[`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks) set to `true` in order to enable script checks. ## Initial Health Check Status @@ -538,7 +538,7 @@ provided by the node will remain unchanged. ## Agent Certificates for TLS Checks -The [enable_agent_tls_for_checks](/docs/agent/options#enable_agent_tls_for_checks) +The [enable_agent_tls_for_checks](/docs/agent/config/agent-config-files#enable_agent_tls_for_checks) agent configuration option can be utilized to have HTTP or gRPC health checks to use the agent's credentials when configured for TLS. diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index 5de36d932a..208c0110c1 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -21,18 +21,18 @@ are located in the `us-east-1` datacenter, and have no failing health checks. It's that simple! There are a number of configuration options that are important for the DNS interface, -specifically [`client_addr`](/docs/agent/options#client_addr),[`ports.dns`](/docs/agent/options#dns_port), -[`recursors`](/docs/agent/options#recursors),[`domain`](/docs/agent/options#domain), -[`alt_domain`](/docs/agent/options#alt_domain), and [`dns_config`](/docs/agent/options#dns_config). +specifically [`client_addr`](/docs/agent/config/agent-config-files#client_addr),[`ports.dns`](/docs/agent/config/agent-config-files#dns_port), +[`recursors`](/docs/agent/config/agent-config-files#recursors),[`domain`](/docs/agent/config/agent-config-files#domain), +[`alt_domain`](/docs/agent/config/agent-config-files#alt_domain), and [`dns_config`](/docs/agent/config/agent-config-files#dns_config). By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.` domain, without support for further DNS recursion. Please consult the -[documentation on configuration options](/docs/agent/options), +[documentation on configuration options](/docs/agent/config), specifically the configuration items linked above, for more details. There are a few ways to use the DNS interface. One option is to use a custom DNS resolver library and point it at Consul. Another option is to set Consul as the DNS server for a node and provide a -[`recursors`](/docs/agent/options#recursors) configuration so that non-Consul queries +[`recursors`](/docs/agent/config/agent-config-files#recursors) configuration so that non-Consul queries can also be resolved. The last method is to forward all queries for the "consul." domain to a Consul agent from the existing DNS server. Review the [DNS Forwarding tutorial](https://learn.hashicorp.com/tutorials/consul/dns-forwarding?utm_source=consul.io&utm_medium=docs) for examples. @@ -296,15 +296,15 @@ are not truncated. ## Alternative Domain By default, Consul responds to DNS queries in the `consul` domain, -but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/options#domain) parameter. +but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/config/agent-config-files#domain) parameter. In some instances, Consul may need to respond to queries in more than one domain, such as during a DNS migration or to distinguish between internal and external queries. Consul versions 1.5.2+ can be configured to respond to DNS queries on an alternative domain -through the [`alt_domain`](/docs/agent/options#alt_domain) agent configuration +through the [`alt_domain`](/docs/agent/config/agent-config-files#alt_domain) agent configuration option. As of Consul versions 1.11.0+, Consul's DNS response will use the same domain as was used in the query; -in prior versions, the response may use the primary [`domain`](/docs/agent/options#domain) no matter which +in prior versions, the response may use the primary [`domain`](/docs/agent/config/agent-config-files#domain) no matter which domain was used in the query. In the following example, the `alt_domain` parameter is set to `test-domain`: @@ -331,7 +331,7 @@ machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment=" ``` -> **PTR queries:** Responses to PTR queries (`.in-addr.arpa.`) will always use the -[primary domain](/docs/agent/options#domain) (not the alternative domain), +[primary domain](/docs/agent/config/agent-config-files#domain) (not the alternative domain), as there is no way for the query to specify a domain. ## Caching @@ -346,8 +346,8 @@ for [DNS caching](https://learn.hashicorp.com/tutorials/consul/dns-caching). By default, Consul DNS queries will return a node's local address, even when being queried from a remote datacenter. If you need to use a different address to reach a node from outside its datacenter, you can configure this behavior -using the [`advertise-wan`](/docs/agent/options#_advertise-wan) and -[`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs) configuration +using the [`advertise-wan`](/docs/agent/config/agent-config-cli#_advertise-wan) and +[`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs) configuration options. ## Namespaced/Partitioned Services @@ -363,7 +363,7 @@ services from other namespaces or partitions the following form can be used: This is the canonical name of a Consul Enterprise service. Currently all parts must be present - in a future version (once the -[`prefer_namespace` configuration](/docs/agent/options#dns_prefer_namespace) has been +[`prefer_namespace` configuration](/docs/agent/config/agent-config-files#dns_prefer_namespace) has been deprecated), the namespace, partition and datacenter components will become optional and may be individually omitted to default to the `default` namespace, local partition or local datacenter respectively. @@ -377,7 +377,7 @@ are enabled, you must first create ACL tokens with the necessary policies. Consul agents resolve DNS requests using one of the preconfigured tokens below, listed in order of precedence: -1. The agent's [`default` token](/docs/agent/options#acl_tokens_default). +1. The agent's [`default` token](/docs/agent/config/agent-config-files#acl_tokens_default). 2. The built-in [`anonymous` token](/docs/security/acl/acl-system#builtin-tokens). Because the anonymous token is used when any request is made to Consul without explicitly specifying a token, production deployments should not apply policies diff --git a/website/content/docs/dynamic-app-config/kv.mdx b/website/content/docs/dynamic-app-config/kv.mdx index 6ec4f24561..6793d053f5 100644 --- a/website/content/docs/dynamic-app-config/kv.mdx +++ b/website/content/docs/dynamic-app-config/kv.mdx @@ -39,7 +39,7 @@ privileges on one key for developers to update the value related to their application. The datastore itself is located on the Consul servers in the [data -directory](/docs/agent/options#_data_dir). To ensure data is not lost in +directory](/docs/agent/config/agent-config-cli#_data_dir). To ensure data is not lost in the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data. ## Using Consul KV @@ -48,7 +48,7 @@ Objects are opaque to Consul, meaning there are no restrictions on the type of object stored in a key/value entry. The main restriction on an object is size - the maximum is 512 KB. Due to the maximum object size and main use cases, you should not need extra storage; the general [sizing -recommendations](/docs/agent/options#kv_max_value_size) +recommendations](/docs/agent/config/agent-config-files#kv_max_value_size) are usually sufficient. Keys, like objects are not restricted by type and can include any character. diff --git a/website/content/docs/dynamic-app-config/watches.mdx b/website/content/docs/dynamic-app-config/watches.mdx index f56595c680..bd9e0802f2 100644 --- a/website/content/docs/dynamic-app-config/watches.mdx +++ b/website/content/docs/dynamic-app-config/watches.mdx @@ -20,7 +20,7 @@ Watches are implemented using blocking queries in the [HTTP API](/api). Agents automatically make the proper API calls to watch for changes and inform a handler when the data view has updated. -Watches can be configured as part of the [agent's configuration](/docs/agent/options#watches), +Watches can be configured as part of the [agent's configuration](/docs/agent/config/agent-config-files#watches), causing them to run once the agent is initialized. Reloading the agent configuration allows for adding or removing watches dynamically. diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index b6d5230636..60e567a62e 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -62,7 +62,7 @@ however there are some important inputs worth highlighting: This is where you include application containers. - `port` is the port that your application listens on. This should be set to a string, not an integer, i.e. `port = "9090"`, not `port = 9090`. -- `retry_join` is passed to the [`-retry-join`](/docs/agent/options#_retry_join) option for the Consul agent. This tells +- `retry_join` is passed to the [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) option for the Consul agent. This tells the agent the location of your Consul servers so that it can join the Consul cluster. -> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true` diff --git a/website/content/docs/enterprise/audit-logging.mdx b/website/content/docs/enterprise/audit-logging.mdx index aec2723d80..030dea3e69 100644 --- a/website/content/docs/enterprise/audit-logging.mdx +++ b/website/content/docs/enterprise/audit-logging.mdx @@ -25,14 +25,14 @@ For more experience leveraging Consul's audit logging functionality, explore our HashiCorp Learn tutorial [Capture Consul Events with Audit Logging](https://learn.hashicorp.com/tutorials/consul/audit-logging). For detailed configuration information on configuring the Consul Enterprise's audit -logging, review the Consul [Audit Log](https://www.consul.io/docs/agent/options#audit) +logging, review the Consul [Audit Log](https://www.consul.io/docs/agent/config/agent-config-files#audit) documentation. ## Example Configuration Audit logging must be enabled on every agent in order to accurately capture all operations performed through the HTTP API. To enable logging, add -the [`audit`](/docs/agent/options#audit) stanza to the agent's configuration. +the [`audit`](/docs/agent/config/agent-config-files#audit) stanza to the agent's configuration. -> **Note**: Consul only logs operations which are initiated via the HTTP API. The audit log does not record operations that take place over the internal RPC diff --git a/website/content/docs/enterprise/license/overview.mdx b/website/content/docs/enterprise/license/overview.mdx index 67947e273d..ae99a58746 100644 --- a/website/content/docs/enterprise/license/overview.mdx +++ b/website/content/docs/enterprise/license/overview.mdx @@ -36,7 +36,7 @@ When using these binaries no further action is necessary to configure the licens ### Binaries Without Built In Licenses For Consul Enterprise 1.10.0 or greater, binaries that do not include built in licenses a license must be available at the time the agent starts. -For server agents this means that they must either have the [`license_path`](/docs/agent/options#license_path) +For server agents this means that they must either have the [`license_path`](/docs/agent/config/agent-config-files#license_path) configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or `CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH` environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment @@ -55,9 +55,9 @@ to retrieve the license automatically under specific circumstances. When a client agent starts without a license in its configuration or environment, it will try to retrieve the license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the request but the token doesn't need any particular permissions. As the license is required before the client -actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/options#start_join) -or [`retry_join`](/docs/agent/options#retry_join) configurations. If those are both unset or no -[`agent` token](/docs/agent/options#acl_tokens_agent) is set then the client agent will immediately shut itself down. +actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/config/agent-config-files#start_join) +or [`retry_join`](/docs/agent/config/agent-config-files#retry_join) configurations. If those are both unset or no +[`agent` token](/docs/agent/config/agent-config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down. If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a diff --git a/website/content/docs/enterprise/network-segments.mdx b/website/content/docs/enterprise/network-segments.mdx index 001cb6f7ee..75929181d3 100644 --- a/website/content/docs/enterprise/network-segments.mdx +++ b/website/content/docs/enterprise/network-segments.mdx @@ -15,7 +15,7 @@ description: |- Consul requires full connectivity between all agents (servers and clients) in a -[datacenter](/docs/agent/options#_datacenter) within a given +[datacenter](/docs/agent/config/agent-config-cli#_datacenter) within a given LAN gossip pool. By default, all Consul agents will be a part of one shared Serf LAN gossip pool known as the `` network segment, thus requiring full mesh connectivity within the datacenter. @@ -46,7 +46,7 @@ Consul networking models and their capabilities. **Cluster:** A set of Consul servers forming a Raft quorum along with a collection of Consul clients, all set to the same -[datacenter](/docs/agent/options#_datacenter), and joined together to form +[datacenter](/docs/agent/config/agent-config-cli#_datacenter), and joined together to form what we will call a "local cluster". Consul clients discover the Consul servers in their local cluster through the gossip mechanism and make RPC requests to them. LAN Gossip (OSS) is an open intra-cluster networking model, and Network @@ -73,7 +73,7 @@ group of agents to only connect with the agents in its segment. Server agents are members of all segments. The datacenter includes a `` segment, as well as additional segments defined in the -[`segments`](/docs/agent/options#segments) server agent configuration option. +[`segments`](/docs/agent/config/agent-config-files#segments) server agent configuration option. Each additional segment is defined by: - a non-empty name @@ -130,19 +130,19 @@ segments = [ -The server [agent configuration](/docs/agent/options) options relevant to network +The server [agent configuration](/docs/agent/config/agent-config-files) options relevant to network segments are: -- [`ports.serf_lan`](/docs/agent/options#serf_lan_port): The Serf LAN port on this server +- [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port): The Serf LAN port on this server for the `` network segment's gossip pool. -- [`segments`](/docs/agent/options#segments): A list of user-defined network segments +- [`segments`](/docs/agent/config/agent-config-files#segments): A list of user-defined network segments on this server, including their names and Serf LAN ports. ## Client Configuration Each client agent can only be a member of one segment at a time. This will be the `` segment unless otherwise specified in the agent's -[`segment`](/docs/agent/options.html#_segment) agent configuration option. +[`segment`](/docs/agent/config/agent-config-cli#_segment) agent configuration option. ### Join a Client to a Segment ((#join_a_client_to_a_segment)) @@ -155,14 +155,14 @@ configured segment. Clients A and B specify the same segment S. Client B is already joined to the segment S LAN gossip pool. Client A wants to join via Client B. In order to do so, Client A -must connect to Client B's configured [Serf LAN port](/docs/agent/options#serf_lan_port). +must connect to Client B's configured [Serf LAN port](/docs/agent/config/agent-config-files#serf_lan_port). Client A specifies segment S and wants to join the segment S gossip pool via Server 1. In order to do so, Client A must connect to Server 1's configured [Serf LAN port -for segment S](/docs/agent/options#segment_port). +for segment S](/docs/agent/config/agent-config-files#segment_port). @@ -172,12 +172,12 @@ of precedence: 1. **Specify an explicit port in the join address**. This can be done at the CLI when starting the agent (e.g., `consul agent -retry-join "client-b-address:8303"`), or in the agent's - configuration using the [retry-join option](/docs/agent/options#retry_join). This method + configuration using the [retry-join option](/docs/agent/config/agent-config-files#retry_join). This method is not compatible with [cloud auto-join](/docs/install/cloud-auto-join#auto-join-with-network-segments). 2. **Specify an alternate Serf LAN port for the agent**. This can be done at the CLI when starting the agent (e.g., `consul agent -retry-join "client-b-address" -serf-lan-port 8303`), or in - the agent's configuration using the [serf_lan](/docs/agent/options#serf_lan_port) option. + the agent's configuration using the [serf_lan](/docs/agent/config/agent-config-files#serf_lan_port) option. When a Serf LAN port is not explicitly specified in the join address, the agent will attempt to join the target host at the Serf LAN port specified in CLI or agent configuration. @@ -222,15 +222,15 @@ ports = { -The client [agent configuration](/docs/agent/options) options relevant to network +The client [agent configuration](/docs/agent/config/agent-config-files) options relevant to network segments are: -- [`segment`](/docs/agent/options#segment-2): The name of the network segment this +- [`segment`](/docs/agent/config/agent-config-files#segment-2): The name of the network segment this client agent belongs to. -- [`ports.serf_lan`](/docs/agent/options#serf_lan_port): +- [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port): Serf LAN port for the above segment on this client. This is not required to match the configured Serf LAN port for other agents on this segment. -- [`retry_join`](/docs/agent/options#retry_join) or - [`start_join`](/docs/agent/options#start_join): A list of agent addresses to join +- [`retry_join`](/docs/agent/config/agent-config-files#retry_join) or + [`start_join`](/docs/agent/config/agent-config-files#start_join): A list of agent addresses to join when starting. Ensure the correct Serf LAN port for this segment is used when joining the LAN gossip pool using one of the [available configuration methods](#join_a_client_to_a_segment). diff --git a/website/content/docs/enterprise/read-scale.mdx b/website/content/docs/enterprise/read-scale.mdx index 65faf68f97..c7b6006b5d 100644 --- a/website/content/docs/enterprise/read-scale.mdx +++ b/website/content/docs/enterprise/read-scale.mdx @@ -19,6 +19,6 @@ to include voting servers and read replicas. Read replicas still receive data fr however, they do not take part in quorum election operations. Expanding your Consul cluster in this way can scale reads without impacting write latency. -For more details, review the [Consul server configuration](/docs/agent/options) -documentation and the [-read-replica](/docs/agent/options#_read_replica) +For more details, review the [Consul server configuration](/docs/agent/config) +documentation and the [-read-replica](/docs/agent/config/agent-config-cli#_read_replica) configuration flag. diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx index d9ff3ca892..6388baf517 100644 --- a/website/content/docs/index.mdx +++ b/website/content/docs/index.mdx @@ -16,5 +16,5 @@ and a link to our guides that walk you through common tasks. Note that the guides are located on the HashiCorp Learn site. - Follow [the documentation](/docs/install) to install Consul either with a precompiled binary or from source. -- Read more about the [configuration options](/docs/agent/options) for Consul servers and clients. +- Read more about the [configuration options](/docs/agent/config) for Consul servers and clients. - Get started using Consul with our step-by-step guides at [HashiCorp Learn](https://learn.hashicorp.com/consul). diff --git a/website/content/docs/install/bootstrapping.mdx b/website/content/docs/install/bootstrapping.mdx index 7f9c355763..33342bd152 100644 --- a/website/content/docs/install/bootstrapping.mdx +++ b/website/content/docs/install/bootstrapping.mdx @@ -30,16 +30,16 @@ as data loss is inevitable in a failure scenario. Please refer to the Manual bootstrapping with `-bootstrap` is not recommended in newer versions of Consul (0.5 and newer) as it is more error-prone. Instead you should use automatic bootstrapping -with [`-bootstrap-expect`](/docs/agent/options#_bootstrap_expect). +with [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect). ## Bootstrapping the Servers -The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/options#_bootstrap_expect) +The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect) configuration option. This option informs Consul of the expected number of server nodes and automatically bootstraps when that many servers are available. To prevent inconsistencies and split-brain (clusters where multiple servers consider themselves leader) situations, you should either specify the same value for -[`-bootstrap-expect`](/docs/agent/options#_bootstrap_expect) +[`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect) or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster. Suppose we are starting a three server cluster. We can start `Node A`, `Node B`, and `Node C` with each @@ -61,11 +61,11 @@ You can trigger leader election by joining the servers together, to create a clu There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case. - Specify a list of servers with - [-join](/docs/agent/options#_join) and - [start_join](/docs/agent/options#start_join) + [-join](/docs/agent/config/agent-config-cli#_join) and + [start_join](/docs/agent/config/agent-config-files#start_join) options. -- Specify a list of servers with [-retry-join](/docs/agent/options#_retry_join) option. -- Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/options#_retry_join) option. +- Specify a list of servers with [-retry-join](/docs/agent/config/agent-config-cli#_retry_join) option. +- Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/config/agent-config-cli#_retry_join) option. All three methods can be set in the agent configuration file or the command line flag. diff --git a/website/content/docs/install/cloud-auto-join.mdx b/website/content/docs/install/cloud-auto-join.mdx index 077affac71..f3053632ce 100644 --- a/website/content/docs/install/cloud-auto-join.mdx +++ b/website/content/docs/install/cloud-auto-join.mdx @@ -69,7 +69,7 @@ to use port `8303` as its Serf LAN port prior to attempting to join the cluster. The following example configuration overrides the default Serf LAN port using the -[`ports.serf_lan`](/docs/agent/options#serf_lan_port) configuration option. +[`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port) configuration option. @@ -85,7 +85,7 @@ ports { The following example overrides the default Serf LAN port using the -[`-serf-lan-port`](/docs/agent/options#_serf_lan_port) command line flag. +[`-serf-lan-port`](/docs/agent/config/agent-config-cli#_serf_lan_port) command line flag. ```shell $ consul agent -serf-lan-port=8303 -retry-join "provider=..." diff --git a/website/content/docs/install/manual-bootstrap.mdx b/website/content/docs/install/manual-bootstrap.mdx index 63c238456f..5a1c564590 100644 --- a/website/content/docs/install/manual-bootstrap.mdx +++ b/website/content/docs/install/manual-bootstrap.mdx @@ -23,7 +23,7 @@ storing the cluster state. The client nodes are mostly stateless and rely on the server nodes, so they can be started easily. Manual bootstrapping requires that the first server that is deployed in a new -datacenter provide the [`-bootstrap` configuration option](/docs/agent/options#_bootstrap). +datacenter provide the [`-bootstrap` configuration option](/docs/agent/config/agent-config-cli#_bootstrap). This option allows the server to assert leadership of the cluster without agreement from any other server. This is necessary because at this point, there are no other servers running in diff --git a/website/content/docs/install/performance.mdx b/website/content/docs/install/performance.mdx index 85fa3161c7..0dd92817b6 100644 --- a/website/content/docs/install/performance.mdx +++ b/website/content/docs/install/performance.mdx @@ -18,7 +18,7 @@ reads work from a fully in-memory data store that is optimized for concurrent ac ## Minimum Server Requirements ((#minimum)) -In Consul 0.7, the default server [performance parameters](/docs/agent/options#performance) +In Consul 0.7, the default server [performance parameters](/docs/agent/config/agent-config-files#performance) were tuned to allow Consul to run reliably (but relatively slowly) on a server cluster of three [AWS t2.micro](https://aws.amazon.com/ec2/instance-types/) instances. These thresholds were determined empirically using a leader instance that was under sufficient read, write, @@ -43,7 +43,7 @@ The default performance configuration is equivalent to this: ## Production Server Requirements ((#production)) When running Consul 0.7 and later in production, it is recommended to configure the server -[performance parameters](/docs/agent/options#performance) back to Consul's original +[performance parameters](/docs/agent/config/agent-config-files#performance) back to Consul's original high-performance settings. This will let Consul servers detect a failed leader and complete leader elections much more quickly than the default configuration which extends key Raft timeouts by a factor of 5, so it can be quite slow during these events. @@ -103,14 +103,14 @@ Here are some general recommendations: issues between the servers or insufficient CPU resources. Users in cloud environments often bump their servers up to the next instance class with improved networking and CPU until leader elections stabilize, and in Consul 0.7 or later the [performance - parameters](/docs/agent/options#performance) configuration now gives you tools + parameters](/docs/agent/config/agent-config-files#performance) configuration now gives you tools to trade off performance instead of upsizing servers. You can use the [`consul.raft.leader.lastContact` telemetry](/docs/agent/telemetry#leadership-changes) to observe how the Raft timing is performing and guide the decision to de-tune Raft performance or add more powerful servers. - For DNS-heavy workloads, configuring all Consul agents in a cluster with the - [`allow_stale`](/docs/agent/options#allow_stale) configuration option will allow reads to + [`allow_stale`](/docs/agent/config/agent-config-files#allow_stale) configuration option will allow reads to scale across all Consul servers, not just the leader. Consul 0.7 and later enables stale reads for DNS by default. See [Stale Reads](https://learn.hashicorp.com/tutorials/consul/dns-caching#stale-reads) in the [DNS Caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) guide for more details. It's also good to set @@ -121,7 +121,7 @@ Here are some general recommendations: [stale consistency mode](/api/features/consistency#stale) available to allow reads to scale across all the servers and not just be forwarded to the leader. -- In Consul 0.9.3 and later, a new [`limits`](/docs/agent/options#limits) configuration is +- In Consul 0.9.3 and later, a new [`limits`](/docs/agent/config/agent-config-files#limits) configuration is available on Consul clients to limit the RPC request rate they are allowed to make against the Consul servers. After hitting the limit, requests will start to return rate limit errors until time has passed and more requests are allowed. Configuring this across the cluster can help with @@ -156,11 +156,11 @@ For **write-heavy** workloads, the total RAM available for overhead must approxi RAM NEEDED = number of keys * average key size * 2-3x ``` -Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/options#_data_dir)) +Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/config/agent-config-cli#_data_dir)) For a **read-heavy** workload, configure all Consul server agents with the `allow_stale` DNS option, or query the API with the `stale` [consistency mode](/api/features/consistency). By default, all queries made to the server are RPC forwarded to and serviced by the leader. By enabling stale reads, any server will respond to any query, thereby reducing overhead on the leader. Typically, the stale response is `100ms` or less from consistent mode but it drastically improves performance and reduces latency under high load. -If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/options#max_stale)). +If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/config/agent-config-files#max_stale)). It should be noted that `stale` is not appropriate for coordination where strong consistency is important (i.e. locking or application leader election). For critical cases, the optional `consistent` API query mode is required for true linearizability; the trade off is that this turns a read into a full quorum write so requires more resources and takes longer. @@ -168,7 +168,7 @@ It should be noted that `stale` is not appropriate for coordination where strong Consul’s agents use network sockets for communicating with the other nodes (gossip) and with the server agent. In addition, file descriptors are also opened for watch handlers, health checks, and log files. For a **write heavy** cluster, the `ulimit` size must be increased from the default value (`1024`) to prevent the leader from running out of file descriptors. -To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/options#limits) +To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/config/agent-config-files#limits) ~> **NOTE** Rate limiting is configured on the client agent only. @@ -191,8 +191,8 @@ Smearing requests over 30s is sufficient to bring RPC load to a reasonable level in all but the very largest clusters, but the extra CPU load from cryptographic operations could impact the server's normal work. To limit that, Consul since 1.4.1 exposes two ways to limit the impact Certificate signing has on the leader -[`csr_max_per_second`](/docs/agent/options#ca_csr_max_per_second) and -[`csr_max_concurrent`](/docs/agent/options#ca_csr_max_concurrent). +[`csr_max_per_second`](/docs/agent/config/agent-config-files#ca_csr_max_per_second) and +[`csr_max_concurrent`](/docs/agent/config/agent-config-files#ca_csr_max_concurrent). By default we set a limit of 50 per second which is reasonable on modest hardware but may be too low and impact rotation times if more than 1500 service diff --git a/website/content/docs/install/ports.mdx b/website/content/docs/install/ports.mdx index a9763327ca..6cbc9eb828 100644 --- a/website/content/docs/install/ports.mdx +++ b/website/content/docs/install/ports.mdx @@ -55,4 +55,4 @@ the Serf WAN port (TCP/UDP) to be listening on both WAN and LAN interfaces. See **Server RPC** This is used by servers to handle incoming requests from other agents. -Note, the default ports can be changed in the [agent configuration](/docs/agent/options#ports). +Note, the default ports can be changed in the [agent configuration](/docs/agent/config/agent-config-files#ports). diff --git a/website/content/docs/k8s/connect/connect-ca-provider.mdx b/website/content/docs/k8s/connect/connect-ca-provider.mdx index de1bca22ab..9d9ce93853 100644 --- a/website/content/docs/k8s/connect/connect-ca-provider.mdx +++ b/website/content/docs/k8s/connect/connect-ca-provider.mdx @@ -199,5 +199,5 @@ To update any settings under these keys, you must use Consul's [Update CA Config To renew the Vault token, use the [`vault token renew`](https://www.vaultproject.io/docs/commands/token/renew) CLI command or API. -[`ca_config`]: /docs/agent/options#connect_ca_config -[`ca_provider`]: /docs/agent/options#connect_ca_provider +[`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config +[`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index d721523a55..0816ac031a 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -57,7 +57,7 @@ Use these links to navigate to a particular top-level stanza. the prefix will be `-consul`. - `domain` ((#v-global-domain)) (`string: consul`) - The domain Consul will answer DNS queries for - (see `-domain` (https://consul.io/docs/agent/options#_domain)) and the domain services synced from + (see `-domain` (https://consul.io/docs/agent/config/agent-config-cli#_domain)) and the domain services synced from Consul into Kubernetes will have, e.g. `service-name.service.consul`. - `adminPartitions` ((#v-global-adminpartitions)) - Enabling `adminPartitions` allows creation of Admin Partitions in Kubernetes clusters. @@ -215,7 +215,7 @@ Use these links to navigate to a particular top-level stanza. ``` - `gossipEncryption` ((#v-global-gossipencryption)) - Configures Consul's gossip encryption key. - (see `-encrypt` (https://consul.io/docs/agent/options#_encrypt)). + (see `-encrypt` (https://consul.io/docs/agent/config/agent-config-cli#_encrypt)). By default, gossip encryption is not enabled. The gossip encryption key may be set automatically or manually. The recommended method is to automatically generate the key. To automatically generate and set a gossip encryption key, set autoGenerate to true. @@ -246,7 +246,7 @@ Use these links to navigate to a particular top-level stanza. - `recursors` ((#v-global-recursors)) (`array: []`) - A list of addresses of upstream DNS servers that are used to recursively resolve DNS queries. These values are given as `-recursor` flags to Consul servers and clients. - See https://www.consul.io/docs/agent/options#_recursor for more details. + See https://www.consul.io/docs/agent/config/agent-config-cli#_recursor for more details. If this is an empty array (the default), then Consul DNS will only resolve queries for the Consul top level domain (by default `.consul`). - `tls` ((#v-global-tls)) - Enables TLS (https://learn.hashicorp.com/tutorials/consul/tls-encryption-secure) @@ -577,7 +577,7 @@ Use these links to navigate to a particular top-level stanza. --set 'server.disruptionBudget.maxUnavailable=0'` flag to the helm chart installation command because of a limitation in the Helm templating language. - - `extraConfig` ((#v-server-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/options) for Consul + - `extraConfig` ((#v-server-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/config) for Consul servers. This will be saved as-is into a ConfigMap that is read by the Consul server agents. This can be used to add additional configuration that isn't directly exposed by the chart. @@ -778,7 +778,7 @@ Use these links to navigate to a particular top-level stanza. - `image` ((#v-client-image)) (`string: null`) - The name of the Docker image (including any tag) for the containers running Consul client agents. - - `join` ((#v-client-join)) (`array: null`) - A list of valid `-retry-join` values (https://consul.io/docs/agent/options#retry-join). + - `join` ((#v-client-join)) (`array: null`) - A list of valid `-retry-join` values (https://consul.io/docs/agent/config/agent-config-files#retry-join). If this is `null` (default), then the clients will attempt to automatically join the server cluster running within Kubernetes. This means that with `server.enabled` set to true, clients will automatically @@ -799,7 +799,7 @@ Use these links to navigate to a particular top-level stanza. required for Connect. - `nodeMeta` ((#v-client-nodemeta)) - nodeMeta specifies an arbitrary metadata key/value pair to associate with the node - (see https://www.consul.io/docs/agent/options.html#_node_meta) + (see https://www.consul.io/docs/agent/config/agent-config-cli#_node_meta) - `pod-name` ((#v-client-nodemeta-pod-name)) (`string: ${HOSTNAME}`) @@ -843,7 +843,7 @@ Use these links to navigate to a particular top-level stanza. - `tlsInit` ((#v-client-containersecuritycontext-tlsinit)) (`map`) - The tls-init initContainer - - `extraConfig` ((#v-client-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/options) for Consul + - `extraConfig` ((#v-client-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/config) for Consul clients. This will be saved as-is into a ConfigMap that is read by the Consul client agents. This can be used to add additional configuration that isn't directly exposed by the chart. @@ -1152,7 +1152,7 @@ Use these links to navigate to a particular top-level stanza. will inherit from `global.metrics.enabled` value. - `provider` ((#v-ui-metrics-provider)) (`string: prometheus`) - Provider for metrics. See - https://www.consul.io/docs/agent/options#ui_config_metrics_provider + https://www.consul.io/docs/agent/config/agent-config-files#ui_config_metrics_provider This value is only used if `ui.enabled` is set to true. - `baseURL` ((#v-ui-metrics-baseurl)) (`string: http://prometheus-server`) - baseURL is the URL of the prometheus server, usually the service URL. diff --git a/website/content/docs/k8s/index.mdx b/website/content/docs/k8s/index.mdx index e3efa8d0d8..a8811d715b 100644 --- a/website/content/docs/k8s/index.mdx +++ b/website/content/docs/k8s/index.mdx @@ -62,7 +62,7 @@ Kubernetes cluster. The server agents are run as a **StatefulSet**, using persistent volume claims to store the server state. This also ensures that the -[node ID](/docs/agent/options#_node_id) is persisted so that servers +[node ID](/docs/agent/config/agent-config-cli#_node_id) is persisted so that servers can be rescheduled onto new IP addresses without causing issues. The server agents are configured with [anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) diff --git a/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx b/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx index dd3031d0f3..f945693c73 100644 --- a/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx +++ b/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx @@ -22,7 +22,7 @@ you want the clients to be exposed on the Kubernetes internal node IPs (`true`) their pod IPs (`false`). Finally, `client.join` is set to an array of valid -[`-retry-join` values](/docs/agent/options#retry-join). In the +[`-retry-join` values](/docs/agent/config/agent-config-cli#retry-join). In the example above, a fake [cloud auto-join](/docs/agent/cloud-auto-join) value is specified. This should be set to resolve to the proper addresses of your existing Consul cluster. diff --git a/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx b/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx index c48166623d..5f10a716f2 100644 --- a/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx +++ b/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx @@ -271,8 +271,8 @@ The automatically generated federation secret contains: - **Consul server config** - This is a JSON snippet that must be used as part of the server config for secondary datacenters. It sets: - - [`primary_datacenter`](/docs/agent/options#primary_datacenter) to the name of the primary datacenter. - - [`primary_gateways`](/docs/agent/options#primary_gateways) to an array of IPs or hostnames + - [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) to the name of the primary datacenter. + - [`primary_gateways`](/docs/agent/config/agent-config-files#primary_gateways) to an array of IPs or hostnames for the mesh gateways in the primary datacenter. These are the addresses that Consul servers in secondary clusters will use to communicate with the primary datacenter. diff --git a/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx b/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx index d40bb02617..7a1adcd880 100644 --- a/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx +++ b/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx @@ -91,7 +91,7 @@ The following sections detail how to export this data. ==> Saved dc1-client-consul-0-key.pem ``` - Or use the [auto_encrypt](/docs/agent/options#auto_encrypt) feature. + Or use the [auto_encrypt](/docs/agent/config/agent-config-files#auto_encrypt) feature. ### Mesh Gateway Addresses diff --git a/website/content/docs/nia/configuration.mdx b/website/content/docs/nia/configuration.mdx index 455f01e77a..1dcf4fb3a2 100644 --- a/website/content/docs/nia/configuration.mdx +++ b/website/content/docs/nia/configuration.mdx @@ -61,7 +61,7 @@ tls { The `consul` block is used to configure Consul-Terraform-Sync connection with a Consul agent to perform queries to the Consul Catalog and Consul KV pertaining to task execution. --> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/options) must be configured for the local Consul with the [cert_file](/docs/agent/options#cert_file) and [key_file](/docs/agent/options#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. +-> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/config/agent-config-files) must be configured for the local Consul with the [cert_file](/docs/agent/config/agent-config-filess#cert_file) and [key_file](/docs/agent/config/agent-config-files#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/installation/requirements#run-an-agent). @@ -80,7 +80,7 @@ consul { - `enabled` - (bool) - `username` - (string) - `password` - (string) -- `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/options#verify_incoming). +- `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/config/agent-config-files#verify_incoming). - `enabled` - (bool) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly. - `verify` - (bool: true) Enables TLS peer verification. The default is enabled, which will check the global certificate authority (CA) chain to make sure the certificates returned by Consul are valid. - If Consul is using a self-signed certificate that you have not added to the global CA chain, you can set this certificate with `ca_cert` or `ca_path`. Alternatively, you can disable SSL verification by setting `verify` to false. However, disabling verification is a potential security vulnerability. @@ -98,7 +98,7 @@ consul { - `max_idle_conns` - (int: 0) The maximum number of total idle connections across all hosts. The limit is disabled by default. - `max_idle_conns_per_host` - (int: 100) The maximum number of idle connections per remote host. The majority of connections are established with one host, the Consul agent. - To achieve the shortest latency between a Consul service update to a task execution, configure `max_idle_conns_per_host` equal to or greater than the number of services in automation across all tasks. - - This value should be lower than the configured [`http_max_conns_per_client`](https://www.consul.io/docs/agent/options#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, Consul-Terraform-Sync may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as Consul-Terraform-Sync will contribute to the Consul agent connection limit._ + - This value should be lower than the configured [`http_max_conns_per_client`](https://www.consul.io/docs/agent/config/agent-config-files#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, Consul-Terraform-Sync may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as Consul-Terraform-Sync will contribute to the Consul agent connection limit._ - `tls_handshake_timeout` - (string: "10s") amount of time to wait to complete the TLS handshake. ## Service diff --git a/website/content/docs/nia/installation/requirements.mdx b/website/content/docs/nia/installation/requirements.mdx index 10bf027bf2..e07a644c03 100644 --- a/website/content/docs/nia/installation/requirements.mdx +++ b/website/content/docs/nia/installation/requirements.mdx @@ -35,7 +35,7 @@ The Consul agent must be running in order to dynamically update network devices. When running a Consul agent with Consul-Terraform-Sync in production, we suggest to keep a few considerations in mind. Consul-Terraform-Sync uses [blocking queries](/api/features/blocking) to monitor task dependencies, like changes to registered services. This results in multiple long running TCP connections between Consul-Terraform-Sync and the agent to poll changes for each dependency. Monitoring a high number of services may quickly hit the default Consul agent connection limits. -There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between Consul-Terraform-Sync and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync. +There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between Consul-Terraform-Sync and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync. ### Register Services diff --git a/website/content/docs/release-notes/1-9-0.mdx b/website/content/docs/release-notes/1-9-0.mdx index da06931dfd..3ce0edf024 100644 --- a/website/content/docs/release-notes/1-9-0.mdx +++ b/website/content/docs/release-notes/1-9-0.mdx @@ -21,7 +21,7 @@ page_title: 1.9.0 - **Active Health Checks for Consul on Kubernetes:** Consul service mesh now integrates with Kubernetes Readiness probes. This provides the ability to natively detect health status from Kubernetes via Readiness probe, and is then used for directing service mesh traffic. - **Streaming:** This feature introduces a major architectural enhancement in how update notifications for blocking queries are delivered within the cluster. Streaming results in very significant reduction of CPU and network bandwidth usage on Consul servers in large-scale deployments. Streaming is particularly helpful in scaling blocking queries in Consul clusters that have rapid changes in service state. - - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](https://www.consul.io/docs/agent/options#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](https://www.consul.io/docs/agent/options#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. + - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](https://www.consul.io/docs/agent/config/agent-config-files#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](https://www.consul.io/docs/agent/config/agent-config-files#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. ## What's Changed diff --git a/website/content/docs/security/acl/acl-legacy.mdx b/website/content/docs/security/acl/acl-legacy.mdx index b556ee2b00..5a4d87f6c3 100644 --- a/website/content/docs/security/acl/acl-legacy.mdx +++ b/website/content/docs/security/acl/acl-legacy.mdx @@ -89,7 +89,7 @@ and [Policies](/api/acl/policies). ~> **Warning**: In this document we use the deprecated configuration parameter `acl_datacenter`. In Consul 1.4 and newer the -parameter has been updated to [`primary_datacenter`](/docs/agent/options#primary_datacenter). +parameter has been updated to [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter). Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is @@ -129,7 +129,7 @@ token are automatically applied. The anonymous token is managed using the Tokens are bound to a set of rules that control which Consul resources the token has access to. Policies can be defined in either an allowlist or denylist mode depending on the configuration of -[`acl_default_policy`](/docs/agent/options#acl_default_policy). If the default +[`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy). If the default policy is to "deny" all actions, then token rules can be set to allowlist specific actions. In the inverse, the "allow" all default behavior is a denylist where rules are used to prohibit actions. By default, Consul will allow all actions. @@ -169,7 +169,7 @@ Constructing rules from these policies is covered in detail in the #### ACL Datacenter All nodes (clients and servers) must be configured with a -[`acl_datacenter`](/docs/agent/options#acl_datacenter) which enables ACL +[`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) which enables ACL enforcement but also specifies the authoritative datacenter. Consul relies on [RPC forwarding](/docs/internals/architecture) to support multi-datacenter configurations. However, because requests can be made across datacenter boundaries, @@ -179,14 +179,14 @@ is considered authoritative and stores the canonical set of tokens. When a request is made to an agent in a non-authoritative datacenter, it must be resolved into the appropriate policy. This is done by reading the token from the authoritative server and caching the result for a configurable -[`acl_ttl`](/docs/agent/options#acl_ttl). The implication of caching is that +[`acl_ttl`](/docs/agent/config/agent-config-files#acl_ttl). The implication of caching is that the cache TTL is an upper bound on the staleness of policy that is enforced. It is possible to set a zero TTL, but this has adverse performance impacts, as every request requires refreshing the policy via an RPC call. During an outage of the ACL datacenter, or loss of connectivity, the cache will be used as long as the TTL is valid, or the cache may be extended if the -[`acl_down_policy`](/docs/agent/options#acl_down_policy) is set accordingly. +[`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) is set accordingly. This configuration also allows the ACL system to fail open or closed. [ACL replication](#replication) is also available to allow for the full set of ACL tokens to be replicated for use during an outage. @@ -198,10 +198,10 @@ as to whether they are set on servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | --------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- | -| [`acl_datacenter`](/docs/agent/options#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | -| [`acl_default_policy`](/docs/agent/options#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | -| [`acl_down_policy`](/docs/agent/options#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | -| [`acl_ttl`](/docs/agent/options#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | +| [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | +| [`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | +| [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | +| [`acl_ttl`](/docs/agent/config/agent-config-files#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | There are some additional configuration items related to [ACL replication](#replication) and [Version 8 ACL support](#version_8_acls). These are discussed in those respective sections @@ -212,17 +212,17 @@ system, or accessing Consul in special situations: | Special Token | Servers | Clients | Purpose | | ----------------------------------------------------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | -| [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | -| [`acl_master_token`](/docs/agent/options#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | -| [`acl_token`](/docs/agent/options#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | +| [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | +| [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | +| [`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | +| [`acl_token`](/docs/agent/config/agent-config-files#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). #### ACL Agent Master Token -Since the [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): +Since the [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): ```hcl agent "" { @@ -238,7 +238,7 @@ In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via #### ACL Agent Token -The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/options#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: +The [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/config/agent-config-files#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: 1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates 2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog @@ -258,7 +258,7 @@ key "_rexec" { } ``` -The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key` policy can be omitted. +The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/agent-config-files#disable_remote_exec), the default, then the `key` policy can be omitted. In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). @@ -294,12 +294,12 @@ The servers will need to be restarted to load the new configuration. Please take to start the servers one at a time, and ensure each server has joined and is operating correctly before starting another. -The [`acl_master_token`](/docs/agent/options#acl_master_token) will be created +The [`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) will be created as a "management" type token automatically. The -[`acl_master_token`](/docs/agent/options#acl_master_token) is only installed when +[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) is only installed when a server acquires cluster leadership. If you would like to install or change the -[`acl_master_token`](/docs/agent/options#acl_master_token), set the new value for -[`acl_master_token`](/docs/agent/options#acl_master_token) in the configuration +[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token), set the new value for +[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) in the configuration for all servers. Once this is done, restart the current leader to force a leader election. In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api/acl/acl#bootstrap-acls) @@ -332,7 +332,7 @@ servers related to permission denied errors: ``` These errors are because the agent doesn't yet have a properly configured -[`acl_agent_token`](/docs/agent/options#acl_agent_token) that it can use for its +[`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) that it can use for its own internal operations like updating its node information in the catalog and performing [anti-entropy](/docs/internals/anti-entropy) syncing. We can create a token using the ACL API, and the ACL master token we set in the previous step: @@ -550,9 +550,9 @@ The next section shows an alternative to the anonymous token. #### Set Agent-Specific Default Tokens (Optional) -An alternative to the anonymous token is the [`acl_token`](/docs/agent/options#acl_token) +An alternative to the anonymous token is the [`acl_token`](/docs/agent/config/agent-config-files#acl_token) configuration item. When a request is made to a particular Consul agent and no token is -supplied, the [`acl_token`](/docs/agent/options#acl_token) will be used for the token, +supplied, the [`acl_token`](/docs/agent/config/agent-config-files#acl_token) will be used for the token, instead of being left empty which would normally invoke the anonymous token. In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the @@ -563,7 +563,7 @@ agent, if desired. For example, this allows more fine grained control of what DN given agent can service, or can give the agent read access to some key-value store prefixes by default. -If using [`acl_token`](/docs/agent/options#acl_token), then it's likely the anonymous +If using [`acl_token`](/docs/agent/config/agent-config-files#acl_token), then it's likely the anonymous token will have a more restrictive policy than shown in the examples here. #### Create Tokens for UI Use (Optional) @@ -727,7 +727,7 @@ starts with "bar". Since [Agent API](/api/agent) utility operations may be required before an agent is joined to a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be -configured with [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) to allow +configured with [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token) to allow write access to these operations even if no ACL resolution capability is available. #### Event Rules @@ -753,7 +753,7 @@ starts with "deploy". The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to give agents a token with access to this event prefix, in addition to configuring -[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`. +[`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) to `false`. #### Key/Value Rules @@ -861,13 +861,13 @@ the example above, the rules allow read-only access to any node name with the em read-write access to any node name that starts with "app", and deny all access to any node name that starts with "admin". -Agents need to be configured with an [`acl_agent_token`](/docs/agent/options#acl_agent_token) +Agents need to be configured with an [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) with at least "write" privileges to their own node name in order to register their information with the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. Consul's DNS interface is also affected by restrictions on node rules. If the -[`acl_token`](/docs/agent/options#acl_token) used by the agent does not have "read" access to a +[`acl_token`](/docs/agent/config/agent-config-files#acl_token) used by the agent does not have "read" access to a given node, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, node rules are @@ -880,7 +880,7 @@ periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require a ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl_token](/docs/agent/options#acl_token) configuration +1. Using the [acl_token](/docs/agent/config/agent-config-files#acl_token) configuration directive. This allows a single token to be configured globally and used during all check registration operations. 2. Providing an ACL token with service and check definitions at @@ -891,7 +891,7 @@ to use for registration events: [HTTP API](/api) for operations that require them. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/options#_enable_script_checks) set to `true` in order to enable +[`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) set to `true` in order to enable script checks. #### Operator Rules @@ -1025,7 +1025,7 @@ read-write access to any service name that starts with "app", and deny all acces starts with "admin". Consul's DNS interface is affected by restrictions on service rules. If the -[`acl_token`](/docs/agent/options#acl_token) used by the agent does not have "read" access to a +[`acl_token`](/docs/agent/config/agent-config-files#acl_token) used by the agent does not have "read" access to a given service, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, service rules are @@ -1037,7 +1037,7 @@ performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl_token](/docs/agent/options#acl_token) configuration +1. Using the [acl_token](/docs/agent/config/agent-config-files#acl_token) configuration directive. This allows a single token to be configured globally and used during all service and check registration operations. 2. Providing an ACL token with service and check definitions at registration @@ -1048,12 +1048,12 @@ to use for registration events: API](/api) for operations that require them. **Note:** all tokens passed to an agent are persisted on local disk to allow recovery from restarts. See [`-data-dir` flag - documentation](/docs/agent/options#acl_token) for notes on securing + documentation](/docs/agent/config/agent-config-files#acl_token) for notes on securing access. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/options#_enable_script_checks) or -[`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks) +[`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) or +[`enable_local_script_checks`](/docs/agent/config/agent-config-files#enable_local_script_checks) set to `true` in order to enable script checks. #### Session Rules @@ -1084,20 +1084,20 @@ name that starts with "admin". #### Outages and ACL Replication ((#replication)) The Consul ACL system is designed with flexible rules to accommodate for an outage -of the [`acl_datacenter`](/docs/agent/options#acl_datacenter) or networking +of the [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) or networking issues preventing access to it. In this case, it may be impossible for agents in non-authoritative datacenters to resolve tokens. Consul provides -a number of configurable [`acl_down_policy`](/docs/agent/options#acl_down_policy) +a number of configurable [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) choices to tune behavior. It is possible to deny or permit all actions or to ignore cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs for any previously resolved tokens and to deny any uncached tokens. Consul 0.7 added an ACL Replication capability that can allow non-authoritative datacenter agents to resolve even uncached tokens. This is enabled by setting an -[`acl_replication_token`](/docs/agent/options#acl_replication_token) in the +[`acl_replication_token`](/docs/agent/config/agent-config-files#acl_replication_token) in the configuration on the servers in the non-authoritative datacenters. In Consul 0.9.1 and later you can enable ACL replication using -[`enable_acl_replication`](/docs/agent/options#enable_acl_replication) and +[`enable_acl_replication`](/docs/agent/config/agent-config-files#enable_acl_replication) and then set the token later using the [agent token API](/api/agent#update-acl-tokens) on each server. This can also be used to rotate the token without restarting the Consul servers. @@ -1113,7 +1113,7 @@ every 30 seconds. Replicated changes are written at a rate that's throttled to a large set of ACLs. If there's a partition or other outage affecting the authoritative datacenter, -and the [`acl_down_policy`](/docs/agent/options#acl_down_policy) +and the [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) is set to "extend-cache", tokens will be resolved during the outage using the replicated set of ACLs. An [ACL replication status](/api/acl/acl#check-acl-replication) endpoint is available to monitor the health of the replication process. @@ -1123,7 +1123,7 @@ already cached and is expired while similar semantics than "extend-cache". It allows to avoid having issues when connectivity with the authoritative is not completely broken, but very slow. -Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options#acl_ttl) +Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/config/agent-config-files#acl_ttl) setting of the non-authoritative datacenter, so these entries may persist in the cache for up to the TTL, even after the authoritative datacenter comes back online. @@ -1149,7 +1149,7 @@ Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consu agents for the first time. To ease the transition to Consul 0.8 for existing ACL users, there's a configuration option to disable these new features. To disable support for these new ACLs, set the -[`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) configuration +[`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8) configuration option to `false` on Consul clients and servers. Here's a summary of the new features: @@ -1172,31 +1172,31 @@ Here's a summary of the new features: Two new configuration options are used once version 8 ACLs are enabled: -- [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) is used as +- [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token) is used as a special access token that has `agent` ACL policy `write` privileges on each agent where it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token should only be used by operators during outages when Consul servers aren't available to resolve ACL tokens. Applications should use regular ACL tokens during normal operation. -- [`acl_agent_token`](/docs/agent/options#acl_agent_token) is used internally by +- [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) is used internally by Consul agents to perform operations to the service catalog when registering themselves or sending network coordinates to the servers. This token must at least have `node` ACL policy `write` access to the node name it will register as in order to register any node-level information like metadata or tagged addresses. -Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/options#acl_down_policy) +Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) now applies to Consul clients as well as Consul servers. This will determine what the client will do in the event that the servers are down. -Consul clients must have [`acl_datacenter`](/docs/agent/options#acl_datacenter) configured +Consul clients must have [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) configured in order to enable agent-level ACL features. If this is set, the agents will contact the Consul servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not enabled, they will check at most every 2 minutes to see if they have become enabled, and will start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will -need to use the [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) to +need to use the [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token) to perform agent-level operations if the Consul servers aren't present (such as for a manual join -to the cluster), unless the [`acl_down_policy`](/docs/agent/options#acl_down_policy) on the +to the cluster), unless the [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) on the agent is set to "allow". Non-server agents do not need to have the -[`acl_master_token`](/docs/agent/options#acl_master_token) configured; it is not +[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) configured; it is not used by agents in any way. diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index 0d76efce7d..511f1ae9f4 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -102,7 +102,7 @@ Use the `policy` keyword and one of the following access levels to set a policy - `write`: Allows the resource to be read and modified. - `deny`: Denies read and write access to the resource. -The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/options#acl_enable_key_list_policy) setting must be set to `true`. +The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/config/agent-config-files#acl_enable_key_list_policy) setting must be set to `true`. ### Matching and Prefix Values @@ -493,7 +493,7 @@ with `bar`. Since [Agent API](/api/agent) utility operations may be required before an agent is joined to a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be -configured with [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) to allow +configured with [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) to allow write access to these operations even if no ACL resolution capability is available. ### Event Rules @@ -537,7 +537,7 @@ read-only access to any event, and firing of the "deploy" event. The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to give agents a token with access to this event prefix, in addition to configuring -[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`. +[`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) to `false`. ### Key/Value Rules @@ -869,16 +869,16 @@ node "admin" { Agents must be configured with `write` privileges for their own node name so that the agent can register their node metadata, tagged addresses, and other information in the catalog. If configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. -Configure `write` access in the [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) parameter. +Configure `write` access in the [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) parameter. -The [`acl.token.default`](/docs/agent/options#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. +The [`acl.token.default`](/docs/agent/config/agent-config-files#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. Node rules are used to filter query results when reading from the catalog or retrieving information from the health endpoints. This allows for configurations where a token has access to a given service name, but only on an allowed subset of node names. Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs. These actions may required an ACL token to complete. Use the following methods to configure ACL tokens for registration events: -* Configure a global token in the [acl.tokens.default](/docs/agent/options#acl_tokens_default) parameter. +* Configure a global token in the [acl.tokens.default](/docs/agent/config/agent-config-files#acl_tokens_default) parameter. This allows a single token to be used during all check registration operations. * Provide an ACL token with service and check definitions at registration time. This allows for greater flexibility and enables the use of multiple tokens on the same agent. @@ -1060,7 +1060,7 @@ service "admin" { Consul's DNS interface is affected by restrictions on service rules. If the -[`acl.tokens.default`](/docs/agent/options#acl_tokens_default) used by the agent does not have `read` access to a +[`acl.tokens.default`](/docs/agent/config/agent-config-files#acl_tokens_default) used by the agent does not have `read` access to a given service, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, service rules are @@ -1072,7 +1072,7 @@ performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl.tokens.default](/docs/agent/options#acl_tokens_default) configuration +1. Using the [acl.tokens.default](/docs/agent/config/agent-config-files#acl_tokens_default) configuration directive. This allows a single token to be configured globally and used during all service and check registration operations. 2. Providing an ACL token with service and check definitions at registration @@ -1083,12 +1083,12 @@ to use for registration events: API](/api) for operations that require them. **Note:** all tokens passed to an agent are persisted on local disk to allow recovery from restarts. See [`-data-dir` flag - documentation](/docs/agent/options#acl_token) for notes on securing + documentation](/docs/agent/config/agent-config-files#acl_token) for notes on securing access. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/options#_enable_script_checks) or -[`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks) +[`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) or +[`enable_local_script_checks`](/docs/agent/config/agent-config-files#enable_local_script_checks) set to `true` in order to enable script checks. Service rules are also used to grant read or write access to intentions. The diff --git a/website/content/docs/security/acl/acl-system.mdx b/website/content/docs/security/acl/acl-system.mdx index 8f951d0043..9d8babfcb1 100644 --- a/website/content/docs/security/acl/acl-system.mdx +++ b/website/content/docs/security/acl/acl-system.mdx @@ -51,7 +51,7 @@ may benefit from additional components in the ACL system: - **ACL Node Identities** - Node identities are a policy template for expressing a link to a policy suitable for use as an [Consul `agent` token - ](/docs/agent/options#acl_tokens_agent). At authorization time this acts like an + ](/docs/agent/config/agent-config-files#acl_tokens_agent). At authorization time this acts like an additional policy was attached, the contents of which are described further below. These are directly attached to tokens and roles and are not independently configured. (Added in Consul 1.8.1) @@ -174,7 +174,7 @@ examples of using a service identity. -> Added in Consul 1.8.1 An ACL node identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy -suitable for use as an [Consul `agent` token](/docs/agent/options#acl_tokens_agent). They are usable +suitable for use as an [Consul `agent` token](/docs/agent/config/agent-config-files#acl_tokens_agent). They are usable on both tokens and roles and are composed of the following elements: - **Node Name** - The name of the node to grant access to. @@ -309,7 +309,7 @@ token will be used. The rules from all policies, roles, and service identities linked with a token are combined to form that token's effective rule set. Policy rules can be defined in either an allowlist or denylist -mode depending on the configuration of [`acl_default_policy`](/docs/agent/options#acl_default_policy). +mode depending on the configuration of [`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy). If the default policy is to "deny" access to all resources, then policy rules can be set to allowlist access to specific resources. Conversely, if the default policy is “allow” then policy rules can be used to explicitly deny access to resources. @@ -358,22 +358,22 @@ as to whether they are set on servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | -------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- | -| [`acl.enabled`](/docs/agent/options#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | -| [`acl.default_policy`](/docs/agent/options#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | -| [`acl.down_policy`](/docs/agent/options#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | -| [`acl.role_ttl`](/docs/agent/options#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | -| [`acl.policy_ttl`](/docs/agent/options#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | -| [`acl.token_ttl`](/docs/agent/options#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | +| [`acl.enabled`](/docs/agent/config/agent-config-files#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | +| [`acl.default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | +| [`acl.down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | +| [`acl.role_ttl`](/docs/agent/config/agent-config-files#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | +| [`acl.policy_ttl`](/docs/agent/config/agent-config-files#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | +| [`acl.token_ttl`](/docs/agent/config/agent-config-files#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | A number of special tokens can also be configured which allow for bootstrapping the ACL system, or accessing Consul in special situations: | Special Token | Servers | Clients | Purpose | | ------------------------------------------------------------------------------------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Recovery Token](#acl-agent-recovery-token) section for more details | -| [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | -| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details | -| [`acl.tokens.default`](/docs/agent/options#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | +| [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Recovery Token](#acl-agent-recovery-token) section for more details | +| [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | +| [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details | +| [`acl.tokens.default`](/docs/agent/config/agent-config-files#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | All of these tokens except the `initial_management` token can all be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). @@ -381,12 +381,12 @@ In Consul 1.4 - 1.10, the following special tokens were known by different names | New Name (1.11+) | Old Name (1.4 - 1.10) | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | -| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) | -| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) | +| [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/config/agent-config-files#acl_tokens_agent_master) | +| [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/config/agent-config-files#acl_tokens_master) | #### ACL Agent Recovery Token -Since the [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it +Since the [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it In Consul 1.4 - 1.10, this was called the `agent_master` token. It was renamed to `agent_recovery` token in Consul 1.11. @@ -401,7 +401,7 @@ node_prefix "" { #### ACL Agent Token -The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/options#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: +The [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/config/agent-config-files#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: 1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates 2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog @@ -421,7 +421,7 @@ key_prefix "_rexec" { } ``` -The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. +The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/agent-config-files#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. ## Next Steps diff --git a/website/content/docs/security/acl/auth-methods/index.mdx b/website/content/docs/security/acl/auth-methods/index.mdx index 102e156045..4a1dd9e634 100644 --- a/website/content/docs/security/acl/auth-methods/index.mdx +++ b/website/content/docs/security/acl/auth-methods/index.mdx @@ -60,7 +60,7 @@ using the API or command line before they can be used by applications. endpoints](/api/acl/binding-rules). -> **Note** - To configure auth methods in any connected secondary datacenter, -[ACL token replication](/docs/agent/options#acl_enable_token_replication) +[ACL token replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be enabled. Auth methods require the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. diff --git a/website/content/docs/security/encryption.mdx b/website/content/docs/security/encryption.mdx index 2956d19ee2..75b2ba56c4 100644 --- a/website/content/docs/security/encryption.mdx +++ b/website/content/docs/security/encryption.mdx @@ -75,17 +75,17 @@ CA then signs keys for each of the agents, as in ~> Certificates need to be created with x509v3 extendedKeyUsage attributes for both clientAuth and serverAuth since Consul uses a single cert/key pair for both server and client communications. TLS can be used to verify the authenticity of the servers or verify the authenticity of clients. -These modes are controlled by the [`verify_outgoing`](/docs/agent/options#verify_outgoing), -[`verify_server_hostname`](/docs/agent/options#verify_server_hostname), -and [`verify_incoming`](/docs/agent/options#verify_incoming) options, respectively. +These modes are controlled by the [`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing), +[`verify_server_hostname`](/docs/agent/config/agent-config-files#verify_server_hostname), +and [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) options, respectively. -If [`verify_outgoing`](/docs/agent/options#verify_outgoing) is set, agents verify the +If [`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing) is set, agents verify the authenticity of Consul for outgoing connections. Server nodes must present a certificate signed by a common certificate authority present on all agents, set via the agent's -[`ca_file`](/docs/agent/options#ca_file) and [`ca_path`](/docs/agent/options#ca_path) -options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/options#cert_file) and [`key_file`](/docs/agent/options#key_file). +[`ca_file`](/docs/agent/config/agent-config-files#ca_file) and [`ca_path`](/docs/agent/config/agent-config-files#ca_path) +options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/config/agent-config-files#cert_file) and [`key_file`](/docs/agent/config/agent-config-files#key_file). -If [`verify_server_hostname`](/docs/agent/options#verify_server_hostname) is set, then +If [`verify_server_hostname`](/docs/agent/config/agent-config-files#verify_server_hostname) is set, then outgoing connections perform hostname verification. All servers must have a certificate valid for `server..` or the client will reject the handshake. This is a new configuration as of 0.5.1, and it is used to prevent a compromised client from being @@ -93,12 +93,12 @@ able to restart in server mode and perform a MITM (Man-In-The-Middle) attack. Ne to true, and generate the proper certificates, but this is defaulted to false to avoid breaking existing deployments. -If [`verify_incoming`](/docs/agent/options#verify_incoming) is set, the servers verify the +If [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) is set, the servers verify the authenticity of all incoming connections. All clients must have a valid key pair set using -[`cert_file`](/docs/agent/options#cert_file) and -[`key_file`](/docs/agent/options#key_file). Servers will +[`cert_file`](/docs/agent/config/agent-config-files#cert_file) and +[`key_file`](/docs/agent/config/agent-config-files#key_file). Servers will also disallow any non-TLS connections. To force clients to use TLS, -[`verify_outgoing`](/docs/agent/options#verify_outgoing) must also be set. +[`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing) must also be set. TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP and is secured using a symmetric key. See above for enabling gossip encryption. diff --git a/website/content/docs/security/security-models/core.mdx b/website/content/docs/security/security-models/core.mdx index 83ac5ade65..1a15df739d 100644 --- a/website/content/docs/security/security-models/core.mdx +++ b/website/content/docs/security/security-models/core.mdx @@ -72,28 +72,28 @@ environment and adapt these configurations accordingly. - **mTLS** - Mutual authentication of both the TLS server and client x509 certificates prevents internal abuse through unauthorized access to Consul agents within the cluster. - - [`verify_incoming`](/docs/agent/options#verify_incoming) - By default this is false, and should almost always be set + - [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) - By default this is false, and should almost always be set to true to require TLS verification for incoming client connections. This applies to both server RPC and to the HTTPS API. - - [`verify_incoming_https`](/docs/agent/options#verify_incoming_https) - By default this is false, and should be set + - [`verify_incoming_https`](/docs/agent/config/agent-config-files#verify_incoming_https) - By default this is false, and should be set to true to require clients to provide a valid TLS certificate when the Consul HTTPS API is enabled. TLS for the API may be not be necessary if it is exclusively served over a loopback interface such as `localhost`. - - [`verify_incoming_rpc`](/docs/agent/options#verify_incoming_rpc) - By default this is false, and should almost + - [`verify_incoming_rpc`](/docs/agent/config/agent-config-files#verify_incoming_rpc) - By default this is false, and should almost always be set to true to require clients to provide a valid TLS certificate for Consul agent RPCs. - - [`verify_outgoing`](/docs/agent/options#verify_outgoing) - By default this is false, and should be set to true to + - [`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing) - By default this is false, and should be set to true to require TLS for outgoing connections from server or client agents. Servers that specify `verify_outgoing = true` will always talk to other servers over TLS, but they still accept non-TLS connections to allow for a transition of all clients to TLS. Currently the only way to enforce that no client can communicate with a server unencrypted is to also enable `verify_incoming` which requires client certificates too. - - [`enable_agent_tls_for_checks`](/docs/agent/options#enable_agent_tls_for_checks) - By default this is false, and + - [`enable_agent_tls_for_checks`](/docs/agent/config/agent-config-files#enable_agent_tls_for_checks) - By default this is false, and should almost always be set to true to require mTLS to set up the client for HTTP or gRPC health checks. This was added in Consul 1.0.1. - - [`verify_server_hostname`](/docs/agent/options#verify_server_hostname) - By default this is false, and should be + - [`verify_server_hostname`](/docs/agent/config/agent-config-files#verify_server_hostname) - By default this is false, and should be set to true to require that the TLS certificate presented by the servers matches `server..` hostname for outgoing TLS connections. The default configuration does not verify the hostname of the certificate, only that it is signed by a trusted CA. This setting is critical to prevent a @@ -104,14 +104,14 @@ environment and adapt these configurations accordingly. [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) for more details. This is fixed in 1.4.1. - - [`auto_encrypt`](/docs/agent/options#auto_encrypt) - Enables automated TLS certificate distribution for client - agent RPC communication using the Connect CA. Using this configuration a [`ca_file`](/docs/agent/options#ca_file) + - [`auto_encrypt`](/docs/agent/config/agent-config-files#auto_encrypt) - Enables automated TLS certificate distribution for client + agent RPC communication using the Connect CA. Using this configuration a [`ca_file`](/docs/agent/config/agent-config-files#ca_file) and ACL token would still need to be distributed to client agents. - - [`allow_tls`](/docs/agent/options#allow_tls) - By default this is false, and should be set to true on server + - [`allow_tls`](/docs/agent/config/agent-config-files#allow_tls) - By default this is false, and should be set to true on server agents to allow certificates to be automatically generated and distributed from the Connect CA to client agents. - - [`tls`](/docs/agent/options#tls) - By default this is false, and should be set to true on client agents to + - [`tls`](/docs/agent/config/agent-config-files#tls) - By default this is false, and should be set to true on client agents to automatically request a client TLS certificate from the server's Connect CA. **Example Server Agent TLS Configuration** @@ -144,7 +144,7 @@ environment and adapt these configurations accordingly. } ``` - -> The client agent TLS configuration from above sets [`verify_incoming`](/docs/agent/options#verify_incoming) to + -> The client agent TLS configuration from above sets [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) to false which assumes all incoming traffic is restricted to `localhost`. The primary benefit for this configuration would be to avoid provisioning client TLS certificates (in addition to ACL tokens) for all tools or applications using the local Consul agent. In this case ACLs should be enabled to provide authorization and only ACL tokens would @@ -152,7 +152,7 @@ environment and adapt these configurations accordingly. - **ACLs** - The access control list (ACL) system provides a security mechanism for Consul administrators to grant capabilities tied to an individual human, or machine operator identity. To ultimately secure the ACL system, - administrators should configure the [`default_policy`](/docs/agent/options#acl_default_policy) to "deny". + administrators should configure the [`default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) to "deny". The [system](/docs/acl/acl-system) is comprised of five major components: @@ -179,10 +179,10 @@ environment and adapt these configurations accordingly. Two optional gossip encryption options enable Consul servers without gossip encryption to safely upgrade. After upgrading, the verification options should be enabled, or removed to set them to their default state: - - [`encrypt_verify_incoming`](/docs/agent/options#encrypt_verify_incoming) - By default this is true to enforce + - [`encrypt_verify_incoming`](/docs/agent/config/agent-config-files#encrypt_verify_incoming) - By default this is true to enforce encryption on _incoming_ gossip communications. - - [`encrypt_verify_outgoing`](/docs/agent/options#encrypt_verify_outgoing) - By default this is true to enforce + - [`encrypt_verify_outgoing`](/docs/agent/config/agent-config-files#encrypt_verify_outgoing) - By default this is true to enforce encryption on _outgoing_ gossip communications. - **Namespaces** - Read and write operations should be scoped to logical namespaces to @@ -223,19 +223,19 @@ environment and adapt these configurations accordingly. - **Linux Security Modules** - Use of security modules that can be directly integrated into operating systems such as AppArmor, SElinux, and Seccomp on Consul agent hosts. -- **Customize TLS Settings** - TLS settings such as the [available cipher suites](/docs/agent/options#tls_cipher_suites), +- **Customize TLS Settings** - TLS settings such as the [available cipher suites](/docs/agent/config/agent-config-files#tls_cipher_suites), should be tuned to fit the needs of your environment. - - [`tls_min_version`](/docs/agent/options#tls_min_version) - Used to specify the minimum TLS version to use. + - [`tls_min_version`](/docs/agent/config/agent-config-files#tls_min_version) - Used to specify the minimum TLS version to use. - - [`tls_cipher_suites`](/docs/agent/options#tls_cipher_suites) - Used to specify which TLS cipher suites are allowed. + - [`tls_cipher_suites`](/docs/agent/config/agent-config-files#tls_cipher_suites) - Used to specify which TLS cipher suites are allowed. - - [`tls_prefer_server_cipher_suites`](/docs/agent/options#tls_prefer_server_cipher_suites) - Used to specify which TLS + - [`tls_prefer_server_cipher_suites`](/docs/agent/config/agent-config-files#tls_prefer_server_cipher_suites) - Used to specify which TLS cipher suites are preferred on the server side. - **Customize HTTP Response Headers** - Additional security headers, such as [`X-XSS-Protection`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection), can be - [configured](https://www.consul.io/docs/agent/options#response_headers) for HTTP API responses. + [configured](https://www.consul.io/docs/agent/config/agent-config-files#response_headers) for HTTP API responses. ```hcl http_config { @@ -248,28 +248,28 @@ environment and adapt these configurations accordingly. - **Customize Default Limits** - Consul has a number of builtin features with default connection limits that should be tuned to fit your environment. - - [`http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) - Used to limit concurrent access from + - [`http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) - Used to limit concurrent access from a single client to the HTTP(S) endpoint on Consul agents. - - [`https_handshake_timeout`](/docs/agent/options#https_handshake_timeout) - Used to timeout TLS connection for the + - [`https_handshake_timeout`](/docs/agent/config/agent-config-files#https_handshake_timeout) - Used to timeout TLS connection for the HTTP(S) endpoint for Consul agents. - - [`rpc_handshake_timeout`](/docs/agent/options#rpc_handshake_timeout) - Used to timeout TLS connections for the RPC + - [`rpc_handshake_timeout`](/docs/agent/config/agent-config-files#rpc_handshake_timeout) - Used to timeout TLS connections for the RPC endpoint for Consul agents. - - [`rpc_max_conns_per_client`](/docs/agent/options#rpc_max_conns_per_client) - Used to limit concurrent access from a + - [`rpc_max_conns_per_client`](/docs/agent/config/agent-config-files#rpc_max_conns_per_client) - Used to limit concurrent access from a single client to the RPC endpoint on Consul agents. - - [`rpc_rate`](/docs/agent/options#rpc_rate) - Disabled by default, this is used to limit (requests/second) for client + - [`rpc_rate`](/docs/agent/config/agent-config-files#rpc_rate) - Disabled by default, this is used to limit (requests/second) for client agents making RPC calls to server agents. - - [`rpc_max_burst`](/docs/agent/options#rpc_max_burst) - Used as the token bucket size for client agents making RPC + - [`rpc_max_burst`](/docs/agent/config/agent-config-files#rpc_max_burst) - Used as the token bucket size for client agents making RPC calls to server agents. - - [`kv_max_value_size`](/docs/agent/options#kv_max_value_size) - Used to configure the max number of bytes in a + - [`kv_max_value_size`](/docs/agent/config/agent-config-files#kv_max_value_size) - Used to configure the max number of bytes in a key-value API request. - - [`txn_max_req_len`](/docs/agent/options#txn_max_req_len) - Used to configure the max number of bytes in a + - [`txn_max_req_len`](/docs/agent/config/agent-config-files#txn_max_req_len) - Used to configure the max number of bytes in a transaction API request. - **Secure UI Access** - Access to Consul’s builtin UI can be secured in various ways: @@ -289,7 +289,7 @@ environment and adapt these configurations accordingly. [Securing Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production), which includes a section on [creating ACL tokens that provide a desired level UI access](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#consul-ui-token). - - **Restrict HTTP Writes** - Using the [`allow_write_http_from`](/docs/agent/options#allow_write_http_from) + - **Restrict HTTP Writes** - Using the [`allow_write_http_from`](/docs/agent/config/agent-config-files#allow_write_http_from) configuration option to restrict write access for agent endpoints to hosts on the specified list of CIDRs. **Example Agent Configuration** diff --git a/website/content/docs/troubleshoot/common-errors.mdx b/website/content/docs/troubleshoot/common-errors.mdx index 3307b048b8..762d38721f 100644 --- a/website/content/docs/troubleshoot/common-errors.mdx +++ b/website/content/docs/troubleshoot/common-errors.mdx @@ -198,14 +198,14 @@ We recommend raising an issue with the CNI you're using to add support for `host and switching back to `hostPort` eventually. [troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting -[node_name]: /docs/agent/options#node_name -[retry_join]: /docs/agent/options#retry-join +[node_name]: /docs/agent/config/agent-config-files#node_name +[retry_join]: /docs/agent/config/agent-config-cli#retry-join [license]: /commands/license [releases]: https://releases.hashicorp.com/consul/ [files]: https://easyengine.io/tutorials/linux/increase-open-files-limit [certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates [systemd]: https://learn.hashicorp.com/consul/advanced/day-1-operations/deployment-guide#configure-systemd [monitoring]: https://learn.hashicorp.com/consul/advanced/day-1-operations/monitoring -[bind]: /docs/agent/options#_bind +[bind]: /docs/agent/config/agent-config-cli#_bind [jq]: https://stedolan.github.io/jq/ [go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template diff --git a/website/content/docs/troubleshoot/faq.mdx b/website/content/docs/troubleshoot/faq.mdx index 4bc63d5c8f..9ebb19b45b 100644 --- a/website/content/docs/troubleshoot/faq.mdx +++ b/website/content/docs/troubleshoot/faq.mdx @@ -62,8 +62,8 @@ messages. This anonymous ID can be disabled. In fact, using the Checkpoint service is optional and can be disabled. -See [`disable_anonymous_signature`](/docs/agent/options#disable_anonymous_signature) -and [`disable_update_check`](/docs/agent/options#disable_update_check). +See [`disable_anonymous_signature`](/docs/agent/config/agent-config-files#disable_anonymous_signature) +and [`disable_update_check`](/docs/agent/config/agent-config-files#disable_update_check). ### Q: Does Consul rely on UDP Broadcast or Multicast? @@ -116,7 +116,7 @@ as well as race conditions between data updates and watch registrations. ### Q: What network ports does Consul use? -The [Ports Used](/docs/agent/options#ports) section of the Configuration +The [Ports Used](/docs/agent/config/agent-config-files#ports) section of the Configuration documentation lists all ports that Consul uses. ### Q: Does Consul require certain user process resource limits? @@ -143,7 +143,7 @@ of any excessive resource utilization before arbitrarily increasing the limits. The default recommended limit on a key's value size is 512KB. This is strictly enforced and an HTTP 413 status will be returned to any client that attempts to store more than that limit in a value. The limit can be increased by using the -[`kv_max_value_size`](/docs/agent/options#kv_max_value_size) configuration option. +[`kv_max_value_size`](/docs/agent/config/agent-config-files#kv_max_value_size) configuration option. It should be noted that the Consul key/value store is not designed to be used as a general purpose database. See diff --git a/website/content/docs/upgrading/instructions/general-process.mdx b/website/content/docs/upgrading/instructions/general-process.mdx index c18e361f1e..c559058aa2 100644 --- a/website/content/docs/upgrading/instructions/general-process.mdx +++ b/website/content/docs/upgrading/instructions/general-process.mdx @@ -74,7 +74,7 @@ this snapshot somewhere safe. More documentation on snapshot usage is available - https://www.consul.io/commands/snapshot - https://learn.hashicorp.com/tutorials/consul/backup-and-restore -**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options.html#_log_level) +**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/config/agent-config-cli#_log_level) is set to `debug`. After doing this, issue the following command on your servers to reload the configuration: @@ -183,7 +183,7 @@ then the following options for further assistance are available: When contacting Hashicorp Support, please include the following information in your ticket: - Consul version you were upgrading FROM and TO. -- [Debug level logs](/docs/agent/options.html#_log_level) from all servers in the cluster +- [Debug level logs](/docs/agent/config/agent-config-cli#_log_level) from all servers in the cluster that you are having trouble with. These should include logs from prior to the upgrade attempt up through the current time. If your logs were not set at debug level prior to the upgrade, please include those logs as well. Also, update your config to use debug logs, diff --git a/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx b/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx index 5251b5968e..e83820459d 100644 --- a/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx +++ b/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx @@ -20,7 +20,7 @@ Here is some documentation that may prove useful for reference during this upgra - [ACL System in Legacy Mode](https://www.consul.io/docs/acl/acl-legacy) - You can find information about legacy configuration options and differences between modes here. -- [Configuration](https://www.consul.io/docs/agent/options) - You can find more details +- [Configuration](https://www.consul.io/docs/agent/config) - You can find more details around legacy ACL and new ACL configuration options here. Legacy ACL config options will be listed as deprecates as of 1.4.0. @@ -51,7 +51,7 @@ Looking through these changes prior to upgrading is highly recommended. Two very notable items are: - 1.6.2 introduced more strict JSON decoding. Invalid JSON that was previously ignored might result in errors now (e.g., `Connect: null` in service definitions). See [[GH#6680](https://github.com/hashicorp/consul/pull/6680)]. -- 1.6.3 introduced the [http_max_conns_per_client](https://www.consul.io/docs/agent/options.html#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] +- 1.6.3 introduced the [http_max_conns_per_client](https://www.consul.io/docs/agent/config/agent-config-files.html#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] ## Procedure @@ -202,8 +202,8 @@ update those now to avoid issues when moving to newer versions. These are the changes you will need to make: -- `acl_datacenter` is now named `primary_datacenter` (review our [docs](https://www.consul.io/docs/agent/options#primary_datacenter) for more info) -- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](https://www.consul.io/docs/agent/options#acl) for more info): +- `acl_datacenter` is now named `primary_datacenter` (review our [docs](https://www.consul.io/docs/agent/config/agent-config-files#primary_datacenter) for more info) +- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](https://www.consul.io/docs/agent/config/agent-config-files#acl) for more info): ```hcl acl { enabled = true/false diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 757c1d73fd..32fb884c24 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -42,7 +42,7 @@ Due to this rename the following endpoint is also deprecated: These config keys are now deprecated: - `audit.sink[].name` - - [`dns_config.dns_prefer_namespace`](/docs/agent/options#dns_prefer_namespace) + - [`dns_config.dns_prefer_namespace`](/docs/agent/config/agent-config-files#dns_prefer_namespace) ### Deprecated CLI Subcommands @@ -107,8 +107,8 @@ have a license loaded from a configuration file or from their environment the sa agents must have the license specified. Both agents can still perform automatic retrieval of their license but with a few extra stipulations. First, license auto-retrieval now requires that ACLs are on and that the client or snapshot agent is configured with a valid ACL token. Secondly, client -agents require that either the [`start_join`](/docs/agent/options#start_join) or -[`retry_join`](/docs/agent/options#retry_join) configurations are set and that they resolve to server +agents require that either the [`start_join`](/docs/agent/config/agent-config-files#start_join) or +[`retry_join`](/docs/agent/config/agent-config-files#retry_join) configurations are set and that they resolve to server agents. If those stipulations are not met, attempting to start the client or snapshot agent will result in it immediately shutting down. @@ -202,7 +202,7 @@ to Consul 1.9.0. ### Changes to Configuration Defaults -The [`enable_central_service_config`](/docs/agent/options#enable_central_service_config) +The [`enable_central_service_config`](/docs/agent/config/agent-config-files#enable_central_service_config) configuration now defaults to `true`. ### Changes to Intentions @@ -271,7 +271,7 @@ behavior: #### Removal of Deprecated Features -The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) +The [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8) configuration has been removed (with version 8 ACL support by being on by default). @@ -314,7 +314,7 @@ to more precisely capture the view of _active_ blocking queries. ### Vault: default `http_max_conns_per_client` too low to run Vault properly -Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/options#http_max_conns_per_client). The default value +Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/config/agent-config-files#http_max_conns_per_client). The default value was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.7.0, you should change the value to 200. Starting with Consul 1.7.1 this is the new default. @@ -322,7 +322,7 @@ Starting with Consul 1.7.1 this is the new default. ### Vault: default `http_max_conns_per_client` too low to run Vault properly -Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/options#http_max_conns_per_client). The default value +Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/config/agent-config-files#http_max_conns_per_client). The default value was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.6.3 through 1.7.0, you should change the value to 200. Starting with Consul 1.7.1 this is the new default. @@ -361,7 +361,7 @@ datacenter". All configuration is backwards compatible and shouldn't need to change prior to upgrade although it's strongly recommended to migrate ACL configuration to the new syntax soon after upgrade. This includes moving to `primary_datacenter` rather than `acl_datacenter` and `acl_*` to the new [ACL -block](/docs/agent/options#acl). +block](/docs/agent/config/agent-config-files#acl). Datacenters can be upgraded in any order although secondaries will remain in [Legacy ACL mode](#legacy-acl-mode) until the primary datacenter is fully @@ -488,11 +488,11 @@ The following previously deprecated fields and config options have been removed: Consul 1.0.1 (and earlier versions of Consul) checked for raft snapshots every 5 seconds, and created new snapshots for every 8192 writes. These defaults cause constant disk IO in large busy clusters. Consul 1.1.0 increases these to larger values, -and makes them tunable via the [raft_snapshot_interval](/docs/agent/options#_raft_snapshot_interval) and -[raft_snapshot_threshold](/docs/agent/options#_raft_snapshot_threshold) parameters. We recommend +and makes them tunable via the [raft_snapshot_interval](/docs/agent/config/agent-config-files#_raft_snapshot_interval) and +[raft_snapshot_threshold](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) parameters. We recommend keeping the new defaults. However, operators can go back to the old defaults by changing their -config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/options#_raft_snapshot_interval) -and [raft_snapshot_threshold](/docs/agent/options#_raft_snapshot_threshold) to understand the trade-offs +config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/config/agent-config-files#_raft_snapshot_interval) +and [raft_snapshot_threshold](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) to understand the trade-offs when tuning these. ## Consul 1.0.7 @@ -520,7 +520,7 @@ before proceeding. #### Carefully Check and Remove Stale Servers During Rolling Upgrades Consul 1.0 (and earlier versions of Consul when running with [Raft protocol -3](/docs/agent/options#_raft_protocol) had an issue where performing +3](/docs/agent/config/agent-config-files#_raft_protocol) had an issue where performing rolling updates of Consul servers could result in an outage from old servers remaining in the cluster. [Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) @@ -541,7 +541,7 @@ Please be sure to read over all the details here before upgrading. #### Raft Protocol Now Defaults to 3 -The [`-raft-protocol`](/docs/agent/options#_raft_protocol) default has +The [`-raft-protocol`](/docs/agent/config/agent-config-cli#_raft_protocol) default has been changed from 2 to 3, enabling all [Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) features by default. @@ -570,7 +570,7 @@ servers, and then slowly stand down each of the older servers in a similar fashion. When using Raft protocol version 3, servers are identified by their -[`-node-id`](/docs/agent/options#_node_id) instead of their IP address +[`-node-id`](/docs/agent/config/agent-config-cli#_node_id) instead of their IP address when Consul makes changes to its internal Raft quorum configuration. This means that once a cluster has been upgraded with servers all running Raft protocol version 3, it will no longer allow servers running any older Raft protocol @@ -585,7 +585,7 @@ to map the server to its node ID in the Raft quorum configuration. As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format for Consul's config files, an `.hcl` or `.json` extension is required for all config files loaded by Consul, even when using the -[`-config-file`](/docs/agent/options#_config_file) argument to specify a +[`-config-file`](/docs/agent/config/agent-config-cli#_config_file) argument to specify a file directly. #### Service Definition Parameter Case changed @@ -602,30 +602,30 @@ upgrading. Here's the complete list of removed options and their equivalents: | Removed Option | Equivalent | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-dc` | [`-datacenter`](/docs/agent/options#_datacenter) | -| `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/options#_retry_join) | +| `-dc` | [`-datacenter`](/docs/agent/config/agent-config-cli#_datacenter) | +| `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | | `addresses.rpc` | None, the RPC server for CLI commands is no longer supported. | -| `advertise_addrs` | [`ports`](/docs/agent/options#ports) with [`advertise_addr`](/docs/agent/options#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/options#advertise_addr_wan) | -| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/options#telemetry-dogstatsd_addr) | -| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/options#telemetry-dogstatsd_tags) | -| `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/options#response_headers) | +| `advertise_addrs` | [`ports`](/docs/agent/config/agent-config-files#ports) with [`advertise_addr`](/docs/agent/config/agent-config-files#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/config/agent-config-files#advertise_addr_wan) | +| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/config/agent-config-files#telemetry-dogstatsd_addr) | +| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/config/agent-config-files#telemetry-dogstatsd_tags) | +| `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/config/agent-config-files#response_headers) | | `ports.rpc` | None, the RPC server for CLI commands is no longer supported. | -| `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/options.mdx#recursors) | -| `retry_join_azure` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `retry_join_ec2` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `retry_join_gce` | [`-retry-join`](/docs/agent/options#_retry_join) | -| `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/options.mdx#telemetry-statsd_address) | -| `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/options.mdx#telemetry-statsite_address) | -| `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/options#telemetry-metrics_prefix) | -| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/options#telemetry-metrics_prefix) | +| `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/agent-config-files.mdx#recursors) | +| `retry_join_azure` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `retry_join_ec2` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `retry_join_gce` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/agent-config-files.mdx#telemetry-statsd_address) | +| `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/agent-config-files.mdx#telemetry-statsite_address) | +| `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix) | +| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix) | | (service definitions) `serviceid` | [`service_id`](/docs/agent/services) | | (service definitions) `dockercontainerid` | [`docker_container_id`](/docs/agent/services) | | (service definitions) `tlsskipverify` | [`tls_skip_verify`](/docs/agent/services) | @@ -635,7 +635,7 @@ upgrading. Here's the complete list of removed options and their equivalents: Since the `statsite_prefix` configuration option applied to all telemetry providers, `statsite_prefix` was renamed to -[`metrics_prefix`](/docs/agent/options#telemetry-metrics_prefix). +[`metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix). Configuration files will need to be updated when upgrading to this version of Consul. @@ -647,8 +647,8 @@ wrongly stated that you could configure both host and port. #### Escaping Behavior Changed for go-discover Configs -The format for [`-retry-join`](/docs/agent/options#retry-join) and -[`-retry-join-wan`](/docs/agent/options#retry-join-wan) values that use +The format for [`-retry-join`](/docs/agent/config/agent-config-cli#retry-join) and +[`-retry-join-wan`](/docs/agent/config/agent-config-cli#retry-join-wan) values that use [go-discover](https://github.com/hashicorp/go-discover) cloud auto joining has changed. Values in `key=val` sequences must no longer be URL encoded and can be provided as literals as long as they do not contain spaces, backslashes `\` or @@ -766,7 +766,7 @@ invalid health checks would get skipped. #### Script Checks Are Now Opt-In -A new [`enable_script_checks`](/docs/agent/options#_enable_script_checks) +A new [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks) configuration option was added, and defaults to `false`, meaning that in order to allow an agent to run health checks that execute scripts, this will need to be configured and set to `true`. This provides a safer out-of-the-box @@ -788,10 +788,10 @@ for more information. Consul releases will no longer include a `web_ui.zip` file with the compiled web assets. These have been built in to the Consul binary since the 0.7.x -series and can be enabled with the [`-ui`](/docs/agent/options#_ui) +series and can be enabled with the [`-ui`](/docs/agent/config/agent-config-cli#_ui) configuration option. These built-in web assets have always been identical to the contents of the `web_ui.zip` file for each release. The -[`-ui-dir`](/docs/agent/options#_ui_dir) option is still available for +[`-ui-dir`](/docs/agent/config/agent-config-cli#_ui_dir) option is still available for hosting customized versions of the web assets, but the vast majority of Consul users can just use the built in web assets. @@ -823,12 +823,12 @@ to the following commands: #### Version 8 ACLs Are Now Opt-Out -The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) +The [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8) configuration now defaults to `true` to enable full version 8 ACL support by default. If you are upgrading an existing cluster with ACLs enabled, you will need to set this to `false` during the upgrade on **both Consul agents and Consul servers**. Version 8 ACLs were also changed so that -[`acl_datacenter`](/docs/agent/options#acl_datacenter) must be set on +[`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) must be set on agents in order to enable the agent-side enforcement of ACLs. This makes for a smoother experience in clusters where ACLs aren't enabled at all, but where the agents would have to wait to contact a Consul server before learning that. @@ -836,14 +836,14 @@ agents would have to wait to contact a Consul server before learning that. #### Remote Exec Is Now Opt-In The default for -[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) was +[`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) was changed to "true", so now operators need to opt-in to having agents support running commands remotely via [`consul exec`](/commands/exec). #### Raft Protocol Version Compatibility When upgrading to Consul 0.8.0 from a version lower than 0.7.0, users will need -to set the [`-raft-protocol`](/docs/agent/options#_raft_protocol) option +to set the [`-raft-protocol`](/docs/agent/config/agent-config-cli#_raft_protocol) option to 1 in order to maintain backwards compatibility with the old servers during the upgrade. After the servers have been migrated to version 0.8.0, `-raft-protocol` can be moved up to 2 and the servers restarted to match the @@ -878,7 +878,7 @@ process to reap child processes. #### DNS Resiliency Defaults -The default for [`max_stale`](/docs/agent/options#max_stale) has been +The default for [`max_stale`](/docs/agent/config/agent-config-files#max_stale) has been increased from 5 seconds to a near-indefinite threshold (10 years) to allow DNS queries to continue to be served in the event of a long outage with no leader. A new telemetry counter was added at `consul.dns.stale_queries` to track when @@ -892,7 +892,7 @@ to be aware of during an upgrade are categorized below. #### Performance Timing Defaults and Tuning Consul 0.7 now defaults the DNS configuration to allow for stale queries by -defaulting [`allow_stale`](/docs/agent/options#allow_stale) to true for +defaulting [`allow_stale`](/docs/agent/config/agent-config-files#allow_stale) to true for better utilization of available servers. If you want to retain the previous behavior, set the following configuration: @@ -905,7 +905,7 @@ behavior, set the following configuration: ``` Consul also 0.7 introduced support for tuning Raft performance using a new -[performance configuration block](/docs/agent/options#performance). Also, +[performance configuration block](/docs/agent/config/agent-config-files#performance). Also, the default Raft timing is set to a lower-performance mode suitable for [minimal Consul servers](/docs/install/performance#minimum). @@ -925,8 +925,8 @@ See the [Server Performance](/docs/install/performance) guide for more details. #### Leave-Related Configuration Defaults -The default behavior of [`leave_on_terminate`](/docs/agent/options#leave_on_terminate) -and [`skip_leave_on_interrupt`](/docs/agent/options#skip_leave_on_interrupt) +The default behavior of [`leave_on_terminate`](/docs/agent/config/agent-config-files#leave_on_terminate) +and [`skip_leave_on_interrupt`](/docs/agent/config/agent-config-files#skip_leave_on_interrupt) are now dependent on whether or not the agent is acting as a server or client: - For servers, `leave_on_terminate` defaults to "false" and `skip_leave_on_interrupt` @@ -965,7 +965,7 @@ using this feature. #### WAN Address Translation in HTTP Endpoints Consul version 0.7 added support for translating WAN addresses in certain -[HTTP endpoints](/docs/agent/options#translate_wan_addrs). The servers +[HTTP endpoints](/docs/agent/config/agent-config-files#translate_wan_addrs). The servers and the agents need to be running version 0.7 or later in order to use this feature. @@ -1047,7 +1047,7 @@ which require it: } When the DNS interface is queried, the agent's -[`acl_token`](/docs/agent/options#acl_token) is used, so be sure +[`acl_token`](/docs/agent/config/agent-config-files#acl_token) is used, so be sure that token has sufficient privileges to return the DNS records you expect to retrieve from it. diff --git a/website/content/partials/http_api_options_client.mdx b/website/content/partials/http_api_options_client.mdx index 890253a614..516579bba6 100644 --- a/website/content/partials/http_api_options_client.mdx +++ b/website/content/partials/http_api_options_client.mdx @@ -20,7 +20,7 @@ used instead. The scheme can also be set to HTTPS by setting the environment variable `CONSUL_HTTP_SSL=true`. This may be a unix domain socket using `unix:///path/to/socket` if the [agent is configured to - listen](/docs/agent/options#addresses) that way. + listen](/docs/agent/config/agent-config-files#addresses) that way. - `-tls-server-name=` - The server name to use as the SNI host when connecting via TLS. This can also be specified via the `CONSUL_TLS_SERVER_NAME` From 7e4c43f45dd251151268243707a8e20cad5b909e Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 17:16:24 -0800 Subject: [PATCH 07/10] chore: rebase updates --- website/content/docs/agent/config/agent-config-cli.mdx | 2 +- website/content/docs/agent/config/agent-config-files.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/agent-config-cli.mdx index 82d6608034..df4a096f6a 100644 --- a/website/content/docs/agent/config/agent-config-cli.mdx +++ b/website/content/docs/agent/config/agent-config-cli.mdx @@ -7,7 +7,7 @@ description: >- # Command-line Options ((#commandline_options)) --> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](#config_key_reference) for equivalent HCL Keys. +-> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/docs/agent/config/agent-config-files#config_key_reference) for equivalent HCL Keys. The options below are all specified on the command-line. diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx index 08a9f43980..78b9184533 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/agent-config-files.mdx @@ -43,7 +43,7 @@ definitions support being updated during a reload. } ``` -# Configuration Key Reference +# Configuration Key Reference ((#config_key_reference)) -> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following [formatting specification](https://golang.org/pkg/time/#ParseDuration): "A From 448f50c45925adde6e7ae106ce2cd53677167e24 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 17:26:47 -0800 Subject: [PATCH 08/10] docs: pr feedback --- website/content/docs/agent/config/agent-config-cli.mdx | 6 +++++- website/content/docs/agent/config/agent-config-files.mdx | 6 ++++-- website/redirects.next.js | 5 +++++ 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/agent-config-cli.mdx index df4a096f6a..0272dda5df 100644 --- a/website/content/docs/agent/config/agent-config-cli.mdx +++ b/website/content/docs/agent/config/agent-config-cli.mdx @@ -9,7 +9,11 @@ description: >- -> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/docs/agent/config/agent-config-files#config_key_reference) for equivalent HCL Keys. -The options below are all specified on the command-line. +This topic describes the available command-line options for the Consul agent. + +## Usage + +See [Agent Overview](/docs/agent#starting-the-consul-agent) for examples of how to use flags with the `consul agent` CLI. ## Environment Variables diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/agent-config-files.mdx index 78b9184533..9b21fbd148 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/agent-config-files.mdx @@ -7,8 +7,10 @@ description: >- # Configuration Files ((#configuration_files)) -In addition to the command-line options, configuration can be put into -files. This may be easier in certain situations, for example when Consul is +You can create one or more files to configure the Consul agent on startup. We recommend +grouping similar configurations into separate files, such as ACL parameters, to make it +easier to manage configuration changes. Using external files may be easier than +configuring agents on the command-line when Consul is being configured using a configuration management system. The configuration files are JSON formatted, making them easily readable diff --git a/website/redirects.next.js b/website/redirects.next.js index 525ab50775..002bc51208 100644 --- a/website/redirects.next.js +++ b/website/redirects.next.js @@ -1272,4 +1272,9 @@ module.exports = [ destination: '/docs/k8s/operations/tls-on-existing-cluster', permanent: true, }, + { + source: '/docs/agent/options', + destination: '/docs/agent/config', + permanent: true, + }, ] From 24c67f2dfad51e81425014380adb5f4c9cd43448 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 17:30:50 -0800 Subject: [PATCH 09/10] docs: simplify agent docs slugs --- .../network-areas/README.md | 2 +- docs/config/README.md | 4 +- docs/config/checklist-adding-config-fields.md | 4 +- docs/rpc/README.md | 2 +- website/content/api-docs/acl/index.mdx | 10 +- website/content/api-docs/agent/index.mdx | 18 +-- website/content/api-docs/config.mdx | 2 +- .../content/api-docs/connect/intentions.mdx | 2 +- website/content/api-docs/health.mdx | 2 +- website/content/api-docs/index.mdx | 4 +- .../content/api-docs/operator/autopilot.mdx | 2 +- .../content/commands/acl/set-agent-token.mdx | 2 +- website/content/commands/config/index.mdx | 2 +- website/content/commands/connect/envoy.mdx | 2 +- website/content/commands/debug.mdx | 2 +- website/content/commands/index.mdx | 2 +- .../content/commands/operator/autopilot.mdx | 4 +- website/content/commands/validate.mdx | 2 +- website/content/docs/agent/config-entries.mdx | 4 +- .../{agent-config-cli.mdx => cli-flags.mdx} | 12 +- ...gent-config-files.mdx => config-files.mdx} | 96 +++++++-------- website/content/docs/agent/config/index.mdx | 22 ++-- website/content/docs/agent/index.mdx | 28 ++--- website/content/docs/agent/telemetry.mdx | 20 ++-- website/content/docs/connect/ca/aws.mdx | 6 +- website/content/docs/connect/ca/consul.mdx | 2 +- website/content/docs/connect/ca/index.mdx | 2 +- website/content/docs/connect/ca/vault.mdx | 4 +- .../config-entries/exported-services.mdx | 2 +- .../docs/connect/config-entries/index.mdx | 2 +- .../connect/config-entries/proxy-defaults.mdx | 4 +- .../config-entries/service-defaults.mdx | 4 +- .../config-entries/service-intentions.mdx | 4 +- .../content/docs/connect/configuration.mdx | 14 +-- .../docs/connect/connect-internals.mdx | 4 +- .../docs/connect/gateways/ingress-gateway.mdx | 4 +- ...service-to-service-traffic-datacenters.mdx | 10 +- .../service-to-service-traffic-partitions.mdx | 4 +- .../wan-federation-via-mesh-gateways.mdx | 2 +- .../connect/gateways/terminating-gateway.mdx | 4 +- .../docs/connect/intentions-legacy.mdx | 2 +- website/content/docs/connect/intentions.mdx | 2 +- .../docs/connect/observability/index.mdx | 6 +- .../observability/ui-visualization.mdx | 14 +-- .../content/docs/connect/proxies/built-in.mdx | 2 +- .../content/docs/connect/proxies/envoy.mdx | 2 +- .../connect/proxies/managed-deprecated.mdx | 4 +- .../registration/service-registration.mdx | 4 +- .../connect/registration/sidecar-service.mdx | 2 +- website/content/docs/discovery/checks.mdx | 10 +- website/content/docs/discovery/dns.mdx | 24 ++-- .../content/docs/dynamic-app-config/kv.mdx | 4 +- .../docs/dynamic-app-config/watches.mdx | 2 +- .../content/docs/ecs/get-started/install.mdx | 2 +- .../content/docs/enterprise/audit-logging.mdx | 4 +- .../docs/enterprise/license/overview.mdx | 8 +- .../docs/enterprise/network-segments.mdx | 32 ++--- .../content/docs/enterprise/read-scale.mdx | 2 +- .../content/docs/install/bootstrapping.mdx | 14 +-- .../content/docs/install/cloud-auto-join.mdx | 4 +- .../content/docs/install/manual-bootstrap.mdx | 2 +- website/content/docs/install/performance.mdx | 20 ++-- website/content/docs/install/ports.mdx | 2 +- .../docs/k8s/connect/connect-ca-provider.mdx | 4 +- website/content/docs/k8s/helm.mdx | 12 +- website/content/docs/k8s/index.mdx | 2 +- .../servers-outside-kubernetes.mdx | 2 +- .../installation/multi-cluster/kubernetes.mdx | 4 +- .../multi-cluster/vms-and-kubernetes.mdx | 2 +- website/content/docs/nia/configuration.mdx | 6 +- .../docs/nia/installation/requirements.mdx | 2 +- website/content/docs/release-notes/1-9-0.mdx | 2 +- .../content/docs/security/acl/acl-legacy.mdx | 98 ++++++++-------- .../content/docs/security/acl/acl-rules.mdx | 22 ++-- .../content/docs/security/acl/acl-system.mdx | 36 +++--- .../docs/security/acl/auth-methods/index.mdx | 2 +- website/content/docs/security/encryption.mdx | 22 ++-- .../docs/security/security-models/core.mdx | 56 ++++----- .../docs/troubleshoot/common-errors.mdx | 6 +- website/content/docs/troubleshoot/faq.mdx | 8 +- .../instructions/general-process.mdx | 4 +- .../instructions/upgrade-to-1-6-x.mdx | 6 +- .../docs/upgrading/upgrade-specific.mdx | 110 +++++++++--------- .../partials/http_api_options_client.mdx | 2 +- website/data/docs-nav-data.json | 4 +- 85 files changed, 451 insertions(+), 451 deletions(-) rename website/content/docs/agent/config/{agent-config-cli.mdx => cli-flags.mdx} (96%) rename website/content/docs/agent/config/{agent-config-files.mdx => config-files.mdx} (97%) diff --git a/docs/cluster-federation/network-areas/README.md b/docs/cluster-federation/network-areas/README.md index efe10aa069..08a2014d53 100644 --- a/docs/cluster-federation/network-areas/README.md +++ b/docs/cluster-federation/network-areas/README.md @@ -35,7 +35,7 @@ Every Consul Enterprise server maintains a reconciliation routine where every 30 Joining a network area pool involves: 1. Setting memberlist and Serf configuration. - * Prior to Consul `v1.8.11` and `v1.9.5`, network areas were configured with memberlist's [DefaultWANConfig](https://github.com/hashicorp/memberlist/blob/838073fef1a4e1f6cb702a57a8075304098b1c31/config.go#L315). This was then updated to instead use the server's [gossip_wan](https://www.consul.io/docs/agent/config/agent-config-files#gossip_wan) configuration, which falls back to the DefaultWANConfig if it was not specified. + * Prior to Consul `v1.8.11` and `v1.9.5`, network areas were configured with memberlist's [DefaultWANConfig](https://github.com/hashicorp/memberlist/blob/838073fef1a4e1f6cb702a57a8075304098b1c31/config.go#L315). This was then updated to instead use the server's [gossip_wan](https://www.consul.io/docs/agent/config/config-files#gossip_wan) configuration, which falls back to the DefaultWANConfig if it was not specified. * As of Consul `v1.8.11`/`v1.9.5` it is not possible to tune gossip communication on a per-area basis. 2. Update the server's gossip network, which keeps track of network areas that the server is a part of. This gossip network is also used to dispatch incoming **gossip** connections to handlers for the appropriate area. diff --git a/docs/config/README.md b/docs/config/README.md index fe38011b9b..98cd35ee83 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -13,7 +13,7 @@ See also the [checklist for adding a new field] to the configuration. [Agent Configuration]: https://www.consul.io/docs/agent/config [checklist for adding a new field]: ./checklist-adding-config-fields.md [Auto-Config]: #auto-config -[Config Entries]: https://www.consul.io/docs/agent/config/agent-config-files#config_entries +[Config Entries]: https://www.consul.io/docs/agent/config/config-files#config_entries [Services]: https://www.consul.io/docs/discovery/services [Checks]: https://www.consul.io/docs/discovery/checks @@ -53,6 +53,6 @@ implemented in a couple packages. * the server RPC endpoint is in [agent/consul/auto_config_endpoint.go] * the client that receives and applies the config is implemented in [agent/auto-config] -[auto_config]: https://www.consul.io/docs/agent/config/agent-config-files#auto_config +[auto_config]: https://www.consul.io/docs/agent/config/config-files#auto_config [agent/consul/auto_config_endpoint.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/auto_config_endpoint.go [agent/auto-config]: https://github.com/hashicorp/consul/tree/main/agent/auto-config diff --git a/docs/config/checklist-adding-config-fields.md b/docs/config/checklist-adding-config-fields.md index 66807c0721..e171394115 100644 --- a/docs/config/checklist-adding-config-fields.md +++ b/docs/config/checklist-adding-config-fields.md @@ -55,7 +55,7 @@ There are four specific cases covered with increasing complexity: state for client agent's RPC client. - [ ] Add a test to `agent/agent_test.go` similar to others with prefix `TestAgent_reloadConfig*`. - - [ ] Add documentation to `website/content/docs/agent/config/agent-config-files.mdx`. + - [ ] Add documentation to `website/content/docs/agent/config/config-files.mdx`. Done! You can now use your new field in a client agent by accessing `s.agent.Config.`. @@ -75,7 +75,7 @@ If the config field also needs a CLI flag, then follow these steps. `TestLoad_IntegrationWithFlags` in `agent/config/runtime_test.go` to ensure setting the flag works. - [ ] Add flag (as well as config file) documentation to - `website/source/docs/agent/config/agent-config-files.mdx` and `website/source/docs/agent/config/agent-config-cli.mdx`. + `website/source/docs/agent/config/config-files.mdx` and `website/source/docs/agent/config/cli-flags.mdx`. ## Adding a Simple Config Field for Servers Consul servers have a separate Config struct for reasons. Note that Consul diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 7d8a75cad2..4e9adbacf0 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -22,7 +22,7 @@ The "RPC Server" accepts requests to the [server port] and routes the requests b configuration of the Server and the the first byte in the request. The diagram below shows all the possible routing flows. -[server port]: https://www.consul.io/docs/agent/config/agent-config-files#server_rpc_port +[server port]: https://www.consul.io/docs/agent/config/config-files#server_rpc_port ![RPC Routing](./routing.svg) diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx index ee663be92e..06067f9eb6 100644 --- a/website/content/api-docs/acl/index.mdx +++ b/website/content/api-docs/acl/index.mdx @@ -16,7 +16,7 @@ the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-s ## Bootstrap ACLs This endpoint does a special one-time bootstrap of the ACL system, making the first -management token if the [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management) +management token if the [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management) configuration entry is not specified in the Consul server configuration and if the cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all Consul servers to be upgraded in order to operate. @@ -141,7 +141,7 @@ $ curl \ - `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being replicated from and will match the - [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) configuration. + [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) configuration. - `ReplicationType` - The type of replication that is currently in use. @@ -289,7 +289,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be +replication](/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. @@ -415,7 +415,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be +replication](/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. @@ -495,7 +495,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) must be +replication](/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. diff --git a/website/content/api-docs/agent/index.mdx b/website/content/api-docs/agent/index.mdx index 6ed7603896..d027b69296 100644 --- a/website/content/api-docs/agent/index.mdx +++ b/website/content/api-docs/agent/index.mdx @@ -432,7 +432,7 @@ page. In order to enable [Prometheus](https://prometheus.io/) support, you need to use the configuration directive -[`prometheus_retention_time`](/docs/agent/config/agent-config-files#telemetry-prometheus_retention_time). +[`prometheus_retention_time`](/docs/agent/config/config-files#telemetry-prometheus_retention_time). Since Consul 1.7.2 this endpoint will also automatically switch output format if the request contains an `Accept` header with a compatible MIME type such as @@ -731,7 +731,7 @@ $ curl \ This endpoint updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens will be persisted -only if the [`acl.enable_token_persistence`](/docs/agent/config/agent-config-files#acl_enable_token_persistence) +only if the [`acl.enable_token_persistence`](/docs/agent/config/config-files#acl_enable_token_persistence) configuration is `true`. When not being persisted, they will need to be reset if the agent is restarted. @@ -743,9 +743,9 @@ is restarted. | `PUT` | `/agent/token/replication` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`default`](/docs/agent/config/agent-config-files#acl_tokens_default), [`agent`](/docs/agent/config/agent-config-files#acl_tokens_agent), -[`agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery), and -[`replication`](/docs/agent/config/agent-config-files#acl_tokens_replication). +[`default`](/docs/agent/config/config-files#acl_tokens_default), [`agent`](/docs/agent/config/config-files#acl_tokens_agent), +[`agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery), and +[`replication`](/docs/agent/config/config-files#acl_tokens_replication). -> **Deprecation Note:** The following paths were deprecated in version 1.11 @@ -754,7 +754,7 @@ The paths above correspond to the token names as found in the agent configuratio | `PUT` | `/agent/token/agent_master` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`agent_master`](/docs/agent/config/agent-config-files#acl_tokens_agent_master). +[`agent_master`](/docs/agent/config/config-files#acl_tokens_agent_master). -> **Deprecation Note:** The following paths were deprecated in version 1.4.3 @@ -766,9 +766,9 @@ The paths above correspond to the token names as found in the agent configuratio | `PUT` | `/agent/token/acl_replication_token` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`acl_token`](/docs/agent/config/agent-config-files#acl_token_legacy), [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token_legacy), -[`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy), and -[`acl_replication_token`](/docs/agent/config/agent-config-files#acl_replication_token_legacy). +[`acl_token`](/docs/agent/config/config-files#acl_token_legacy), [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token_legacy), +[`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token_legacy), and +[`acl_replication_token`](/docs/agent/config/config-files#acl_replication_token_legacy). The table below shows this endpoint's support for [blocking queries](/api/features/blocking), diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx index 96303beab6..e35d6ffe84 100644 --- a/website/content/api-docs/config.mdx +++ b/website/content/api-docs/config.mdx @@ -10,7 +10,7 @@ description: |- The `/config` endpoints create, update, delete and query central configuration entries registered with Consul. See the -[agent configuration](/docs/agent/config/agent-config-files#enable_central_service_config) +[agent configuration](/docs/agent/config/config-files#enable_central_service_config) for more information on how to enable this functionality for centrally configuring services and [configuration entries docs](/docs/agent/config-entries) for a description of the configuration entries content. diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index bc7652548e..2c29cc4e0d 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -94,7 +94,7 @@ The table below shows this endpoint's support for evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default intention behavior is defined by the default [ACL - policy](/docs/agent/config/agent-config-files#acl_default_policy). + policy](/docs/agent/config/config-files#acl_default_policy). This should be omitted for an L4 intention as it is mutually exclusive with the `Action` field. diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index 602e991ae7..b12fd3ad98 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -235,7 +235,7 @@ The table below shows this endpoint's support for ascending order based on the estimated round trip time from that node. Passing `?near=_agent` will use the agent's node for the sort. This is specified as part of the URL as a query parameter. **Note** that using `near` will ignore - [`use_streaming_backend`](/docs/agent/config/agent-config-files#use_streaming_backend) and always + [`use_streaming_backend`](/docs/agent/config/config-files#use_streaming_backend) and always use blocking queries, because the data required to sort the results is not available to the streaming backend. diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index 5810d50c76..f4ea4507f3 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -79,7 +79,7 @@ $ curl \ Consul 0.7 added the ability to translate addresses in HTTP response based on the configuration setting for -[`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs). In order +[`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs). In order to allow clients to know if address translation is in effect, the `X-Consul-Translate-Addresses` header will be added if translation is enabled, and will have a value of `true`. If translation is not enabled then this header @@ -90,7 +90,7 @@ will not be present. All API responses for Consul versions after 1.9 will include an HTTP response header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which mirrors the current value of the agent's -[`acl.default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) option. +[`acl.default_policy`](/docs/agent/config/config-files#acl_default_policy) option. This is also the default [intention](/docs/connect/intentions) enforcement action if no intention matches. diff --git a/website/content/api-docs/operator/autopilot.mdx b/website/content/api-docs/operator/autopilot.mdx index a3a1f9923b..4e6a56b405 100644 --- a/website/content/api-docs/operator/autopilot.mdx +++ b/website/content/api-docs/operator/autopilot.mdx @@ -67,7 +67,7 @@ $ curl \ ``` For more information about the Autopilot configuration options, see the -[agent configuration section](/docs/agent/config/agent-config-files#autopilot). +[agent configuration section](/docs/agent/config/config-files#autopilot). ## Update Configuration diff --git a/website/content/commands/acl/set-agent-token.mdx b/website/content/commands/acl/set-agent-token.mdx index fca77f61c4..af54f32d92 100644 --- a/website/content/commands/acl/set-agent-token.mdx +++ b/website/content/commands/acl/set-agent-token.mdx @@ -10,7 +10,7 @@ Command: `consul acl set-agent-token` This command updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens are not persisted unless -[`acl.enable_token_persistence`](/docs/agent/config/agent-config-files#acl_enable_token_persistence) +[`acl.enable_token_persistence`](/docs/agent/config/config-files#acl_enable_token_persistence) is `true`, so tokens will need to be updated again if that option is `false` and the agent is restarted. diff --git a/website/content/commands/config/index.mdx b/website/content/commands/config/index.mdx index 5b22e51153..891e1ffcec 100644 --- a/website/content/commands/config/index.mdx +++ b/website/content/commands/config/index.mdx @@ -10,7 +10,7 @@ Command: `consul config` The `config` command is used to interact with Consul's central configuration system. It exposes commands for creating, updating, reading, and deleting different kinds of config entries. See the -[agent configuration](/docs/agent/config/agent-config-files#enable_central_service_config) +[agent configuration](/docs/agent/config/config-files#enable_central_service_config) for more information on how to enable this functionality for centrally configuring services and [configuration entries docs](/docs/agent/config-entries) for a description of the configuration entries content. diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index 4c8b701ac6..d35ebd3868 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -42,7 +42,7 @@ proxy configuration needed. be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using `unix:///path/to/socket` if the [agent is configured to - listen](/docs/agent/config/agent-config-files#addresses) that way. + listen](/docs/agent/config/config-files#addresses) that way. -> **Note:** gRPC uses the same TLS settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS diff --git a/website/content/commands/debug.mdx b/website/content/commands/debug.mdx index 23ff3d0da9..0e7b16e826 100644 --- a/website/content/commands/debug.mdx +++ b/website/content/commands/debug.mdx @@ -78,7 +78,7 @@ information when `debug` is running. By default, it captures all information. | `members` | A list of all the WAN and LAN members in the cluster. | | `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. | | `logs` | `DEBUG` level logs for the target agent, captured for the duration. | -| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/config/agent-config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. | +| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/config/config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. | ## Examples diff --git a/website/content/commands/index.mdx b/website/content/commands/index.mdx index eb225022d6..724163ab70 100644 --- a/website/content/commands/index.mdx +++ b/website/content/commands/index.mdx @@ -226,7 +226,7 @@ CONSUL_TLS_SERVER_NAME=consulserver.domain Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the local agent is listening for gRPC requests. Currently gRPC is only used for integrating [Envoy proxy](/docs/connect/proxies/envoy) and must be [enabled -explicitly](/docs/agent/config/agent-config-files#grpc_port) in agent configuration. +explicitly](/docs/agent/config/config-files#grpc_port) in agent configuration. ``` CONSUL_GRPC_ADDR=127.0.0.1:8502 diff --git a/website/content/commands/operator/autopilot.mdx b/website/content/commands/operator/autopilot.mdx index 26a3cdb7b9..d8d334d29a 100644 --- a/website/content/commands/operator/autopilot.mdx +++ b/website/content/commands/operator/autopilot.mdx @@ -84,10 +84,10 @@ Usage: `consul operator autopilot set-config [options]` - `-disable-upgrade-migration` - Controls whether Consul will avoid promoting new servers until it can perform a migration. Must be one of `[true|false]`. -- `-redundancy-zone-tag` - Controls the [`-node-meta`](/docs/agent/config/agent-config-cli#_node_meta) +- `-redundancy-zone-tag` - Controls the [`-node-meta`](/docs/agent/config/cli-flags#_node_meta) key name used for separating servers into different redundancy zones. -- `-upgrade-version-tag` - Controls the [`-node-meta`](/docs/agent/config/agent-config-cli#_node_meta) +- `-upgrade-version-tag` - Controls the [`-node-meta`](/docs/agent/config/cli-flags#_node_meta) tag to use for version info when performing upgrade migrations. If left blank, the Consul version will be used. ### Command Output diff --git a/website/content/commands/validate.mdx b/website/content/commands/validate.mdx index ade1339282..abdb0657f4 100644 --- a/website/content/commands/validate.mdx +++ b/website/content/commands/validate.mdx @@ -21,7 +21,7 @@ to be loaded by the agent. This command cannot operate on partial configuration fragments since those won't pass the full agent validation. For more information on the format of Consul's configuration files, read the -consul agent [Configuration Files](/docs/agent/config/agent-config-files) +consul agent [Configuration Files](/docs/agent/config/config-files) section. ## Usage diff --git a/website/content/docs/agent/config-entries.mdx b/website/content/docs/agent/config-entries.mdx index 6548dd6496..18e0c8c928 100644 --- a/website/content/docs/agent/config-entries.mdx +++ b/website/content/docs/agent/config-entries.mdx @@ -52,7 +52,7 @@ Configuration entries outside of Kubernetes should be managed with the Consul [CLI](/commands/config) or [API](/api/config). Additionally, as a convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's -[configuration files](/docs/agent/config/agent-config-files#config_entries_bootstrap) +[configuration files](/docs/agent/config/config-files#config_entries_bootstrap) ### Managing Configuration Entries with the CLI @@ -156,7 +156,7 @@ api ### Bootstrapping From A Configuration File Configuration entries can be bootstrapped by adding them [inline to each Consul -server's configuration file](/docs/agent/config/agent-config-files#config_entries). When a +server's configuration file](/docs/agent/config/config-files#config_entries). When a server gains leadership, it will attempt to initialize the configuration entries. If a configuration entry does not already exist outside of the servers configuration, then it will create it. If a configuration entry does exist, that diff --git a/website/content/docs/agent/config/agent-config-cli.mdx b/website/content/docs/agent/config/cli-flags.mdx similarity index 96% rename from website/content/docs/agent/config/agent-config-cli.mdx rename to website/content/docs/agent/config/cli-flags.mdx index 0272dda5df..3b97a76b0d 100644 --- a/website/content/docs/agent/config/agent-config-cli.mdx +++ b/website/content/docs/agent/config/cli-flags.mdx @@ -7,7 +7,7 @@ description: >- # Command-line Options ((#commandline_options)) --> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/docs/agent/config/agent-config-files#config_key_reference) for equivalent HCL Keys. +-> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/docs/agent/config/config-files#config_key_reference) for equivalent HCL Keys. This topic describes the available command-line options for the Consul agent. @@ -30,7 +30,7 @@ information. limit of 4k for maximum size of checks, this is a positive value. By limiting this size, it allows to put less pressure on Consul servers when many checks are having a very large output in their checks. In order to completely disable check output - capture, it is possible to use [`discard_check_output`](/docs/agent/config/agent-config-files#discard_check_output). + capture, it is possible to use [`discard_check_output`](/docs/agent/config/config-files#discard_check_output). - `-client` ((#\_client)) - The address to which Consul will bind client interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", @@ -126,7 +126,7 @@ information. - `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version of the Raft consensus protocol used for server communications. This must be set - to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](/docs/agent/config/agent-config-files#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details. + to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](/docs/agent/config/config-files#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details. - `-segment` ((#\_segment)) - This flag is used to set the name of the network segment the agent belongs to. An agent can only join and @@ -150,13 +150,13 @@ information. - `-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`](/docs/agent/config/agent-config-files#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address + This can also be set on client agents when used in combination with the [`translate_wan_addrs`](/docs/agent/config/config-files#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`](/docs/agent/config/agent-config-files#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] + accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. ## Address Bind Options @@ -294,7 +294,7 @@ information. If Consul is running on the non-default Serf LAN port, the port must be specified in the join address, or configured as the agent's default Serf port - using the [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port) configuration option or + using the [`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port) configuration option or [`-serf-lan-port`](#_serf_lan_port) command line flag. If using network segments (Enterprise), see [additional documentation on diff --git a/website/content/docs/agent/config/agent-config-files.mdx b/website/content/docs/agent/config/config-files.mdx similarity index 97% rename from website/content/docs/agent/config/agent-config-files.mdx rename to website/content/docs/agent/config/config-files.mdx index 9b21fbd148..88cdc17808 100644 --- a/website/content/docs/agent/config/agent-config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -82,7 +82,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `https` - The HTTPS API. Defaults to `client_addr` - `grpc` - The gRPC API. Defaults to `client_addr` -- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](/docs/agent/config/agent-config-cli#_alt_domain) +- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](/docs/agent/config/cli-flags#_alt_domain) - `audit` - 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). @@ -209,7 +209,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `server_addresses` (Defaults to `[]`) This specifies the addresses of servers in the local datacenter to use for the initial RPC. These addresses support - [Cloud Auto-Joining](/docs/agent/config/agent-config-cli#cloud-auto-joining) and can optionally include a port to + [Cloud Auto-Joining](/docs/agent/config/cli-flags#cloud-auto-joining) and can optionally include a port to use when making the outbound connection. If not port is provided the `server_port` will be used. @@ -312,7 +312,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `partition` - The admin partition name the client is requesting. -- `bind_addr` Equivalent to the [`-bind` command-line flag](/docs/agent/config/agent-config-cli#_bind). +- `bind_addr` Equivalent to the [`-bind` command-line flag](/docs/agent/config/cli-flags#_bind). This parameter can be set to a go-sockaddr template that resolves to a single address. Special characters such as backslashes `\` or double quotes `"` @@ -360,7 +360,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr changes state, the new state and associated output is synchronized immediately. To disable this behavior, set the value to "0s". -- `client_addr` Equivalent to the [`-client` command-line flag](/docs/agent/config/agent-config-cli#_client). +- `client_addr` Equivalent to the [`-client` command-line flag](/docs/agent/config/cli-flags#_client). - `config_entries` This object allows setting options for centralized config entries. @@ -374,9 +374,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr See the [configuration entry docs](/docs/agent/config-entries) for more details about the contents of each entry. -- `datacenter` Equivalent to the [`-datacenter` command-line flag](/docs/agent/config/agent-config-cli#_datacenter). +- `datacenter` Equivalent to the [`-datacenter` command-line flag](/docs/agent/config/cli-flags#_datacenter). -- `data_dir` Equivalent to the [`-data-dir` command-line flag](/docs/agent/config/agent-config-cli#_data_dir). +- `data_dir` Equivalent to the [`-data-dir` command-line flag](/docs/agent/config/cli-flags#_data_dir). - `disable_anonymous_signature` Disables providing an anonymous signature for de-duplication with the update check. See [`disable_update_check`](#disable_update_check). @@ -406,17 +406,17 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `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](/docs/agent/config/agent-config-cli#_enable_script_checks). +- `enable_script_checks` Equivalent to the [`-enable-script-checks` command-line flag](/docs/agent/config/cli-flags#_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](/docs/agent/config/agent-config-cli#_enable_local_script_checks). +- `enable_local_script_checks` Equivalent to the [`-enable-local-script-checks` command-line flag](/docs/agent/config/cli-flags#_enable_local_script_checks). - `disable_keyring_file` - Equivalent to the - [`-disable-keyring-file` command-line flag](/docs/agent/config/agent-config-cli#_disable_keyring_file). + [`-disable-keyring-file` command-line flag](/docs/agent/config/cli-flags#_disable_keyring_file). - `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). When network coordinates are disabled the `near` query param will not work to sort the nodes, @@ -476,9 +476,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `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. -- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](/docs/agent/config/agent-config-cli#_default_query_time). +- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](/docs/agent/config/cli-flags#_default_query_time). -- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](/docs/agent/config/agent-config-cli#_max_query_time). +- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](/docs/agent/config/cli-flags#_max_query_time). - `partition` - This flag is used to set the name of the admin partition the agent belongs to. An agent can only join @@ -559,7 +559,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr enforcement of ACLs. - `primary_gateways` Equivalent to the [`-primary-gateway` - command-line flag](/docs/agent/config/agent-config-cli#_primary_gateway). Takes a list of addresses to use as the + command-line flag](/docs/agent/config/cli-flags#_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 @@ -570,7 +570,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 30s. This was added in Consul 1.8.0. - `protocol` ((#protocol)) Equivalent to the [`-protocol` command-line - flag](/docs/agent/config/agent-config-cli#_protocol). + flag](/docs/agent/config/cli-flags#_protocol). - `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 @@ -612,7 +612,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr servers in all federated datacenters must have this enabled before any client can use [`use_streaming_backend`](#use_streaming_backend). -- `segment` - Equivalent to the [`-segment` command-line flag](/docs/agent/config/agent-config-cli#_segment). +- `segment` - Equivalent to the [`-segment` command-line flag](/docs/agent/config/cli-flags#_segment). ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. @@ -635,11 +635,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr port. Only valid if the segment's bind address differs from the [`-bind`](#_bind) address. Defaults to false. -- `server` Equivalent to the [`-server` command-line flag](/docs/agent/config/agent-config-cli#_server). +- `server` Equivalent to the [`-server` command-line flag](/docs/agent/config/cli-flags#_server). - `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** -- `read_replica` - Equivalent to the [`-read-replica` command-line flag](/docs/agent/config/agent-config-cli#_read_replica). +- `read_replica` - Equivalent to the [`-read-replica` command-line flag](/docs/agent/config/cli-flags#_read_replica). - `session_ttl_min` 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 @@ -907,7 +907,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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/config/agent-config-files#acl_down_policy) is set to "extend-cache", tokens not + [`acl_down_policy`](/docs/agent/config/config-files#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 @@ -937,13 +937,13 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Advertise Address Parameters -- `advertise_addr` Equivalent to the [`-advertise` command-line flag](/docs/agent/config/agent-config-cli#_advertise). +- `advertise_addr` Equivalent to the [`-advertise` command-line flag](/docs/agent/config/cli-flags#_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](/docs/agent/config/agent-config-cli#_advertise-wan). +- `advertise_addr_wan` Equivalent to the [`-advertise-wan` command-line flag](/docs/agent/config/cli-flags#_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. @@ -956,9 +956,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Bootstrap Parameters -- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](/docs/agent/config/agent-config-cli#_bootstrap). +- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](/docs/agent/config/cli-flags#_bootstrap). -- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](/docs/agent/config/agent-config-cli#_bootstrap_expect). +- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](/docs/agent/config/cli-flags#_bootstrap_expect). ## Connect Parameters @@ -1230,7 +1230,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr 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](/docs/agent/config/agent-config-cli#_domain). +- `domain` Equivalent to the [`-domain` command-line flag](/docs/agent/config/cli-flags#_domain). ## Encryption Parameters @@ -1273,7 +1273,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr the certificates requested by `auto_encrypt` from the server have these `ip_san` set as IP SAN. -- `encrypt` Equivalent to the [`-encrypt` command-line flag](/docs/agent/config/agent-config-cli#_encrypt). +- `encrypt` Equivalent to the [`-encrypt` command-line flag](/docs/agent/config/cli-flags#_encrypt). - `encrypt_verify_incoming` - This is an optional parameter that can be used to disable enforcing encryption for incoming gossip @@ -1375,15 +1375,15 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Join Parameters -- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](/docs/agent/config/agent-config-cli#_rejoin). +- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](/docs/agent/config/cli-flags#_rejoin). -- `retry_join` - Equivalent to the [`-retry-join`](/docs/agent/config/agent-config-cli#retry-join) command-line flag. +- `retry_join` - Equivalent to the [`-retry-join`](/docs/agent/config/cli-flags#retry-join) command-line flag. -- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](/docs/agent/config/agent-config-cli#_retry_interval). +- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](/docs/agent/config/cli-flags#_retry_interval). -- `retry_join_wan` Equivalent to the [`-retry-join-wan` command-line flag](/docs/agent/config/agent-config-cli#_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_join_wan` Equivalent to the [`-retry-join-wan` command-line flag](/docs/agent/config/cli-flags#_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](/docs/agent/config/agent-config-cli#_retry_interval_wan). +- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](/docs/agent/config/cli-flags#_retry_interval_wan). - `start_join` An array of strings specifying addresses of nodes to [`-join`](#_join) upon startup. Note that using @@ -1395,19 +1395,19 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Log Parameters -- `log_file` Equivalent to the [`-log-file` command-line flag](/docs/agent/config/agent-config-cli#_log_file). +- `log_file` Equivalent to the [`-log-file` command-line flag](/docs/agent/config/cli-flags#_log_file). -- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](/docs/agent/config/agent-config-cli#_log_rotate_duration). +- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](/docs/agent/config/cli-flags#_log_rotate_duration). -- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](/docs/agent/config/agent-config-cli#_log_rotate_bytes). +- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](/docs/agent/config/cli-flags#_log_rotate_bytes). -- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](/docs/agent/config/agent-config-cli#_log_rotate_max_files). +- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](/docs/agent/config/cli-flags#_log_rotate_max_files). -- `log_level` Equivalent to the [`-log-level` command-line flag](/docs/agent/config/agent-config-cli#_log_level). +- `log_level` Equivalent to the [`-log-level` command-line flag](/docs/agent/config/cli-flags#_log_level). -- `log_json` Equivalent to the [`-log-json` command-line flag](/docs/agent/config/agent-config-cli#_log_json). +- `log_json` Equivalent to the [`-log-json` command-line flag](/docs/agent/config/cli-flags#_log_json). -- `enable_syslog` Equivalent to the [`-syslog` command-line flag](/docs/agent/config/agent-config-cli#_syslog). +- `enable_syslog` Equivalent to the [`-syslog` command-line flag](/docs/agent/config/cli-flags#_syslog). - `syslog_facility` When [`enable_syslog`](#enable_syslog) is provided, this controls to which facility messages are sent. By default, `LOCAL0` @@ -1415,11 +1415,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Node Parameters -- `node_id` Equivalent to the [`-node-id` command-line flag](/docs/agent/config/agent-config-cli#_node_id). +- `node_id` Equivalent to the [`-node-id` command-line flag](/docs/agent/config/cli-flags#_node_id). -- `node_name` Equivalent to the [`-node` command-line flag](/docs/agent/config/agent-config-cli#_node). +- `node_name` Equivalent to the [`-node` command-line flag](/docs/agent/config/cli-flags#_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](/docs/agent/config/agent-config-cli#_node_meta) for more information. +- `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](/docs/agent/config/cli-flags#_node_meta) for more information. ```json { @@ -1429,7 +1429,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr } ``` -- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/docs/agent/config/agent-config-cli#_disable_host_node_id). +- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/docs/agent/config/cli-flags#_disable_host_node_id). ## Raft Parameters @@ -1444,7 +1444,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `raft_protocol` ((#raft_protocol)) Equivalent to the [`-raft-protocol` - command-line flag](/docs/agent/config/agent-config-cli#_raft_protocol). + command-line flag](/docs/agent/config/cli-flags#_raft_protocol). - `raft_snapshot_threshold` ((#\_raft_snapshot_threshold)) This controls the minimum number of raft commit entries between snapshots that are saved to @@ -1493,14 +1493,14 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Serf Parameters -- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](/docs/agent/config/agent-config-cli#_serf_lan_bind). +- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](/docs/agent/config/cli-flags#_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](/docs/agent/config/agent-config-cli#_serf_lan_allowed_cidrs). +- `serf_lan_allowed_cidrs` ((#serf_lan_allowed_cidrs)) Equivalent to the [`-serf-lan-allowed-cidrs` command-line flag](/docs/agent/config/cli-flags#_serf_lan_allowed_cidrs). -- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](/docs/agent/config/agent-config-cli#_serf_wan_bind). +- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](/docs/agent/config/cli-flags#_serf_wan_bind). -- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](/docs/agent/config/agent-config-cli#_serf_wan_allowed_cidrs). +- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](/docs/agent/config/cli-flags#_serf_wan_allowed_cidrs). ## Telemetry Paramters @@ -1639,7 +1639,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## UI Parameters - `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** - Equivalent to the [`-ui`](/docs/agent/config/agent-config-cli#_ui) command-line flag. + Equivalent to the [`-ui`](/docs/agent/config/cli-flags#_ui) command-line flag. - `ui_config` - This object allows a number of sub-keys to be set which controls the display or features available in the UI. Configuring the UI with this @@ -1650,12 +1650,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `enabled` ((#ui_config_enabled)) - This enables the service of the web UI from this agent. Boolean value, defaults to false. In `-dev` mode this defaults to true. Replaces `ui` from before 1.9.0. Equivalent to the - [`-ui`](/docs/agent/config/agent-config-cli#_ui) command-line flag. + [`-ui`](/docs/agent/config/cli-flags#_ui) command-line flag. - `dir` ((#ui_config_dir)) - This specifies that the web UI should be served from an external dir rather than the build in one. This allows for customization or development. Replaces `ui_dir` from before 1.9.0. - Equivalent to the [`-ui-dir`](/docs/agent/config/agent-config-cli#_ui_dir) command-line flag. + Equivalent to the [`-ui-dir`](/docs/agent/config/cli-flags#_ui_dir) command-line flag. - `content_path` ((#ui_config_content_path)) - This specifies the HTTP path that the web UI should be served from. Defaults to `/ui/`. Equivalent to the @@ -1764,7 +1764,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `{{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`](/docs/agent/config/agent-config-cli#_ui_dir) command-line + Equivalent to the [`-ui-dir`](/docs/agent/config/cli-flags#_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. diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx index 7928be877c..1ef04e168e 100644 --- a/website/content/docs/agent/config/index.mdx +++ b/website/content/docs/agent/config/index.mdx @@ -16,8 +16,8 @@ descriptions. Configuration precedence is evaluated in the following order: -1. [Command line arguments](/docs/agent/config/agent-config-cli) -2. [Configuration files](/docs/agent/config/agent-config-files) +1. [Command line arguments](/docs/agent/config/cli-flags) +2. [Configuration files](/docs/agent/config/config-files) When loading configuration, Consul loads the configuration from files and directories in lexical order. For example, configuration file @@ -57,22 +57,22 @@ Reloading configuration does not reload all configuration items. The items which are reloaded include: - ACL Tokens -- [Configuration Entry Bootstrap](/docs/agent/config/agent-config-files#config_entries_bootstrap) +- [Configuration Entry Bootstrap](/docs/agent/config/config-files#config_entries_bootstrap) - Checks -- [Discard Check Output](/docs/agent/config/agent-config-files#discard_check_output) +- [Discard Check Output](/docs/agent/config/config-files#discard_check_output) - HTTP Client Address - Log level -- [Metric Prefix Filter](/docs/agent/config/agent-config-files#telemetry-prefix_filter) -- [Node Metadata](/docs/agent/config/agent-config-files#node_meta) +- [Metric Prefix Filter](/docs/agent/config/config-files#telemetry-prefix_filter) +- [Node Metadata](/docs/agent/config/config-files#node_meta) - Some Raft options (since Consul 1.10.0) - - [`raft_snapshot_threshold`](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) - - [`raft_snapshot_interval`](/docs/agent/config/agent-config-files#_raft_snapshot_interval) - - [`raft_trailing_logs`](/docs/agent/config/agent-config-files#_raft_trailing_logs) + - [`raft_snapshot_threshold`](/docs/agent/config/config-files#_raft_snapshot_threshold) + - [`raft_snapshot_interval`](/docs/agent/config/config-files#_raft_snapshot_interval) + - [`raft_trailing_logs`](/docs/agent/config/config-files#_raft_trailing_logs) - 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. -- [RPC rate limiting](/docs/agent/config/agent-config-files#limits) -- [HTTP Maximum Connections per Client](/docs/agent/config/agent-config-files#http_max_conns_per_client) +- [RPC rate limiting](/docs/agent/config/config-files#limits) +- [HTTP Maximum Connections per Client](/docs/agent/config/config-files#http_max_conns_per_client) - 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. diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index 09d396bde0..1099ab593d 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -127,16 +127,16 @@ $ consul agent -data-dir=/tmp/consul - **Node name**: This is a unique name for the agent. By default, this is the hostname of the machine, but you may customize it using the - [`-node`](/docs/agent/config/agent-config-cli#_node) flag. + [`-node`](/docs/agent/config/cli-flags#_node) flag. - **Datacenter**: This is the datacenter in which the agent is configured to - run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/config/agent-config-cli#_datacenter) flag. + run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/config/cli-flags#_datacenter) flag. Consul has first-class support for multiple datacenters, but configuring each node to report its datacenter improves agent efficiency. - **Server**: This indicates whether the agent is running in server or client mode. Running an agent in server mode requires additional overhead. This is because they participate in the consensus quorum, store cluster state, and handle queries. A server may also be - in ["bootstrap"](/docs/agent/config/agent-config-cli#_bootstrap_expect) mode, which enables the server to elect itselft as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. + in ["bootstrap"](/docs/agent/config/cli-flags#_bootstrap_expect) mode, which enables the server to elect itselft as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. - **Client Addr**: This is the address used for client interfaces to the agent. This includes the ports for the HTTP and DNS interfaces. By default, this @@ -179,18 +179,18 @@ The following settings are commonly used in the configuration file (also called | Parameter | Description | Default | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `node_name` | String value that specifies a name for the agent node.
See [`-node-id`](/docs/agent/config/agent-config-cli#_node_id) for details. | Hostname of the machine | -| `server` | Boolean value that determines if the agent runs in server mode.
See [`-server`](/docs/agent/config/agent-config-cli#_server) for details. | `false` | -| `datacenter` | String value that specifies which datacenter the agent runs in.
See [-datacenter](/docs/agent/config/agent-config-cli#_datacenter) for details. | `dc1` | -| `data_dir` | String value that specifies a directory for storing agent state data.
See [`-data-dir`](/docs/agent/config/agent-config-cli#_data_dir) for details. | none | -| `log_level` | String value that specifies the level of logging the agent reports.
See [`-log-level`](/docs/agent/config/agent-config-cli#_log_level) for details. | `info` | -| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member.
See [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) for details. | none | -| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/config/agent-config-files#addresses) | -| `ports` | Block of nested objects that define ports bound to agent addresses.
See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/config/agent-config-files#ports) | +| `node_name` | String value that specifies a name for the agent node.
See [`-node-id`](/docs/agent/config/cli-flags#_node_id) for details. | Hostname of the machine | +| `server` | Boolean value that determines if the agent runs in server mode.
See [`-server`](/docs/agent/config/cli-flags#_server) for details. | `false` | +| `datacenter` | String value that specifies which datacenter the agent runs in.
See [-datacenter](/docs/agent/config/cli-flags#_datacenter) for details. | `dc1` | +| `data_dir` | String value that specifies a directory for storing agent state data.
See [`-data-dir`](/docs/agent/config/cli-flags#_data_dir) for details. | none | +| `log_level` | String value that specifies the level of logging the agent reports.
See [`-log-level`](/docs/agent/config/cli-flags#_log_level) for details. | `info` | +| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member.
See [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) for details. | none | +| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/config/config-files#addresses) | +| `ports` | Block of nested objects that define ports bound to agent addresses.
See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/config/config-files#ports) | ### Server Node in a Service Mesh -The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/config/agent-config-cli#_bootstrap) and the Consul GUI is enabled. +The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/config/cli-flags#_bootstrap) and the Consul GUI is enabled. The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/docs/connect) for details. @@ -399,6 +399,6 @@ may not be important for your use case. For example, for a web server and load balancer setup, both result in the same outcome: the web node is removed from the load balancer pool. -The [`skip_leave_on_interrupt`](/docs/agent/config/agent-config-files#skip_leave_on_interrupt) and -[`leave_on_terminate`](/docs/agent/config/agent-config-files#leave_on_terminate) configuration +The [`skip_leave_on_interrupt`](/docs/agent/config/config-files#skip_leave_on_interrupt) and +[`leave_on_terminate`](/docs/agent/config/config-files#leave_on_terminate) configuration options allow you to adjust this behavior. diff --git a/website/content/docs/agent/telemetry.mdx b/website/content/docs/agent/telemetry.mdx index 634583e213..e0d751686d 100644 --- a/website/content/docs/agent/telemetry.mdx +++ b/website/content/docs/agent/telemetry.mdx @@ -29,7 +29,7 @@ This telemetry information can be used for debugging or otherwise getting a better view of what Consul is doing. Review the [Monitoring and Metrics tutorial](https://learn.hashicorp.com/tutorials/consul/monitor-datacenter-health?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data. -Additionally, if the [`telemetry` configuration options](/docs/agent/config/agent-config-files#telemetry) +Additionally, if the [`telemetry` configuration options](/docs/agent/config/config-files#telemetry) are provided, the telemetry information will be streamed to a [statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where it can be aggregated and flushed to Graphite or any other metrics store. @@ -138,7 +138,7 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference() | Metric Name | Description | Unit | Type | | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server | requests | counter | -| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/agent-config-files#limits) configuration. | requests | counter | +| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/config-files#limits) configuration. | requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | **Why they're important:** These measurements indicate the current load created from a Consul agent, including when the load becomes high enough to be rate limited. A high RPC count, especially from `consul.client.rpcexceeded` meaning that the requests are being rate-limited, could imply a misconfigured Consul agent. @@ -170,7 +170,7 @@ Under these conditions, a follower after a restart may be unable to catch up on replication and become a voter again since it takes longer to restore from disk or the leader than the leader takes to write a new snapshot and truncate its logs. Servers retain -[`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) (default +[`raft_trailing_logs`](/docs/agent/config/config-files#raft_trailing_logs) (default `10240`) log entries even if their snapshot was more recent. On a leader processing 500 commits/second, that is only about 20 seconds worth of logs. Assuming the leader is able to write out a snapshot and truncate the logs in @@ -195,7 +195,7 @@ repeatedly as well as reduce the fault tolerance and serving capacity of the cluster. Since Consul 1.5.3 -[`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) has been +[`raft_trailing_logs`](/docs/agent/config/config-files#raft_trailing_logs) has been configurable. Increasing it allows the leader to retain more logs and give followers more time to restore and catch up. The tradeoff is potentially slower appends which eventually might affect write throughput and latency @@ -206,7 +206,7 @@ mean loosing cluster availability and needing to recover the cluster from a loss of quorum. Since Consul 1.10.0 -[`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) is now +[`raft_trailing_logs`](/docs/agent/config/config-files#raft_trailing_logs) is now reloadable with `consul reload` or `SIGHUP` allowing operators to increase this without the leader restarting or loosing leadership allowing the cluster to be recovered gracefully. @@ -277,7 +277,7 @@ This is a full list of metrics emitted by Consul. | `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter | | `consul.api.http` | Migrated from consul.http.. this samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter | -| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/agent-config-files#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | +| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/config-files#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.api.catalog_register.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter | | `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter | @@ -375,7 +375,7 @@ These metrics are used to monitor the health of the Consul servers. | `consul.raft.last_index` | Represents the raft applied index. | index | gauge | | `consul.raft.leader.dispatchLog` | Measures the time it takes for the leader to write log entries to disk. | ms | timer | | `consul.raft.leader.dispatchNumLogs` | Measures the number of logs committed to disk in a batch. | logs | gauge | -| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/config/agent-config-files#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance) guide for more details. | ms | timer | +| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/config/config-files#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance) guide for more details. | ms | timer | | `consul.raft.leader.oldestLogAge` | The number of milliseconds since the _oldest_ log in the leader's log store was written. This can be important for replication health where write rate is high and the snapshot is large as followers may be unable to recover from a restart if restoring takes longer than the minimum value for the current leader. Compare this with `consul.raft.fsm.lastRestoreDuration` and `consul.raft.rpc.installSnapshot` to monitor. In normal usage this gauge value will grow linearly over time until a snapshot completes on the leader and the log is truncated. Note: this metric won't be emitted until the leader writes a snapshot. After an upgrade to Consul 1.10.0 it won't be emitted until the oldest log was written after the upgrade. | ms | gauge | | `consul.raft.replication.heartbeat` | Measures the time taken to invoke appendEntries on a peer, so that it doesn’t timeout on a periodic basis. | ms | timer | | `consul.raft.replication.appendEntries` | Measures the time it takes to replicate log entries to followers. This is a general indicator of the load pressure on the Consul servers, as well as the performance of the communication between the servers. | ms | timer | @@ -473,7 +473,7 @@ These metrics give insight into the health of the cluster as a whole. | `consul.memberlist.degraded.timeout` | Counts the number of times an agent was marked as a dead node, whilst not getting enough confirmations from a randomly selected list of agent nodes in an agent's membership. | occurrence / interval | counter | | `consul.memberlist.msg.dead` | Counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter | | `consul.memberlist.health.score` | Describes a node's perception of its own health based on how well it is meeting the soft real-time requirements of the protocol. This metric ranges from 0 to 8, where 0 indicates "totally healthy". This health score is used to scale the time between outgoing probes, and higher scores translate into longer probing intervals. For more details see section IV of the Lifeguard paper: https://arxiv.org/pdf/1707.00788.pdf | score | gauge | -| `consul.memberlist.msg.suspect` | Increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/config/agent-config-files#ports). | suspect messages received / interval | counter | +| `consul.memberlist.msg.suspect` | Increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/config/config-files#ports). | suspect messages received / interval | counter | | `consul.memberlist.tcp.accept` | Counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter | | `consul.memberlist.udp.sent/received` | Measures the total number of bytes sent/received by an agent through the UDP protocol. | bytes sent or bytes received / interval | counter | | `consul.memberlist.tcp.connect` | Counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter | @@ -484,8 +484,8 @@ These metrics give insight into the health of the cluster as a whole. | `consul.memberlist.msg_suspect` | The number of suspect messages that the agent has processed so far, based on the message information given by the network layer. | messages / Interval | counter | | `consul.memberlist.probeNode` | Measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter | | `consul.memberlist.pushPullNode` | Measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter | -| `consul.serf.member.failed` | Increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/agent-config-files#ports). | failures / interval | counter | -| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/agent-config-files#ports). | flaps / interval | counter | +| `consul.serf.member.failed` | Increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/config-files#ports). | failures / interval | counter | +| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/config-files#ports). | flaps / interval | counter | | `consul.serf.member.join` | Increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter | | `consul.serf.member.left` | Increments when an agent leaves the cluster. | leaves / interval | counter | | `consul.serf.events` | Increments when an agent processes an [event](/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter | diff --git a/website/content/docs/connect/ca/aws.mdx b/website/content/docs/connect/ca/aws.mdx index 3b4ed80b90..1c608c2c62 100644 --- a/website/content/docs/connect/ca/aws.mdx +++ b/website/content/docs/connect/ca/aws.mdx @@ -173,11 +173,11 @@ So monthly cost would be calculated as: - 500 ⨉ 13.3 = 6,650 certificates issued in dc3 The number of certificates issued could be reduced by increasing -[`leaf_cert_ttl`](/docs/agent/config/agent-config-files#ca_leaf_cert_ttl) in the CA Provider +[`leaf_cert_ttl`](/docs/agent/config/config-files#ca_leaf_cert_ttl) in the CA Provider configuration if the longer lived credentials are an acceptable risk tradeoff against the cost. -[`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config -[`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider +[`ca_config`]: /docs/agent/config/config-files#connect_ca_config +[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider [`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration diff --git a/website/content/docs/connect/ca/consul.mdx b/website/content/docs/connect/ca/consul.mdx index 69778d0667..7f8e73b5df 100644 --- a/website/content/docs/connect/ca/consul.mdx +++ b/website/content/docs/connect/ca/consul.mdx @@ -92,7 +92,7 @@ Connect is enabled - the PrivateKey and RootCert fields have not been set, so th been generated (as seen above in the roots list). There are two ways to have the Consul CA use a custom private key and root certificate: -either through the `ca_config` section of the [Agent configuration](/docs/agent/config/agent-config-files#connect_ca_config) (which can only be used during the cluster's +either through the `ca_config` section of the [Agent configuration](/docs/agent/config/config-files#connect_ca_config) (which can only be used during the cluster's initial bootstrap) or through the [Update CA Configuration endpoint](/api/connect/ca#update-ca-configuration). Currently Consul requires that root certificates are valid [SPIFFE SVID Signing certificates](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded diff --git a/website/content/docs/connect/ca/index.mdx b/website/content/docs/connect/ca/index.mdx index 4fd96a79bf..c064ae61b6 100644 --- a/website/content/docs/connect/ca/index.mdx +++ b/website/content/docs/connect/ca/index.mdx @@ -30,7 +30,7 @@ will generate the initial root certificates and setup the internal Consul server state. For the initial bootstrap, the CA provider can be configured through the -[Agent configuration](/docs/agent/config/agent-config-files#connect_ca_config). After +[Agent configuration](/docs/agent/config/config-files#connect_ca_config). After initialization, the CA can only be updated through the [Update CA Configuration API endpoint](/api/connect/ca#update-ca-configuration). If a CA is already initialized, any changes to the CA configuration in the diff --git a/website/content/docs/connect/ca/vault.mdx b/website/content/docs/connect/ca/vault.mdx index 514fb4544a..b30e5627d2 100644 --- a/website/content/docs/connect/ca/vault.mdx +++ b/website/content/docs/connect/ca/vault.mdx @@ -271,6 +271,6 @@ path "/connect_inter/*" { -[`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config -[`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider +[`ca_config`]: /docs/agent/config/config-files#connect_ca_config +[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider [`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index 9e13659002..82982e00e8 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -28,7 +28,7 @@ You can configure the settings defined in the `exported-services` configuration ## Usage 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). -1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/config/agent-config-files#config_entries)) as described in [Configuration](#configuration). +1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/config/config-files#config_entries)) as described in [Configuration](#configuration). 1. Apply the configuration using one of the following methods: - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. diff --git a/website/content/docs/connect/config-entries/index.mdx b/website/content/docs/connect/config-entries/index.mdx index 2ff6142fa8..43b2a3d99c 100644 --- a/website/content/docs/connect/config-entries/index.mdx +++ b/website/content/docs/connect/config-entries/index.mdx @@ -49,7 +49,7 @@ See [Agent - Config Entries](/docs/agent/config-entries). ## Using Configuration Entries For Service Defaults Outside of Kubernetes, when the agent is -[configured](/docs/agent/config/agent-config-files#enable_central_service_config) to enable +[configured](/docs/agent/config/config-files#enable_central_service_config) to enable central service configurations, it will look for service configuration defaults that match a registering service instance. If it finds any, the agent will merge those defaults with the service instance configuration. This allows for things diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 83e9721eb1..256652a61f 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -300,8 +300,8 @@ spec: type: 'bool: false', description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port). + [advertise address](/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/docs/agent/config/config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost.`, }, { diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index b2764273c6..ac48d3ed14 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -649,8 +649,8 @@ spec: type: 'bool: false', description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port). + [advertise address](/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/docs/agent/config/config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running Consul on Kubernetes, and Consul agents run in their own pods.`, }, diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 51a6ae79de..70db30d305 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -468,7 +468,7 @@ spec: first permission to match in the list is terminal and stops further evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default - intention behavior is defined by the default [ACL policy](/docs/agent/config/agent-config-files#acl_default_policy).

+ intention behavior is defined by the default [ACL policy](/docs/agent/config/config-files#acl_default_policy).

This should be omitted for an L4 intention as it is mutually exclusive with the \`Action\` field.

Setting \`Permissions\` is not valid if a wildcard is used for the \`Name\` or \`Namespace\` because they can only be @@ -478,7 +478,7 @@ spec: first permission to match in the list is terminal and stops further evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default - intention behavior is defined by the default [ACL policy](/docs/agent/config/agent-config-files#acl_default_policy).

+ intention behavior is defined by the default [ACL policy](/docs/agent/config/config-files#acl_default_policy).

This should be omitted for an L4 intention as it is mutually exclusive with the \`action\` field.

Setting \`permissions\` is not valid if a wildcard is used for the \`spec.destination.name\` or \`spec.destination.namespace\` diff --git a/website/content/docs/connect/configuration.mdx b/website/content/docs/connect/configuration.mdx index ca0f6a1cdf..c4687d2c6e 100644 --- a/website/content/docs/connect/configuration.mdx +++ b/website/content/docs/connect/configuration.mdx @@ -22,7 +22,7 @@ The first step to use Connect is to enable Connect for your Consul cluster. By default, Connect is disabled. Enabling Connect requires changing the configuration of only your Consul _servers_ (not client agents). To enable Connect, add the following to a new or existing -[server configuration file](/docs/agent/config/agent-config-files). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: +[server configuration file](/docs/agent/config/config-files). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: ```hcl connect { @@ -43,20 +43,20 @@ connection attempts to fail until Connect is enabled on the server agents. Other optional Connect configurations that you can set in the server configuration file include: -- [certificate authority settings](/docs/agent/config/agent-config-files#connect) -- [token replication](/docs/agent/config/agent-config-files#acl_tokens_replication) -- [dev mode](/docs/agent/config/agent-config-cli#_dev) -- [server host name verification](/docs/agent/config/agent-config-files#verify_server_hostname) +- [certificate authority settings](/docs/agent/config/config-files#connect) +- [token replication](/docs/agent/config/config-files#acl_tokens_replication) +- [dev mode](/docs/agent/config/cli-flags#_dev) +- [server host name verification](/docs/agent/config/config-files#verify_server_hostname) If you would like to use Envoy as your Connect proxy you will need to [enable -gRPC](/docs/agent/config/agent-config-files#grpc_port). +gRPC](/docs/agent/config/config-files#grpc_port). Additionally if you plan on using the observability features of Connect, it can be convenient to configure your proxies and services using [configuration entries](/docs/agent/config-entries) which you can interact with using the CLI or API, or by creating configuration entry files. You will want to enable [centralized service -configuration](/docs/agent/config/agent-config-files#enable_central_service_config) on +configuration](/docs/agent/config/config-files#enable_central_service_config) on clients, which allows each service's proxy configuration to be managed centrally via API. diff --git a/website/content/docs/connect/connect-internals.mdx b/website/content/docs/connect/connect-internals.mdx index c4f30ae12d..1cbc9396dc 100644 --- a/website/content/docs/connect/connect-internals.mdx +++ b/website/content/docs/connect/connect-internals.mdx @@ -109,10 +109,10 @@ externally routable IPs at the service level. ## Intention Replication Intention replication happens automatically but requires the -[`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) +[`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) configuration to be set to specify a datacenter that is authoritative for intentions. In production setups with ACLs enabled, the -[replication token](/docs/agent/config/agent-config-files#acl_tokens_replication) must also +[replication token](/docs/agent/config/config-files#acl_tokens_replication) must also be set in the secondary datacenter server's configuration. ## Certificate Authority Federation diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx index 8e02b22d57..004fad0d83 100644 --- a/website/content/docs/connect/gateways/ingress-gateway.mdx +++ b/website/content/docs/connect/gateways/ingress-gateway.mdx @@ -40,8 +40,8 @@ the [hosts](/docs/connect/config-entries/ingress-gateway#hosts) field. Ingress gateways also require that your Consul datacenters are configured correctly: - You'll need to use Consul version 1.8.0 or newer. -- Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled on all client agents. +- Consul [Connect](/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx index f970753182..d7d401a894 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx @@ -30,12 +30,12 @@ Ensure that your Consul environment meets the following requirements. * Consul version 1.6.0 or newer. * A local Consul agent is required to manage its configuration. -* Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled in both datacenters. -* Each [datacenter](/docs/agent/config/agent-config-files#datacenter) must have a unique name. +* Consul [Connect](/docs/agent/config/config-files#connect) must be enabled in both datacenters. +* Each [datacenter](/docs/agent/config/config-files#datacenter) must have a unique name. * Each datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan). -* The [primary datacenter](/docs/agent/config/agent-config-files#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. -* [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled. -* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/agent-config-files#enable_central_service_config). +* The [primary datacenter](/docs/agent/config/config-files#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. +* [gRPC](/docs/agent/config/config-files#grpc_port) must be enabled. +* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/config-files#enable_central_service_config). ### Network diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx index 278d504efd..31f032cf3f 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx @@ -24,9 +24,9 @@ Ensure that your Consul environment meets the following requirements. * Consul Enterprise version 1.11.0 or newer. * A local Consul agent is required to manage its configuration. -* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/config/agent-config-files#connect) for details. +* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/config/config-files#connect) for details. * Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enteprise/admin-partitions) for details. -* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/agent-config-files#enable_central_service_config). +* If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/config-files#enable_central_service_config). ### Proxy diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index 126c50ead0..76eb21791c 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -124,7 +124,7 @@ connect { } ``` -Any references to [`start_join_wan`](/docs/agent/config/agent-config-files#start_join_wan) or [`retry_join_wan`](/docs/agent/config/agent-config-files#retry_join_wan) should be omitted. +Any references to [`start_join_wan`](/docs/agent/config/config-files#start_join_wan) or [`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) should be omitted. -> The `primary_gateways` configuration can also use `go-discover` syntax just like `retry_join_wan`. diff --git a/website/content/docs/connect/gateways/terminating-gateway.mdx b/website/content/docs/connect/gateways/terminating-gateway.mdx index 064e5ed070..43f8f2c797 100644 --- a/website/content/docs/connect/gateways/terminating-gateway.mdx +++ b/website/content/docs/connect/gateways/terminating-gateway.mdx @@ -59,8 +59,8 @@ Each terminating gateway needs: Terminating gateways also require that your Consul datacenters are configured correctly: - You'll need to use Consul version 1.8.0 or newer. -- Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled on all client agents. +- Consul [Connect](/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul. diff --git a/website/content/docs/connect/intentions-legacy.mdx b/website/content/docs/connect/intentions-legacy.mdx index 6061a867ea..9082e71aff 100644 --- a/website/content/docs/connect/intentions-legacy.mdx +++ b/website/content/docs/connect/intentions-legacy.mdx @@ -25,7 +25,7 @@ is allowed by testing the intentions. If authorize returns false the connection must be terminated. The default intention behavior is defined by the default [ACL -policy](/docs/agent/config/agent-config-files#acl_default_policy). If the default ACL policy is +policy](/docs/agent/config/config-files#acl_default_policy). If the default ACL policy is "allow all", then all Connect connections are allowed by default. If the default ACL policy is "deny all", then all Connect connections are denied by default. diff --git a/website/content/docs/connect/intentions.mdx b/website/content/docs/connect/intentions.mdx index 95aef154cf..36c2e3d9dc 100644 --- a/website/content/docs/connect/intentions.mdx +++ b/website/content/docs/connect/intentions.mdx @@ -49,7 +49,7 @@ target destination. After verifying the TLS client certificate, the cached intentions should be consulted for each incoming connection/request to determine if it should be accepted or rejected. -The default intention behavior is defined by the [`default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) configuration. +The default intention behavior is defined by the [`default_policy`](/docs/agent/config/config-files#acl_default_policy) configuration. If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. If is set to `deny`, then all connections or requests will be denied by default. diff --git a/website/content/docs/connect/observability/index.mdx b/website/content/docs/connect/observability/index.mdx index 0aa3026ba0..06dfdf576c 100644 --- a/website/content/docs/connect/observability/index.mdx +++ b/website/content/docs/connect/observability/index.mdx @@ -18,10 +18,10 @@ to: - Define the upstreams for each of your services. If you are using Envoy as your sidecar proxy, you will need to [enable -gRPC](/docs/agent/config/agent-config-files#grpc_port) on your client agents. To define the +gRPC](/docs/agent/config/config-files#grpc_port) on your client agents. To define the metrics destination and service protocol you may want to enable [configuration -entries](/docs/agent/config/agent-config-files#config_entries) and [centralized service -configuration](/docs/agent/config/agent-config-files#enable_central_service_config). +entries](/docs/agent/config/config-files#config_entries) and [centralized service +configuration](/docs/agent/config/config-files#enable_central_service_config). ### Kubernetes If you are using Kubernetes, the Helm chart can simplify much of the configuration needed to enable observability. See diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx index 9477b77ec7..60be9b76a0 100644 --- a/website/content/docs/connect/observability/ui-visualization.mdx +++ b/website/content/docs/connect/observability/ui-visualization.mdx @@ -47,11 +47,11 @@ UI. If there are multiple clients with the UI enabled in a datacenter for redundancy these configurations must be added to all of them. We assume that the UI is already enabled by setting -[`ui_config.enabled`](/docs/agent/config/agent-config-files#ui_config_enabled) to `true` in the +[`ui_config.enabled`](/docs/agent/config/config-files#ui_config_enabled) to `true` in the agent's configuration file. To use the built-in Prometheus provider -[`ui_config.metrics_provider`](/docs/agent/config/agent-config-files#ui_config_metrics_provider) +[`ui_config.metrics_provider`](/docs/agent/config/config-files#ui_config_metrics_provider) must be set to `prometheus`. The UI must query the metrics provider through a proxy endpoint. This simplifies @@ -59,7 +59,7 @@ deployment where Prometheus is not exposed externally to UI user's browsers. To set this up, provide the URL that the _Consul agent_ should use to reach the Prometheus server in -[`ui_config.metrics_proxy.base_url`](/docs/agent/config/agent-config-files#ui_config_metrics_proxy_base_url). +[`ui_config.metrics_proxy.base_url`](/docs/agent/config/config-files#ui_config_metrics_proxy_base_url). For example in Kubernetes, the Prometheus helm chart by default installs a service named `prometheus-server` so each Consul agent can reach it on `http://prometheus-server` (using Kubernetes' DNS resolution). @@ -87,7 +87,7 @@ service-specific dashboard in an external tool like [Grafana](https://grafana.com) or a hosted provider. To configure this, you must provide a URL template in the [agent configuration -file](/docs/agent/config/agent-config-files#ui_config_dashboard_url_templates) for all agents that +file](/docs/agent/config/config-files#ui_config_dashboard_url_templates) for all agents that have the UI enabled. The template is essentially the URL to the external dashboard, but can have placeholder values which will be replaced with the service name, namespace and datacenter where appropriate to allow deep-linking @@ -498,12 +498,12 @@ ui_config { ``` More than one JavaScript file may be specified in -[`metrics_provider_files`](/docs/agent/config/agent-config-files#ui_config_metrics_provider_files) +[`metrics_provider_files`](/docs/agent/config/config-files#ui_config_metrics_provider_files) and all we be served allowing flexibility if needed to include dependencies. Only one metrics provider can be configured and used at one time. The -[`metrics_provider_options_json`](/docs/agent/config/agent-config-files#ui_config_metrics_provider_options_json) +[`metrics_provider_options_json`](/docs/agent/config/config-files#ui_config_metrics_provider_options_json) field is an optional literal JSON object which is passed to the provider's `init` method at startup time. This allows configuring arbitrary parameters for the provider in config rather than hard coding them into the provider itself to @@ -512,7 +512,7 @@ make providers more reusable. The provider may fetch metrics directly from another source although in this case the agent will probably need to serve the correct CORS headers to prevent browsers from blocking these requests. These may be configured with -[`http_config.response_headers`](/docs/agent/config/agent-config-files#response_headers). +[`http_config.response_headers`](/docs/agent/config/config-files#response_headers). Alternatively, the provider may choose to use the [built-in metrics proxy](#metrics-proxy) to avoid cross domain issues or to inject additional diff --git a/website/content/docs/connect/proxies/built-in.mdx b/website/content/docs/connect/proxies/built-in.mdx index f66a6747d7..439a7d3102 100644 --- a/website/content/docs/connect/proxies/built-in.mdx +++ b/website/content/docs/connect/proxies/built-in.mdx @@ -58,7 +58,7 @@ All fields are optional with a reasonable default. - `bind_port` - The port the proxy will bind its _public_ mTLS listener to. If not provided, the agent will attempt to assign one from its - [configured proxy port range](/docs/agent/config/agent-config-files#sidecar_min_port) if available. + [configured proxy port range](/docs/agent/config/config-files#sidecar_min_port) if available. By default the range is [20000, 20255] and the port is selected at random from that range. diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 8e6cde206f..de7c4a8d7a 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -188,7 +188,7 @@ the upstream listeners of any downstream service. One example is how users can define a service's protocol in a [`service-defaults` configuration entry](/docs/connect/config-entries/service-defaults). Agents with -[`enable_central_service_config`](/docs/agent/config/agent-config-files#enable_central_service_config) +[`enable_central_service_config`](/docs/agent/config/config-files#enable_central_service_config) set to true will automatically discover the protocol when configuring a proxy for a service. The proxy will discover the main protocol of the service it represents and use this to configure its main public listener. It will also diff --git a/website/content/docs/connect/proxies/managed-deprecated.mdx b/website/content/docs/connect/proxies/managed-deprecated.mdx index 7d14ce8c09..197994c1d9 100644 --- a/website/content/docs/connect/proxies/managed-deprecated.mdx +++ b/website/content/docs/connect/proxies/managed-deprecated.mdx @@ -24,7 +24,7 @@ Managed proxies have been deprecated since Consul 1.3 and have been fully remove in Consul 1.6. Anyone using Managed Proxies should aim to change their workflow as soon as possible to avoid issues with a later upgrade. -After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/config/agent-config-cli#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. +After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/config/cli-flags#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. **new and known issues will not be fixed**. @@ -275,6 +275,6 @@ level logs showing service discovery, certificate and authorization information. ~> **Note:** In `-dev` mode there is no `data_dir` unless one is explicitly configured so logging is disabled. You can access logs by providing the -[`-data-dir`](/docs/agent/config/agent-config-cli#_data_dir) CLI option. If a data dir is +[`-data-dir`](/docs/agent/config/cli-flags#_data_dir) CLI option. If a data dir is configured, this will also cause proxy processes to stay running when the agent terminates as described in [Lifecycle](#lifecycle). diff --git a/website/content/docs/connect/registration/service-registration.mdx b/website/content/docs/connect/registration/service-registration.mdx index bef0ff0ea2..d121030d17 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/registration/service-registration.mdx @@ -437,8 +437,8 @@ registrations](/docs/agent/services#service-definition-parameter-case). - `checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port). + [advertise address](/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/docs/agent/config/config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running Consul on Kubernetes, and Consul agents run in their own pods. - `paths` `array: []` - A list of paths to expose through Envoy. diff --git a/website/content/docs/connect/registration/sidecar-service.mdx b/website/content/docs/connect/registration/sidecar-service.mdx index ffa5f5e699..1aa72370e3 100644 --- a/website/content/docs/connect/registration/sidecar-service.mdx +++ b/website/content/docs/connect/registration/sidecar-service.mdx @@ -131,7 +131,7 @@ proxy. - `tags` - Defaults to the tags of the parent service. - `meta` - Defaults to the service metadata of the parent service. - `port` - Defaults to being auto-assigned from a [configurable - range](/docs/agent/config/agent-config-files#sidecar_min_port) that is + range](/docs/agent/config/config-files#sidecar_min_port) that is by default `[21000, 21255]`. - `kind` - Defaults to `connect-proxy`. This can't be overridden currently. - `check`, `checks` - By default we add a TCP check on the local address and diff --git a/website/content/docs/discovery/checks.mdx b/website/content/docs/discovery/checks.mdx index 29095d32e5..075e916301 100644 --- a/website/content/docs/discovery/checks.mdx +++ b/website/content/docs/discovery/checks.mdx @@ -34,10 +34,10 @@ There are several different kinds of checks: In Consul 0.9.0 and later, script checks are not enabled by default. To use them you can either use : - - [`enable_local_script_checks`](/docs/agent/config/agent-config-cli#_enable_local_script_checks): + - [`enable_local_script_checks`](/docs/agent/config/cli-flags#_enable_local_script_checks): enable script checks defined in local config files. Script checks defined via the HTTP API will not be allowed. - - [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks): enable + - [`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks): enable script checks regardless of how they are defined. ~> **Security Warning:** Enabling script checks in some configurations may @@ -105,7 +105,7 @@ There are several different kinds of checks: has to be performed is configurable which makes it possible to run containers which have different shells on the same host. Check output for Docker is limited to 4KB. Any output larger than this will be truncated. In Consul 0.9.0 and later, the agent - must be configured with [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks) + must be configured with [`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks) set to `true` in order to enable Docker health checks. - `gRPC + Interval` - These checks are intended for applications that support the standard @@ -462,7 +462,7 @@ This is the only convention that Consul depends on. Any output of the script will be captured and stored in the `output` field. In Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks) set to `true` +[`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks) set to `true` in order to enable script checks. ## Initial Health Check Status @@ -538,7 +538,7 @@ provided by the node will remain unchanged. ## Agent Certificates for TLS Checks -The [enable_agent_tls_for_checks](/docs/agent/config/agent-config-files#enable_agent_tls_for_checks) +The [enable_agent_tls_for_checks](/docs/agent/config/config-files#enable_agent_tls_for_checks) agent configuration option can be utilized to have HTTP or gRPC health checks to use the agent's credentials when configured for TLS. diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index 208c0110c1..64a4ac6dac 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -21,9 +21,9 @@ are located in the `us-east-1` datacenter, and have no failing health checks. It's that simple! There are a number of configuration options that are important for the DNS interface, -specifically [`client_addr`](/docs/agent/config/agent-config-files#client_addr),[`ports.dns`](/docs/agent/config/agent-config-files#dns_port), -[`recursors`](/docs/agent/config/agent-config-files#recursors),[`domain`](/docs/agent/config/agent-config-files#domain), -[`alt_domain`](/docs/agent/config/agent-config-files#alt_domain), and [`dns_config`](/docs/agent/config/agent-config-files#dns_config). +specifically [`client_addr`](/docs/agent/config/config-files#client_addr),[`ports.dns`](/docs/agent/config/config-files#dns_port), +[`recursors`](/docs/agent/config/config-files#recursors),[`domain`](/docs/agent/config/config-files#domain), +[`alt_domain`](/docs/agent/config/config-files#alt_domain), and [`dns_config`](/docs/agent/config/config-files#dns_config). By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.` domain, without support for further DNS recursion. Please consult the [documentation on configuration options](/docs/agent/config), @@ -32,7 +32,7 @@ specifically the configuration items linked above, for more details. There are a few ways to use the DNS interface. One option is to use a custom DNS resolver library and point it at Consul. Another option is to set Consul as the DNS server for a node and provide a -[`recursors`](/docs/agent/config/agent-config-files#recursors) configuration so that non-Consul queries +[`recursors`](/docs/agent/config/config-files#recursors) configuration so that non-Consul queries can also be resolved. The last method is to forward all queries for the "consul." domain to a Consul agent from the existing DNS server. Review the [DNS Forwarding tutorial](https://learn.hashicorp.com/tutorials/consul/dns-forwarding?utm_source=consul.io&utm_medium=docs) for examples. @@ -296,15 +296,15 @@ are not truncated. ## Alternative Domain By default, Consul responds to DNS queries in the `consul` domain, -but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/config/agent-config-files#domain) parameter. +but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/config/config-files#domain) parameter. In some instances, Consul may need to respond to queries in more than one domain, such as during a DNS migration or to distinguish between internal and external queries. Consul versions 1.5.2+ can be configured to respond to DNS queries on an alternative domain -through the [`alt_domain`](/docs/agent/config/agent-config-files#alt_domain) agent configuration +through the [`alt_domain`](/docs/agent/config/config-files#alt_domain) agent configuration option. As of Consul versions 1.11.0+, Consul's DNS response will use the same domain as was used in the query; -in prior versions, the response may use the primary [`domain`](/docs/agent/config/agent-config-files#domain) no matter which +in prior versions, the response may use the primary [`domain`](/docs/agent/config/config-files#domain) no matter which domain was used in the query. In the following example, the `alt_domain` parameter is set to `test-domain`: @@ -331,7 +331,7 @@ machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment=" ``` -> **PTR queries:** Responses to PTR queries (`.in-addr.arpa.`) will always use the -[primary domain](/docs/agent/config/agent-config-files#domain) (not the alternative domain), +[primary domain](/docs/agent/config/config-files#domain) (not the alternative domain), as there is no way for the query to specify a domain. ## Caching @@ -346,8 +346,8 @@ for [DNS caching](https://learn.hashicorp.com/tutorials/consul/dns-caching). By default, Consul DNS queries will return a node's local address, even when being queried from a remote datacenter. If you need to use a different address to reach a node from outside its datacenter, you can configure this behavior -using the [`advertise-wan`](/docs/agent/config/agent-config-cli#_advertise-wan) and -[`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs) configuration +using the [`advertise-wan`](/docs/agent/config/cli-flags#_advertise-wan) and +[`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs) configuration options. ## Namespaced/Partitioned Services @@ -363,7 +363,7 @@ services from other namespaces or partitions the following form can be used: This is the canonical name of a Consul Enterprise service. Currently all parts must be present - in a future version (once the -[`prefer_namespace` configuration](/docs/agent/config/agent-config-files#dns_prefer_namespace) has been +[`prefer_namespace` configuration](/docs/agent/config/config-files#dns_prefer_namespace) has been deprecated), the namespace, partition and datacenter components will become optional and may be individually omitted to default to the `default` namespace, local partition or local datacenter respectively. @@ -377,7 +377,7 @@ are enabled, you must first create ACL tokens with the necessary policies. Consul agents resolve DNS requests using one of the preconfigured tokens below, listed in order of precedence: -1. The agent's [`default` token](/docs/agent/config/agent-config-files#acl_tokens_default). +1. The agent's [`default` token](/docs/agent/config/config-files#acl_tokens_default). 2. The built-in [`anonymous` token](/docs/security/acl/acl-system#builtin-tokens). Because the anonymous token is used when any request is made to Consul without explicitly specifying a token, production deployments should not apply policies diff --git a/website/content/docs/dynamic-app-config/kv.mdx b/website/content/docs/dynamic-app-config/kv.mdx index 6793d053f5..6a57875ca2 100644 --- a/website/content/docs/dynamic-app-config/kv.mdx +++ b/website/content/docs/dynamic-app-config/kv.mdx @@ -39,7 +39,7 @@ privileges on one key for developers to update the value related to their application. The datastore itself is located on the Consul servers in the [data -directory](/docs/agent/config/agent-config-cli#_data_dir). To ensure data is not lost in +directory](/docs/agent/config/cli-flags#_data_dir). To ensure data is not lost in the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data. ## Using Consul KV @@ -48,7 +48,7 @@ Objects are opaque to Consul, meaning there are no restrictions on the type of object stored in a key/value entry. The main restriction on an object is size - the maximum is 512 KB. Due to the maximum object size and main use cases, you should not need extra storage; the general [sizing -recommendations](/docs/agent/config/agent-config-files#kv_max_value_size) +recommendations](/docs/agent/config/config-files#kv_max_value_size) are usually sufficient. Keys, like objects are not restricted by type and can include any character. diff --git a/website/content/docs/dynamic-app-config/watches.mdx b/website/content/docs/dynamic-app-config/watches.mdx index bd9e0802f2..a0d23acb85 100644 --- a/website/content/docs/dynamic-app-config/watches.mdx +++ b/website/content/docs/dynamic-app-config/watches.mdx @@ -20,7 +20,7 @@ Watches are implemented using blocking queries in the [HTTP API](/api). Agents automatically make the proper API calls to watch for changes and inform a handler when the data view has updated. -Watches can be configured as part of the [agent's configuration](/docs/agent/config/agent-config-files#watches), +Watches can be configured as part of the [agent's configuration](/docs/agent/config/config-files#watches), causing them to run once the agent is initialized. Reloading the agent configuration allows for adding or removing watches dynamically. diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index 60e567a62e..d91ecdcadd 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -62,7 +62,7 @@ however there are some important inputs worth highlighting: This is where you include application containers. - `port` is the port that your application listens on. This should be set to a string, not an integer, i.e. `port = "9090"`, not `port = 9090`. -- `retry_join` is passed to the [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) option for the Consul agent. This tells +- `retry_join` is passed to the [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) option for the Consul agent. This tells the agent the location of your Consul servers so that it can join the Consul cluster. -> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true` diff --git a/website/content/docs/enterprise/audit-logging.mdx b/website/content/docs/enterprise/audit-logging.mdx index 030dea3e69..2d56c20468 100644 --- a/website/content/docs/enterprise/audit-logging.mdx +++ b/website/content/docs/enterprise/audit-logging.mdx @@ -25,14 +25,14 @@ For more experience leveraging Consul's audit logging functionality, explore our HashiCorp Learn tutorial [Capture Consul Events with Audit Logging](https://learn.hashicorp.com/tutorials/consul/audit-logging). For detailed configuration information on configuring the Consul Enterprise's audit -logging, review the Consul [Audit Log](https://www.consul.io/docs/agent/config/agent-config-files#audit) +logging, review the Consul [Audit Log](https://www.consul.io/docs/agent/config/config-files#audit) documentation. ## Example Configuration Audit logging must be enabled on every agent in order to accurately capture all operations performed through the HTTP API. To enable logging, add -the [`audit`](/docs/agent/config/agent-config-files#audit) stanza to the agent's configuration. +the [`audit`](/docs/agent/config/config-files#audit) stanza to the agent's configuration. -> **Note**: Consul only logs operations which are initiated via the HTTP API. The audit log does not record operations that take place over the internal RPC diff --git a/website/content/docs/enterprise/license/overview.mdx b/website/content/docs/enterprise/license/overview.mdx index ae99a58746..377137248d 100644 --- a/website/content/docs/enterprise/license/overview.mdx +++ b/website/content/docs/enterprise/license/overview.mdx @@ -36,7 +36,7 @@ When using these binaries no further action is necessary to configure the licens ### Binaries Without Built In Licenses For Consul Enterprise 1.10.0 or greater, binaries that do not include built in licenses a license must be available at the time the agent starts. -For server agents this means that they must either have the [`license_path`](/docs/agent/config/agent-config-files#license_path) +For server agents this means that they must either have the [`license_path`](/docs/agent/config/config-files#license_path) configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or `CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH` environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment @@ -55,9 +55,9 @@ to retrieve the license automatically under specific circumstances. When a client agent starts without a license in its configuration or environment, it will try to retrieve the license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the request but the token doesn't need any particular permissions. As the license is required before the client -actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/config/agent-config-files#start_join) -or [`retry_join`](/docs/agent/config/agent-config-files#retry_join) configurations. If those are both unset or no -[`agent` token](/docs/agent/config/agent-config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down. +actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/config/config-files#start_join) +or [`retry_join`](/docs/agent/config/config-files#retry_join) configurations. If those are both unset or no +[`agent` token](/docs/agent/config/config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down. If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a diff --git a/website/content/docs/enterprise/network-segments.mdx b/website/content/docs/enterprise/network-segments.mdx index 75929181d3..df955e7b3a 100644 --- a/website/content/docs/enterprise/network-segments.mdx +++ b/website/content/docs/enterprise/network-segments.mdx @@ -15,7 +15,7 @@ description: |- Consul requires full connectivity between all agents (servers and clients) in a -[datacenter](/docs/agent/config/agent-config-cli#_datacenter) within a given +[datacenter](/docs/agent/config/cli-flags#_datacenter) within a given LAN gossip pool. By default, all Consul agents will be a part of one shared Serf LAN gossip pool known as the `` network segment, thus requiring full mesh connectivity within the datacenter. @@ -46,7 +46,7 @@ Consul networking models and their capabilities. **Cluster:** A set of Consul servers forming a Raft quorum along with a collection of Consul clients, all set to the same -[datacenter](/docs/agent/config/agent-config-cli#_datacenter), and joined together to form +[datacenter](/docs/agent/config/cli-flags#_datacenter), and joined together to form what we will call a "local cluster". Consul clients discover the Consul servers in their local cluster through the gossip mechanism and make RPC requests to them. LAN Gossip (OSS) is an open intra-cluster networking model, and Network @@ -73,7 +73,7 @@ group of agents to only connect with the agents in its segment. Server agents are members of all segments. The datacenter includes a `` segment, as well as additional segments defined in the -[`segments`](/docs/agent/config/agent-config-files#segments) server agent configuration option. +[`segments`](/docs/agent/config/config-files#segments) server agent configuration option. Each additional segment is defined by: - a non-empty name @@ -130,19 +130,19 @@ segments = [ -The server [agent configuration](/docs/agent/config/agent-config-files) options relevant to network +The server [agent configuration](/docs/agent/config/config-files) options relevant to network segments are: -- [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port): The Serf LAN port on this server +- [`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port): The Serf LAN port on this server for the `` network segment's gossip pool. -- [`segments`](/docs/agent/config/agent-config-files#segments): A list of user-defined network segments +- [`segments`](/docs/agent/config/config-files#segments): A list of user-defined network segments on this server, including their names and Serf LAN ports. ## Client Configuration Each client agent can only be a member of one segment at a time. This will be the `` segment unless otherwise specified in the agent's -[`segment`](/docs/agent/config/agent-config-cli#_segment) agent configuration option. +[`segment`](/docs/agent/config/cli-flags#_segment) agent configuration option. ### Join a Client to a Segment ((#join_a_client_to_a_segment)) @@ -155,14 +155,14 @@ configured segment. Clients A and B specify the same segment S. Client B is already joined to the segment S LAN gossip pool. Client A wants to join via Client B. In order to do so, Client A -must connect to Client B's configured [Serf LAN port](/docs/agent/config/agent-config-files#serf_lan_port). +must connect to Client B's configured [Serf LAN port](/docs/agent/config/config-files#serf_lan_port). Client A specifies segment S and wants to join the segment S gossip pool via Server 1. In order to do so, Client A must connect to Server 1's configured [Serf LAN port -for segment S](/docs/agent/config/agent-config-files#segment_port). +for segment S](/docs/agent/config/config-files#segment_port). @@ -172,12 +172,12 @@ of precedence: 1. **Specify an explicit port in the join address**. This can be done at the CLI when starting the agent (e.g., `consul agent -retry-join "client-b-address:8303"`), or in the agent's - configuration using the [retry-join option](/docs/agent/config/agent-config-files#retry_join). This method + configuration using the [retry-join option](/docs/agent/config/config-files#retry_join). This method is not compatible with [cloud auto-join](/docs/install/cloud-auto-join#auto-join-with-network-segments). 2. **Specify an alternate Serf LAN port for the agent**. This can be done at the CLI when starting the agent (e.g., `consul agent -retry-join "client-b-address" -serf-lan-port 8303`), or in - the agent's configuration using the [serf_lan](/docs/agent/config/agent-config-files#serf_lan_port) option. + the agent's configuration using the [serf_lan](/docs/agent/config/config-files#serf_lan_port) option. When a Serf LAN port is not explicitly specified in the join address, the agent will attempt to join the target host at the Serf LAN port specified in CLI or agent configuration. @@ -222,15 +222,15 @@ ports = { -The client [agent configuration](/docs/agent/config/agent-config-files) options relevant to network +The client [agent configuration](/docs/agent/config/config-files) options relevant to network segments are: -- [`segment`](/docs/agent/config/agent-config-files#segment-2): The name of the network segment this +- [`segment`](/docs/agent/config/config-files#segment-2): The name of the network segment this client agent belongs to. -- [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port): +- [`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port): Serf LAN port for the above segment on this client. This is not required to match the configured Serf LAN port for other agents on this segment. -- [`retry_join`](/docs/agent/config/agent-config-files#retry_join) or - [`start_join`](/docs/agent/config/agent-config-files#start_join): A list of agent addresses to join +- [`retry_join`](/docs/agent/config/config-files#retry_join) or + [`start_join`](/docs/agent/config/config-files#start_join): A list of agent addresses to join when starting. Ensure the correct Serf LAN port for this segment is used when joining the LAN gossip pool using one of the [available configuration methods](#join_a_client_to_a_segment). diff --git a/website/content/docs/enterprise/read-scale.mdx b/website/content/docs/enterprise/read-scale.mdx index c7b6006b5d..3665db34e4 100644 --- a/website/content/docs/enterprise/read-scale.mdx +++ b/website/content/docs/enterprise/read-scale.mdx @@ -20,5 +20,5 @@ however, they do not take part in quorum election operations. Expanding your Con reads without impacting write latency. For more details, review the [Consul server configuration](/docs/agent/config) -documentation and the [-read-replica](/docs/agent/config/agent-config-cli#_read_replica) +documentation and the [-read-replica](/docs/agent/config/cli-flags#_read_replica) configuration flag. diff --git a/website/content/docs/install/bootstrapping.mdx b/website/content/docs/install/bootstrapping.mdx index 33342bd152..22c0e76890 100644 --- a/website/content/docs/install/bootstrapping.mdx +++ b/website/content/docs/install/bootstrapping.mdx @@ -30,16 +30,16 @@ as data loss is inevitable in a failure scenario. Please refer to the Manual bootstrapping with `-bootstrap` is not recommended in newer versions of Consul (0.5 and newer) as it is more error-prone. Instead you should use automatic bootstrapping -with [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect). +with [`-bootstrap-expect`](/docs/agent/config/cli-flags#_bootstrap_expect). ## Bootstrapping the Servers -The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect) +The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/config/cli-flags#_bootstrap_expect) configuration option. This option informs Consul of the expected number of server nodes and automatically bootstraps when that many servers are available. To prevent inconsistencies and split-brain (clusters where multiple servers consider themselves leader) situations, you should either specify the same value for -[`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect) +[`-bootstrap-expect`](/docs/agent/config/cli-flags#_bootstrap_expect) or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster. Suppose we are starting a three server cluster. We can start `Node A`, `Node B`, and `Node C` with each @@ -61,11 +61,11 @@ You can trigger leader election by joining the servers together, to create a clu There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case. - Specify a list of servers with - [-join](/docs/agent/config/agent-config-cli#_join) and - [start_join](/docs/agent/config/agent-config-files#start_join) + [-join](/docs/agent/config/cli-flags#_join) and + [start_join](/docs/agent/config/config-files#start_join) options. -- Specify a list of servers with [-retry-join](/docs/agent/config/agent-config-cli#_retry_join) option. -- Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/config/agent-config-cli#_retry_join) option. +- Specify a list of servers with [-retry-join](/docs/agent/config/cli-flags#_retry_join) option. +- Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/config/cli-flags#_retry_join) option. All three methods can be set in the agent configuration file or the command line flag. diff --git a/website/content/docs/install/cloud-auto-join.mdx b/website/content/docs/install/cloud-auto-join.mdx index f3053632ce..708bdba990 100644 --- a/website/content/docs/install/cloud-auto-join.mdx +++ b/website/content/docs/install/cloud-auto-join.mdx @@ -69,7 +69,7 @@ to use port `8303` as its Serf LAN port prior to attempting to join the cluster. The following example configuration overrides the default Serf LAN port using the -[`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port) configuration option. +[`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port) configuration option. @@ -85,7 +85,7 @@ ports { The following example overrides the default Serf LAN port using the -[`-serf-lan-port`](/docs/agent/config/agent-config-cli#_serf_lan_port) command line flag. +[`-serf-lan-port`](/docs/agent/config/cli-flags#_serf_lan_port) command line flag. ```shell $ consul agent -serf-lan-port=8303 -retry-join "provider=..." diff --git a/website/content/docs/install/manual-bootstrap.mdx b/website/content/docs/install/manual-bootstrap.mdx index 5a1c564590..f6945dc39c 100644 --- a/website/content/docs/install/manual-bootstrap.mdx +++ b/website/content/docs/install/manual-bootstrap.mdx @@ -23,7 +23,7 @@ storing the cluster state. The client nodes are mostly stateless and rely on the server nodes, so they can be started easily. Manual bootstrapping requires that the first server that is deployed in a new -datacenter provide the [`-bootstrap` configuration option](/docs/agent/config/agent-config-cli#_bootstrap). +datacenter provide the [`-bootstrap` configuration option](/docs/agent/config/cli-flags#_bootstrap). This option allows the server to assert leadership of the cluster without agreement from any other server. This is necessary because at this point, there are no other servers running in diff --git a/website/content/docs/install/performance.mdx b/website/content/docs/install/performance.mdx index 0dd92817b6..19013d3d77 100644 --- a/website/content/docs/install/performance.mdx +++ b/website/content/docs/install/performance.mdx @@ -18,7 +18,7 @@ reads work from a fully in-memory data store that is optimized for concurrent ac ## Minimum Server Requirements ((#minimum)) -In Consul 0.7, the default server [performance parameters](/docs/agent/config/agent-config-files#performance) +In Consul 0.7, the default server [performance parameters](/docs/agent/config/config-files#performance) were tuned to allow Consul to run reliably (but relatively slowly) on a server cluster of three [AWS t2.micro](https://aws.amazon.com/ec2/instance-types/) instances. These thresholds were determined empirically using a leader instance that was under sufficient read, write, @@ -43,7 +43,7 @@ The default performance configuration is equivalent to this: ## Production Server Requirements ((#production)) When running Consul 0.7 and later in production, it is recommended to configure the server -[performance parameters](/docs/agent/config/agent-config-files#performance) back to Consul's original +[performance parameters](/docs/agent/config/config-files#performance) back to Consul's original high-performance settings. This will let Consul servers detect a failed leader and complete leader elections much more quickly than the default configuration which extends key Raft timeouts by a factor of 5, so it can be quite slow during these events. @@ -103,14 +103,14 @@ Here are some general recommendations: issues between the servers or insufficient CPU resources. Users in cloud environments often bump their servers up to the next instance class with improved networking and CPU until leader elections stabilize, and in Consul 0.7 or later the [performance - parameters](/docs/agent/config/agent-config-files#performance) configuration now gives you tools + parameters](/docs/agent/config/config-files#performance) configuration now gives you tools to trade off performance instead of upsizing servers. You can use the [`consul.raft.leader.lastContact` telemetry](/docs/agent/telemetry#leadership-changes) to observe how the Raft timing is performing and guide the decision to de-tune Raft performance or add more powerful servers. - For DNS-heavy workloads, configuring all Consul agents in a cluster with the - [`allow_stale`](/docs/agent/config/agent-config-files#allow_stale) configuration option will allow reads to + [`allow_stale`](/docs/agent/config/config-files#allow_stale) configuration option will allow reads to scale across all Consul servers, not just the leader. Consul 0.7 and later enables stale reads for DNS by default. See [Stale Reads](https://learn.hashicorp.com/tutorials/consul/dns-caching#stale-reads) in the [DNS Caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) guide for more details. It's also good to set @@ -121,7 +121,7 @@ Here are some general recommendations: [stale consistency mode](/api/features/consistency#stale) available to allow reads to scale across all the servers and not just be forwarded to the leader. -- In Consul 0.9.3 and later, a new [`limits`](/docs/agent/config/agent-config-files#limits) configuration is +- In Consul 0.9.3 and later, a new [`limits`](/docs/agent/config/config-files#limits) configuration is available on Consul clients to limit the RPC request rate they are allowed to make against the Consul servers. After hitting the limit, requests will start to return rate limit errors until time has passed and more requests are allowed. Configuring this across the cluster can help with @@ -156,11 +156,11 @@ For **write-heavy** workloads, the total RAM available for overhead must approxi RAM NEEDED = number of keys * average key size * 2-3x ``` -Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/config/agent-config-cli#_data_dir)) +Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/config/cli-flags#_data_dir)) For a **read-heavy** workload, configure all Consul server agents with the `allow_stale` DNS option, or query the API with the `stale` [consistency mode](/api/features/consistency). By default, all queries made to the server are RPC forwarded to and serviced by the leader. By enabling stale reads, any server will respond to any query, thereby reducing overhead on the leader. Typically, the stale response is `100ms` or less from consistent mode but it drastically improves performance and reduces latency under high load. -If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/config/agent-config-files#max_stale)). +If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/config/config-files#max_stale)). It should be noted that `stale` is not appropriate for coordination where strong consistency is important (i.e. locking or application leader election). For critical cases, the optional `consistent` API query mode is required for true linearizability; the trade off is that this turns a read into a full quorum write so requires more resources and takes longer. @@ -168,7 +168,7 @@ It should be noted that `stale` is not appropriate for coordination where strong Consul’s agents use network sockets for communicating with the other nodes (gossip) and with the server agent. In addition, file descriptors are also opened for watch handlers, health checks, and log files. For a **write heavy** cluster, the `ulimit` size must be increased from the default value (`1024`) to prevent the leader from running out of file descriptors. -To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/config/agent-config-files#limits) +To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/config/config-files#limits) ~> **NOTE** Rate limiting is configured on the client agent only. @@ -191,8 +191,8 @@ Smearing requests over 30s is sufficient to bring RPC load to a reasonable level in all but the very largest clusters, but the extra CPU load from cryptographic operations could impact the server's normal work. To limit that, Consul since 1.4.1 exposes two ways to limit the impact Certificate signing has on the leader -[`csr_max_per_second`](/docs/agent/config/agent-config-files#ca_csr_max_per_second) and -[`csr_max_concurrent`](/docs/agent/config/agent-config-files#ca_csr_max_concurrent). +[`csr_max_per_second`](/docs/agent/config/config-files#ca_csr_max_per_second) and +[`csr_max_concurrent`](/docs/agent/config/config-files#ca_csr_max_concurrent). By default we set a limit of 50 per second which is reasonable on modest hardware but may be too low and impact rotation times if more than 1500 service diff --git a/website/content/docs/install/ports.mdx b/website/content/docs/install/ports.mdx index 6cbc9eb828..0923935ba1 100644 --- a/website/content/docs/install/ports.mdx +++ b/website/content/docs/install/ports.mdx @@ -55,4 +55,4 @@ the Serf WAN port (TCP/UDP) to be listening on both WAN and LAN interfaces. See **Server RPC** This is used by servers to handle incoming requests from other agents. -Note, the default ports can be changed in the [agent configuration](/docs/agent/config/agent-config-files#ports). +Note, the default ports can be changed in the [agent configuration](/docs/agent/config/config-files#ports). diff --git a/website/content/docs/k8s/connect/connect-ca-provider.mdx b/website/content/docs/k8s/connect/connect-ca-provider.mdx index 9d9ce93853..9533c4b77a 100644 --- a/website/content/docs/k8s/connect/connect-ca-provider.mdx +++ b/website/content/docs/k8s/connect/connect-ca-provider.mdx @@ -199,5 +199,5 @@ To update any settings under these keys, you must use Consul's [Update CA Config To renew the Vault token, use the [`vault token renew`](https://www.vaultproject.io/docs/commands/token/renew) CLI command or API. -[`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config -[`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider +[`ca_config`]: /docs/agent/config/config-files#connect_ca_config +[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index 0816ac031a..47dda6da88 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -57,7 +57,7 @@ Use these links to navigate to a particular top-level stanza. the prefix will be `-consul`. - `domain` ((#v-global-domain)) (`string: consul`) - The domain Consul will answer DNS queries for - (see `-domain` (https://consul.io/docs/agent/config/agent-config-cli#_domain)) and the domain services synced from + (see `-domain` (https://consul.io/docs/agent/config/cli-flags#_domain)) and the domain services synced from Consul into Kubernetes will have, e.g. `service-name.service.consul`. - `adminPartitions` ((#v-global-adminpartitions)) - Enabling `adminPartitions` allows creation of Admin Partitions in Kubernetes clusters. @@ -215,7 +215,7 @@ Use these links to navigate to a particular top-level stanza. ``` - `gossipEncryption` ((#v-global-gossipencryption)) - Configures Consul's gossip encryption key. - (see `-encrypt` (https://consul.io/docs/agent/config/agent-config-cli#_encrypt)). + (see `-encrypt` (https://consul.io/docs/agent/config/cli-flags#_encrypt)). By default, gossip encryption is not enabled. The gossip encryption key may be set automatically or manually. The recommended method is to automatically generate the key. To automatically generate and set a gossip encryption key, set autoGenerate to true. @@ -246,7 +246,7 @@ Use these links to navigate to a particular top-level stanza. - `recursors` ((#v-global-recursors)) (`array: []`) - A list of addresses of upstream DNS servers that are used to recursively resolve DNS queries. These values are given as `-recursor` flags to Consul servers and clients. - See https://www.consul.io/docs/agent/config/agent-config-cli#_recursor for more details. + See https://www.consul.io/docs/agent/config/cli-flags#_recursor for more details. If this is an empty array (the default), then Consul DNS will only resolve queries for the Consul top level domain (by default `.consul`). - `tls` ((#v-global-tls)) - Enables TLS (https://learn.hashicorp.com/tutorials/consul/tls-encryption-secure) @@ -778,7 +778,7 @@ Use these links to navigate to a particular top-level stanza. - `image` ((#v-client-image)) (`string: null`) - The name of the Docker image (including any tag) for the containers running Consul client agents. - - `join` ((#v-client-join)) (`array: null`) - A list of valid `-retry-join` values (https://consul.io/docs/agent/config/agent-config-files#retry-join). + - `join` ((#v-client-join)) (`array: null`) - A list of valid `-retry-join` values (https://consul.io/docs/agent/config/config-files#retry-join). If this is `null` (default), then the clients will attempt to automatically join the server cluster running within Kubernetes. This means that with `server.enabled` set to true, clients will automatically @@ -799,7 +799,7 @@ Use these links to navigate to a particular top-level stanza. required for Connect. - `nodeMeta` ((#v-client-nodemeta)) - nodeMeta specifies an arbitrary metadata key/value pair to associate with the node - (see https://www.consul.io/docs/agent/config/agent-config-cli#_node_meta) + (see https://www.consul.io/docs/agent/config/cli-flags#_node_meta) - `pod-name` ((#v-client-nodemeta-pod-name)) (`string: ${HOSTNAME}`) @@ -1152,7 +1152,7 @@ Use these links to navigate to a particular top-level stanza. will inherit from `global.metrics.enabled` value. - `provider` ((#v-ui-metrics-provider)) (`string: prometheus`) - Provider for metrics. See - https://www.consul.io/docs/agent/config/agent-config-files#ui_config_metrics_provider + https://www.consul.io/docs/agent/config/config-files#ui_config_metrics_provider This value is only used if `ui.enabled` is set to true. - `baseURL` ((#v-ui-metrics-baseurl)) (`string: http://prometheus-server`) - baseURL is the URL of the prometheus server, usually the service URL. diff --git a/website/content/docs/k8s/index.mdx b/website/content/docs/k8s/index.mdx index a8811d715b..92f38ee97a 100644 --- a/website/content/docs/k8s/index.mdx +++ b/website/content/docs/k8s/index.mdx @@ -62,7 +62,7 @@ Kubernetes cluster. The server agents are run as a **StatefulSet**, using persistent volume claims to store the server state. This also ensures that the -[node ID](/docs/agent/config/agent-config-cli#_node_id) is persisted so that servers +[node ID](/docs/agent/config/cli-flags#_node_id) is persisted so that servers can be rescheduled onto new IP addresses without causing issues. The server agents are configured with [anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) diff --git a/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx b/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx index f945693c73..73d2885c70 100644 --- a/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx +++ b/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx @@ -22,7 +22,7 @@ you want the clients to be exposed on the Kubernetes internal node IPs (`true`) their pod IPs (`false`). Finally, `client.join` is set to an array of valid -[`-retry-join` values](/docs/agent/config/agent-config-cli#retry-join). In the +[`-retry-join` values](/docs/agent/config/cli-flags#retry-join). In the example above, a fake [cloud auto-join](/docs/agent/cloud-auto-join) value is specified. This should be set to resolve to the proper addresses of your existing Consul cluster. diff --git a/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx b/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx index 5f10a716f2..09d8e8c095 100644 --- a/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx +++ b/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx @@ -271,8 +271,8 @@ The automatically generated federation secret contains: - **Consul server config** - This is a JSON snippet that must be used as part of the server config for secondary datacenters. It sets: - - [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) to the name of the primary datacenter. - - [`primary_gateways`](/docs/agent/config/agent-config-files#primary_gateways) to an array of IPs or hostnames + - [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) to the name of the primary datacenter. + - [`primary_gateways`](/docs/agent/config/config-files#primary_gateways) to an array of IPs or hostnames for the mesh gateways in the primary datacenter. These are the addresses that Consul servers in secondary clusters will use to communicate with the primary datacenter. diff --git a/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx b/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx index 7a1adcd880..e31592ec54 100644 --- a/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx +++ b/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx @@ -91,7 +91,7 @@ The following sections detail how to export this data. ==> Saved dc1-client-consul-0-key.pem ``` - Or use the [auto_encrypt](/docs/agent/config/agent-config-files#auto_encrypt) feature. + Or use the [auto_encrypt](/docs/agent/config/config-files#auto_encrypt) feature. ### Mesh Gateway Addresses diff --git a/website/content/docs/nia/configuration.mdx b/website/content/docs/nia/configuration.mdx index 1dcf4fb3a2..328a07e360 100644 --- a/website/content/docs/nia/configuration.mdx +++ b/website/content/docs/nia/configuration.mdx @@ -61,7 +61,7 @@ tls { The `consul` block is used to configure Consul-Terraform-Sync connection with a Consul agent to perform queries to the Consul Catalog and Consul KV pertaining to task execution. --> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/config/agent-config-files) must be configured for the local Consul with the [cert_file](/docs/agent/config/agent-config-filess#cert_file) and [key_file](/docs/agent/config/agent-config-files#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. +-> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/config/config-files) must be configured for the local Consul with the [cert_file](/docs/agent/config/config-filess#cert_file) and [key_file](/docs/agent/config/config-files#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/installation/requirements#run-an-agent). @@ -80,7 +80,7 @@ consul { - `enabled` - (bool) - `username` - (string) - `password` - (string) -- `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/config/agent-config-files#verify_incoming). +- `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/config/config-files#verify_incoming). - `enabled` - (bool) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly. - `verify` - (bool: true) Enables TLS peer verification. The default is enabled, which will check the global certificate authority (CA) chain to make sure the certificates returned by Consul are valid. - If Consul is using a self-signed certificate that you have not added to the global CA chain, you can set this certificate with `ca_cert` or `ca_path`. Alternatively, you can disable SSL verification by setting `verify` to false. However, disabling verification is a potential security vulnerability. @@ -98,7 +98,7 @@ consul { - `max_idle_conns` - (int: 0) The maximum number of total idle connections across all hosts. The limit is disabled by default. - `max_idle_conns_per_host` - (int: 100) The maximum number of idle connections per remote host. The majority of connections are established with one host, the Consul agent. - To achieve the shortest latency between a Consul service update to a task execution, configure `max_idle_conns_per_host` equal to or greater than the number of services in automation across all tasks. - - This value should be lower than the configured [`http_max_conns_per_client`](https://www.consul.io/docs/agent/config/agent-config-files#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, Consul-Terraform-Sync may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as Consul-Terraform-Sync will contribute to the Consul agent connection limit._ + - This value should be lower than the configured [`http_max_conns_per_client`](https://www.consul.io/docs/agent/config/config-files#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, Consul-Terraform-Sync may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as Consul-Terraform-Sync will contribute to the Consul agent connection limit._ - `tls_handshake_timeout` - (string: "10s") amount of time to wait to complete the TLS handshake. ## Service diff --git a/website/content/docs/nia/installation/requirements.mdx b/website/content/docs/nia/installation/requirements.mdx index e07a644c03..5b66e621a8 100644 --- a/website/content/docs/nia/installation/requirements.mdx +++ b/website/content/docs/nia/installation/requirements.mdx @@ -35,7 +35,7 @@ The Consul agent must be running in order to dynamically update network devices. When running a Consul agent with Consul-Terraform-Sync in production, we suggest to keep a few considerations in mind. Consul-Terraform-Sync uses [blocking queries](/api/features/blocking) to monitor task dependencies, like changes to registered services. This results in multiple long running TCP connections between Consul-Terraform-Sync and the agent to poll changes for each dependency. Monitoring a high number of services may quickly hit the default Consul agent connection limits. -There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between Consul-Terraform-Sync and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync. +There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between Consul-Terraform-Sync and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/config/config-files#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync. ### Register Services diff --git a/website/content/docs/release-notes/1-9-0.mdx b/website/content/docs/release-notes/1-9-0.mdx index 3ce0edf024..675f2befae 100644 --- a/website/content/docs/release-notes/1-9-0.mdx +++ b/website/content/docs/release-notes/1-9-0.mdx @@ -21,7 +21,7 @@ page_title: 1.9.0 - **Active Health Checks for Consul on Kubernetes:** Consul service mesh now integrates with Kubernetes Readiness probes. This provides the ability to natively detect health status from Kubernetes via Readiness probe, and is then used for directing service mesh traffic. - **Streaming:** This feature introduces a major architectural enhancement in how update notifications for blocking queries are delivered within the cluster. Streaming results in very significant reduction of CPU and network bandwidth usage on Consul servers in large-scale deployments. Streaming is particularly helpful in scaling blocking queries in Consul clusters that have rapid changes in service state. - - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](https://www.consul.io/docs/agent/config/agent-config-files#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](https://www.consul.io/docs/agent/config/agent-config-files#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. + - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](https://www.consul.io/docs/agent/config/config-files#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](https://www.consul.io/docs/agent/config/config-files#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. ## What's Changed diff --git a/website/content/docs/security/acl/acl-legacy.mdx b/website/content/docs/security/acl/acl-legacy.mdx index 5a4d87f6c3..f6e5343036 100644 --- a/website/content/docs/security/acl/acl-legacy.mdx +++ b/website/content/docs/security/acl/acl-legacy.mdx @@ -89,7 +89,7 @@ and [Policies](/api/acl/policies). ~> **Warning**: In this document we use the deprecated configuration parameter `acl_datacenter`. In Consul 1.4 and newer the -parameter has been updated to [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter). +parameter has been updated to [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter). Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is @@ -129,7 +129,7 @@ token are automatically applied. The anonymous token is managed using the Tokens are bound to a set of rules that control which Consul resources the token has access to. Policies can be defined in either an allowlist or denylist mode depending on the configuration of -[`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy). If the default +[`acl_default_policy`](/docs/agent/config/config-files#acl_default_policy). If the default policy is to "deny" all actions, then token rules can be set to allowlist specific actions. In the inverse, the "allow" all default behavior is a denylist where rules are used to prohibit actions. By default, Consul will allow all actions. @@ -169,7 +169,7 @@ Constructing rules from these policies is covered in detail in the #### ACL Datacenter All nodes (clients and servers) must be configured with a -[`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) which enables ACL +[`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) which enables ACL enforcement but also specifies the authoritative datacenter. Consul relies on [RPC forwarding](/docs/internals/architecture) to support multi-datacenter configurations. However, because requests can be made across datacenter boundaries, @@ -179,14 +179,14 @@ is considered authoritative and stores the canonical set of tokens. When a request is made to an agent in a non-authoritative datacenter, it must be resolved into the appropriate policy. This is done by reading the token from the authoritative server and caching the result for a configurable -[`acl_ttl`](/docs/agent/config/agent-config-files#acl_ttl). The implication of caching is that +[`acl_ttl`](/docs/agent/config/config-files#acl_ttl). The implication of caching is that the cache TTL is an upper bound on the staleness of policy that is enforced. It is possible to set a zero TTL, but this has adverse performance impacts, as every request requires refreshing the policy via an RPC call. During an outage of the ACL datacenter, or loss of connectivity, the cache will be used as long as the TTL is valid, or the cache may be extended if the -[`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) is set accordingly. +[`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) is set accordingly. This configuration also allows the ACL system to fail open or closed. [ACL replication](#replication) is also available to allow for the full set of ACL tokens to be replicated for use during an outage. @@ -198,10 +198,10 @@ as to whether they are set on servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | --------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- | -| [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | -| [`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | -| [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | -| [`acl_ttl`](/docs/agent/config/agent-config-files#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | +| [`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | +| [`acl_default_policy`](/docs/agent/config/config-files#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | +| [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | +| [`acl_ttl`](/docs/agent/config/config-files#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | There are some additional configuration items related to [ACL replication](#replication) and [Version 8 ACL support](#version_8_acls). These are discussed in those respective sections @@ -212,17 +212,17 @@ system, or accessing Consul in special situations: | Special Token | Servers | Clients | Purpose | | ----------------------------------------------------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | -| [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | -| [`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | -| [`acl_token`](/docs/agent/config/agent-config-files#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | +| [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | +| [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | +| [`acl_master_token`](/docs/agent/config/config-files#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | +| [`acl_token`](/docs/agent/config/config-files#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). #### ACL Agent Master Token -Since the [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): +Since the [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): ```hcl agent "" { @@ -238,7 +238,7 @@ In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via #### ACL Agent Token -The [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/config/agent-config-files#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: +The [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/config/config-files#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: 1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates 2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog @@ -258,7 +258,7 @@ key "_rexec" { } ``` -The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/agent-config-files#disable_remote_exec), the default, then the `key` policy can be omitted. +The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/config-files#disable_remote_exec), the default, then the `key` policy can be omitted. In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). @@ -294,12 +294,12 @@ The servers will need to be restarted to load the new configuration. Please take to start the servers one at a time, and ensure each server has joined and is operating correctly before starting another. -The [`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) will be created +The [`acl_master_token`](/docs/agent/config/config-files#acl_master_token) will be created as a "management" type token automatically. The -[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) is only installed when +[`acl_master_token`](/docs/agent/config/config-files#acl_master_token) is only installed when a server acquires cluster leadership. If you would like to install or change the -[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token), set the new value for -[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) in the configuration +[`acl_master_token`](/docs/agent/config/config-files#acl_master_token), set the new value for +[`acl_master_token`](/docs/agent/config/config-files#acl_master_token) in the configuration for all servers. Once this is done, restart the current leader to force a leader election. In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api/acl/acl#bootstrap-acls) @@ -332,7 +332,7 @@ servers related to permission denied errors: ``` These errors are because the agent doesn't yet have a properly configured -[`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) that it can use for its +[`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) that it can use for its own internal operations like updating its node information in the catalog and performing [anti-entropy](/docs/internals/anti-entropy) syncing. We can create a token using the ACL API, and the ACL master token we set in the previous step: @@ -550,9 +550,9 @@ The next section shows an alternative to the anonymous token. #### Set Agent-Specific Default Tokens (Optional) -An alternative to the anonymous token is the [`acl_token`](/docs/agent/config/agent-config-files#acl_token) +An alternative to the anonymous token is the [`acl_token`](/docs/agent/config/config-files#acl_token) configuration item. When a request is made to a particular Consul agent and no token is -supplied, the [`acl_token`](/docs/agent/config/agent-config-files#acl_token) will be used for the token, +supplied, the [`acl_token`](/docs/agent/config/config-files#acl_token) will be used for the token, instead of being left empty which would normally invoke the anonymous token. In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the @@ -563,7 +563,7 @@ agent, if desired. For example, this allows more fine grained control of what DN given agent can service, or can give the agent read access to some key-value store prefixes by default. -If using [`acl_token`](/docs/agent/config/agent-config-files#acl_token), then it's likely the anonymous +If using [`acl_token`](/docs/agent/config/config-files#acl_token), then it's likely the anonymous token will have a more restrictive policy than shown in the examples here. #### Create Tokens for UI Use (Optional) @@ -727,7 +727,7 @@ starts with "bar". Since [Agent API](/api/agent) utility operations may be required before an agent is joined to a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be -configured with [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token) to allow +configured with [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token) to allow write access to these operations even if no ACL resolution capability is available. #### Event Rules @@ -753,7 +753,7 @@ starts with "deploy". The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to give agents a token with access to this event prefix, in addition to configuring -[`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) to `false`. +[`disable_remote_exec`](/docs/agent/config/config-files#disable_remote_exec) to `false`. #### Key/Value Rules @@ -861,13 +861,13 @@ the example above, the rules allow read-only access to any node name with the em read-write access to any node name that starts with "app", and deny all access to any node name that starts with "admin". -Agents need to be configured with an [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) +Agents need to be configured with an [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) with at least "write" privileges to their own node name in order to register their information with the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. Consul's DNS interface is also affected by restrictions on node rules. If the -[`acl_token`](/docs/agent/config/agent-config-files#acl_token) used by the agent does not have "read" access to a +[`acl_token`](/docs/agent/config/config-files#acl_token) used by the agent does not have "read" access to a given node, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, node rules are @@ -880,7 +880,7 @@ periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require a ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl_token](/docs/agent/config/agent-config-files#acl_token) configuration +1. Using the [acl_token](/docs/agent/config/config-files#acl_token) configuration directive. This allows a single token to be configured globally and used during all check registration operations. 2. Providing an ACL token with service and check definitions at @@ -891,7 +891,7 @@ to use for registration events: [HTTP API](/api) for operations that require them. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) set to `true` in order to enable +[`enable_script_checks`](/docs/agent/config/config-files#enable_script_checks) set to `true` in order to enable script checks. #### Operator Rules @@ -1025,7 +1025,7 @@ read-write access to any service name that starts with "app", and deny all acces starts with "admin". Consul's DNS interface is affected by restrictions on service rules. If the -[`acl_token`](/docs/agent/config/agent-config-files#acl_token) used by the agent does not have "read" access to a +[`acl_token`](/docs/agent/config/config-files#acl_token) used by the agent does not have "read" access to a given service, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, service rules are @@ -1037,7 +1037,7 @@ performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl_token](/docs/agent/config/agent-config-files#acl_token) configuration +1. Using the [acl_token](/docs/agent/config/config-files#acl_token) configuration directive. This allows a single token to be configured globally and used during all service and check registration operations. 2. Providing an ACL token with service and check definitions at registration @@ -1048,12 +1048,12 @@ to use for registration events: API](/api) for operations that require them. **Note:** all tokens passed to an agent are persisted on local disk to allow recovery from restarts. See [`-data-dir` flag - documentation](/docs/agent/config/agent-config-files#acl_token) for notes on securing + documentation](/docs/agent/config/config-files#acl_token) for notes on securing access. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) or -[`enable_local_script_checks`](/docs/agent/config/agent-config-files#enable_local_script_checks) +[`enable_script_checks`](/docs/agent/config/config-files#enable_script_checks) or +[`enable_local_script_checks`](/docs/agent/config/config-files#enable_local_script_checks) set to `true` in order to enable script checks. #### Session Rules @@ -1084,20 +1084,20 @@ name that starts with "admin". #### Outages and ACL Replication ((#replication)) The Consul ACL system is designed with flexible rules to accommodate for an outage -of the [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) or networking +of the [`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) or networking issues preventing access to it. In this case, it may be impossible for agents in non-authoritative datacenters to resolve tokens. Consul provides -a number of configurable [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) +a number of configurable [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) choices to tune behavior. It is possible to deny or permit all actions or to ignore cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs for any previously resolved tokens and to deny any uncached tokens. Consul 0.7 added an ACL Replication capability that can allow non-authoritative datacenter agents to resolve even uncached tokens. This is enabled by setting an -[`acl_replication_token`](/docs/agent/config/agent-config-files#acl_replication_token) in the +[`acl_replication_token`](/docs/agent/config/config-files#acl_replication_token) in the configuration on the servers in the non-authoritative datacenters. In Consul 0.9.1 and later you can enable ACL replication using -[`enable_acl_replication`](/docs/agent/config/agent-config-files#enable_acl_replication) and +[`enable_acl_replication`](/docs/agent/config/config-files#enable_acl_replication) and then set the token later using the [agent token API](/api/agent#update-acl-tokens) on each server. This can also be used to rotate the token without restarting the Consul servers. @@ -1113,7 +1113,7 @@ every 30 seconds. Replicated changes are written at a rate that's throttled to a large set of ACLs. If there's a partition or other outage affecting the authoritative datacenter, -and the [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) +and the [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) is set to "extend-cache", tokens will be resolved during the outage using the replicated set of ACLs. An [ACL replication status](/api/acl/acl#check-acl-replication) endpoint is available to monitor the health of the replication process. @@ -1123,7 +1123,7 @@ already cached and is expired while similar semantics than "extend-cache". It allows to avoid having issues when connectivity with the authoritative is not completely broken, but very slow. -Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/config/agent-config-files#acl_ttl) +Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/config/config-files#acl_ttl) setting of the non-authoritative datacenter, so these entries may persist in the cache for up to the TTL, even after the authoritative datacenter comes back online. @@ -1149,7 +1149,7 @@ Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consu agents for the first time. To ease the transition to Consul 0.8 for existing ACL users, there's a configuration option to disable these new features. To disable support for these new ACLs, set the -[`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8) configuration +[`acl_enforce_version_8`](/docs/agent/config/config-files#acl_enforce_version_8) configuration option to `false` on Consul clients and servers. Here's a summary of the new features: @@ -1172,31 +1172,31 @@ Here's a summary of the new features: Two new configuration options are used once version 8 ACLs are enabled: -- [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token) is used as +- [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token) is used as a special access token that has `agent` ACL policy `write` privileges on each agent where it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token should only be used by operators during outages when Consul servers aren't available to resolve ACL tokens. Applications should use regular ACL tokens during normal operation. -- [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token) is used internally by +- [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) is used internally by Consul agents to perform operations to the service catalog when registering themselves or sending network coordinates to the servers. This token must at least have `node` ACL policy `write` access to the node name it will register as in order to register any node-level information like metadata or tagged addresses. -Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) +Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) now applies to Consul clients as well as Consul servers. This will determine what the client will do in the event that the servers are down. -Consul clients must have [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) configured +Consul clients must have [`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) configured in order to enable agent-level ACL features. If this is set, the agents will contact the Consul servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not enabled, they will check at most every 2 minutes to see if they have become enabled, and will start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will -need to use the [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token) to +need to use the [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token) to perform agent-level operations if the Consul servers aren't present (such as for a manual join -to the cluster), unless the [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) on the +to the cluster), unless the [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) on the agent is set to "allow". Non-server agents do not need to have the -[`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) configured; it is not +[`acl_master_token`](/docs/agent/config/config-files#acl_master_token) configured; it is not used by agents in any way. diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index 511f1ae9f4..11870b996b 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -102,7 +102,7 @@ Use the `policy` keyword and one of the following access levels to set a policy - `write`: Allows the resource to be read and modified. - `deny`: Denies read and write access to the resource. -The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/config/agent-config-files#acl_enable_key_list_policy) setting must be set to `true`. +The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/config/config-files#acl_enable_key_list_policy) setting must be set to `true`. ### Matching and Prefix Values @@ -493,7 +493,7 @@ with `bar`. Since [Agent API](/api/agent) utility operations may be required before an agent is joined to a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be -configured with [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) to allow +configured with [`acl.tokens.agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery) to allow write access to these operations even if no ACL resolution capability is available. ### Event Rules @@ -537,7 +537,7 @@ read-only access to any event, and firing of the "deploy" event. The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to give agents a token with access to this event prefix, in addition to configuring -[`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) to `false`. +[`disable_remote_exec`](/docs/agent/config/config-files#disable_remote_exec) to `false`. ### Key/Value Rules @@ -869,16 +869,16 @@ node "admin" { Agents must be configured with `write` privileges for their own node name so that the agent can register their node metadata, tagged addresses, and other information in the catalog. If configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. -Configure `write` access in the [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) parameter. +Configure `write` access in the [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) parameter. -The [`acl.token.default`](/docs/agent/config/agent-config-files#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. +The [`acl.token.default`](/docs/agent/config/config-files#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. Node rules are used to filter query results when reading from the catalog or retrieving information from the health endpoints. This allows for configurations where a token has access to a given service name, but only on an allowed subset of node names. Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs. These actions may required an ACL token to complete. Use the following methods to configure ACL tokens for registration events: -* Configure a global token in the [acl.tokens.default](/docs/agent/config/agent-config-files#acl_tokens_default) parameter. +* Configure a global token in the [acl.tokens.default](/docs/agent/config/config-files#acl_tokens_default) parameter. This allows a single token to be used during all check registration operations. * Provide an ACL token with service and check definitions at registration time. This allows for greater flexibility and enables the use of multiple tokens on the same agent. @@ -1060,7 +1060,7 @@ service "admin" { Consul's DNS interface is affected by restrictions on service rules. If the -[`acl.tokens.default`](/docs/agent/config/agent-config-files#acl_tokens_default) used by the agent does not have `read` access to a +[`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default) used by the agent does not have `read` access to a given service, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, service rules are @@ -1072,7 +1072,7 @@ performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl.tokens.default](/docs/agent/config/agent-config-files#acl_tokens_default) configuration +1. Using the [acl.tokens.default](/docs/agent/config/config-files#acl_tokens_default) configuration directive. This allows a single token to be configured globally and used during all service and check registration operations. 2. Providing an ACL token with service and check definitions at registration @@ -1083,12 +1083,12 @@ to use for registration events: API](/api) for operations that require them. **Note:** all tokens passed to an agent are persisted on local disk to allow recovery from restarts. See [`-data-dir` flag - documentation](/docs/agent/config/agent-config-files#acl_token) for notes on securing + documentation](/docs/agent/config/config-files#acl_token) for notes on securing access. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) or -[`enable_local_script_checks`](/docs/agent/config/agent-config-files#enable_local_script_checks) +[`enable_script_checks`](/docs/agent/config/config-files#enable_script_checks) or +[`enable_local_script_checks`](/docs/agent/config/config-files#enable_local_script_checks) set to `true` in order to enable script checks. Service rules are also used to grant read or write access to intentions. The diff --git a/website/content/docs/security/acl/acl-system.mdx b/website/content/docs/security/acl/acl-system.mdx index 9d8babfcb1..1d7fb66e44 100644 --- a/website/content/docs/security/acl/acl-system.mdx +++ b/website/content/docs/security/acl/acl-system.mdx @@ -51,7 +51,7 @@ may benefit from additional components in the ACL system: - **ACL Node Identities** - Node identities are a policy template for expressing a link to a policy suitable for use as an [Consul `agent` token - ](/docs/agent/config/agent-config-files#acl_tokens_agent). At authorization time this acts like an + ](/docs/agent/config/config-files#acl_tokens_agent). At authorization time this acts like an additional policy was attached, the contents of which are described further below. These are directly attached to tokens and roles and are not independently configured. (Added in Consul 1.8.1) @@ -174,7 +174,7 @@ examples of using a service identity. -> Added in Consul 1.8.1 An ACL node identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy -suitable for use as an [Consul `agent` token](/docs/agent/config/agent-config-files#acl_tokens_agent). They are usable +suitable for use as an [Consul `agent` token](/docs/agent/config/config-files#acl_tokens_agent). They are usable on both tokens and roles and are composed of the following elements: - **Node Name** - The name of the node to grant access to. @@ -309,7 +309,7 @@ token will be used. The rules from all policies, roles, and service identities linked with a token are combined to form that token's effective rule set. Policy rules can be defined in either an allowlist or denylist -mode depending on the configuration of [`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy). +mode depending on the configuration of [`acl_default_policy`](/docs/agent/config/config-files#acl_default_policy). If the default policy is to "deny" access to all resources, then policy rules can be set to allowlist access to specific resources. Conversely, if the default policy is “allow” then policy rules can be used to explicitly deny access to resources. @@ -358,22 +358,22 @@ as to whether they are set on servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | -------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- | -| [`acl.enabled`](/docs/agent/config/agent-config-files#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | -| [`acl.default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | -| [`acl.down_policy`](/docs/agent/config/agent-config-files#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | -| [`acl.role_ttl`](/docs/agent/config/agent-config-files#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | -| [`acl.policy_ttl`](/docs/agent/config/agent-config-files#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | -| [`acl.token_ttl`](/docs/agent/config/agent-config-files#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | +| [`acl.enabled`](/docs/agent/config/config-files#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | +| [`acl.default_policy`](/docs/agent/config/config-files#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | +| [`acl.down_policy`](/docs/agent/config/config-files#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | +| [`acl.role_ttl`](/docs/agent/config/config-files#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | +| [`acl.policy_ttl`](/docs/agent/config/config-files#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | +| [`acl.token_ttl`](/docs/agent/config/config-files#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | A number of special tokens can also be configured which allow for bootstrapping the ACL system, or accessing Consul in special situations: | Special Token | Servers | Clients | Purpose | | ------------------------------------------------------------------------------------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Recovery Token](#acl-agent-recovery-token) section for more details | -| [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | -| [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details | -| [`acl.tokens.default`](/docs/agent/config/agent-config-files#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | +| [`acl.tokens.agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Recovery Token](#acl-agent-recovery-token) section for more details | +| [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | +| [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details | +| [`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | All of these tokens except the `initial_management` token can all be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). @@ -381,12 +381,12 @@ In Consul 1.4 - 1.10, the following special tokens were known by different names | New Name (1.11+) | Old Name (1.4 - 1.10) | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | -| [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/config/agent-config-files#acl_tokens_agent_master) | -| [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/config/agent-config-files#acl_tokens_master) | +| [`acl.tokens.agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/config/config-files#acl_tokens_agent_master) | +| [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/config/config-files#acl_tokens_master) | #### ACL Agent Recovery Token -Since the [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it +Since the [`acl.tokens.agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it In Consul 1.4 - 1.10, this was called the `agent_master` token. It was renamed to `agent_recovery` token in Consul 1.11. @@ -401,7 +401,7 @@ node_prefix "" { #### ACL Agent Token -The [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/config/agent-config-files#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: +The [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: 1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates 2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog @@ -421,7 +421,7 @@ key_prefix "_rexec" { } ``` -The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/agent-config-files#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. +The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/config-files#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. ## Next Steps diff --git a/website/content/docs/security/acl/auth-methods/index.mdx b/website/content/docs/security/acl/auth-methods/index.mdx index 4a1dd9e634..fa4aa8b46a 100644 --- a/website/content/docs/security/acl/auth-methods/index.mdx +++ b/website/content/docs/security/acl/auth-methods/index.mdx @@ -60,7 +60,7 @@ using the API or command line before they can be used by applications. endpoints](/api/acl/binding-rules). -> **Note** - To configure auth methods in any connected secondary datacenter, -[ACL token replication](/docs/agent/config/agent-config-files#acl_enable_token_replication) +[ACL token replication](/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Auth methods require the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. diff --git a/website/content/docs/security/encryption.mdx b/website/content/docs/security/encryption.mdx index 75b2ba56c4..d23c29d4c0 100644 --- a/website/content/docs/security/encryption.mdx +++ b/website/content/docs/security/encryption.mdx @@ -75,17 +75,17 @@ CA then signs keys for each of the agents, as in ~> Certificates need to be created with x509v3 extendedKeyUsage attributes for both clientAuth and serverAuth since Consul uses a single cert/key pair for both server and client communications. TLS can be used to verify the authenticity of the servers or verify the authenticity of clients. -These modes are controlled by the [`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing), -[`verify_server_hostname`](/docs/agent/config/agent-config-files#verify_server_hostname), -and [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) options, respectively. +These modes are controlled by the [`verify_outgoing`](/docs/agent/config/config-files#verify_outgoing), +[`verify_server_hostname`](/docs/agent/config/config-files#verify_server_hostname), +and [`verify_incoming`](/docs/agent/config/config-files#verify_incoming) options, respectively. -If [`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing) is set, agents verify the +If [`verify_outgoing`](/docs/agent/config/config-files#verify_outgoing) is set, agents verify the authenticity of Consul for outgoing connections. Server nodes must present a certificate signed by a common certificate authority present on all agents, set via the agent's -[`ca_file`](/docs/agent/config/agent-config-files#ca_file) and [`ca_path`](/docs/agent/config/agent-config-files#ca_path) -options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/config/agent-config-files#cert_file) and [`key_file`](/docs/agent/config/agent-config-files#key_file). +[`ca_file`](/docs/agent/config/config-files#ca_file) and [`ca_path`](/docs/agent/config/config-files#ca_path) +options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/config/config-files#cert_file) and [`key_file`](/docs/agent/config/config-files#key_file). -If [`verify_server_hostname`](/docs/agent/config/agent-config-files#verify_server_hostname) is set, then +If [`verify_server_hostname`](/docs/agent/config/config-files#verify_server_hostname) is set, then outgoing connections perform hostname verification. All servers must have a certificate valid for `server..` or the client will reject the handshake. This is a new configuration as of 0.5.1, and it is used to prevent a compromised client from being @@ -93,12 +93,12 @@ able to restart in server mode and perform a MITM (Man-In-The-Middle) attack. Ne to true, and generate the proper certificates, but this is defaulted to false to avoid breaking existing deployments. -If [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) is set, the servers verify the +If [`verify_incoming`](/docs/agent/config/config-files#verify_incoming) is set, the servers verify the authenticity of all incoming connections. All clients must have a valid key pair set using -[`cert_file`](/docs/agent/config/agent-config-files#cert_file) and -[`key_file`](/docs/agent/config/agent-config-files#key_file). Servers will +[`cert_file`](/docs/agent/config/config-files#cert_file) and +[`key_file`](/docs/agent/config/config-files#key_file). Servers will also disallow any non-TLS connections. To force clients to use TLS, -[`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing) must also be set. +[`verify_outgoing`](/docs/agent/config/config-files#verify_outgoing) must also be set. TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP and is secured using a symmetric key. See above for enabling gossip encryption. diff --git a/website/content/docs/security/security-models/core.mdx b/website/content/docs/security/security-models/core.mdx index 1a15df739d..8952c6fd11 100644 --- a/website/content/docs/security/security-models/core.mdx +++ b/website/content/docs/security/security-models/core.mdx @@ -72,28 +72,28 @@ environment and adapt these configurations accordingly. - **mTLS** - Mutual authentication of both the TLS server and client x509 certificates prevents internal abuse through unauthorized access to Consul agents within the cluster. - - [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) - By default this is false, and should almost always be set + - [`verify_incoming`](/docs/agent/config/config-files#verify_incoming) - By default this is false, and should almost always be set to true to require TLS verification for incoming client connections. This applies to both server RPC and to the HTTPS API. - - [`verify_incoming_https`](/docs/agent/config/agent-config-files#verify_incoming_https) - By default this is false, and should be set + - [`verify_incoming_https`](/docs/agent/config/config-files#verify_incoming_https) - By default this is false, and should be set to true to require clients to provide a valid TLS certificate when the Consul HTTPS API is enabled. TLS for the API may be not be necessary if it is exclusively served over a loopback interface such as `localhost`. - - [`verify_incoming_rpc`](/docs/agent/config/agent-config-files#verify_incoming_rpc) - By default this is false, and should almost + - [`verify_incoming_rpc`](/docs/agent/config/config-files#verify_incoming_rpc) - By default this is false, and should almost always be set to true to require clients to provide a valid TLS certificate for Consul agent RPCs. - - [`verify_outgoing`](/docs/agent/config/agent-config-files#verify_outgoing) - By default this is false, and should be set to true to + - [`verify_outgoing`](/docs/agent/config/config-files#verify_outgoing) - By default this is false, and should be set to true to require TLS for outgoing connections from server or client agents. Servers that specify `verify_outgoing = true` will always talk to other servers over TLS, but they still accept non-TLS connections to allow for a transition of all clients to TLS. Currently the only way to enforce that no client can communicate with a server unencrypted is to also enable `verify_incoming` which requires client certificates too. - - [`enable_agent_tls_for_checks`](/docs/agent/config/agent-config-files#enable_agent_tls_for_checks) - By default this is false, and + - [`enable_agent_tls_for_checks`](/docs/agent/config/config-files#enable_agent_tls_for_checks) - By default this is false, and should almost always be set to true to require mTLS to set up the client for HTTP or gRPC health checks. This was added in Consul 1.0.1. - - [`verify_server_hostname`](/docs/agent/config/agent-config-files#verify_server_hostname) - By default this is false, and should be + - [`verify_server_hostname`](/docs/agent/config/config-files#verify_server_hostname) - By default this is false, and should be set to true to require that the TLS certificate presented by the servers matches `server..` hostname for outgoing TLS connections. The default configuration does not verify the hostname of the certificate, only that it is signed by a trusted CA. This setting is critical to prevent a @@ -104,14 +104,14 @@ environment and adapt these configurations accordingly. [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) for more details. This is fixed in 1.4.1. - - [`auto_encrypt`](/docs/agent/config/agent-config-files#auto_encrypt) - Enables automated TLS certificate distribution for client - agent RPC communication using the Connect CA. Using this configuration a [`ca_file`](/docs/agent/config/agent-config-files#ca_file) + - [`auto_encrypt`](/docs/agent/config/config-files#auto_encrypt) - Enables automated TLS certificate distribution for client + agent RPC communication using the Connect CA. Using this configuration a [`ca_file`](/docs/agent/config/config-files#ca_file) and ACL token would still need to be distributed to client agents. - - [`allow_tls`](/docs/agent/config/agent-config-files#allow_tls) - By default this is false, and should be set to true on server + - [`allow_tls`](/docs/agent/config/config-files#allow_tls) - By default this is false, and should be set to true on server agents to allow certificates to be automatically generated and distributed from the Connect CA to client agents. - - [`tls`](/docs/agent/config/agent-config-files#tls) - By default this is false, and should be set to true on client agents to + - [`tls`](/docs/agent/config/config-files#tls) - By default this is false, and should be set to true on client agents to automatically request a client TLS certificate from the server's Connect CA. **Example Server Agent TLS Configuration** @@ -144,7 +144,7 @@ environment and adapt these configurations accordingly. } ``` - -> The client agent TLS configuration from above sets [`verify_incoming`](/docs/agent/config/agent-config-files#verify_incoming) to + -> The client agent TLS configuration from above sets [`verify_incoming`](/docs/agent/config/config-files#verify_incoming) to false which assumes all incoming traffic is restricted to `localhost`. The primary benefit for this configuration would be to avoid provisioning client TLS certificates (in addition to ACL tokens) for all tools or applications using the local Consul agent. In this case ACLs should be enabled to provide authorization and only ACL tokens would @@ -152,7 +152,7 @@ environment and adapt these configurations accordingly. - **ACLs** - The access control list (ACL) system provides a security mechanism for Consul administrators to grant capabilities tied to an individual human, or machine operator identity. To ultimately secure the ACL system, - administrators should configure the [`default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) to "deny". + administrators should configure the [`default_policy`](/docs/agent/config/config-files#acl_default_policy) to "deny". The [system](/docs/acl/acl-system) is comprised of five major components: @@ -179,10 +179,10 @@ environment and adapt these configurations accordingly. Two optional gossip encryption options enable Consul servers without gossip encryption to safely upgrade. After upgrading, the verification options should be enabled, or removed to set them to their default state: - - [`encrypt_verify_incoming`](/docs/agent/config/agent-config-files#encrypt_verify_incoming) - By default this is true to enforce + - [`encrypt_verify_incoming`](/docs/agent/config/config-files#encrypt_verify_incoming) - By default this is true to enforce encryption on _incoming_ gossip communications. - - [`encrypt_verify_outgoing`](/docs/agent/config/agent-config-files#encrypt_verify_outgoing) - By default this is true to enforce + - [`encrypt_verify_outgoing`](/docs/agent/config/config-files#encrypt_verify_outgoing) - By default this is true to enforce encryption on _outgoing_ gossip communications. - **Namespaces** - Read and write operations should be scoped to logical namespaces to @@ -223,19 +223,19 @@ environment and adapt these configurations accordingly. - **Linux Security Modules** - Use of security modules that can be directly integrated into operating systems such as AppArmor, SElinux, and Seccomp on Consul agent hosts. -- **Customize TLS Settings** - TLS settings such as the [available cipher suites](/docs/agent/config/agent-config-files#tls_cipher_suites), +- **Customize TLS Settings** - TLS settings such as the [available cipher suites](/docs/agent/config/config-files#tls_cipher_suites), should be tuned to fit the needs of your environment. - - [`tls_min_version`](/docs/agent/config/agent-config-files#tls_min_version) - Used to specify the minimum TLS version to use. + - [`tls_min_version`](/docs/agent/config/config-files#tls_min_version) - Used to specify the minimum TLS version to use. - - [`tls_cipher_suites`](/docs/agent/config/agent-config-files#tls_cipher_suites) - Used to specify which TLS cipher suites are allowed. + - [`tls_cipher_suites`](/docs/agent/config/config-files#tls_cipher_suites) - Used to specify which TLS cipher suites are allowed. - - [`tls_prefer_server_cipher_suites`](/docs/agent/config/agent-config-files#tls_prefer_server_cipher_suites) - Used to specify which TLS + - [`tls_prefer_server_cipher_suites`](/docs/agent/config/config-files#tls_prefer_server_cipher_suites) - Used to specify which TLS cipher suites are preferred on the server side. - **Customize HTTP Response Headers** - Additional security headers, such as [`X-XSS-Protection`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection), can be - [configured](https://www.consul.io/docs/agent/config/agent-config-files#response_headers) for HTTP API responses. + [configured](https://www.consul.io/docs/agent/config/config-files#response_headers) for HTTP API responses. ```hcl http_config { @@ -248,28 +248,28 @@ environment and adapt these configurations accordingly. - **Customize Default Limits** - Consul has a number of builtin features with default connection limits that should be tuned to fit your environment. - - [`http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) - Used to limit concurrent access from + - [`http_max_conns_per_client`](/docs/agent/config/config-files#http_max_conns_per_client) - Used to limit concurrent access from a single client to the HTTP(S) endpoint on Consul agents. - - [`https_handshake_timeout`](/docs/agent/config/agent-config-files#https_handshake_timeout) - Used to timeout TLS connection for the + - [`https_handshake_timeout`](/docs/agent/config/config-files#https_handshake_timeout) - Used to timeout TLS connection for the HTTP(S) endpoint for Consul agents. - - [`rpc_handshake_timeout`](/docs/agent/config/agent-config-files#rpc_handshake_timeout) - Used to timeout TLS connections for the RPC + - [`rpc_handshake_timeout`](/docs/agent/config/config-files#rpc_handshake_timeout) - Used to timeout TLS connections for the RPC endpoint for Consul agents. - - [`rpc_max_conns_per_client`](/docs/agent/config/agent-config-files#rpc_max_conns_per_client) - Used to limit concurrent access from a + - [`rpc_max_conns_per_client`](/docs/agent/config/config-files#rpc_max_conns_per_client) - Used to limit concurrent access from a single client to the RPC endpoint on Consul agents. - - [`rpc_rate`](/docs/agent/config/agent-config-files#rpc_rate) - Disabled by default, this is used to limit (requests/second) for client + - [`rpc_rate`](/docs/agent/config/config-files#rpc_rate) - Disabled by default, this is used to limit (requests/second) for client agents making RPC calls to server agents. - - [`rpc_max_burst`](/docs/agent/config/agent-config-files#rpc_max_burst) - Used as the token bucket size for client agents making RPC + - [`rpc_max_burst`](/docs/agent/config/config-files#rpc_max_burst) - Used as the token bucket size for client agents making RPC calls to server agents. - - [`kv_max_value_size`](/docs/agent/config/agent-config-files#kv_max_value_size) - Used to configure the max number of bytes in a + - [`kv_max_value_size`](/docs/agent/config/config-files#kv_max_value_size) - Used to configure the max number of bytes in a key-value API request. - - [`txn_max_req_len`](/docs/agent/config/agent-config-files#txn_max_req_len) - Used to configure the max number of bytes in a + - [`txn_max_req_len`](/docs/agent/config/config-files#txn_max_req_len) - Used to configure the max number of bytes in a transaction API request. - **Secure UI Access** - Access to Consul’s builtin UI can be secured in various ways: @@ -289,7 +289,7 @@ environment and adapt these configurations accordingly. [Securing Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production), which includes a section on [creating ACL tokens that provide a desired level UI access](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#consul-ui-token). - - **Restrict HTTP Writes** - Using the [`allow_write_http_from`](/docs/agent/config/agent-config-files#allow_write_http_from) + - **Restrict HTTP Writes** - Using the [`allow_write_http_from`](/docs/agent/config/config-files#allow_write_http_from) configuration option to restrict write access for agent endpoints to hosts on the specified list of CIDRs. **Example Agent Configuration** diff --git a/website/content/docs/troubleshoot/common-errors.mdx b/website/content/docs/troubleshoot/common-errors.mdx index 762d38721f..065ae703e5 100644 --- a/website/content/docs/troubleshoot/common-errors.mdx +++ b/website/content/docs/troubleshoot/common-errors.mdx @@ -198,14 +198,14 @@ We recommend raising an issue with the CNI you're using to add support for `host and switching back to `hostPort` eventually. [troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting -[node_name]: /docs/agent/config/agent-config-files#node_name -[retry_join]: /docs/agent/config/agent-config-cli#retry-join +[node_name]: /docs/agent/config/config-files#node_name +[retry_join]: /docs/agent/config/cli-flags#retry-join [license]: /commands/license [releases]: https://releases.hashicorp.com/consul/ [files]: https://easyengine.io/tutorials/linux/increase-open-files-limit [certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates [systemd]: https://learn.hashicorp.com/consul/advanced/day-1-operations/deployment-guide#configure-systemd [monitoring]: https://learn.hashicorp.com/consul/advanced/day-1-operations/monitoring -[bind]: /docs/agent/config/agent-config-cli#_bind +[bind]: /docs/agent/config/cli-flags#_bind [jq]: https://stedolan.github.io/jq/ [go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template diff --git a/website/content/docs/troubleshoot/faq.mdx b/website/content/docs/troubleshoot/faq.mdx index 9ebb19b45b..18ef8d704e 100644 --- a/website/content/docs/troubleshoot/faq.mdx +++ b/website/content/docs/troubleshoot/faq.mdx @@ -62,8 +62,8 @@ messages. This anonymous ID can be disabled. In fact, using the Checkpoint service is optional and can be disabled. -See [`disable_anonymous_signature`](/docs/agent/config/agent-config-files#disable_anonymous_signature) -and [`disable_update_check`](/docs/agent/config/agent-config-files#disable_update_check). +See [`disable_anonymous_signature`](/docs/agent/config/config-files#disable_anonymous_signature) +and [`disable_update_check`](/docs/agent/config/config-files#disable_update_check). ### Q: Does Consul rely on UDP Broadcast or Multicast? @@ -116,7 +116,7 @@ as well as race conditions between data updates and watch registrations. ### Q: What network ports does Consul use? -The [Ports Used](/docs/agent/config/agent-config-files#ports) section of the Configuration +The [Ports Used](/docs/agent/config/config-files#ports) section of the Configuration documentation lists all ports that Consul uses. ### Q: Does Consul require certain user process resource limits? @@ -143,7 +143,7 @@ of any excessive resource utilization before arbitrarily increasing the limits. The default recommended limit on a key's value size is 512KB. This is strictly enforced and an HTTP 413 status will be returned to any client that attempts to store more than that limit in a value. The limit can be increased by using the -[`kv_max_value_size`](/docs/agent/config/agent-config-files#kv_max_value_size) configuration option. +[`kv_max_value_size`](/docs/agent/config/config-files#kv_max_value_size) configuration option. It should be noted that the Consul key/value store is not designed to be used as a general purpose database. See diff --git a/website/content/docs/upgrading/instructions/general-process.mdx b/website/content/docs/upgrading/instructions/general-process.mdx index c559058aa2..b27bd2b4f2 100644 --- a/website/content/docs/upgrading/instructions/general-process.mdx +++ b/website/content/docs/upgrading/instructions/general-process.mdx @@ -74,7 +74,7 @@ this snapshot somewhere safe. More documentation on snapshot usage is available - https://www.consul.io/commands/snapshot - https://learn.hashicorp.com/tutorials/consul/backup-and-restore -**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/config/agent-config-cli#_log_level) +**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/config/cli-flags#_log_level) is set to `debug`. After doing this, issue the following command on your servers to reload the configuration: @@ -183,7 +183,7 @@ then the following options for further assistance are available: When contacting Hashicorp Support, please include the following information in your ticket: - Consul version you were upgrading FROM and TO. -- [Debug level logs](/docs/agent/config/agent-config-cli#_log_level) from all servers in the cluster +- [Debug level logs](/docs/agent/config/cli-flags#_log_level) from all servers in the cluster that you are having trouble with. These should include logs from prior to the upgrade attempt up through the current time. If your logs were not set at debug level prior to the upgrade, please include those logs as well. Also, update your config to use debug logs, diff --git a/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx b/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx index e83820459d..76063aa2ba 100644 --- a/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx +++ b/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx @@ -51,7 +51,7 @@ Looking through these changes prior to upgrading is highly recommended. Two very notable items are: - 1.6.2 introduced more strict JSON decoding. Invalid JSON that was previously ignored might result in errors now (e.g., `Connect: null` in service definitions). See [[GH#6680](https://github.com/hashicorp/consul/pull/6680)]. -- 1.6.3 introduced the [http_max_conns_per_client](https://www.consul.io/docs/agent/config/agent-config-files.html#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] +- 1.6.3 introduced the [http_max_conns_per_client](https://www.consul.io/docs/agent/config/config-files.html#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] ## Procedure @@ -202,8 +202,8 @@ update those now to avoid issues when moving to newer versions. These are the changes you will need to make: -- `acl_datacenter` is now named `primary_datacenter` (review our [docs](https://www.consul.io/docs/agent/config/agent-config-files#primary_datacenter) for more info) -- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](https://www.consul.io/docs/agent/config/agent-config-files#acl) for more info): +- `acl_datacenter` is now named `primary_datacenter` (review our [docs](https://www.consul.io/docs/agent/config/config-files#primary_datacenter) for more info) +- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](https://www.consul.io/docs/agent/config/config-files#acl) for more info): ```hcl acl { enabled = true/false diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 32fb884c24..52bf8416cc 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -42,7 +42,7 @@ Due to this rename the following endpoint is also deprecated: These config keys are now deprecated: - `audit.sink[].name` - - [`dns_config.dns_prefer_namespace`](/docs/agent/config/agent-config-files#dns_prefer_namespace) + - [`dns_config.dns_prefer_namespace`](/docs/agent/config/config-files#dns_prefer_namespace) ### Deprecated CLI Subcommands @@ -107,8 +107,8 @@ have a license loaded from a configuration file or from their environment the sa agents must have the license specified. Both agents can still perform automatic retrieval of their license but with a few extra stipulations. First, license auto-retrieval now requires that ACLs are on and that the client or snapshot agent is configured with a valid ACL token. Secondly, client -agents require that either the [`start_join`](/docs/agent/config/agent-config-files#start_join) or -[`retry_join`](/docs/agent/config/agent-config-files#retry_join) configurations are set and that they resolve to server +agents require that either the [`start_join`](/docs/agent/config/config-files#start_join) or +[`retry_join`](/docs/agent/config/config-files#retry_join) configurations are set and that they resolve to server agents. If those stipulations are not met, attempting to start the client or snapshot agent will result in it immediately shutting down. @@ -202,7 +202,7 @@ to Consul 1.9.0. ### Changes to Configuration Defaults -The [`enable_central_service_config`](/docs/agent/config/agent-config-files#enable_central_service_config) +The [`enable_central_service_config`](/docs/agent/config/config-files#enable_central_service_config) configuration now defaults to `true`. ### Changes to Intentions @@ -271,7 +271,7 @@ behavior: #### Removal of Deprecated Features -The [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8) +The [`acl_enforce_version_8`](/docs/agent/config/config-files#acl_enforce_version_8) configuration has been removed (with version 8 ACL support by being on by default). @@ -314,7 +314,7 @@ to more precisely capture the view of _active_ blocking queries. ### Vault: default `http_max_conns_per_client` too low to run Vault properly -Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/config/agent-config-files#http_max_conns_per_client). The default value +Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/config/config-files#http_max_conns_per_client). The default value was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.7.0, you should change the value to 200. Starting with Consul 1.7.1 this is the new default. @@ -322,7 +322,7 @@ Starting with Consul 1.7.1 this is the new default. ### Vault: default `http_max_conns_per_client` too low to run Vault properly -Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/config/agent-config-files#http_max_conns_per_client). The default value +Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/config/config-files#http_max_conns_per_client). The default value was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.6.3 through 1.7.0, you should change the value to 200. Starting with Consul 1.7.1 this is the new default. @@ -361,7 +361,7 @@ datacenter". All configuration is backwards compatible and shouldn't need to change prior to upgrade although it's strongly recommended to migrate ACL configuration to the new syntax soon after upgrade. This includes moving to `primary_datacenter` rather than `acl_datacenter` and `acl_*` to the new [ACL -block](/docs/agent/config/agent-config-files#acl). +block](/docs/agent/config/config-files#acl). Datacenters can be upgraded in any order although secondaries will remain in [Legacy ACL mode](#legacy-acl-mode) until the primary datacenter is fully @@ -488,11 +488,11 @@ The following previously deprecated fields and config options have been removed: Consul 1.0.1 (and earlier versions of Consul) checked for raft snapshots every 5 seconds, and created new snapshots for every 8192 writes. These defaults cause constant disk IO in large busy clusters. Consul 1.1.0 increases these to larger values, -and makes them tunable via the [raft_snapshot_interval](/docs/agent/config/agent-config-files#_raft_snapshot_interval) and -[raft_snapshot_threshold](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) parameters. We recommend +and makes them tunable via the [raft_snapshot_interval](/docs/agent/config/config-files#_raft_snapshot_interval) and +[raft_snapshot_threshold](/docs/agent/config/config-files#_raft_snapshot_threshold) parameters. We recommend keeping the new defaults. However, operators can go back to the old defaults by changing their -config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/config/agent-config-files#_raft_snapshot_interval) -and [raft_snapshot_threshold](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) to understand the trade-offs +config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/config/config-files#_raft_snapshot_interval) +and [raft_snapshot_threshold](/docs/agent/config/config-files#_raft_snapshot_threshold) to understand the trade-offs when tuning these. ## Consul 1.0.7 @@ -520,7 +520,7 @@ before proceeding. #### Carefully Check and Remove Stale Servers During Rolling Upgrades Consul 1.0 (and earlier versions of Consul when running with [Raft protocol -3](/docs/agent/config/agent-config-files#_raft_protocol) had an issue where performing +3](/docs/agent/config/config-files#_raft_protocol) had an issue where performing rolling updates of Consul servers could result in an outage from old servers remaining in the cluster. [Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) @@ -541,7 +541,7 @@ Please be sure to read over all the details here before upgrading. #### Raft Protocol Now Defaults to 3 -The [`-raft-protocol`](/docs/agent/config/agent-config-cli#_raft_protocol) default has +The [`-raft-protocol`](/docs/agent/config/cli-flags#_raft_protocol) default has been changed from 2 to 3, enabling all [Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) features by default. @@ -570,7 +570,7 @@ servers, and then slowly stand down each of the older servers in a similar fashion. When using Raft protocol version 3, servers are identified by their -[`-node-id`](/docs/agent/config/agent-config-cli#_node_id) instead of their IP address +[`-node-id`](/docs/agent/config/cli-flags#_node_id) instead of their IP address when Consul makes changes to its internal Raft quorum configuration. This means that once a cluster has been upgraded with servers all running Raft protocol version 3, it will no longer allow servers running any older Raft protocol @@ -585,7 +585,7 @@ to map the server to its node ID in the Raft quorum configuration. As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format for Consul's config files, an `.hcl` or `.json` extension is required for all config files loaded by Consul, even when using the -[`-config-file`](/docs/agent/config/agent-config-cli#_config_file) argument to specify a +[`-config-file`](/docs/agent/config/cli-flags#_config_file) argument to specify a file directly. #### Service Definition Parameter Case changed @@ -602,30 +602,30 @@ upgrading. Here's the complete list of removed options and their equivalents: | Removed Option | Equivalent | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-dc` | [`-datacenter`](/docs/agent/config/agent-config-cli#_datacenter) | -| `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | +| `-dc` | [`-datacenter`](/docs/agent/config/cli-flags#_datacenter) | +| `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | | `addresses.rpc` | None, the RPC server for CLI commands is no longer supported. | -| `advertise_addrs` | [`ports`](/docs/agent/config/agent-config-files#ports) with [`advertise_addr`](/docs/agent/config/agent-config-files#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/config/agent-config-files#advertise_addr_wan) | -| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/config/agent-config-files#telemetry-dogstatsd_addr) | -| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/config/agent-config-files#telemetry-dogstatsd_tags) | -| `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/config/agent-config-files#response_headers) | +| `advertise_addrs` | [`ports`](/docs/agent/config/config-files#ports) with [`advertise_addr`](/docs/agent/config/config-files#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/config/config-files#advertise_addr_wan) | +| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/config/config-files#telemetry-dogstatsd_addr) | +| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/config/config-files#telemetry-dogstatsd_tags) | +| `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/config/config-files#response_headers) | | `ports.rpc` | None, the RPC server for CLI commands is no longer supported. | -| `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/agent-config-files.mdx#recursors) | -| `retry_join_azure` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `retry_join_ec2` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `retry_join_gce` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) | -| `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/agent-config-files.mdx#telemetry-statsd_address) | -| `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/agent-config-files.mdx#telemetry-statsite_address) | -| `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix) | -| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix) | +| `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/config-files.mdx#recursors) | +| `retry_join_azure` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `retry_join_ec2` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `retry_join_gce` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/config-files.mdx#telemetry-statsd_address) | +| `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/config/config-files.mdx#telemetry-statsite_address) | +| `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/config-files#telemetry-metrics_prefix) | +| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/config-files#telemetry-metrics_prefix) | | (service definitions) `serviceid` | [`service_id`](/docs/agent/services) | | (service definitions) `dockercontainerid` | [`docker_container_id`](/docs/agent/services) | | (service definitions) `tlsskipverify` | [`tls_skip_verify`](/docs/agent/services) | @@ -635,7 +635,7 @@ upgrading. Here's the complete list of removed options and their equivalents: Since the `statsite_prefix` configuration option applied to all telemetry providers, `statsite_prefix` was renamed to -[`metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix). +[`metrics_prefix`](/docs/agent/config/config-files#telemetry-metrics_prefix). Configuration files will need to be updated when upgrading to this version of Consul. @@ -647,8 +647,8 @@ wrongly stated that you could configure both host and port. #### Escaping Behavior Changed for go-discover Configs -The format for [`-retry-join`](/docs/agent/config/agent-config-cli#retry-join) and -[`-retry-join-wan`](/docs/agent/config/agent-config-cli#retry-join-wan) values that use +The format for [`-retry-join`](/docs/agent/config/cli-flags#retry-join) and +[`-retry-join-wan`](/docs/agent/config/cli-flags#retry-join-wan) values that use [go-discover](https://github.com/hashicorp/go-discover) cloud auto joining has changed. Values in `key=val` sequences must no longer be URL encoded and can be provided as literals as long as they do not contain spaces, backslashes `\` or @@ -766,7 +766,7 @@ invalid health checks would get skipped. #### Script Checks Are Now Opt-In -A new [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks) +A new [`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks) configuration option was added, and defaults to `false`, meaning that in order to allow an agent to run health checks that execute scripts, this will need to be configured and set to `true`. This provides a safer out-of-the-box @@ -788,10 +788,10 @@ for more information. Consul releases will no longer include a `web_ui.zip` file with the compiled web assets. These have been built in to the Consul binary since the 0.7.x -series and can be enabled with the [`-ui`](/docs/agent/config/agent-config-cli#_ui) +series and can be enabled with the [`-ui`](/docs/agent/config/cli-flags#_ui) configuration option. These built-in web assets have always been identical to the contents of the `web_ui.zip` file for each release. The -[`-ui-dir`](/docs/agent/config/agent-config-cli#_ui_dir) option is still available for +[`-ui-dir`](/docs/agent/config/cli-flags#_ui_dir) option is still available for hosting customized versions of the web assets, but the vast majority of Consul users can just use the built in web assets. @@ -823,12 +823,12 @@ to the following commands: #### Version 8 ACLs Are Now Opt-Out -The [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8) +The [`acl_enforce_version_8`](/docs/agent/config/config-files#acl_enforce_version_8) configuration now defaults to `true` to enable full version 8 ACL support by default. If you are upgrading an existing cluster with ACLs enabled, you will need to set this to `false` during the upgrade on **both Consul agents and Consul servers**. Version 8 ACLs were also changed so that -[`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) must be set on +[`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) must be set on agents in order to enable the agent-side enforcement of ACLs. This makes for a smoother experience in clusters where ACLs aren't enabled at all, but where the agents would have to wait to contact a Consul server before learning that. @@ -836,14 +836,14 @@ agents would have to wait to contact a Consul server before learning that. #### Remote Exec Is Now Opt-In The default for -[`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) was +[`disable_remote_exec`](/docs/agent/config/config-files#disable_remote_exec) was changed to "true", so now operators need to opt-in to having agents support running commands remotely via [`consul exec`](/commands/exec). #### Raft Protocol Version Compatibility When upgrading to Consul 0.8.0 from a version lower than 0.7.0, users will need -to set the [`-raft-protocol`](/docs/agent/config/agent-config-cli#_raft_protocol) option +to set the [`-raft-protocol`](/docs/agent/config/cli-flags#_raft_protocol) option to 1 in order to maintain backwards compatibility with the old servers during the upgrade. After the servers have been migrated to version 0.8.0, `-raft-protocol` can be moved up to 2 and the servers restarted to match the @@ -878,7 +878,7 @@ process to reap child processes. #### DNS Resiliency Defaults -The default for [`max_stale`](/docs/agent/config/agent-config-files#max_stale) has been +The default for [`max_stale`](/docs/agent/config/config-files#max_stale) has been increased from 5 seconds to a near-indefinite threshold (10 years) to allow DNS queries to continue to be served in the event of a long outage with no leader. A new telemetry counter was added at `consul.dns.stale_queries` to track when @@ -892,7 +892,7 @@ to be aware of during an upgrade are categorized below. #### Performance Timing Defaults and Tuning Consul 0.7 now defaults the DNS configuration to allow for stale queries by -defaulting [`allow_stale`](/docs/agent/config/agent-config-files#allow_stale) to true for +defaulting [`allow_stale`](/docs/agent/config/config-files#allow_stale) to true for better utilization of available servers. If you want to retain the previous behavior, set the following configuration: @@ -905,7 +905,7 @@ behavior, set the following configuration: ``` Consul also 0.7 introduced support for tuning Raft performance using a new -[performance configuration block](/docs/agent/config/agent-config-files#performance). Also, +[performance configuration block](/docs/agent/config/config-files#performance). Also, the default Raft timing is set to a lower-performance mode suitable for [minimal Consul servers](/docs/install/performance#minimum). @@ -925,8 +925,8 @@ See the [Server Performance](/docs/install/performance) guide for more details. #### Leave-Related Configuration Defaults -The default behavior of [`leave_on_terminate`](/docs/agent/config/agent-config-files#leave_on_terminate) -and [`skip_leave_on_interrupt`](/docs/agent/config/agent-config-files#skip_leave_on_interrupt) +The default behavior of [`leave_on_terminate`](/docs/agent/config/config-files#leave_on_terminate) +and [`skip_leave_on_interrupt`](/docs/agent/config/config-files#skip_leave_on_interrupt) are now dependent on whether or not the agent is acting as a server or client: - For servers, `leave_on_terminate` defaults to "false" and `skip_leave_on_interrupt` @@ -965,7 +965,7 @@ using this feature. #### WAN Address Translation in HTTP Endpoints Consul version 0.7 added support for translating WAN addresses in certain -[HTTP endpoints](/docs/agent/config/agent-config-files#translate_wan_addrs). The servers +[HTTP endpoints](/docs/agent/config/config-files#translate_wan_addrs). The servers and the agents need to be running version 0.7 or later in order to use this feature. @@ -1047,7 +1047,7 @@ which require it: } When the DNS interface is queried, the agent's -[`acl_token`](/docs/agent/config/agent-config-files#acl_token) is used, so be sure +[`acl_token`](/docs/agent/config/config-files#acl_token) is used, so be sure that token has sufficient privileges to return the DNS records you expect to retrieve from it. diff --git a/website/content/partials/http_api_options_client.mdx b/website/content/partials/http_api_options_client.mdx index 516579bba6..472c250e66 100644 --- a/website/content/partials/http_api_options_client.mdx +++ b/website/content/partials/http_api_options_client.mdx @@ -20,7 +20,7 @@ used instead. The scheme can also be set to HTTPS by setting the environment variable `CONSUL_HTTP_SSL=true`. This may be a unix domain socket using `unix:///path/to/socket` if the [agent is configured to - listen](/docs/agent/config/agent-config-files#addresses) that way. + listen](/docs/agent/config/config-files#addresses) that way. - `-tls-server-name=` - The server name to use as the SNI host when connecting via TLS. This can also be specified via the `CONSUL_TLS_SERVER_NAME` diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 9e25b99bfc..f81faf6680 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -778,11 +778,11 @@ }, { "title": "CLI Reference", - "path": "agent/config/agent-config-cli" + "path": "agent/config/cli-flags" }, { "title": "Configuration Reference", - "path": "agent/config/agent-config-files" + "path": "agent/config/config-files" } ] }, From cd907b75cebdefe62a30986e0cdc7bd528c52159 Mon Sep 17 00:00:00 2001 From: Natalie Smith Date: Mon, 10 Jan 2022 17:50:06 -0800 Subject: [PATCH 10/10] docs: fix yet more references to agent/options --- .../linux/package/etc/consul.d/consul.hcl | 2 +- CHANGELOG.md | 80 +++++++++---------- agent/config/runtime.go | 6 +- agent/consul/server.go | 2 +- agent/kvs_endpoint.go | 2 +- agent/txn_endpoint.go | 4 +- 6 files changed, 48 insertions(+), 48 deletions(-) diff --git a/.release/linux/package/etc/consul.d/consul.hcl b/.release/linux/package/etc/consul.d/consul.hcl index e1b8e6e198..16e5333946 100644 --- a/.release/linux/package/etc/consul.d/consul.hcl +++ b/.release/linux/package/etc/consul.d/consul.hcl @@ -1,4 +1,4 @@ -# Fullconfiguration options can be found at https://www.consul.io/docs/agent/options.html +# Fullconfiguration options can be found at https://www.consul.io/docs/agent/config.html # datacenter # This flag controls the datacenter in which the agent is running. If not provided, diff --git a/CHANGELOG.md b/CHANGELOG.md index 0391f6984c..3da2828639 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -272,7 +272,7 @@ token. [[GH-10795](https://github.com/hashicorp/consul/issues/10795)] KNOWN ISSUES: -* The change to enable streaming by default uncovered an incompatibility between streaming and WAN federation over mesh gateways causing traffic to fall back to attempting a direct WAN connection rather than transiting through the gateways. We currently suggest explicitly setting [`use_streaming_backend=false`](https://www.consul.io/docs/agent/options#use_streaming_backend) if using WAN federation over mesh gateways when upgrading to 1.10.1 and are working to address this issue in a future patch release. +* The change to enable streaming by default uncovered an incompatibility between streaming and WAN federation over mesh gateways causing traffic to fall back to attempting a direct WAN connection rather than transiting through the gateways. We currently suggest explicitly setting [`use_streaming_backend=false`](https://www.consul.io/docs/agent/config/config-files#use_streaming_backend) if using WAN federation over mesh gateways when upgrading to 1.10.1 and are working to address this issue in a future patch release. SECURITY: @@ -1634,7 +1634,7 @@ FEATURES: * **Connect Envoy Supports L7 Routing:** Additional configuration entry types `service-router`, `service-resolver`, and `service-splitter`, allow for configuring Envoy sidecars to enable reliability and deployment patterns at L7 such as HTTP path-based routing, traffic shifting, and advanced failover capabilities. For more information see the [L7 traffic management](https://www.consul.io/docs/connect/l7-traffic-management.html) docs. * **Mesh Gateways:** Envoy can now be run as a gateway to route Connect traffic across datacenters using SNI headers, allowing connectivty across platforms and clouds and other complex network topologies. Read more in the [mesh gateway docs](https://www.consul.io/docs/connect/mesh_gateway.html). -* **Intention & CA Replication:** In order to enable connecitivty for services across datacenters, Connect intentions are now replicated and the Connect CA cross-signs from the [primary_datacenter](/docs/agent/options.html#primary_datacenter). This feature was previously part of Consul Enterprise. +* **Intention & CA Replication:** In order to enable connecitivty for services across datacenters, Connect intentions are now replicated and the Connect CA cross-signs from the [primary_datacenter](/docs/agent/config/config-files.html#primary_datacenter). This feature was previously part of Consul Enterprise. * agent: add `local-only` parameter to operator/keyring list requests to force queries to only hit local servers. [[GH-6279](https://github.com/hashicorp/consul/pull/6279)] * connect: expose an API endpoint to compile the discovery chain [[GH-6248](https://github.com/hashicorp/consul/issues/6248)] * connect: generate the full SNI names for discovery targets in the compiler rather than in the xds package [[GH-6340](https://github.com/hashicorp/consul/issues/6340)] @@ -2070,7 +2070,7 @@ FEATURES: IMPROVEMENTS: * proxy: With `-register` flag, heartbeat failures will only log once service registration succeeds. [[GH-4314](https://github.com/hashicorp/consul/pull/4314)] -* http: 1.0.3 introduced rejection of non-printable chars in HTTP URLs due to a security vulnerability. Some users who had keys written with an older version which are now dissallowed were unable to delete them. A new config option [disable_http_unprintable_char_filter](https://www.consul.io/docs/agent/options.html#disable_http_unprintable_char_filter) is added to allow those users to remove the offending keys. Leaving this new option set long term is strongly discouraged as it bypasses filtering necessary to prevent some known vulnerabilities. [[GH-4442](https://github.com/hashicorp/consul/pull/4442)] +* http: 1.0.3 introduced rejection of non-printable chars in HTTP URLs due to a security vulnerability. Some users who had keys written with an older version which are now dissallowed were unable to delete them. A new config option [disable_http_unprintable_char_filter](https://www.consul.io/docs/agent/config/config-files.html#disable_http_unprintable_char_filter) is added to allow those users to remove the offending keys. Leaving this new option set long term is strongly discouraged as it bypasses filtering necessary to prevent some known vulnerabilities. [[GH-4442](https://github.com/hashicorp/consul/pull/4442)] * agent: Allow for advanced configuration of some gossip related parameters. [[GH-4058](https://github.com/hashicorp/consul/issues/4058)] * agent: Make some Gossip tuneables configurable via the config file [[GH-4444](https://github.com/hashicorp/consul/pull/4444)] * ui: Included searching on `.Tags` when using the freetext search field. [[GH-4383](https://github.com/hashicorp/consul/pull/4383)] @@ -2302,13 +2302,13 @@ IMPROVEMENTS: * agent: (Consul Enterprise) Added [AWS KMS support](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html) for S3 snapshots using the snapshot agent. * agent: Watches in the Consul agent can now be configured to invoke an HTTP endpoint instead of an executable. [[GH-3305](https://github.com/hashicorp/consul/issues/3305)] -* agent: Added a new [`-config-format`](https://www.consul.io/docs/agent/options.html#_config_format) command line option which can be set to `hcl` or `json` to specify the format of configuration files. This is useful for cases where the file name cannot be controlled in order to provide the required extension. [[GH-3620](https://github.com/hashicorp/consul/issues/3620)] +* agent: Added a new [`-config-format`](https://www.consul.io/docs/agent/config/cli-flags.html#_config_format) command line option which can be set to `hcl` or `json` to specify the format of configuration files. This is useful for cases where the file name cannot be controlled in order to provide the required extension. [[GH-3620](https://github.com/hashicorp/consul/issues/3620)] * agent: DNS recursors can now be specified as [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template) templates. [[GH-2932](https://github.com/hashicorp/consul/issues/2932)] * agent: Serf snapshots no longer save network coordinate information. This enables recovery from errors upon agent restart. [[GH-489](https://github.com/hashicorp/serf/issues/489)] * agent: Added defensive code to prevent out of range ping times from infecting network coordinates. Updates to the coordinate system with negative round trip times or round trip times higher than 10 seconds will log an error but will be ignored. * agent: The agent now warns when there are extra unparsed command line arguments and refuses to start. [[GH-3397](https://github.com/hashicorp/consul/issues/3397)] * agent: Updated go-sockaddr library to get CoreOS route detection fixes and the new `mask` functionality. [[GH-3633](https://github.com/hashicorp/consul/issues/3633)] -* agent: Added a new [`enable_agent_tls_for_checks`](https://www.consul.io/docs/agent/options.html#enable_agent_tls_for_checks) configuration option that allows HTTP health checks for services requiring 2-way TLS to be checked using the agent's credentials. [[GH-3364](https://github.com/hashicorp/consul/issues/3364)] +* agent: Added a new [`enable_agent_tls_for_checks`](https://www.consul.io/docs/agent/config/config-files.html#enable_agent_tls_for_checks) configuration option that allows HTTP health checks for services requiring 2-way TLS to be checked using the agent's credentials. [[GH-3364](https://github.com/hashicorp/consul/issues/3364)] * agent: Made logging of health check status more uniform and moved log entries with full check output from DEBUG to TRACE level for less noise. [[GH-3683](https://github.com/hashicorp/consul/issues/3683)] * build: Consul is now built with Go 1.9.2. [[GH-3663](https://github.com/hashicorp/consul/issues/3663)] @@ -2333,8 +2333,8 @@ SECURITY: BREAKING CHANGES: -* **Raft Protocol Now Defaults to 3:** The [`-raft-protocol`](https://www.consul.io/docs/agent/options.html#_raft_protocol) default has been changed from 2 to 3, enabling all [Autopilot](https://www.consul.io/docs/guides/autopilot.html) features by default. Version 3 requires Consul running 0.8.0 or newer on all servers in order to work, so if you are upgrading with older servers in a cluster then you will need to set this back to 2 in order to upgrade. See [Raft Protocol Version Compatibility](https://www.consul.io/docs/upgrade-specific.html#raft-protocol-version-compatibility) for more details. Also the format of `peers.json` used for outage recovery is different when running with the lastest Raft protocol. See [Manual Recovery Using peers.json](https://www.consul.io/docs/guides/outage.html#manual-recovery-using-peers-json) for a description of the required format. [[GH-3477](https://github.com/hashicorp/consul/issues/3477)] -* **Config Files Require an Extension:** As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format for Consul's config files, an `.hcl` or `.json` extension is required for all config files loaded by Consul, even when using the [`-config-file`](https://www.consul.io/docs/agent/options.html#_config_file) argument to specify a file directly. [[GH-3480](https://github.com/hashicorp/consul/issues/3480)] +* **Raft Protocol Now Defaults to 3:** The [`-raft-protocol`](https://www.consul.io/docs/agent/config/cli-flags.html#_raft_protocol) default has been changed from 2 to 3, enabling all [Autopilot](https://www.consul.io/docs/guides/autopilot.html) features by default. Version 3 requires Consul running 0.8.0 or newer on all servers in order to work, so if you are upgrading with older servers in a cluster then you will need to set this back to 2 in order to upgrade. See [Raft Protocol Version Compatibility](https://www.consul.io/docs/upgrade-specific.html#raft-protocol-version-compatibility) for more details. Also the format of `peers.json` used for outage recovery is different when running with the lastest Raft protocol. See [Manual Recovery Using peers.json](https://www.consul.io/docs/guides/outage.html#manual-recovery-using-peers-json) for a description of the required format. [[GH-3477](https://github.com/hashicorp/consul/issues/3477)] +* **Config Files Require an Extension:** As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format for Consul's config files, an `.hcl` or `.json` extension is required for all config files loaded by Consul, even when using the [`-config-file`](https://www.consul.io/docs/agent/config/cli-flags.html#_config_file) argument to specify a file directly. [[GH-3480](https://github.com/hashicorp/consul/issues/3480)] * **Deprecated Options Have Been Removed:** All of Consul's previously deprecated command line flags and config options have been removed, so these will need to be mapped to their equivalents before upgrading. [[GH-3480](https://github.com/hashicorp/consul/issues/3480)]
Detailed List of Removed Options and their Equivalents @@ -2345,35 +2345,35 @@ BREAKING CHANGES: | `-atlas-token`| None, Atlas is no longer supported. | | `-atlas-join` | None, Atlas is no longer supported. | | `-atlas-endpoint` | None, Atlas is no longer supported. | - | `-dc` | [`-datacenter`](https://www.consul.io/docs/agent/options.html#_datacenter) | - | `-retry-join-azure-tag-name` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#microsoft-azure) | - | `-retry-join-azure-tag-value` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#microsoft-azure) | - | `-retry-join-ec2-region` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#amazon-ec2) | - | `-retry-join-ec2-tag-key` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#amazon-ec2) | - | `-retry-join-ec2-tag-value` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#amazon-ec2) | - | `-retry-join-gce-credentials-file` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#google-compute-engine) | - | `-retry-join-gce-project-name` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#google-compute-engine) | - | `-retry-join-gce-tag-name` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#google-compute-engine) | - | `-retry-join-gce-zone-pattern` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#google-compute-engine) | + | `-dc` | [`-datacenter`](https://www.consul.io/docs/agent/config/cli-flags.html#_datacenter) | + | `-retry-join-azure-tag-name` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-azure-tag-value` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-ec2-region` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-ec2-tag-key` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-ec2-tag-value` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-gce-credentials-file` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-gce-project-name` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-gce-tag-name` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `-retry-join-gce-zone-pattern` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | | `addresses.rpc` | None, the RPC server for CLI commands is no longer supported. | - | `advertise_addrs` | [`ports`](https://www.consul.io/docs/agent/options.html#ports) with [`advertise_addr`](https://www.consul/io/docs/agent/options.html#advertise_addr) and/or [`advertise_addr_wan`](https://www.consul.io/docs/agent/options.html#advertise_addr_wan) | + | `advertise_addrs` | [`ports`](https://www.consul.io/docs/agent/config/config-files.html#ports) with [`advertise_addr`](https://www.consul/io/docs/agent/config/config-files.html#advertise_addr) and/or [`advertise_addr_wan`](https://www.consul.io/docs/agent/config/config-files.html#advertise_addr_wan) | | `atlas_infrastructure` | None, Atlas is no longer supported. | | `atlas_token` | None, Atlas is no longer supported. | | `atlas_acl_token` | None, Atlas is no longer supported. | | `atlas_join` | None, Atlas is no longer supported. | | `atlas_endpoint` | None, Atlas is no longer supported. | - | `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](https://www.consul.io/docs/agent/options.html#telemetry-dogstatsd_addr) | - | `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](https://www.consul.io/docs/agent/options.html#telemetry-dogstatsd_tags) | - | `http_api_response_headers` | [`http_config.response_headers`](https://www.consul.io/docs/agent/options.html#response_headers) | + | `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](https://www.consul.io/docs/agent/config/config-files.html#telemetry-dogstatsd_addr) | + | `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](https://www.consul.io/docs/agent/config/config-files.html#telemetry-dogstatsd_tags) | + | `http_api_response_headers` | [`http_config.response_headers`](https://www.consul.io/docs/agent/config/config-files.html#response_headers) | | `ports.rpc` | None, the RPC server for CLI commands is no longer supported. | - | `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/source/docs/agent/options.html.md#recursors) | - | `retry_join_azure` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#microsoft-azure) | - | `retry_join_ec2` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#amazon-ec2) | - | `retry_join_gce` | [`-retry-join`](https://www.consul.io/docs/agent/options.html#google-compute-engine) | - | `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/source/docs/agent/options.html.md#telemetry-statsd_address) | - | `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/source/docs/agent/options.html.md#telemetry-statsite_address) | - | `statsite_prefix` | [`telemetry.metrics_prefix`](https://www.consul.io/docs/agent/options.html#telemetry-metrics_prefix) | - | `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](https://www.consul.io/docs/agent/options.html#telemetry-metrics_prefix) | + | `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/source/docs/agent/config/config-files.html.md#recursors) | + | `retry_join_azure` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `retry_join_ec2` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `retry_join_gce` | [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) | + | `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/source/docs/agent/config/config-files.html.md#telemetry-statsd_address) | + | `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/source/docs/agent/config/config-files.html.md#telemetry-statsite_address) | + | `statsite_prefix` | [`telemetry.metrics_prefix`](https://www.consul.io/docs/agent/config/config-files.html#telemetry-metrics_prefix) | + | `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](https://www.consul.io/docs/agent/config/config-files.html#telemetry-metrics_prefix) | | (service definitions) `serviceid` | [`service_id`](https://www.consul.io/docs/agent/services.html) | | (service definitions) `dockercontainerid` | [`docker_container_id`](https://www.consul.io/docs/agent/services.html) | | (service definitions) `tlsskipverify` | [`tls_skip_verify`](https://www.consul.io/docs/agent/services.html) | @@ -2381,9 +2381,9 @@ BREAKING CHANGES:
-* **`statsite_prefix` Renamed to `metrics_prefix`:** Since the `statsite_prefix` configuration option applied to all telemetry providers, `statsite_prefix` was renamed to [`metrics_prefix`](https://www.consul.io/docs/agent/options.html#telemetry-metrics_prefix). Configuration files will need to be updated when upgrading to this version of Consul. [[GH-3498](https://github.com/hashicorp/consul/issues/3498)] +* **`statsite_prefix` Renamed to `metrics_prefix`:** Since the `statsite_prefix` configuration option applied to all telemetry providers, `statsite_prefix` was renamed to [`metrics_prefix`](https://www.consul.io/docs/agent/config/config-files.html#telemetry-metrics_prefix). Configuration files will need to be updated when upgrading to this version of Consul. [[GH-3498](https://github.com/hashicorp/consul/issues/3498)] * **`advertise_addrs` Removed:** This configuration option was removed since it was redundant with `advertise_addr` and `advertise_addr_wan` in combination with `ports` and also wrongly stated that you could configure both host and port. [[GH-3516](https://github.com/hashicorp/consul/issues/3516)] -* **Escaping Behavior Changed for go-discover Configs:** The format for [`-retry-join`](https://www.consul.io/docs/agent/options.html#retry-join) and [`-retry-join-wan`](https://www.consul.io/docs/agent/options.html#retry-join-wan) values that use [go-discover](https://github.com/hashicorp/go-discover) Cloud auto joining has changed. Values in `key=val` sequences must no longer be URL encoded and can be provided as literals as long as they do not contain spaces, backslashes `\` or double quotes `"`. If values contain these characters then use double quotes as in `"some key"="some value"`. Special characters within a double quoted string can be escaped with a backslash `\`. [[GH-3417](https://github.com/hashicorp/consul/issues/3417)] +* **Escaping Behavior Changed for go-discover Configs:** The format for [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) and [`-retry-join-wan`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join_wan) values that use [go-discover](https://github.com/hashicorp/go-discover) Cloud auto joining has changed. Values in `key=val` sequences must no longer be URL encoded and can be provided as literals as long as they do not contain spaces, backslashes `\` or double quotes `"`. If values contain these characters then use double quotes as in `"some key"="some value"`. Special characters within a double quoted string can be escaped with a backslash `\`. [[GH-3417](https://github.com/hashicorp/consul/issues/3417)] * **HTTP Verbs are Enforced in Many HTTP APIs:** Many endpoints in the HTTP API that previously took any HTTP verb now check for specific HTTP verbs and enforce them. This may break clients relying on the old behavior. [[GH-3405](https://github.com/hashicorp/consul/issues/3405)]
Detailed List of Updated Endpoints and Required HTTP Verbs @@ -2464,7 +2464,7 @@ BREAKING CHANGES: FEATURES: * **Support for HCL Config Files:** Consul now supports HashiCorp's [HCL](https://github.com/hashicorp/hcl#syntax) format for config files. This is easier to work with than JSON and supports comments. As part of this change, all config files will need to have either an `.hcl` or `.json` extension in order to specify their format. [[GH-3480](https://github.com/hashicorp/consul/issues/3480)] -* **Support for Binding to Multiple Addresses:** Consul now supports binding to multiple addresses for its HTTP, HTTPS, and DNS services. You can provide a space-separated list of addresses to [`-client`](https://www.consul.io/docs/agent/options.html#_client) and [`addresses`](https://www.consul.io/docs/agent/options.html#addresses) configurations, or specify a [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template) template that resolves to multiple addresses. [[GH-3480](https://github.com/hashicorp/consul/issues/3480)] +* **Support for Binding to Multiple Addresses:** Consul now supports binding to multiple addresses for its HTTP, HTTPS, and DNS services. You can provide a space-separated list of addresses to [`-client`](https://www.consul.io/docs/agent/config/cli-flags.html#_client) and [`addresses`](https://www.consul.io/docs/agent/config/config-files.html#addresses) configurations, or specify a [go-sockaddr](https://godoc.org/github.com/hashicorp/go-sockaddr/template) template that resolves to multiple addresses. [[GH-3480](https://github.com/hashicorp/consul/issues/3480)] * **Support for RFC1464 DNS TXT records:** Consul DNS responses now contain the node meta data encoded according to RFC1464 as TXT records. [[GH-3343](https://github.com/hashicorp/consul/issues/3343)] * **Support for Running Subproccesses Directly Without a Shell:** Consul agent checks and watches now support an `args` configuration which is a list of arguments to run for the subprocess, which runs the subprocess directly without a shell. The old `script` and `handler` configurations are now deprecated (specify a shell explicitly if you require one). A `-shell=false` option is also available on `consul lock`, `consul watch`, and `consul exec` to run the subprocesses associated with those without a shell. [[GH-3509](https://github.com/hashicorp/consul/issues/3509)] * **Sentinel Integration:** (Consul Enterprise) Consul's ACL system integrates with [Sentinel](https://www.consul.io/docs/guides/sentinel.html) to enable code policies that apply to KV writes. @@ -2475,7 +2475,7 @@ IMPROVEMENTS: * agent: Improved /v1/operator/raft/configuration endpoint which allows Consul to avoid an extra agent RPC call for the `consul operator raft list-peers` command. [[GH-3449](https://github.com/hashicorp/consul/issues/3449)] * agent: Improved ACL system for the KV store to support list permissions. This behavior can be opted in. For more information, see the [ACL Guide](https://www.consul.io/docs/guides/acl.html#list-policy-for-keys). [[GH-3511](https://github.com/hashicorp/consul/issues/3511)] * agent: Updates miekg/dns library to later version to pick up bug fixes and improvements. [[GH-3547](https://github.com/hashicorp/consul/issues/3547)] -* agent: Added automatic retries to the RPC path, and a brief RPC drain time when servers leave. These changes make Consul more robust during graceful leaves of Consul servers, such as during upgrades, and help shield applications from "no leader" errors. These are configured with new [`performance`](https://www.consul.io/docs/agent/options.html#performance) options. [[GH-3514](https://github.com/hashicorp/consul/issues/3514)] +* agent: Added automatic retries to the RPC path, and a brief RPC drain time when servers leave. These changes make Consul more robust during graceful leaves of Consul servers, such as during upgrades, and help shield applications from "no leader" errors. These are configured with new [`performance`](https://www.consul.io/docs/agent/config/config-files.html#performance) options. [[GH-3514](https://github.com/hashicorp/consul/issues/3514)] * agent: Added a new `discard_check_output` agent-level configuration option that can be used to trade off write load to the Consul servers vs. visibility of health check output. This is reloadable so it can be toggled without fully restarting the agent. [[GH-3562](https://github.com/hashicorp/consul/issues/3562)] * api: Updated the API client to ride out network errors when monitoring locks and semaphores. [[GH-3553](https://github.com/hashicorp/consul/issues/3553)] * build: Updated Go toolchain to version 1.9.1. [[GH-3537](https://github.com/hashicorp/consul/issues/3537)] @@ -2503,7 +2503,7 @@ SECURITY: FEATURES: * **LAN Network Segments:** (Consul Enterprise) Added a new [Network Segments](https://www.consul.io/docs/guides/segments.html) capability which allows users to configure Consul to support segmented LAN topologies with multiple, distinct gossip pools. [[GH-3431](https://github.com/hashicorp/consul/issues/3431)] * **WAN Join for Cloud Providers:** Added WAN support for retry join for Cloud providers via go-discover, including Amazon AWS, Microsoft Azure, Google Cloud, and SoftLayer. This uses the same "provider" syntax supported for `-retry-join` via the `-retry-join-wan` configuration. [[GH-3406](https://github.com/hashicorp/consul/issues/3406)] -* **RPC Rate Limiter:** Consul agents in client mode have a new [`limits`](https://www.consul.io/docs/agent/options.html#limits) configuration that enables a rate limit on RPC calls the agent makes to Consul servers. [[GH-3140](https://github.com/hashicorp/consul/issues/3140)] +* **RPC Rate Limiter:** Consul agents in client mode have a new [`limits`](https://www.consul.io/docs/agent/config/config-files.html#limits) configuration that enables a rate limit on RPC calls the agent makes to Consul servers. [[GH-3140](https://github.com/hashicorp/consul/issues/3140)] IMPROVEMENTS: @@ -2533,13 +2533,13 @@ BUG FIXES: FEATURES: * **Secure ACL Token Introduction:** It's now possible to manage Consul's ACL tokens without having to place any tokens inside configuration files. This supports introduction of tokens as well as rotating. This is enabled with two new APIs: - * A new [`/v1/agent/token`](https://www.consul.io/api/agent.html#update-acl-tokens) API allows an agent's ACL tokens to be introduced without placing them into config files, and to update them without restarting the agent. See the [ACL Guide](https://www.consul.io/docs/guides/acl.html#create-an-agent-token) for an example. This was extended to ACL replication as well, along with a new [`enable_acl_replication`](https://www.consul.io/docs/agent/options.html#enable_acl_replication) config option. [GH-3324,GH-3357] + * A new [`/v1/agent/token`](https://www.consul.io/api/agent.html#update-acl-tokens) API allows an agent's ACL tokens to be introduced without placing them into config files, and to update them without restarting the agent. See the [ACL Guide](https://www.consul.io/docs/guides/acl.html#create-an-agent-token) for an example. This was extended to ACL replication as well, along with a new [`enable_acl_replication`](https://www.consul.io/docs/agent/config/config-files.html#enable_acl_replication) config option. [GH-3324,GH-3357] * A new [`/v1/acl/bootstrap`](https://www.consul.io/api/acl.html#bootstrap-acls) allows a cluster's first management token to be created without using the `acl_master_token` configuration. See the [ACL Guide](https://www.consul.io/docs/guides/acl.html#bootstrapping-acls) for an example. [[GH-3349](https://github.com/hashicorp/consul/issues/3349)] * **Metrics Viewing Endpoint:** A new [`/v1/agent/metrics`](https://www.consul.io/api/agent.html#view-metrics) API displays the current values of internally tracked metrics. [[GH-3369](https://github.com/hashicorp/consul/issues/3369)] IMPROVEMENTS: -* agent: Retry Join for Amazon AWS, Microsoft Azure, Google Cloud, and (new) SoftLayer is now handled through the https://github.com/hashicorp/go-discover library. With this all `-retry-join-{ec2,azure,gce}-*` parameters have been deprecated in favor of a unified configuration. See [`-retry-join`](https://www.consul.io/docs/agent/options.html#_retry_join) for details. [GH-3282,GH-3351] +* agent: Retry Join for Amazon AWS, Microsoft Azure, Google Cloud, and (new) SoftLayer is now handled through the https://github.com/hashicorp/go-discover library. With this all `-retry-join-{ec2,azure,gce}-*` parameters have been deprecated in favor of a unified configuration. See [`-retry-join`](https://www.consul.io/docs/agent/config/cli-flags.html#_retry_join) for details. [GH-3282,GH-3351] * agent: Reports a more detailed error message if the LAN or WAN Serf instance fails to bind to an address. [[GH-3312](https://github.com/hashicorp/consul/issues/3312)] * agent: Added NS records and corrected SOA records to allow Consul's DNS interface to work properly with zone delegation. [[GH-1301](https://github.com/hashicorp/consul/issues/1301)] * agent: Added support for sending metrics with labels/tags to supported backends. [[GH-3369](https://github.com/hashicorp/consul/issues/3369)] @@ -2563,13 +2563,13 @@ BUG FIXES: BREAKING CHANGES: -* agent: Added a new [`enable_script_checks`](https://www.consul.io/docs/agent/options.html#_enable_script_checks) configuration option that defaults to `false`, meaning that in order to allow an agent to run health checks that execute scripts, this will need to be configured and set to `true`. This provides a safer out-of-the-box configuration for Consul where operators must opt-in to allow script-based health checks. [[GH-3087](https://github.com/hashicorp/consul/issues/3087)] +* agent: Added a new [`enable_script_checks`](https://www.consul.io/docs/agent/config/cli-flags.html#_enable_script_checks) configuration option that defaults to `false`, meaning that in order to allow an agent to run health checks that execute scripts, this will need to be configured and set to `true`. This provides a safer out-of-the-box configuration for Consul where operators must opt-in to allow script-based health checks. [[GH-3087](https://github.com/hashicorp/consul/issues/3087)] * api: Reworked `context` support in the API client to more closely match the Go standard library, and added context support to write requests in addition to read requests. [GH-3273, GH-2992] * ui: Since the UI is now bundled with the application we no longer provide a separate UI package for downloading. [[GH-3292](https://github.com/hashicorp/consul/issues/3292)] FEATURES: -* agent: Added a new [`block_endpoints`](https://www.consul.io/docs/agent/options.html#block_endpoints) configuration option that allows blocking HTTP API endpoints by prefix. This allows operators to completely disallow access to specific endpoints on a given agent. [[GH-3252](https://github.com/hashicorp/consul/issues/3252)] +* agent: Added a new [`block_endpoints`](https://www.consul.io/docs/agent/config/config-files.html#block_endpoints) configuration option that allows blocking HTTP API endpoints by prefix. This allows operators to completely disallow access to specific endpoints on a given agent. [[GH-3252](https://github.com/hashicorp/consul/issues/3252)] * cli: Added a new [`consul catalog`](https://www.consul.io/docs/commands/catalog.html) command for reading datacenters, nodes, and services from the catalog. [[GH-3204](https://github.com/hashicorp/consul/issues/3204)] * server: (Consul Enterprise) Added a new [`consul operator area update`](https://www.consul.io/docs/commands/operator/area.html#update) command and corresponding HTTP endpoint to allow for transitioning the TLS setting of network areas at runtime. [[GH-3075](https://github.com/hashicorp/consul/issues/3075)] * server: (Consul Enterprise) Added a new `UpgradeVersionTag` field to the Autopilot config to allow for using the migration feature to roll out configuration or cluster changes, without having to upgrade Consul itself. @@ -2597,7 +2597,7 @@ BUG FIXES: * agent: Fixed an issue in the Docker client where Docker checks would get EOF errors trying to connect to a volume-mounted Docker socket. [[GH-3254](https://github.com/hashicorp/consul/issues/3254)] * agent: Fixed a crash when using Azure auto discovery. [[GH-3193](https://github.com/hashicorp/consul/issues/3193)] * agent: Added `node` read privileges to the `acl_agent_master_token` by default so it can see all nodes, which enables it to be used with operations like `consul members`. [[GH-3113](https://github.com/hashicorp/consul/issues/3113)] -* agent: Fixed an issue where enabling [`-disable-keyring-file`](https://www.consul.io/docs/agent/options.html#_disable_keyring_file) would cause gossip encryption to be disabled. [[GH-3243](https://github.com/hashicorp/consul/issues/3243)] +* agent: Fixed an issue where enabling [`-disable-keyring-file`](https://www.consul.io/docs/agent/config/cli-flags.html#_disable_keyring_file) would cause gossip encryption to be disabled. [[GH-3243](https://github.com/hashicorp/consul/issues/3243)] * agent: Fixed a race condition where checks that are not associated with any existing services were allowed to persist. [[GH-3297](https://github.com/hashicorp/consul/issues/3297)] * agent: Stop docker checks on service deregistration and on shutdown. [GH-3265, GH-3295] * server: Updated the Raft library to pull in a fix where servers that are very far behind in replication can get stuck in a loop trying to install snapshots. [[GH-3201](https://github.com/hashicorp/consul/issues/3201)] @@ -2614,7 +2614,7 @@ BUG FIXES: BREAKING CHANGES: * agent: Parse values given to `?passing` for health endpoints. Previously Consul only checked for the existence of the querystring, not the value. That means using `?passing=false` would actually still include passing values. Consul now parses the value given to passing as a boolean. If no value is provided, the old behavior remains. This may be a breaking change for some users, but the old experience was incorrect and caused enough confusion to warrant changing it. [GH-2212, GH-3136] -* agent: The default value of [`-disable-host-node-id`](https://www.consul.io/docs/agent/options.html#_disable_host_node_id) has been changed from false to true. This means you need to opt-in to host-based node IDs and by default Consul will generate a random node ID. A high number of users struggled to deploy newer versions of Consul with host-based IDs because of various edge cases of how the host IDs work in Docker, on specially-provisioned machines, etc. so changing this from opt-out to opt-in will ease operations for many Consul users. [[GH-3171](https://github.com/hashicorp/consul/issues/3171)] +* agent: The default value of [`-disable-host-node-id`](https://www.consul.io/docs/agent/config/cli-flags.html#_disable_host_node_id) has been changed from false to true. This means you need to opt-in to host-based node IDs and by default Consul will generate a random node ID. A high number of users struggled to deploy newer versions of Consul with host-based IDs because of various edge cases of how the host IDs work in Docker, on specially-provisioned machines, etc. so changing this from opt-out to opt-in will ease operations for many Consul users. [[GH-3171](https://github.com/hashicorp/consul/issues/3171)] IMPROVEMENTS: diff --git a/agent/config/runtime.go b/agent/config/runtime.go index 1d13e19d8d..9f2fd3bcb5 100644 --- a/agent/config/runtime.go +++ b/agent/config/runtime.go @@ -835,7 +835,7 @@ type RuntimeConfig struct { // PrimaryGateways is a list of addresses and/or go-discover expressions to // discovery the mesh gateways in the primary datacenter. See - // https://www.consul.io/docs/agent/options.html#cloud-auto-joining for + // https://www.consul.io/docs/agent/config/cli-flags.html#cloud-auto-joining for // details. // // hcl: primary_gateways = []string @@ -991,7 +991,7 @@ type RuntimeConfig struct { // RetryJoinLAN is a list of addresses and/or go-discover expressions to // join with retry enabled. See - // https://www.consul.io/docs/agent/options.html#cloud-auto-joining for + // https://www.consul.io/docs/agent/config/cli-flags.html#cloud-auto-joining for // details. // // hcl: retry_join = []string @@ -1016,7 +1016,7 @@ type RuntimeConfig struct { // RetryJoinWAN is a list of addresses and/or go-discover expressions to // join -wan with retry enabled. See - // https://www.consul.io/docs/agent/options.html#cloud-auto-joining for + // https://www.consul.io/docs/agent/config/cli-flags.html#cloud-auto-joining for // details. // // hcl: retry_join_wan = []string diff --git a/agent/consul/server.go b/agent/consul/server.go index e076af7214..418509460e 100644 --- a/agent/consul/server.go +++ b/agent/consul/server.go @@ -1537,7 +1537,7 @@ const peersInfoContent = ` As of Consul 0.7.0, the peers.json file is only used for recovery after an outage. The format of this file depends on what the server has configured for its Raft protocol version. Please see the agent configuration -page at https://www.consul.io/docs/agent/options.html#_raft_protocol for more +page at https://www.consul.io/docs/agent/config/cli-flags.html#_raft_protocol for more details about this parameter. For Raft protocol version 2 and earlier, this should be formatted as a JSON diff --git a/agent/kvs_endpoint.go b/agent/kvs_endpoint.go index 6534718d20..3ee95185cc 100644 --- a/agent/kvs_endpoint.go +++ b/agent/kvs_endpoint.go @@ -209,7 +209,7 @@ func (s *HTTPHandlers) KVSPut(resp http.ResponseWriter, req *http.Request, args fmt.Fprintf(resp, "Request body(%d bytes) too large, max size: %d bytes. See %s.", req.ContentLength, s.agent.config.KVMaxValueSize, - "https://www.consul.io/docs/agent/options.html#kv_max_value_size", + "https://www.consul.io/docs/agent/config/config-files.html#kv_max_value_size", ) return nil, nil } diff --git a/agent/txn_endpoint.go b/agent/txn_endpoint.go index afe298d629..dcf6c2d999 100644 --- a/agent/txn_endpoint.go +++ b/agent/txn_endpoint.go @@ -91,7 +91,7 @@ func (s *HTTPHandlers) convertOps(resp http.ResponseWriter, req *http.Request) ( fmt.Fprintf(resp, "Request body(%d bytes) too large, max size: %d bytes. See %s.", req.ContentLength, maxTxnLen, - "https://www.consul.io/docs/agent/options.html#txn_max_req_len", + "https://www.consul.io/docs/agent/config/config-files.html#txn_max_req_len", ) return nil, 0, false } @@ -106,7 +106,7 @@ func (s *HTTPHandlers) convertOps(resp http.ResponseWriter, req *http.Request) ( fmt.Fprintf(resp, "Request body too large, max size: %d bytes. See %s.", maxTxnLen, - "https://www.consul.io/docs/agent/options.html#txn_max_req_len", + "https://www.consul.io/docs/agent/config/config-files.html#txn_max_req_len", ) } else { // Note the body is in API format, and not the RPC format. If we can't