mirror of https://github.com/status-im/consul.git
ACL documentation (#4824)
* Updating the ACL guide. * Update the docs correctly * Finish updating the ACL docs - for now.
This commit is contained in:
Matt Keeler
Jack Pearkes
parent
1757fbc0aa
commit
1ac888aa8c
|
|
@ -201,10 +201,10 @@ will exit with an error at startup.
|
|||
* <a name="_enable_script_checks"></a><a href="#_enable_script_checks">`-enable-script-checks`</a> This
|
||||
controls whether [health checks that execute scripts](/docs/agent/checks.html) are enabled on
|
||||
this agent, and defaults to `false` so operators must opt-in to allowing these. If enabled, it is recommended
|
||||
to [enable ACLs](/docs/guides/acl.html) as well to control which users are allowed to register new checks to
|
||||
to [enable ACLs](/docs/guides/acl.html) as well to control which users are allowed to register new checks to
|
||||
execute scripts. This was added in Consul 0.9.0.
|
||||
|
||||
* <a name="_enable_local_script_checks"></a><a href="#_enable_local_script_checks">`-enable-local-script-checks`</a>
|
||||
* <a name="_enable_local_script_checks"></a><a href="#_enable_local_script_checks">`-enable-local-script-checks`</a>
|
||||
Like [`enable_script_checks`](#_enable_script_checks), but only enable them when they are defined in the local
|
||||
config files. Script checks defined in HTTP API registratrions will still not be allowed.
|
||||
|
||||
|
|
@ -235,7 +235,7 @@ will exit with an error at startup.
|
|||
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.
|
||||
|
||||
* <a name="_log_file"></a><a href="#_log_file">`-log-file`</a> - to redirect all the Consul agent log messages to a file. This can be specified with the complete path along with the name of the log. In case the path doesn't have the filename, the filename defaults to Consul-timestamp.log . Can be combined with <a href="#_log_rotate_bytes"> -log-rotate-bytes</a> and <a href="#_log_rotate_duration"> -log-rotate-duration </a> for a fine-grained log rotation experience.
|
||||
* <a name="_log_file"></a><a href="#_log_file">`-log-file`</a> - to redirect all the Consul agent log messages to a file. This can be specified with the complete path along with the name of the log. In case the path doesn't have the filename, the filename defaults to Consul-timestamp.log . Can be combined with <a href="#_log_rotate_bytes"> -log-rotate-bytes</a> and <a href="#_log_rotate_duration"> -log-rotate-duration </a> for a fine-grained log rotation experience.
|
||||
|
||||
* <a name="_log_rotate_bytes"></a><a href="#_log_rotate_bytes">`-log-rotate-bytes`</a> - 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.
|
||||
|
||||
|
|
@ -509,6 +509,90 @@ default will automatically work with some tooling.
|
|||
|
||||
#### Configuration Key Reference
|
||||
|
||||
* <a name="acl"></a><a href="#acl">`acl`</a> - 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:
|
||||
|
||||
* <a name="acl_enabled"></a><a href="#acl_enabled">`enabled`</a> - Enables ACLs.
|
||||
|
||||
* <a name="acl_policy_ttl"></a><a href="#acl_policy_ttl">`policy_ttl`</a> - 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.
|
||||
|
||||
* <a name="acl_token_ttl"></a><a href="#acl_token_ttl">`token_ttl`</a> - 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.
|
||||
|
||||
* <a name="acl_down_policy"></a><a href="#acl_down_policy">`down_policy`</a> - 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 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
|
||||
the primary and secondary datacenters, latency of operations is not impacted.
|
||||
|
||||
* <a name="acl_default_policy"></a><a href="#acl_default_policy">`default_policy`</a> - 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 blacklist: any operation not specifically prohibited is allowed. In "deny" mode, ACLs are
|
||||
a whitelist: any operation not specifically allowed is blocked. *Note*: this will not take effect until
|
||||
you've enabled ACLs.
|
||||
|
||||
* <a name=`acl_enable_token_replication"></a><a href="#acl_enable_token_replication">`enable_token_replication`</a> - By
|
||||
default secondary Consul datacenters will perform replication of only ACL policies. Setting this configuration will
|
||||
also enable ACL token replication.
|
||||
|
||||
* <a name="acl_tokens"></a><a href="#acl_tokens">`tokens`</a> - This object holds
|
||||
all of the configured ACL tokens for the agents usage.
|
||||
|
||||
* <a name="acl_tokens_master"></a><a href="#acl_tokens_master">`master`</a> - 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.
|
||||
<br/><br/>
|
||||
The `master` token is only installed when a server acquires cluster leadership. If
|
||||
you would like to install or change the `acl_master_token`, set the new value for `master`
|
||||
in the configuration for all servers. Once this is done, restart the current leader to force a
|
||||
leader election. If the `master` token is not supplied, then the servers do not create a master
|
||||
token. When you provide a value, it should be a UUID. To maintaing backwards compatibility
|
||||
and an upgrade path this restriction is not currently enforced but will be in a future major
|
||||
Consul release.
|
||||
|
||||
* <a name="acl_tokens_default"></a><a href="#acl_tokens_default">`default`</a> - 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.
|
||||
|
||||
* <a name="acl_tokens_agent"></a><a href="#acl_tokens_agent">`agent`</a> - Used for clients
|
||||
and servers to perform internal operations. If this isn't specified, then the
|
||||
<a href="#acl_tokens_default">`default`</a> will be used. This was added in Consul
|
||||
<br/><br/>
|
||||
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. There
|
||||
are other places this token is used, please see [ACL Agent Token](/docs/guides/acl.html#acl-agent-token)
|
||||
for more details.
|
||||
|
||||
* <a name="acl_tokens_agent_master"></a><a href="#acl_tokens_agent_master">`agent_master`</a> -
|
||||
Used to access <a href="/api/agent.html">agent endpoints</a> 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.
|
||||
|
||||
* <a name="acl_tokens_replication"></a><a href="#acl_tokens_replication">`replication`</a> -
|
||||
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.html#update-acl-tokens)
|
||||
on each server. If the `replication` token is set in the config. This token must have at least "read" permissions
|
||||
on ACL data but if ACL token replication is enabled then it must have "write" permissions.
|
||||
|
||||
* <a name="acl_datacenter"></a><a href="#acl_datacenter">`acl_datacenter`</a> - **This field is
|
||||
deprecated in Consul 1.4.0. See the [`primary_datacenter`](#primary_datacenter) field instead.**
|
||||
|
||||
|
|
@ -516,14 +600,16 @@ default will automatically work with some tooling.
|
|||
it must be set on them too. In Consul 0.8 and later, this also enables agent-level enforcement
|
||||
of ACLs. Please see the [ACL Guide](/docs/guides/acl.html) for more details.
|
||||
|
||||
* <a name="acl_default_policy"></a><a href="#acl_default_policy">`acl_default_policy`</a> - Either
|
||||
* <a name="acl_default_policy_legacy"></a><a href="#acl_default_policy_legacy">`acl_default_policy`</a> - **Deprecated in Consul 1.4.0.
|
||||
See the [`acl.default_policy`](#acl_default_policy) field instead.** Either
|
||||
"allow" or "deny"; defaults to "allow". The default policy controls the behavior of a token when
|
||||
there is no matching rule. In "allow" mode, ACLs are a blacklist: any operation not specifically
|
||||
prohibited is allowed. In "deny" mode, ACLs are a whitelist: any operation not
|
||||
specifically allowed is blocked. *Note*: this will not take effect until you've set `primary_datacenter`
|
||||
to enable ACL support.
|
||||
|
||||
* <a name="acl_down_policy"></a><a href="#acl_down_policy">`acl_down_policy`</a> - Either
|
||||
* <a name="acl_down_policy_legacy"></a><a href="#acl_down_policy_legacy">`acl_down_policy`</a> - **Deprecated in Consul 1.4.0.
|
||||
See the [`acl.down_policy`](#acl_down_policy) field instead.**Either
|
||||
"allow", "deny", "extend-cache" or "async-cache"; "extend-cache" is the default. In the case that the
|
||||
policy for a token cannot be read from the [`primary_datacenter`](#primary_datacenter) or leader
|
||||
node, the down policy is applied. In "allow" mode, all actions are permitted, "deny" restricts
|
||||
|
|
@ -533,7 +619,8 @@ default will automatically work with some tooling.
|
|||
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.
|
||||
|
||||
* <a name="acl_agent_master_token"></a><a href="#acl_agent_master_token">`acl_agent_master_token`</a> -
|
||||
* <a name="acl_agent_master_token_legacy"></a><a href="#acl_agent_master_token_legacy">`acl_agent_master_token`</a> -
|
||||
**Deprecated in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master) field instead.**
|
||||
Used to access <a href="/api/agent.html">agent endpoints</a> 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
|
||||
|
|
@ -541,8 +628,9 @@ default will automatically work with some tooling.
|
|||
<a href="#acl_enforce_version_8">`acl_enforce_version_8`</a> is set to true. Please see
|
||||
[ACL Agent Master Token](/docs/guides/acl.html#acl-agent-master-token) for more details.
|
||||
|
||||
* <a name="acl_agent_token"></a><a href="#acl_agent_token">`acl_agent_token`</a> - Used for clients
|
||||
and servers to perform internal operations. If this isn't specified, then the
|
||||
* <a name="acl_agent_token_legacy"></a><a href="#acl_agent_token_legacy">`acl_agent_token`</a> -
|
||||
**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
|
||||
<a href="#acl_token">`acl_token`</a> 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
|
||||
|
|
@ -551,13 +639,15 @@ default will automatically work with some tooling.
|
|||
for more details.
|
||||
|
||||
* <a name="acl_enforce_version_8"></a><a href="#acl_enforce_version_8">`acl_enforce_version_8`</a> -
|
||||
**Deprecated in Consul 1.4.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.
|
||||
Please see the [ACL Guide](/docs/guides/acl.html#version_8_acls) for more details.
|
||||
|
||||
* <a name="acl_master_token"></a><a href="#acl_master_token">`acl_master_token`</a> - Only used
|
||||
* <a name="acl_master_token_legacy"></a><a href="#acl_master_token_legacy">`acl_master_token`</a> -
|
||||
**Deprecated in Consul 1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.** 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 ID that is well-known.
|
||||
|
|
@ -569,7 +659,8 @@ default will automatically work with some tooling.
|
|||
token. When you provide a value, it can be any string value. Using a UUID would ensure that it looks
|
||||
the same as the other tokens, but isn't strictly necessary.
|
||||
|
||||
* <a name="acl_replication_token"></a><a href="#acl_replication_token">`acl_replication_token`</a> -
|
||||
* <a name="acl_replication_token_legacy"></a><a href="#acl_replication_token_legacy">`acl_replication_token`</a> -
|
||||
**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](/docs/guides/acl.html#replication) using this
|
||||
token to retrieve and replicate the ACLs to the non-authoritative local datacenter. In Consul 0.9.1
|
||||
|
|
@ -583,12 +674,15 @@ default will automatically work with some tooling.
|
|||
in the cache can be resolved during the outage using the replicated set of ACLs. Please see the
|
||||
[ACL Guide](/docs/guides/acl.html#replication) replication section for more details.
|
||||
|
||||
* <a name="acl_token"></a><a href="#acl_token">`acl_token`</a> - When provided, the agent will use this
|
||||
* <a name="acl_token_legacy"></a><a href="#acl_token_legacy">`acl_token`</a> -
|
||||
**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.
|
||||
|
||||
* <a name="acl_ttl"></a><a href="#acl_ttl">`acl_ttl`</a> - Used to control Time-To-Live caching of ACLs.
|
||||
* <a name="acl_ttl_legacy"></a><a href="#acl_ttl_legacy">`acl_ttl`</a> -
|
||||
**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.
|
||||
|
|
@ -1179,7 +1273,7 @@ default will automatically work with some tooling.
|
|||
* <a name="protocol"></a><a href="#protocol">`protocol`</a> Equivalent to the
|
||||
[`-protocol` command-line flag](#_protocol).
|
||||
|
||||
* <a name="primary_datacenter"></a><a href="#primary_datacenter">`primary_datacenter`</a> - This
|
||||
* <a name="primary_datacenter"></a><a href="#primary_datacenter">`primary_datacenter`</a> - This
|
||||
designates the datacenter which is authoritative for ACL information, intentions and is the root
|
||||
Certificate Authority for Connect. It must be provided to enable ACLs. All servers and datacenters
|
||||
must agree on the primary datacenter. Setting it on the servers is all you need for cluster-level enforcement, but for the APIs to forward properly from the clients, it must be set on them too. In
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -355,6 +355,11 @@
|
|||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-guides-acl") %>>
|
||||
<a href="/docs/guides/acl.html">ACLs</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-guides-acl-legacy") %>>
|
||||
<a href="/docs/guides/acl-legacy.html">Legacy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-guides-servers") %>>
|
||||
<a href="/docs/guides/servers.html">Adding/Removing Servers</a>
|
||||
|
|
|
|||
Loading…
Reference in New Issue