diff --git a/website/content/commands/debug.mdx b/website/content/commands/debug.mdx index 4badf8de5f..0e7b16e826 100644 --- a/website/content/commands/debug.mdx +++ b/website/content/commands/debug.mdx @@ -78,11 +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. | -<<<<<<< HEAD -| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU profile is captured for `duration` in a single file, trace is captured for a single `interval`, 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/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. | ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 ## Examples diff --git a/website/content/docs/agent/config-entries.mdx b/website/content/docs/agent/config-entries.mdx index a020b37a41..f1119dd75a 100644 --- a/website/content/docs/agent/config-entries.mdx +++ b/website/content/docs/agent/config-entries.mdx @@ -56,14 +56,8 @@ See [Kubernetes Custom Resource Definitions](/docs/k8s/crds). 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 -<<<<<<< HEAD -specified in the Consul servers agent's -[configuration files](/docs/agent/options#config_entries_bootstrap) -======= -specified in all of the Consul servers's +convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's [configuration files](/docs/agent/config/config-files#config_entries_bootstrap) ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 ### Managing Configuration Entries with the CLI diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index 807a5b243e..8e1387cac0 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -5,605 +5,20 @@ description: >- This topic describes the supported parameters for configuring Consul agents in HCL and JSON configuration files. --- -<<<<<<< HEAD:website/content/docs/agent/options.mdx -# Configuration +# Configuration Key Reference -The agent has various configuration options that can be specified via -the command-line or via configuration files. All of the configuration -options are completely optional. Defaults are specified with their -descriptions. +This topic describes the supported parameters for configuring Consul agents in HCL and JSON configuration files. -Configuration precedence is evaluated in the following order: +## Overview -1. Command line arguments -2. Configuration files - -When loading configuration, Consul loads the configuration from files and -directories in lexical order. For example, configuration file -`basic_config.json` will be processed before `extra_config.json`. Configuration -can be in either [HCL](https://github.com/hashicorp/hcl#syntax) or JSON format. -Available in Consul 1.0 and later, the HCL support now requires an `.hcl` or -`.json` extension on all configuration files in order to specify their format. - -Configuration specified later will be merged into configuration specified -earlier. In most cases, "merge" means that the later version will override the -earlier. In some cases, such as event handlers, merging appends the handlers to -the existing configuration. The exact merging behavior is specified for each -option below. - -Consul also supports reloading configuration when it receives the -SIGHUP signal. Not all changes are respected, but those that are -documented below in the -[Reloadable Configuration](#reloadable-configuration) section. The -[reload command](/commands/reload) can also be used to trigger a -configuration reload. - -You can test the following configuration options by following the -[Getting Started](https://learn.hashicorp.com/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](/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. - - - - ```shell-session - $ consul agent -advertise '{{ GetInterfaceIP "eth0" }}' - ``` - - - -- `-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-session - $ consul agent -bind '{{ GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address" }}' - ``` - - - - - - ```shell-session - $ consul agent -bind '{{ GetInterfaceIP "eth0" }}' - ``` - - - - - - ```shell-session - $ 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, HTTPS, gRPC 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. - - - - ```shell - $ consul agent -dev -client '{{ GetPrivateInterfaces | exclude "type" "ipv6" | join "address" " " }}' - ``` - - - - - - ```shell - $ consul agent -dev -client '{{ GetPrivateInterfaces | join "address" " " }} {{ GetAllInterfaces | include "flags" "loopback" | join "address" " " }}' - ``` - - - - - - ```shell - $ consul agent -dev -client '{{ GetPrivateInterfaces | exclude "name" "br.*" | join "address" " " }}' - ``` - - - -- `-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/discovery/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-session - $ consul agent -retry-join "consul.domain.internal" - ``` - - - - - - ```shell-session - $ consul agent -retry-join "10.0.4.67" - ``` - - - - - - ```shell-session - $ consul agent -retry-join "192.0.2.10:8304" - ``` - - - - - - ```shell-session - $ consul agent -retry-join "[::1]:8301" - ``` - - - - - - ```shell-session - $ 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/install/cloud-auto-join). - - - - ```shell-session - $ 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/upgrading/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 -files. This may be easier in certain situations, for example when Consul is -======= -# Configuration Files ((#configuration_files)) - -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 +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 ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx being configured using a configuration management system. -The configuration files are formatted as HCL, or JSON. JSON formatted configs are easily readable -and editable by both humans and computers. JSON formatted configuration consists -of a single JSON object with multiple configuration keys specified within it. +The configuration files are formatted as HCL or JSON. JSON-formatted configurations may be easier to read and edit by humans and computers. +JSON formatted configuration consists of a single JSON object with multiple configuration keys specified within it. Configuration files are used for more than just setting up the agent. They are also used to provide check and service definitions that @@ -650,251 +65,17 @@ telemetry { } } ``` - -<<<<<<< HEAD:website/content/docs/agent/options.mdx -#### Configuration Key Reference ((#config_key_reference)) -======= -# Configuration Key Reference ((#config_key_reference)) ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx +### TTL Values --> **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'." +All the TTL values are parsed by Go's `time` package, and have the following [formatting specification](https://golang.org/pkg/time/#ParseDuration): -<<<<<<< HEAD:website/content/docs/agent/options.mdx -- `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 +
+"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'." +
- 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 behavior 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/security/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. - - - - ```hcl - managed_service_provider { - accessor_id = "ed22003b-0832-4e48-ac65-31de64e5c2ff" - secret_id = "cb6be010-bba8-4f30-a9ed-d347128dde17" - } - ``` - - ```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 ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx - `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 @@ -1833,6 +1014,573 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr ## Bootstrap Parameters +- `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/cli-flags#_bootstrap_expect). + +## Connect Parameters + +- `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/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). + +- `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](/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/cli-flags#_enable_local_script_checks). + +- `disable_keyring_file` - Equivalent to the + [`-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, + 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](/docs/agent/config/cli-flags#_default_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 + 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](/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 + 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](/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 + 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](/docs/agent/config/cli-flags#_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](/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/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 + 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` - Specifies a list of watch configurations that + allow an external process to be automatically invoked when a specific data view + is updated. See the [watch documentation](/docs/dynamic-app-config/watches) for details. + Watches can be modified when the configuration is reloaded. + +- `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/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 + 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. + + + - `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/cli-flags#_bootstrap_expect). @@ -2254,35 +2002,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](/docs/agent/config/cli-flags#_rejoin). -<<<<<<< HEAD:website/content/docs/agent/options.mdx - - - ```hcl - http_config { - response_headers { - Access-Control-Allow-Origin = "*" - } - } - ``` - - ```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" ]` -======= - `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/cli-flags#_retry_interval). ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx - `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. @@ -2331,109 +2053,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr instance_type = "t2.medium" } ``` - - ```json - { - "node_meta": { - "instance_type": "t2.medium" - } - } - ``` - -<<<<<<< HEAD:website/content/docs/agent/options.mdx -- `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. -======= - `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/docs/agent/config/cli-flags#_disable_host_node_id). ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx ## Raft Parameters @@ -2497,18 +2119,9 @@ 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/cli-flags#_serf_lan_bind). - This is an IP address, not to be confused with [`ports.serf_lan`](#serf_lan_port). - -<<<<<<< HEAD:website/content/docs/agent/options.mdx -- `session_ttl_min` The minimum allowed session TTL. This ensures sessions are not created with TTLs - 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. -======= + Specifies an IP address and should 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/cli-flags#_serf_lan_allowed_cidrs). ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx - - `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/cli-flags#_serf_wan_allowed_cidrs). ## Telemetry Paramters @@ -2665,12 +2278,10 @@ 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/cli-flags#_ui) command-line flag. +- `ui` - (**Deprecated in 1.9.0. Use [`ui_config.enabled`](#ui_config_enabled) instead.** - `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 display or features available in the UI. The following sub-keys are available: @@ -2796,37 +2407,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. -<<<<<<< HEAD:website/content/docs/agent/options.mdx -- `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/dynamic-app-config/watches) for more detail. - Watches can be modified when the configuration is reloaded. - -======= ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159:website/content/docs/agent/config/config-files.mdx ## TLS Configuration Reference This section documents all of the configuration settings that apply to Agent TLS. Agent diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index 7f1b77ab69..f27926eaea 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -135,12 +135,7 @@ $ consul agent -data-dir=/tmp/consul - **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 -<<<<<<< HEAD - in ["bootstrap"](/docs/agent/options#_bootstrap_expect) mode, which enables the server to elect itself 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. ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 + 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/cli-flags#_bootstrap_expect) mode, which enables the server to elect itself 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 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 cb9069e917..e7ce181d5e 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 @@ -33,15 +33,10 @@ Ensure that your Consul environment meets the following requirements. * 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). -<<<<<<< HEAD -* 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/gateways/mesh-gateway/service-to-service-traffic-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#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). ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 +* 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. ### 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 e32a75e6d5..9f6a3581b7 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 @@ -23,16 +23,16 @@ Ensure that your Consul environment meets the following requirements. ### Consul * Consul Enterprise version 1.11.0 or newer. + * A local Consul agent is required to manage its configuration. -<<<<<<< HEAD -* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/options#connect) for details. + * Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enterprise/admin-partitions) for details. -* If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#enable_central_service_config). -======= + * 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/config-files#enable_central_service_config). ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 ### 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 ca8036e6a1..c7bbd5dd0c 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 @@ -126,14 +126,9 @@ connect { } ``` -<<<<<<< HEAD -The [`start_join_wan`](/docs/agent/options#start_join_wan) or [`retry_join_wan`](/docs/agent/options#retry_join_wan) are only used for the [traditional federation process](/docs/k8s/installation/multi-cluster#traditional-wan-federation). They must be omitted when federating Consul servers via gateways. -======= -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. ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 +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`. +-> The `primary_gateways` configuration can use the same `go-discover` syntax used in `retry_join_wan`. ### Bootstrapping diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index f66077550d..e259df0d45 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -447,14 +447,8 @@ machine.node.dc1.test-domain. 0 IN A 127.0.0.1 machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment=" ``` -<<<<<<< HEAD --> **PTR queries:** Responses to PTR queries (`.in-addr.arpa.`) will always use the -[primary domain](/docs/agent/options#domain) (not the alternative domain), -======= --> **PTR queries:** Responses to PTR queries (`.in-addr.arpa.`) will always use the -[primary domain](/docs/agent/config/config-files#domain) (not the alternative domain), ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 -as there is no way for the query to specify a domain. +-> **PTR queries:** Responses to PTR queries (`.in-addr.arpa.`) always use the +[primary domain](/docs/agent/config/config-files#domain) and not the alternative domain. This is because the query cannot specify a domain. ## Caching diff --git a/website/content/docs/enterprise/audit-logging.mdx b/website/content/docs/enterprise/audit-logging.mdx index 6561a0a4d5..ac3505f402 100644 --- a/website/content/docs/enterprise/audit-logging.mdx +++ b/website/content/docs/enterprise/audit-logging.mdx @@ -24,8 +24,7 @@ greater insight into Consul access and usage patterns. 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](/docs/agent/config/config-files#audit) +For detailed configuration information on configuring the Consul Enterprise's audit logging, review the Consul [Audit Log](/docs/agent/config/config-files#audit) documentation. ## Example Configuration 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 1ed9e4938b..992997b140 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 @@ -6,31 +6,21 @@ description: Running Consul servers outside of Kubernetes # Consul Servers Outside of Kubernetes -If you have a Consul cluster already running, you can configure your -Consul clients inside Kubernetes to join this existing cluster. +This topic describes how to configure your Consul clients inside Kubernetes to join an existing cluster. -The below `config.yaml` file shows how to configure the Helm chart to install -Consul clients that will join an existing cluster. +## Configuration Overview -The `global.enabled` value first disables all chart components by default -so that each component is opt-in. This allows us to _only_ setup the client -agents. We then opt-in to the client agents by setting `client.enabled` to -`true`. +In the following example `config.yaml` file, the Helm chart is configured to install Consul clients that will join an existing cluster. It includes the following parameters: -Next, `client.exposeGossipPorts` can be set to `true` or `false` depending on if -you want the clients to be exposed on the Kubernetes internal node IPs (`true`) or -their pod IPs (`false`). +* The `global.enabled` parameter is set to `false`. This configuration disables all chart components by default so that each component must opt-in. As a result, only client agents will be set up when the configuraiton is applied. -Finally, `client.join` is set to an array of valid -<<<<<<< HEAD -[`-retry-join` values](/docs/agent/options#retry-join). In the -example above, a fake [cloud auto-join](/docs/install/cloud-auto-join) -======= -[`-retry-join` values](/docs/agent/config/cli-flags#retry-join). In the -example above, a fake [cloud auto-join](/docs/agent/cloud-auto-join) ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 -value is specified. This should be set to resolve to the proper addresses of -your existing Consul cluster. +* The `client.enabled` parameter is set to `true`. This configuration opts the client agents into the cluster. + +* The `client.exposeGossipPorts` parameter is set to `true` or `false`. Setting the parameter to `true` exposes the clients on the Kubernetes internal node IPs. Setting to `false` exposes the clients on their pod IPs. + +* The `client.join` is set to an array of valid +[`-retry-join` values](/docs/agent/config/cli-flags#retry-join). The +following example includes a [cloud auto-join](/docs/agent/cloud-auto-join) value resolve to the proper addresses of the existing Consul cluster. diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index f39e3e5cf3..7cbabb8988 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -102,11 +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. -<<<<<<< HEAD -The special `list` access level provides 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/config-files#acl_enable_key_list_policy) setting must be set to `true`. ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 ### Matching and Prefix Values diff --git a/website/content/docs/security/acl/acl-system.mdx b/website/content/docs/security/acl/acl-system.mdx index b10c6c61cc..bb36213cc0 100644 --- a/website/content/docs/security/acl/acl-system.mdx +++ b/website/content/docs/security/acl/acl-system.mdx @@ -173,14 +173,8 @@ examples of using a service identity. -> Added in Consul 1.8.1 -<<<<<<< HEAD -An ACL node identity is an [ACL policy](/docs/security/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 -======= 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/config-files#acl_tokens_agent). They are usable ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 -on both tokens and roles and are composed of the following elements: +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. - **Datacenter** - The datacenter that the node resides within. diff --git a/website/content/docs/security/security-models/core.mdx b/website/content/docs/security/security-models/core.mdx index c0f42a8612..e1a99a2ab3 100644 --- a/website/content/docs/security/security-models/core.mdx +++ b/website/content/docs/security/security-models/core.mdx @@ -235,11 +235,7 @@ environment and adapt these configurations accordingly. - **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 -<<<<<<< HEAD - [configured](/docs/agent/options#response_headers) for HTTP API responses. -======= - [configured](https://www.consul.io/docs/agent/config/config-files#response_headers) for HTTP API responses. ->>>>>>> cd907b75cebdefe62a30986e0cdc7bd528c52159 + [configured](/docs/agent/config/config-files#response_headers) for HTTP API responses. ```hcl http_config { 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 3eb66dd90a..2fa1f14d6f 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](/docs/security/acl/acl-legacy) - You can find information about legacy configuration options and differences between modes here. -- [Configuration](/docs/agent/config) - 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](/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)] +- 1.6.3 introduced the [http_max_conns_per_client](/docs/agent/config/config-files#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