mirror of https://github.com/status-im/consul.git
* docs: Re-add config file content removed in PR #12562 Re-add agent config option content that was erroneously removed in #12562 with commitf4c03d234. * docs: Re-add CLI flag content removed in PR #12562 Re-add CLI flag content that was erroneously removed in #12562 with commitc5220fd18. * Update website/content/docs/agent/config/cli-flags.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
Blake Covarrubias
GitHub
parent
0c855fab98
commit
20321402ce
|
|
@ -21,11 +21,14 @@ Environment variables **cannot** be used to configure the Consul client. They
|
|||
_can_ be used when running other `consul` CLI commands that connect with a
|
||||
running agent, e.g. `CONSUL_HTTP_ADDR=192.168.0.1:8500 consul members`.
|
||||
|
||||
See [Consul Commands](/docs/commands#environment-variables) for more
|
||||
See [Consul Commands](/commands#environment-variables) for more
|
||||
information.
|
||||
|
||||
## General
|
||||
|
||||
- `-auto-reload-config` ((#\_auto_reload_config)) - This option directs Consul to automatically reload the [reloadable configuration options](/docs/agent/config#reloadable-configuration) when configuration files change.
|
||||
Consul also watches the certificate and key files specified with the `cert_file` and `key_file` parameters and reloads the configuration if the files are updated.
|
||||
|
||||
- `-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
|
||||
|
|
@ -38,6 +41,30 @@ information.
|
|||
a space-separated list of addresses to bind to, or a [go-sockaddr]
|
||||
template that can potentially resolve to multiple addresses.
|
||||
|
||||
<CodeBlockConfig hideClipboard heading="Bind consul client interfaces to private IPv4 interfaces">
|
||||
|
||||
```shell
|
||||
$ consul agent -dev -client '{{ GetPrivateInterfaces | exclude "type" "ipv6" | join "address" " " }}'
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig hideClipboard heading="Bind consul client interfaces to private IP addresses and loopback">
|
||||
|
||||
```shell
|
||||
$ consul agent -dev -client '{{ GetPrivateInterfaces | join "address" " " }} {{ GetAllInterfaces | include "flags" "loopback" | join "address" " " }}'
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig hideClipboard heading="Exclude private interfaces that start with 'br-'">
|
||||
|
||||
```shell
|
||||
$ consul agent -dev -client '{{ GetPrivateInterfaces | exclude "name" "br.*" | join "address" " " }}'
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `-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
|
||||
|
|
@ -65,7 +92,7 @@ information.
|
|||
only the given `-encrypt` key will be available on startup. This defaults to false.
|
||||
|
||||
- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether
|
||||
[health checks that execute scripts](/docs/agent/checks) are enabled on this
|
||||
[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.
|
||||
|
||||
|
|
@ -76,11 +103,10 @@ information.
|
|||
for more details.
|
||||
|
||||
- `-enable-local-script-checks` ((#\_enable_local_script_checks))
|
||||
Like [`enable_script_checks`](#_enable_script_checks), but only enable them when
|
||||
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).
|
||||
|
|
@ -92,7 +118,7 @@ information.
|
|||
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.
|
||||
-1 (gRPC disabled). See [ports](/docs/agent/config#ports-used) 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
|
||||
|
|
@ -105,7 +131,7 @@ information.
|
|||
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.
|
||||
-1 (https disabled). See [ports](/docs/agent/config#ports-used) documentation for more detail.
|
||||
|
||||
- `-default-query-time` ((#\_default_query_time)) - This flag controls the
|
||||
amount of time a blocking query will wait before Consul will force a response.
|
||||
|
|
@ -122,7 +148,7 @@ information.
|
|||
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`.
|
||||
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 version`.
|
||||
|
||||
- `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version
|
||||
of the Raft consensus protocol used for server communications. This must be set
|
||||
|
|
@ -136,7 +162,7 @@ information.
|
|||
for more details. By default, this is an empty string, which is the `<default>`
|
||||
network segment.
|
||||
|
||||
~> **Warning:** The `segment` flag cannot be used with the [`partition`](#partition-1) option.
|
||||
~> **Warning:** The `segment` flag cannot be used with the [`partition`](/docs/agent/config/config-files#partition-1) option.
|
||||
|
||||
## Advertise Address Options
|
||||
|
||||
|
|
@ -148,6 +174,14 @@ information.
|
|||
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.
|
||||
|
||||
<CodeBlockConfig heading="Using a static network interface name">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -advertise '{{ GetInterfaceIP "eth0" }}'
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `-advertise-wan` ((#\_advertise-wan)) - The advertise WAN address is used
|
||||
to change the address that we advertise to server nodes joining through the WAN.
|
||||
This can also be set on client agents when used in combination with the [`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address
|
||||
|
|
@ -173,21 +207,30 @@ information.
|
|||
both. If you have any firewalls, be sure to allow both protocols. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
|
||||
template that must resolve at runtime to a single address. Some example templates:
|
||||
|
||||
```shell
|
||||
# Using address within a specific CIDR
|
||||
<CodeBlockConfig heading="Using address within a specific CIDR">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -bind '{{ GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address" }}'
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using a static network interface name
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using a static network interface name">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -bind '{{ GetInterfaceIP "eth0" }}'
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using regular expression matching for network interface name that is forwardable and up
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using regular expression matching for network interface name that is forwardable and up">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -bind '{{ GetAllInterfaces | include "name" "^eth" | include "flags" "forwardable|up" | attr "address" }}'
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `-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`
|
||||
|
|
@ -221,7 +264,7 @@ information.
|
|||
## Configuration File Options
|
||||
|
||||
- `-config-file` ((#\_config_file)) - A configuration file to load. For
|
||||
more information on the format of this file, read the [Configuration Files](#configuration_files)
|
||||
more information on the format of this file, read the [Configuration Files](/docs/agent/config/config-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
|
||||
|
|
@ -234,7 +277,7 @@ information.
|
|||
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.
|
||||
the [Configuration Files](/docs/agent/config/config-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
|
||||
|
|
@ -261,14 +304,14 @@ information.
|
|||
|
||||
- `-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).
|
||||
to the [`recursors` configuration option](/docs/agent/config/config-files#recursors).
|
||||
|
||||
## Join Options
|
||||
|
||||
- `-join` ((#\_join)) - Address of another agent to join upon starting up.
|
||||
This can be specified multiple times to specify multiple agents to join. If Consul
|
||||
is unable to join with any of the specified addresses, agent startup will fail.
|
||||
By default, the agent won't join any nodes when it starts up. Note that using [`retry_join`](#retry_join) could be more appropriate to help mitigate node startup race conditions when automating
|
||||
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
|
||||
|
|
@ -302,31 +345,46 @@ information.
|
|||
|
||||
Here are some examples of using `-retry-join`:
|
||||
|
||||
```shell
|
||||
# Using a DNS entry
|
||||
<CodeBlockConfig heading="Using a DNS entry">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "consul.domain.internal"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using IPv4
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using IPv4">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "10.0.4.67"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using a non-default Serf LAN port
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using a non-default Serf LAN port">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "192.0.2.10:8304"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using IPv6
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using IPv6">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "[::1]:8301"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using multiple addresses
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using multiple addresses">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "consul.domain.internal" -retry-join "10.0.4.67"
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
### Cloud Auto-Joining
|
||||
|
||||
As of Consul 0.9.1, `retry-join` accepts a unified interface using the
|
||||
|
|
@ -334,11 +392,14 @@ information.
|
|||
automatic cluster joining using cloud metadata. For more information, see
|
||||
the [Cloud Auto-join page](/docs/agent/cloud-auto-join).
|
||||
|
||||
```shell
|
||||
# Using Cloud Auto-Joining
|
||||
<CodeBlockConfig heading="Using Cloud Auto-Joining">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "provider=aws tag_key=..."
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `-retry-interval` ((#\_retry_interval)) - Time to wait between join attempts.
|
||||
Defaults to 30s.
|
||||
|
||||
|
|
@ -355,7 +416,7 @@ information.
|
|||
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)
|
||||
- `-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.
|
||||
|
|
@ -363,7 +424,7 @@ information.
|
|||
In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
|
||||
template that is resolved at runtime.
|
||||
|
||||
- `-primary-gateway` ((#\_primary_gateway)) - Similar to [`retry-join-wan`](#_retry_join_wan)
|
||||
- `-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)
|
||||
|
|
@ -415,7 +476,7 @@ information.
|
|||
in a JSON format. By default this is false.
|
||||
|
||||
- `-syslog` ((#\_syslog)) - This flag enables logging to syslog. This is
|
||||
only supported on Linux and OSX. It will result in an error if provided on Windows.
|
||||
only supported on Linux and macOS. It will result in an error if provided on Windows.
|
||||
|
||||
## Node Options
|
||||
|
||||
|
|
@ -486,7 +547,7 @@ information.
|
|||
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.
|
||||
RPC 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
|
||||
|
|
@ -519,3 +580,7 @@ information.
|
|||
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.
|
||||
|
||||
<!-- list of reference-style links -->
|
||||
|
||||
[go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template
|
||||
|
|
|
|||
|
|
@ -13,18 +13,37 @@ easier to manage configuration changes. Using external files may be easier than
|
|||
configuring agents on the command-line when Consul is
|
||||
being configured using a configuration management system.
|
||||
|
||||
The configuration files are JSON formatted, making them easily readable
|
||||
and editable by both humans and computers. The configuration is formatted
|
||||
as a single JSON object with configuration within it.
|
||||
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.
|
||||
|
||||
Configuration files are used for more than just setting up the agent,
|
||||
they are also used to provide check and service definitions. These are used
|
||||
to announce the availability of system servers to the rest of the cluster.
|
||||
They are documented separately under [check configuration](/docs/agent/checks) and
|
||||
[service configuration](/docs/agent/services) respectively. The service and check
|
||||
Configuration files are used for more than just setting up the agent.
|
||||
They are also used to provide check and service definitions that
|
||||
announce the availability of system servers to the rest of the cluster.
|
||||
These definitions are documented separately under [check configuration](/docs/agent/checks) and
|
||||
[service configuration](/docs/agent/services) respectively. Service and check
|
||||
definitions support being updated during a reload.
|
||||
|
||||
#### Example Configuration File
|
||||
<CodeTabs heading="Example Configuration File">
|
||||
|
||||
```hcl
|
||||
datacenter = "east-aws"
|
||||
data_dir = "/opt/consul"
|
||||
log_level = "INFO"
|
||||
node_name = "foobar"
|
||||
server = true
|
||||
watches = [
|
||||
{
|
||||
type = "checks"
|
||||
handler = "/usr/bin/health-check-handler.sh"
|
||||
}
|
||||
]
|
||||
|
||||
telemetry {
|
||||
statsite_address = "127.0.0.1:2180"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -45,6 +64,8 @@ definitions support being updated during a reload.
|
|||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
# Configuration Key Reference ((#config_key_reference))
|
||||
|
||||
-> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following
|
||||
|
|
@ -87,6 +108,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
- `audit` <EnterpriseAlert inline /> - Added in Consul 1.8, the audit object allow users to enable auditing
|
||||
and configure a sink and filters for their audit logs. For more information, review the [audit log tutorial](https://learn.hashicorp.com/tutorials/consul/audit-logging).
|
||||
|
||||
<CodeTabs heading="Example audit configuration">
|
||||
|
||||
```hcl
|
||||
audit {
|
||||
enabled = true
|
||||
|
|
@ -102,6 +125,27 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"audit": {
|
||||
"enabled": true,
|
||||
"sink": {
|
||||
"My sink": {
|
||||
"type": "file",
|
||||
"format": "json",
|
||||
"path": "data/audit/audit.json",
|
||||
"delivery_guarantee": "best-effort",
|
||||
"rotate_duration": "24h",
|
||||
"rotate_max_files": 15,
|
||||
"rotate_bytes": 25165824
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
The following sub-keys are available:
|
||||
|
||||
- `enabled` - Controls whether Consul logs out each time a user
|
||||
|
|
@ -156,7 +200,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
unhealthy. Defaults to 250.
|
||||
|
||||
- `min_quorum` - Sets the minimum number of servers necessary
|
||||
in a cluster before autopilot can prune dead servers. There is no default.
|
||||
in a cluster. Autopilot will stop pruning dead servers when this minimum is reached. There is no default.
|
||||
|
||||
- `server_stabilization_time` - Controls
|
||||
the minimum amount of time a server must be stable in the 'healthy' state before
|
||||
|
|
@ -165,7 +209,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
to `10s`.
|
||||
|
||||
- `redundancy_zone_tag` <EnterpriseAlert inline /> -
|
||||
This controls the [`-node-meta`](#_node_meta) key to use when Autopilot is separating
|
||||
This controls the [`node_meta`](#node_meta) key to use when Autopilot is separating
|
||||
servers into zones for redundancy. Only one server in each zone can be a voting
|
||||
member at one time. If left blank (the default), this feature will be disabled.
|
||||
|
||||
|
|
@ -227,7 +271,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
|
||||
- `static` This object controls configuring the static authorizer setup in the Consul
|
||||
configuration file. Almost all sub-keys are identical to those provided by the [JWT
|
||||
Auth Method](/docs/acl/auth-methods/jwt).
|
||||
Auth Method](/docs/security/acl/auth-methods/jwt).
|
||||
|
||||
- `jwt_validation_pub_keys` (Defaults to `[]`) A list of PEM-encoded public keys
|
||||
to use to authenticate signatures locally.
|
||||
|
|
@ -286,14 +330,16 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
validating all claims to account for clock skew. Defaults to 60s (1 minute)
|
||||
if set to 0s and can be disabled if set to -1ns.
|
||||
|
||||
- `claim_assertions` (Defaults to []) List of assertions about the mapped
|
||||
- `claim_assertions` (Defaults to `[]`) List of assertions about the mapped
|
||||
claims required to authorize the incoming RPC request. The syntax uses
|
||||
github.com/hashicorp/go-bexpr which is shared with the
|
||||
[API filtering feature](/api/features/filtering). For example, the following
|
||||
[github.com/hashicorp/go-bexpr](https://github.com/hashicorp/go-bexpr) which is shared with the
|
||||
[API filtering feature](/api-docs/features/filtering). For example, the following
|
||||
configurations when combined will ensure that the JWT `sub` matches the node
|
||||
name requested by the client.
|
||||
|
||||
```
|
||||
<CodeTabs heading="Ensure that the JWT sub matches the node name requested by the client">
|
||||
|
||||
```hcl
|
||||
claim_mappings {
|
||||
sub = "node_name"
|
||||
}
|
||||
|
|
@ -302,6 +348,17 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
]
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"claim_mappings": {
|
||||
"sub": "node_name"
|
||||
},
|
||||
"claim_assertions": ["value.node_name == \"${node}\""]
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
The assertions are lightly templated using [HIL syntax](https://github.com/hashicorp/hil)
|
||||
to interpolate some values from the RPC request. The list of variables that can be interpolated
|
||||
are:
|
||||
|
|
@ -312,6 +369,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
|
||||
- `partition` <EnterpriseAlert inline /> - The admin partition name the client is requesting.
|
||||
|
||||
- `auto_reload_config` Equivalent to the [`-auto-reload-config` command-line flag](/docs/agent/config/cli-flags#_auto_reload_config).
|
||||
|
||||
- `bind_addr` Equivalent to the [`-bind` command-line flag](/docs/agent/config/cli-flags#_bind).
|
||||
|
||||
This parameter can be set to a go-sockaddr template that resolves to a single
|
||||
|
|
@ -319,19 +378,19 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
within a double quoted string value must be escaped with a backslash `\`.
|
||||
Some example templates:
|
||||
|
||||
<CodeTabs>
|
||||
<CodeTabs>
|
||||
|
||||
```hcl
|
||||
bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}"
|
||||
```
|
||||
```hcl
|
||||
bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"bind_addr": "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}"
|
||||
}
|
||||
```
|
||||
```json
|
||||
{
|
||||
"bind_addr": "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr \"address\" }}"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
</CodeTabs>
|
||||
|
||||
- `cache` configuration for client agents. The configurable values are the following:
|
||||
|
||||
|
|
@ -442,6 +501,17 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `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:
|
||||
|
||||
|
||||
<CodeTabs heading="Enable CORS on the HTTP API endpoints">
|
||||
|
||||
```hcl
|
||||
http_config {
|
||||
response_headers {
|
||||
Access-Control-Allow-Origin = "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"http_config": {
|
||||
|
|
@ -452,9 +522,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
- `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.
|
||||
- `use_cache` ((#http_config_use_cache)) Defaults to true. If disabled, the agent won't be using [agent caching](/api-docs/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.
|
||||
|
||||
|
|
@ -473,8 +545,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `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.
|
||||
- `kv_max_value_size` - **(Advanced)** Configures the maximum number of bytes for a kv request body to the [`/v1/kv`](/api-docs/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-docs/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).
|
||||
|
||||
|
|
@ -488,7 +560,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
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.
|
||||
[`segment`](#segment-2) option or [`-segment`](/docs/agent/config/cli-flags#_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:
|
||||
|
||||
|
|
@ -512,7 +584,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
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).
|
||||
- `pid_file` Equivalent to the [`-pid-file` command line flag](/docs/agent/config/cli-flags#_pid_file).
|
||||
|
||||
- `ports` This is a nested object that allows setting the bind ports for the following keys:
|
||||
|
||||
|
|
@ -529,9 +601,9 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
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).
|
||||
and UDP. Equivalent to the [`-serf-lan-port` command line flag](/docs/agent/config/cli-flags#_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
|
||||
Equivalent to the [`-serf-wan-port` command line flag](/docs/agent/config/cli-flags#_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.
|
||||
|
|
@ -628,11 +700,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `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
|
||||
the segment's gossip layer. Defaults to the [`-advertise`](/docs/agent/config/cli-flags#_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)
|
||||
listener will be started on this segment's [`-bind`](/docs/agent/config/cli-flags#_bind) address on the rpc
|
||||
port. Only valid if the segment's bind address differs from the [`-bind`](/docs/agent/config/cli-flags#_bind)
|
||||
address. Defaults to false.
|
||||
|
||||
- `server` Equivalent to the [`-server` command-line flag](/docs/agent/config/cli-flags#_server).
|
||||
|
|
@ -641,7 +713,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `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
|
||||
- `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.
|
||||
|
||||
|
|
@ -657,26 +729,26 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
a client will gracefully leave).
|
||||
|
||||
- `translate_wan_addrs` If set to true, Consul
|
||||
will prefer a node's configured [WAN address](#_advertise-wan)
|
||||
will prefer a node's configured [WAN address](/docs/agent/config/cli-flags#_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
|
||||
node's configured [WAN address](/docs/agent/config/cli-flags#_advertise-wan) when querying for a node in a remote
|
||||
datacenter. An [`X-Consul-Translate-Addresses`](/api-docs#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/<node>`](/api/catalog#retrieve-map-of-services-for-a-node)
|
||||
- [`/v1/catalog/service/<service>`](/api/catalog#list-nodes-for-service)
|
||||
- [`/v1/health/service/<service>`](/api/health#list-nodes-for-service)
|
||||
- [`/v1/query/<query or name>/execute`](/api/query#execute-prepared-query)
|
||||
- [`/v1/catalog/nodes`](/api-docs/catalog#list-nodes)
|
||||
- [`/v1/catalog/node/<node>`](/api-docs/catalog#retrieve-map-of-services-for-a-node)
|
||||
- [`/v1/catalog/service/<service>`](/api-docs/catalog#list-nodes-for-service)
|
||||
- [`/v1/health/service/<service>`](/api-docs/health#list-nodes-for-service)
|
||||
- [`/v1/query/<query or name>/execute`](/api-docs/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
|
||||
|
|
@ -703,7 +775,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `watches` - Watches is a list of watch specifications which
|
||||
allow an external process to be automatically invoked when a particular data view
|
||||
is updated. See the [watch documentation](/docs/agent/watches) for more detail.
|
||||
is updated. See the [watch documentation](/docs/dynamic-app-config/watches) for more detail.
|
||||
Watches can be modified when the configuration is reloaded.
|
||||
|
||||
## ACL Paramters
|
||||
|
|
@ -740,7 +812,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
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
|
||||
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,
|
||||
|
|
@ -763,8 +835,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `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.
|
||||
allow for the creation of both [local tokens](/api-docs/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
|
||||
|
|
@ -815,7 +887,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `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,
|
||||
Used to access [agent endpoints](/api-docs/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.
|
||||
|
|
@ -825,7 +897,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `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.
|
||||
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-docs/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
|
||||
|
|
@ -835,6 +907,15 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `managed_service_provider` ((#acl_tokens_managed_service_provider)) <EnterpriseAlert inline /> - An
|
||||
array of ACL tokens used by Consul managed service providers for cluster operations.
|
||||
|
||||
<CodeTabs heading="Example managed_service_provider configuration">
|
||||
|
||||
```hcl
|
||||
managed_service_provider {
|
||||
accessor_id = "ed22003b-0832-4e48-ac65-31de64e5c2ff"
|
||||
secret_id = "cb6be010-bba8-4f30-a9ed-d347128dde17"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
"managed_service_provider": [
|
||||
{
|
||||
|
|
@ -844,6 +925,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
]
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
- `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,
|
||||
|
|
@ -871,7 +954,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `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
|
||||
field instead.** Used to access [agent endpoints](/api-docs/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
|
||||
|
|
@ -902,7 +985,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
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)
|
||||
set the token later using the [agent token API](/api-docs/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.
|
||||
|
||||
|
|
@ -927,7 +1010,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `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.
|
||||
and then introduce the token using the [agent token API](/api-docs/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,
|
||||
|
|
@ -976,12 +1059,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `ca_provider` ((#connect_ca_provider)) Controls which CA provider to
|
||||
use for Connect's CA. Currently only the `aws-pca`, `consul`, and `vault` providers are supported.
|
||||
This is only used when initially bootstrapping the cluster. For an existing cluster,
|
||||
use the [Update CA Configuration Endpoint](/api/connect/ca#update-ca-configuration).
|
||||
use the [Update CA Configuration Endpoint](/api-docs/connect/ca#update-ca-configuration).
|
||||
|
||||
- `ca_config` ((#connect_ca_config)) An object which allows setting different
|
||||
config options based on the CA provider chosen. This is only used when initially
|
||||
bootstrapping the cluster. For an existing cluster, use the [Update CA Configuration
|
||||
Endpoint](/api/connect/ca#update-ca-configuration).
|
||||
Endpoint](/api-docs/connect/ca#update-ca-configuration).
|
||||
|
||||
The following providers are supported:
|
||||
|
||||
|
|
@ -1023,6 +1106,23 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
as well as permission to mount the backend at this path if it is not already
|
||||
mounted.
|
||||
|
||||
- `auth_method` ((#vault_ca_auth_method))
|
||||
Vault auth method to use for logging in to Vault.
|
||||
Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for more information
|
||||
on how to configure individual auth methods. If auth method is provided, Consul will obtain a
|
||||
new token from Vault when the token can no longer be renewed.
|
||||
|
||||
- `type` The type of Vault auth method.
|
||||
|
||||
- `mount_path` The mount path of the auth method.
|
||||
If not provided the auth method type will be used as the mount path.
|
||||
|
||||
- `params` The parameters to configure the auth method.
|
||||
Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for information on how
|
||||
to configure the auth method you wish to use. If using the Kubernetes auth method, Consul will
|
||||
read the service account token from the default mount path `/var/run/secrets/kubernetes.io/serviceaccount/token`
|
||||
if the `jwt` parameter is not provided.
|
||||
|
||||
#### Common CA Config Options
|
||||
|
||||
There are also a number of common configuration options supported by all providers:
|
||||
|
|
@ -1048,19 +1148,25 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
if servers have more than one CPU core. Setting this to zero disables rate limiting.
|
||||
Added in 1.4.1.
|
||||
|
||||
- `leaf_cert_ttl` ((#ca_leaf_cert_ttl)) The upper bound on the lease
|
||||
duration of a leaf certificate issued for a service. In most cases a new leaf
|
||||
- `leaf_cert_ttl` ((#ca_leaf_cert_ttl)) Specifies the upper bound on the expiry
|
||||
of a leaf certificate issued for a service. In most cases a new leaf
|
||||
certificate will be requested by a proxy before this limit is reached. This
|
||||
is also the effective limit on how long a server outage can last (with no leader)
|
||||
before network connections will start being rejected. Defaults to `72h`.
|
||||
This value cannot be lower than 1 hour or higher than 1 year.
|
||||
|
||||
You can specify a range from one hour (minimum) up to one year (maximum) using
|
||||
the following units: `h`, `m`, `s`, `ms`, `us` (or `µs`), `ns`, or a combination
|
||||
of those units, e.g. `1h5m`.
|
||||
|
||||
This value is also used when rotating out old root certificates from
|
||||
the cluster. When a root certificate has been inactive (rotated out)
|
||||
for more than twice the _current_ `leaf_cert_ttl`, it will be removed
|
||||
from the trusted list.
|
||||
|
||||
- `root_cert_ttl` ((#ca_root_cert_ttl)) The time to live (TTL) for a root certificate.
|
||||
- `intermediate_cert_ttl` ((#ca_intermediate_cert_ttl)) Specifies the expiry for the
|
||||
intermediate certificates. Defaults to `8760h` (1 year). Must be at least 3 times `leaf_cert_ttl`.
|
||||
|
||||
- `root_cert_ttl` ((#ca_root_cert_ttl)) Specifies the expiry for a root certificate.
|
||||
Defaults to 10 years as `87600h`. This value, if provided, needs to be higher than the
|
||||
intermediate certificate TTL.
|
||||
|
||||
|
|
@ -1211,12 +1317,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
in seconds, default value is 600, ie: 10 minutes.
|
||||
|
||||
- `use_cache` ((#dns_use_cache)) - When set to true, DNS resolution will
|
||||
use the agent cache described in [agent caching](/api/features/caching).
|
||||
use the agent cache described in [agent caching](/api-docs/features/caching).
|
||||
This setting affects all service and prepared queries DNS requests. Implies [`allow_stale`](#allow_stale)
|
||||
|
||||
- `cache_max_age` ((#dns_cache_max_age)) - When [use_cache](#dns_use_cache)
|
||||
is enabled, the agent will attempt to re-fetch the result from the servers if
|
||||
the cached value is older than this duration. See: [agent caching](/api/features/caching).
|
||||
the cached value is older than this duration. See: [agent caching](/api-docs/features/caching).
|
||||
|
||||
**Note** that unlike the `max-age` HTTP header, a value of 0 for this field is
|
||||
equivalent to "no max age". To get a fresh value from the cache use a very small value
|
||||
|
|
@ -1278,13 +1384,13 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `encrypt_verify_incoming` - This is an optional
|
||||
parameter that can be used to disable enforcing encryption for incoming gossip
|
||||
in order to upshift from unencrypted to encrypted gossip on a running cluster.
|
||||
See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster)
|
||||
See [this section](/docs/security/encryption#configuring-gossip-encryption-on-an-existing-cluster)
|
||||
for more information. Defaults to true.
|
||||
|
||||
- `encrypt_verify_outgoing` - This is an optional
|
||||
parameter that can be used to disable enforcing encryption for outgoing gossip
|
||||
in order to upshift from unencrypted to encrypted gossip on a running cluster.
|
||||
See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster)
|
||||
See [this section](/docs/security/encryption#configuring-gossip-encryption-on-an-existing-cluster)
|
||||
for more information. Defaults to true.
|
||||
|
||||
## Gossip Parameters
|
||||
|
|
@ -1386,12 +1492,12 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](/docs/agent/config/cli-flags#_retry_interval_wan).
|
||||
|
||||
- `start_join` An array of strings specifying addresses
|
||||
of nodes to [`-join`](#_join) upon startup. Note that using
|
||||
of nodes to [`-join`](/docs/agent/config/cli-flags#_join) upon startup. Note that using
|
||||
`retry_join` could be more appropriate to help mitigate
|
||||
node startup race conditions when automating a Consul cluster deployment.
|
||||
|
||||
- `start_join_wan` An array of strings specifying addresses
|
||||
of WAN nodes to [`-join-wan`](#_join_wan) upon startup.
|
||||
of WAN nodes to [`-join-wan`](/docs/agent/config/cli-flags#_join_wan) upon startup.
|
||||
|
||||
## Log Parameters
|
||||
|
||||
|
|
@ -1421,6 +1527,14 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `node_meta` Available in Consul 0.7.3 and later, This object allows associating arbitrary metadata key/value pairs with the local node, which can then be used for filtering results from certain catalog endpoints. See the [`-node-meta` command-line flag](/docs/agent/config/cli-flags#_node_meta) for more information.
|
||||
|
||||
<CodeTabs heading="Example node_meta configuration">
|
||||
|
||||
```hcl
|
||||
node_meta {
|
||||
instance_type = "t2.medium"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"node_meta": {
|
||||
|
|
@ -1429,6 +1543,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/docs/agent/config/cli-flags#_disable_host_node_id).
|
||||
|
||||
## Raft Parameters
|
||||
|
|
@ -1565,7 +1681,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
geo location or datacenter, dc:sfo). By default, this is left blank and not used.
|
||||
|
||||
- `disable_compat_1.9` ((#telemetry-disable_compat_1.9))
|
||||
This allows users to disable metrics deprecated in 1.9 so they are no longer emitted, saving on performance and storage in large deployments. Defaults to false.
|
||||
This allows users to disable metrics deprecated in 1.9 so they are no longer emitted, improving performance and reducing storage in large deployments. As of 1.12 this defaults to `true` and will be removed, along with 1.9 style http metrics in 1.13.
|
||||
|
||||
- `disable_hostname` ((#telemetry-disable_hostname))
|
||||
This controls whether or not to prepend runtime telemetry with the machine's
|
||||
|
|
@ -1597,10 +1713,28 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
This is a list of filter rules to apply for allowing/blocking metrics by
|
||||
prefix in the following format:
|
||||
|
||||
```json
|
||||
["+consul.raft.apply", "-consul.http", "+consul.http.GET"]
|
||||
<CodeTabs heading="Example prefix_filter configuration">
|
||||
|
||||
```hcl
|
||||
telemetry {
|
||||
prefix_filter = ["+consul.raft.apply", "-consul.http", "+consul.http.GET"]
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"telemetry": {
|
||||
"prefix_filter": [
|
||||
"+consul.raft.apply",
|
||||
"-consul.http",
|
||||
"+consul.http.GET"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
A leading "**+**" will enable any metrics with the given prefix, and a leading "**-**" will block them. If there is overlap between two rules, the more specific rule will take precedence. Blocking will take priority if the same prefix is listed multiple times.
|
||||
|
||||
- `prometheus_retention_time` ((#telemetry-prometheus_retention_time)) If the value is greater than `0s` (the default), this enables [Prometheus](https://prometheus.io/)
|
||||
|
|
@ -1610,20 +1744,24 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
2 times the interval of scrape of Prometheus, but you might also put a very high
|
||||
retention time such as a few days (for instance 744h to enable retention to 31
|
||||
days). Fetching the metrics using prometheus can then be performed using the
|
||||
[`/v1/agent/metrics?format=prometheus`](/api/agent#view-metrics) endpoint.
|
||||
[`/v1/agent/metrics?format=prometheus`](/api-docs/agent#view-metrics) endpoint.
|
||||
The format is compatible natively with prometheus. When running in this mode,
|
||||
it is recommended to also enable the option [`disable_hostname`](#telemetry-disable_hostname)
|
||||
to avoid having prefixed metrics with hostname. Consul does not use the default
|
||||
Prometheus path, so Prometheus must be configured as follows. Note that using
|
||||
?format=prometheus in the path won't work as ? will be escaped, so it must be
|
||||
`?format=prometheus` in the path won't work as `?` will be escaped, so it must be
|
||||
specified as a parameter.
|
||||
|
||||
<CodeBlockConfig heading="Example Prometheus configuration">
|
||||
|
||||
```yaml
|
||||
metrics_path: '/v1/agent/metrics'
|
||||
params:
|
||||
format: ['prometheus']
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `statsd_address` ((#telemetry-statsd_address)) This provides the address
|
||||
of a statsd instance in the format `host:port`. If provided, Consul will send
|
||||
various telemetry information to that instance for aggregation. This can be used
|
||||
|
|
@ -1659,7 +1797,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
|
||||
- `content_path` ((#ui_config_content_path)) - This specifies the HTTP path
|
||||
that the web UI should be served from. Defaults to `/ui/`. Equivalent to the
|
||||
[`-ui-content-path`](#_ui_content_path) flag.
|
||||
[`-ui-content-path`](/docs/agent/config/cli-flags#_ui_content_path) flag.
|
||||
|
||||
- `metrics_provider` ((#ui_config_metrics_provider)) - Specifies a named
|
||||
metrics provider implementation the UI should use to fetch service metrics.
|
||||
|
|
@ -1772,114 +1910,251 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
## TLS Configuration Reference
|
||||
|
||||
This section documents all of the configuration settings that apply to Agent TLS. Agent
|
||||
TLS is used by the HTTP API, server RPC, and xDS interfaces. Some of these settings may also be
|
||||
applied automatically by [auto_config](#auto_config) or [auto_encrypt](#auto_encrypt).
|
||||
TLS is used by the HTTP API, internal RPC, and gRPC/xDS interfaces. Some of these settings
|
||||
may also be applied automatically by [auto_config](#auto_config) or [auto_encrypt](#auto_encrypt).
|
||||
|
||||
~> **Security Note:** The Certificate Authority (CA) specified by `ca_file` or `ca_path`
|
||||
should be a private CA, not a public one. We recommend using a dedicated CA
|
||||
which should not be used with any other systems. Any certificate signed by the
|
||||
CA will be allowed to communicate with the cluster and a specially crafted certificate
|
||||
signed by the CA can be used to gain full access to Consul.
|
||||
~> **Security Note:** The Certificate Authority (CA) configured on the internal RPC interface
|
||||
(either explicitly by `tls.internal_rpc` or implicitly by `tls.defaults`) should be a private
|
||||
CA, not a public one. We recommend using a dedicated CA which should not be used with any other
|
||||
systems. Any certificate signed by the CA will be allowed to communicate with the cluster and a
|
||||
specially crafted certificate signed by the CA can be used to gain full access to Consul.
|
||||
|
||||
- `ca_file` This provides a file path to a PEM-encoded certificate
|
||||
authority. The certificate authority is used to check the authenticity of client
|
||||
and server connections with the appropriate [`verify_incoming`](#verify_incoming)
|
||||
or [`verify_outgoing`](#verify_outgoing) flags.
|
||||
- `tls` Added in Consul 1.12, for previous versions see
|
||||
[Deprecated Options](#tls_deprecated_options).
|
||||
|
||||
- `ca_path` This provides a path to a directory of PEM-encoded
|
||||
certificate authority files. These certificate authorities are used to check the
|
||||
authenticity of client and server connections with the appropriate [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) flags.
|
||||
- `defaults` ((#tls_defaults)) Provides default settings that will be applied
|
||||
to every interface unless explicitly overridden by `tls.grpc`, `tls.https`,
|
||||
or `tls.internal_rpc`.
|
||||
|
||||
- `cert_file` This provides a file path to a PEM-encoded
|
||||
certificate. The certificate is provided to clients or servers to verify the agent's
|
||||
authenticity. It must be provided along with [`key_file`](#key_file).
|
||||
- `ca_file` ((#tls_defaults_ca_file)) This provides a file path to a
|
||||
PEM-encoded certificate authority. The certificate authority is used to
|
||||
check the authenticity of client and server connections with the
|
||||
appropriate [`verify_incoming`](#tls_defaults_verify_incoming) or
|
||||
[`verify_outgoing`](#tls_defaults_verify_outgoing) flags.
|
||||
|
||||
- `key_file` This provides a the file path to a PEM-encoded
|
||||
private key. The key is used with the certificate to verify the agent's authenticity.
|
||||
This must be provided along with [`cert_file`](#cert_file).
|
||||
- `ca_path` ((#tls_defaults_ca_path)) This provides a path to a directory
|
||||
of PEM-encoded certificate authority files. These certificate authorities
|
||||
are used to check the authenticity of client and server connections with
|
||||
the appropriate [`verify_incoming`](#tls_defaults_verify_incoming) or
|
||||
[`verify_outgoing`](#tls_defaults_verify_outgoing) flags.
|
||||
|
||||
- `cert_file` ((#tls_defaults_cert_file)) This provides a file path to a
|
||||
PEM-encoded certificate. The certificate is provided to clients or servers
|
||||
to verify the agent's authenticity. It must be provided along with
|
||||
[`key_file`](#tls_defaults_key_file).
|
||||
|
||||
- `key_file` ((#tls_defaults_key_file)) This provides a the file path to a
|
||||
PEM-encoded private key. The key is used with the certificate to verify
|
||||
the agent's authenticity. This must be provided along with
|
||||
[`cert_file`](#tls_defaults_cert_file).
|
||||
|
||||
- `tls_min_version` ((#tls_defaults_tls_min_version)) This specifies the
|
||||
minimum supported version of TLS. The following values are accepted:
|
||||
* `TLSv1_0`
|
||||
* `TLSv1_1`
|
||||
* `TLSv1_2` (default)
|
||||
* `TLSv1_3`
|
||||
|
||||
**WARNING: TLS 1.1 and lower are generally considered less secure and
|
||||
should not be used if possible.**
|
||||
|
||||
The following values are also valid, but only when using the
|
||||
[deprecated top-level `tls_min_version` config](#tls_deprecated_options),
|
||||
and will be removed in a future release:
|
||||
|
||||
* `tls10`
|
||||
* `tls11`
|
||||
* `tls12`
|
||||
* `tls13`
|
||||
|
||||
A warning message will appear if a deprecated value is specified.
|
||||
|
||||
- `tls_cipher_suites` ((#tls_defaults_tls_cipher_suites)) This specifies
|
||||
the list of supported ciphersuites as a comma-separated-list. Applicable
|
||||
to TLS 1.2 and below only. The list of all supported ciphersuites is
|
||||
available through [this search](https://github.com/hashicorp/consul/search?q=goTLSCipherSuites+%3D+map).
|
||||
|
||||
~> **Note:** The ordering of cipher suites will not be guaranteed from
|
||||
Consul 1.11 onwards. See this [post](https://go.dev/blog/tls-cipher-suites)
|
||||
for details.
|
||||
|
||||
- `verify_incoming` - ((#tls_defaults_verify_incoming)) If set to true,
|
||||
Consul requires that all incoming connections make use of TLS and that
|
||||
the client provides a certificate signed by a Certificate Authority from
|
||||
the [`ca_file`](#tls_defaults_ca_file) or [`ca_path`](#tls_defaults_ca_path).
|
||||
By default, this is false, and Consul will not enforce the use of TLS or
|
||||
verify a client's authenticity.
|
||||
|
||||
- `verify_outgoing` - ((#tls_defaults_verify_outgoing)) If set to true,
|
||||
Consul requires that all outgoing connections from this agent make use
|
||||
of TLS and that the server provides a certificate that is signed by a
|
||||
Certificate Authority from the [`ca_file`](#tls_defaults_ca_file) or
|
||||
[`ca_path`](#tls_defaults_ca_path). By default, this is false, and Consul
|
||||
will not make use of TLS for outgoing connections. This applies to clients
|
||||
and servers as both will make outgoing connections. This setting *does not*
|
||||
apply to the gRPC interface as Consul makes no outgoing connections on this
|
||||
interface.
|
||||
|
||||
- `grpc` ((#tls_grpc)) Provides settings for the gRPC/xDS interface. To enable
|
||||
the gRPC interface you must define a port via [`ports.grpc`](#grpc_port).
|
||||
To enable TLS on the gRPC interface you also must define an HTTPS port via
|
||||
[`ports.https`](#https_port).
|
||||
|
||||
- `ca_file` ((#tls_grpc_ca_file)) Overrides [`tls.defaults.ca_file`](#tls_defaults_ca_file).
|
||||
|
||||
- `ca_path` ((#tls_grpc_ca_path)) Overrides [`tls.defaults.ca_path`](#tls_defaults_ca_path).
|
||||
|
||||
- `cert_file` ((#tls_grpc_cert_file)) Overrides [`tls.defaults.cert_file`](#tls_defaults_cert_file).
|
||||
|
||||
- `key_file` ((#tls_grpc_key_file)) Overrides [`tls.defaults.key_file`](#tls_defaults_key_file).
|
||||
|
||||
- `tls_min_version` ((#tls_grpc_tls_min_version)) Overrides [`tls.defaults.tls_min_version`](#tls_defaults_tls_min_version).
|
||||
|
||||
- `tls_cipher_suites` ((#tls_grpc_tls_cipher_suites)) Overrides [`tls.defaults.tls_cipher_suites`](#tls_defaults_tls_cipher_suites).
|
||||
|
||||
- `verify_incoming` - ((#tls_grpc_verify_incoming)) Overrides [`tls.defaults.verify_incoming`](#tls_defaults_verify_incoming).
|
||||
|
||||
- `https` ((#tls_https)) Provides settings for the HTTPS interface. To enable
|
||||
the HTTPS interface you must define a port via [`ports.https`](#https_port).
|
||||
|
||||
- `ca_file` ((#tls_https_ca_file)) Overrides [`tls.defaults.ca_file`](#tls_defaults_ca_file).
|
||||
|
||||
- `ca_path` ((#tls_https_ca_path)) Overrides [`tls.defaults.ca_path`](#tls_defaults_ca_path).
|
||||
|
||||
- `cert_file` ((#tls_https_cert_file)) Overrides [`tls.defaults.cert_file`](#tls_defaults_cert_file).
|
||||
|
||||
- `key_file` ((#tls_https_key_file)) Overrides [`tls.defaults.key_file`](#tls_defaults_key_file).
|
||||
|
||||
- `tls_min_version` ((#tls_https_tls_min_version)) Overrides [`tls.defaults.tls_min_version`](#tls_defaults_tls_min_version).
|
||||
|
||||
- `tls_cipher_suites` ((#tls_https_tls_cipher_suites)) Overrides [`tls.defaults.tls_cipher_suites`](#tls_defaults_tls_cipher_suites).
|
||||
|
||||
- `verify_incoming` - ((#tls_https_verify_incoming)) Overrides [`tls.defaults.verify_incoming`](#tls_defaults_verify_incoming).
|
||||
|
||||
- `verify_outgoing` - ((#tls_https_verify_outgoing)) Overrides [`tls.defaults.verify_outgoing`](#tls_defaults_verify_outgoing).
|
||||
|
||||
- `internal_rpc` ((#tls_internal_rpc)) Provides settings for the internal
|
||||
"server" RPC interface configured by [`ports.server`](#server_rpc_port).
|
||||
|
||||
- `ca_file` ((#tls_internal_rpc_ca_file)) Overrides [`tls.defaults.ca_file`](#tls_defaults_ca_file).
|
||||
|
||||
- `ca_path` ((#tls_internal_rpc_ca_path)) Overrides [`tls.defaults.ca_path`](#tls_defaults_ca_path).
|
||||
|
||||
- `cert_file` ((#tls_internal_rpc_cert_file)) Overrides [`tls.defaults.cert_file`](#tls_defaults_cert_file).
|
||||
|
||||
- `key_file` ((#tls_internal_rpc_key_file)) Overrides [`tls.defaults.key_file`](#tls_defaults_key_file).
|
||||
|
||||
- `tls_min_version` ((#tls_internal_rpc_tls_min_version)) Overrides [`tls.defaults.tls_min_version`](#tls_defaults_tls_min_version).
|
||||
|
||||
- `tls_cipher_suites` ((#tls_internal_rpc_tls_cipher_suites)) Overrides [`tls.defaults.tls_cipher_suites`](#tls_defaults_tls_cipher_suites).
|
||||
|
||||
- `verify_incoming` - ((#tls_internal_rpc_verify_incoming)) Overrides [`tls.defaults.verify_incoming`](#tls_defaults_verify_incoming).
|
||||
|
||||
~> **Security Note:** `verify_incoming` *must* be set to true to prevent
|
||||
anyone with access to the internal RPC port from gaining full access to
|
||||
the Consul cluster.
|
||||
|
||||
- `verify_outgoing` ((#tls_internal_rpc_verify_outgoing)) Overrides [`tls.defaults.verify_outgoing`](#tls_defaults_verify_outgoing).
|
||||
|
||||
~> **Security Note:** Servers that specify `verify_outgoing = true` will
|
||||
always talk to other servers over TLS, but they still _accept_ non-TLS
|
||||
connections to allow for a transition of all clients to TLS. Currently the
|
||||
only way to enforce that no client can communicate with a server unencrypted
|
||||
is to also enable `verify_incoming` which requires client certificates too.
|
||||
|
||||
- `verify_server_hostname` ((#tls_internal_rpc_verify_server_hostname)) When
|
||||
set to true, Consul verifies the TLS certificate presented by the servers
|
||||
match the hostname `server.<datacenter>.<domain>`. By default this is false,
|
||||
and Consul does not verify the hostname of the certificate, only that it
|
||||
is signed by a trusted CA. This setting *must* be enabled to prevent a
|
||||
compromised client from gaining full read and write access to all cluster
|
||||
data *including all ACL tokens and Connect CA root keys*.
|
||||
|
||||
- `server_name` When provided, this overrides the [`node_name`](#_node)
|
||||
for the TLS certificate. It can be used to ensure that the certificate name matches
|
||||
the hostname we declare.
|
||||
|
||||
- `tls_min_version` Added in Consul 0.7.4, this specifies
|
||||
the minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12",
|
||||
or "tls13". This defaults to "tls12". WARNING: TLS 1.1 and lower are generally
|
||||
considered less secure; avoid using these if possible.
|
||||
### Deprecated Options ((#tls_deprecated_options))
|
||||
|
||||
- `tls_cipher_suites` Added in Consul 0.8.2, this specifies the list of
|
||||
supported ciphersuites as a comma-separated-list. Applicable to TLS 1.2 and below only.
|
||||
The list of all supported ciphersuites is available through
|
||||
[this search](https://github.com/hashicorp/consul/search?q=cipherMap+%3A%3D+map&unscoped_q=cipherMap+%3A%3D+map).
|
||||
The following options were deprecated in Consul 1.12, please use the
|
||||
[`tls`](#tls) stanza instead.
|
||||
|
||||
~> **Note:** The ordering of cipher suites will not be guaranteed from Consul 1.11 onwards. See this
|
||||
[post](https://go.dev/blog/tls-cipher-suites) for details.
|
||||
- `ca_file` See: [`tls.defaults.ca_file`](#tls_defaults_ca_file).
|
||||
|
||||
- `tls_prefer_server_cipher_suites` Added in Consul 0.8.2, this
|
||||
will cause Consul to prefer the server's ciphersuite over the client ciphersuites.
|
||||
- `ca_path` See: [`tls.defaults.ca_path`](#tls_defaults_ca_path).
|
||||
|
||||
~> **Note:** This config will be deprecated in Consul 1.11. See this
|
||||
[post](https://go.dev/blog/tls-cipher-suites) for details.
|
||||
- `cert_file` See: [`tls.defaults.cert_file`](#tls_defaults_cert_file).
|
||||
|
||||
- `verify_incoming` - If set to true, Consul
|
||||
requires that all incoming connections make use of TLS and that the client
|
||||
provides a certificate signed by a Certificate Authority from the
|
||||
[`ca_file`](#ca_file) or [`ca_path`](#ca_path). This applies to both server
|
||||
RPC and to the HTTPS API. By default, this is false, and Consul will not
|
||||
enforce the use of TLS or verify a client's authenticity. Turning on
|
||||
`verify_incoming` on consul clients protects the HTTPS endpoint, by ensuring
|
||||
that the certificate that is presented by a 3rd party tool to the HTTPS
|
||||
endpoint was created by the CA that the consul client was setup with. If the
|
||||
UI is served, the same checks are performed.
|
||||
- `key_file` See: [`tls.defaults.key_file`](#tls_defaults_key_file).
|
||||
|
||||
- `verify_incoming_rpc` - When set to true, Consul
|
||||
requires that all incoming RPC connections use TLS and that the client
|
||||
provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file)
|
||||
or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce
|
||||
the use of TLS or verify a client's authenticity.
|
||||
- `tls_min_version` Added in Consul 0.7.4.
|
||||
See: [`tls.defaults.tls_min_version`](#tls_defaults_tls_min_version).
|
||||
|
||||
~> **Security Note:** `verify_incoming_rpc` _must_ be set to true to prevent anyone
|
||||
with access to the RPC port from gaining full access to the Consul cluster.
|
||||
- `tls_cipher_suites` Added in Consul 0.8.2.
|
||||
See: [`tls.defaults.tls_cipher_suites`](#tls_defaults_tls_cipher_suites).
|
||||
|
||||
- `verify_incoming_https` - If set to true,
|
||||
Consul requires that all incoming HTTPS connections make use of TLS and that the
|
||||
client provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file)
|
||||
or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce
|
||||
the use of TLS or verify a client's authenticity. To enable the HTTPS API, you
|
||||
must define an HTTPS port via the [`ports`](#ports) configuration. By default,
|
||||
HTTPS is disabled.
|
||||
- `tls_prefer_server_cipher_suites` Added in Consul 0.8.2. This setting will
|
||||
be ignored (see [this post](https://go.dev/blog/tls-cipher-suites) for details).
|
||||
|
||||
- `verify_outgoing` - If set to true, Consul requires
|
||||
that all outgoing connections from this agent make use of TLS and that the server
|
||||
provides a certificate that is signed by a Certificate Authority from the [`ca_file`](#ca_file)
|
||||
or [`ca_path`](#ca_path). By default, this is false, and Consul will not make use
|
||||
of TLS for outgoing connections. This applies to clients and servers as both will
|
||||
make outgoing connections.
|
||||
- `verify_incoming` See: [`tls.defaults.verify_incoming`](#tls_defaults_verify_incoming).
|
||||
|
||||
~> **Security Note:** Note that servers that specify `verify_outgoing = true` will always talk to other servers over TLS, but they still _accept_
|
||||
non-TLS connections to allow for a transition of all clients to TLS.
|
||||
Currently the only way to enforce that no client can communicate with a
|
||||
server unencrypted is to also enable `verify_incoming` which requires client
|
||||
certificates too.
|
||||
- `verify_incoming_rpc` See: [`tls.internal_rpc.verify_incoming`](#tls_internal_rpc_verify_incoming).
|
||||
|
||||
- `verify_server_hostname` - When set to true, Consul verifies the TLS certificate
|
||||
presented by the servers match the hostname `server.<datacenter>.<domain>`.
|
||||
By default this is false, and Consul does not verify the hostname
|
||||
of the certificate, only that it is signed by a trusted CA. This setting _must_ be enabled
|
||||
to prevent a compromised client from gaining full read and write access to all
|
||||
cluster data _including all ACL tokens and Connect CA root keys_. This is new in 0.5.1.
|
||||
- `verify_incoming_https` See: [`tls.https.verify_incoming`](#tls_https_verify_incoming).
|
||||
|
||||
~> **Security Note:** From versions 0.5.1 to 1.4.0, due to a bug, setting
|
||||
this flag alone _does not_ imply `verify_outgoing` and leaves client to server
|
||||
and server to server RPCs unencrypted despite the documentation stating otherwise. See
|
||||
[CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653)
|
||||
for more details. For those versions you **must also set `verify_outgoing = true`** to ensure encrypted RPC connections.
|
||||
- `verify_outgoing` See: [`tls.defaults.verify_outgoing`](#tls_defaults_verify_outgoing).
|
||||
|
||||
- `verify_server_hostname` See: [`tls.internal_rpc.verify_server_hostname`](#tls_internal_rpc_verify_server_hostname).
|
||||
|
||||
### Example Configuration File, with TLS
|
||||
|
||||
~> **Security Note:** all three verify options should be set as `true` to enable secure mTLS communication, enabling both
|
||||
encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing)
|
||||
will result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file).
|
||||
~> **Security Note:** all three verify options should be set as `true` to enable
|
||||
secure mTLS communication, enabling both encryption and authentication. Failing
|
||||
to set [`verify_incoming`](#tls_defaults_verify_incoming) or
|
||||
[`verify_outgoing`](#tls_defaults_verify_outgoing) either in the
|
||||
interface-specific stanza (e.g. `tls.internal_rpc`, `tls.https`) or in
|
||||
`tls.defaults` will result in TLS not being enabled at all, even when specifying
|
||||
a [`ca_file`](#tls_defaults_ca_file), [`cert_file`](#tls_defaults_cert_file),
|
||||
and [`key_file`](#tls_defaults_key_file).
|
||||
|
||||
See, especially, the use of the `ports` setting highlighted below.
|
||||
|
||||
<CodeTabs heading="Example configuration with TLS">
|
||||
|
||||
<CodeBlockConfig lineNumbers highlight="10-12">
|
||||
|
||||
```hcl
|
||||
datacenter = "east-aws"
|
||||
data_dir = "/opt/consul"
|
||||
log_level = "INFO"
|
||||
node_name = "foobar"
|
||||
server = true
|
||||
|
||||
addresses = {
|
||||
https = "0.0.0.0"
|
||||
}
|
||||
ports {
|
||||
https = 8501
|
||||
}
|
||||
|
||||
tls {
|
||||
defaults {
|
||||
key_file = "/etc/pki/tls/private/my.key"
|
||||
cert_file = "/etc/pki/tls/certs/my.crt"
|
||||
ca_file = "/etc/pki/tls/certs/ca-bundle.crt"
|
||||
verify_incoming = true
|
||||
verify_outgoing = true
|
||||
}
|
||||
|
||||
internal_rpc {
|
||||
verify_server_hostname = true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig lineNumbers highlight="10-12">
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -1894,23 +2169,25 @@ will result in TLS not being enabled at all, even when specifying a [`ca_file`](
|
|||
"ports": {
|
||||
"https": 8501
|
||||
},
|
||||
"key_file": "/etc/pki/tls/private/my.key",
|
||||
"cert_file": "/etc/pki/tls/certs/my.crt",
|
||||
"ca_file": "/etc/pki/tls/certs/ca-bundle.crt",
|
||||
"verify_incoming": true,
|
||||
"verify_outgoing": true,
|
||||
"verify_server_hostname": true
|
||||
"tls": {
|
||||
"defaults": {
|
||||
"key_file": "/etc/pki/tls/private/my.key",
|
||||
"cert_file": "/etc/pki/tls/certs/my.crt",
|
||||
"ca_file": "/etc/pki/tls/certs/ca-bundle.crt",
|
||||
"verify_incoming": true,
|
||||
"verify_outgoing": true
|
||||
},
|
||||
"internal_rpc": {
|
||||
"verify_server_hostname": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See, especially, the use of the `ports` setting:
|
||||
</CodeBlockConfig>
|
||||
|
||||
```json
|
||||
"ports": {
|
||||
"https": 8501
|
||||
}
|
||||
```
|
||||
</CodeTabs>
|
||||
|
||||
Consul will not enable TLS for the HTTP API unless the `https` port has been
|
||||
assigned a port number `> 0`. We recommend using `8501` for `https` as this
|
||||
Consul will not enable TLS for the HTTP or gRPC API unless the `https` port has
|
||||
been assigned a port number `> 0`. We recommend using `8501` for `https` as this
|
||||
default will automatically work with some tooling.
|
||||
|
|
@ -76,21 +76,17 @@ items which are reloaded include:
|
|||
- Services
|
||||
- TLS Configuration
|
||||
- Please be aware that this is currently limited to reload a configuration that is already TLS enabled. You cannot enable or disable TLS only with reloading.
|
||||
- To avoid a potential security issue, the following TLS configuration parameters do not automatically reload when [-auto-reload-config](#_auto_reload_config) is enabled:
|
||||
- [encrypt_verify_incoming](#encrypt_verify_incoming)
|
||||
- [verify_incoming](#verify_incoming)
|
||||
- [verify_incoming_rpc](#verify_incoming_rpc)
|
||||
- [verify_incoming_https](#verify_incoming_https)
|
||||
- [verify_outgoing](#verify_outgoing)
|
||||
- [verify_server_hostname](#verify_server_hostname)
|
||||
- [ca_file](#ca_file)
|
||||
- [ca_path](#ca_path)
|
||||
- To avoid a potential security issue, the following TLS configuration parameters do not automatically reload when [-auto-reload-config](/docs/agent/config/cli-flags#_auto_reload_config) is enabled:
|
||||
- [encrypt_verify_incoming](/docs/agent/config/config-files#encrypt_verify_incoming)
|
||||
- [verify_incoming](/docs/agent/config/config-files#verify_incoming)
|
||||
- [verify_incoming_rpc](/docs/agent/config/config-files#verify_incoming_rpc)
|
||||
- [verify_incoming_https](/docs/agent/config/config-files#verify_incoming_https)
|
||||
- [verify_outgoing](/docs/agent/config/config-files#verify_outgoing)
|
||||
- [verify_server_hostname](/docs/agent/config/config-files#verify_server_hostname)
|
||||
- [ca_file](/docs/agent/config/config-files#ca_file)
|
||||
- [ca_path](/docs/agent/config/config-files#ca_path)
|
||||
|
||||
If any of those configurations are changed while [-auto-reload-config](#_auto_reload_config) is enabled,
|
||||
If any of those configurations are changed while [-auto-reload-config](/docs/agent/config/cli-flags#_auto_reload_config) is enabled,
|
||||
Consul will issue the following warning, `Static Runtime config has changed and need a manual config reload to be applied`.
|
||||
You must manually issue the `consul reload` command or send a `SIGHUP` to the Consul process to reload the new values.
|
||||
- Watches
|
||||
|
||||
<!-- list of reference-style links -->
|
||||
|
||||
[go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template
|
||||
|
|
|
|||
Loading…
Reference in New Issue