ACL parameters for Consul agent configuration files

The page provides reference information for ACL parameters in a Consul agent configuration file.

ACL Parameters

acl - This object allows a number of sub-keys to be set which controls the ACL system. Configuring the ACL system within the ACL stanza was added in Consul 1.4.0
The following sub-keys are available:
- enabled - Enables ACLs.
- policy_ttl - Used to control Time-To-Live caching of ACL policies. By default, this is 30 seconds. This setting has a major performance impact: reducing it will cause more frequent refreshes while increasing it reduces the number of refreshes. However, because the caches are not actively invalidated, ACL policy may be stale up to the TTL value.
- role_ttl - Used to control Time-To-Live caching of ACL roles. By default, this is 30 seconds. This setting has a major performance impact: reducing it will cause more frequent refreshes while increasing it reduces the number of refreshes. However, because the caches are not actively invalidated, ACL role may be stale up to the TTL value.
- token_ttl - Used to control Time-To-Live caching of ACL tokens. By default, this is 30 seconds. This setting has a major performance impact: reducing it will cause more frequent refreshes while increasing it reduces the number of refreshes. However, because the caches are not actively invalidated, ACL token may be stale up to the TTL value.
- down_policy - 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 or leader node, the down policy is applied. In "allow" mode, all actions are permitted, "deny" restricts all operations, and "extend-cache" allows any cached objects to be used, ignoring the expiry time of the cached entry. If the request uses an ACL that is not in the cache, "extend-cache" falls back to the behavior of default_policy. The value "async-cache" acts the same way as "extend-cache" but performs updates asynchronously when ACL is present but its TTL is expired, thus, if latency is bad between the primary and secondary datacenters, latency of operations is not impacted.
- default_policy - Either "allow" or "deny"; defaults to "allow" but this will be changed in a future major release. The default policy controls the behavior of a token when there is no matching rule. In "allow" mode, ACLs are a denylist: any operation not specifically prohibited is allowed. In "deny" mode, ACLs are an allowlist: any operation not specifically allowed is blocked. Note: this will not take effect until you've enabled ACLs.
- enable_key_list_policy - Boolean value, defaults to false. When true, the list permission will be required on the prefix being recursively read from the KV store. Regardless of being enabled, the full set of KV entries under the prefix will be filtered to remove any entries that the request's ACL token does not grant at least read permissions. This option is only available in Consul 1.0 and newer.
- enable_token_replication - 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 and auth methods in connected secondary datacenters.
  Warning: When enabling ACL token replication on the secondary datacenter, global tokens already present in the secondary datacenter will be lost. For production environments, consider configuring ACL replication in your initial datacenter bootstrapping process.
- enable_token_persistence - Either true or false. When true tokens set using the API will be persisted to disk and reloaded when an agent restarts.
- tokens - This object holds all of the configured ACL tokens for the agents usage.
  - initial_management - This is available in Consul 1.11 and later. In prior versions, use acl.tokens.master.
    Only used for servers in the primary_datacenter. This token will be created with management-level permissions if it does not exist. It allows operators to bootstrap the ACL system with a token Secret ID that is well-known.
    The initial_management token is only installed when a server acquires cluster leadership. If you would like to install or change it, set the new value for initial_management in the configuration for all servers. Once this is done, restart the current leader to force a leader election. If the initial_management token is not supplied, then the servers do not create an initial management token. When you provide a value, it should be a UUID. To maintain backwards compatibility and an upgrade path this restriction is not currently enforced but will be in a future major Consul release.
  - master Renamed in Consul 1.11 to acl.tokens.initial_management.
  - default - When provided, this agent will use this token by default when making requests to the Consul servers instead of the anonymous token. Consul HTTP API requests can provide an alternate token in their authorization header to override the default or anonymous token on a per-request basis, as described in HTTP API Authentication.
  - agent - Used for clients and servers to perform internal operations. If this isn't specified, then the default will be used.
    This token must at least have write access to the node name it will register as in order to set any of the node-level information in the catalog such as metadata, or the node's tagged addresses.
  - agent_recovery - This is available in Consul 1.11 and later. In prior versions, use acl.tokens.agent_master.
    Used to access agent endpoints that require agent read or write privileges, or node read privileges, even if Consul servers aren't present to validate any tokens. This should only be used by operators during outages, regular ACL tokens should normally be used by applications.
  - agent_master Renamed in Consul 1.11 to acl.tokens.agent_recovery.
  - config_file_service_registration - Specifies the ACL token the agent uses to register services and checks from service and check definitions specified in configuration files or fragments passed to the agent using the -hcl flag.
    If the token field is defined in the service or check definition, then that token is used to register the service or check instead. If the config_file_service_registration token is not defined and if the token field is not defined in the service or check definition, then the agent uses the default token to register the service or check.
    This token needs write permission to register all services and checks defined in this agent's configuration. For example, if there are two service definitions in the agent's configuration files for services "A" and "B", then the token needs service:write permissions for both services "A" and "B" in order to successfully register both services. If the token is missing service:write permissions for service "B", the agent will successfully register service "A" and fail to register service "B". Failed registration requests are eventually retried as part of anti-entropy enforcement. If a registration request is failing due to missing permissions, the token for this agent can be updated with additional policy rules or the config_file_service_registration token can be replaced using the Set Agent Token CLI command.
  - dns - Specifies the token that agents use to request information needed to respond to DNS queries. If the dns token is not set, the default token is used instead. Because the default token allows unauthenticated HTTP API access to list nodes and services, we strongly recommend using the dns token. Create DNS tokens using the templated policy option to ensure that the token has the permissions needed to respond to all DNS queries.
  - replication - Specifies the token that the agent uses to authorize secondary datacenters with the primary datacenter for replication operations. This token is required for servers outside the primary_datacenter when ACLs are enabled. This token may be provided later using the agent token API 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 service mesh data replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data.
    Warning: When enabling ACL token replication on the secondary datacenter, policies and roles already present in the secondary datacenter will be lost. For production environments, consider configuring ACL replication in your initial datacenter bootstrapping process.
  - managed_service_provider Enterprise - An array of ACL tokens used by Consul managed service providers for cluster operations. Refer to the managed service provider example for more information.
acl_datacenter - This field is deprecated in Consul 1.4.0. See the primary_datacenter field instead.
This designates the datacenter which is authoritative for ACL information. It must be provided to enable ACLs. All servers and datacenters must agree on the ACL datacenter. Setting it on the servers is all you need for cluster-level enforcement, but for the APIs to forward properly from the clients, it must be set on them too. In Consul 0.8 and later, this also enables agent-level enforcement of ACLs. Please review the ACL tutorial for more details.
acl_default_policy - Deprecated in Consul 1.4.0. See the acl.default_policy field instead. Either "allow" or "deny"; defaults to "allow". The default policy controls the behavior of a token when there is no matching rule. In "allow" mode, ACLs are a denylist: any operation not specifically prohibited is allowed. In "deny" mode, ACLs are an allowlist: any operation not specifically allowed is blocked. Note: this will not take effect until you've set primary_datacenter to enable ACL support.
acl_down_policy - Deprecated in Consul 1.4.0. See the 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 or leader node, the down policy is applied. In "allow" mode, all actions are permitted, "deny" restricts all operations, and "extend-cache" allows any cached ACLs to be used, ignoring their TTL values. If a non-cached ACL is used, "extend-cache" acts like "deny". The value "async-cache" acts the same way as "extend-cache" but performs updates asynchronously when ACL is present but its TTL is expired, thus, if latency is bad between ACL authoritative and other datacenters, latency of operations is not impacted.
acl_agent_master_token - Deprecated in Consul 1.4.0. See the acl.tokens.agent_master field instead. Used to access agent endpoints that require agent read or write privileges, or node read privileges, even if Consul servers aren't present to validate any tokens. This should only be used by operators during outages, regular ACL tokens should normally be used by applications. This was added in Consul 0.7.2 and is only used when acl_enforce_version_8 is set to true.
acl_agent_token - Deprecated in Consul 1.4.0. See the acl.tokens.agent field instead. Used for clients and servers to perform internal operations. If this isn't specified, then the acl_token will be used. This was added in Consul 0.7.2.
This token must at least have write access to the node name it will register as in order to set any of the node-level information in the catalog such as metadata, or the node's tagged addresses.
acl_enforce_version_8 - Deprecated in Consul 1.4.0 and removed in 1.8.0. Used for clients and servers to determine if enforcement should occur for new ACL policies being previewed before Consul 0.8. Added in Consul 0.7.2, this defaults to false in versions of Consul prior to 0.8, and defaults to true in Consul 0.8 and later. This helps ease the transition to the new ACL features by allowing policies to be in place before enforcement begins.
acl_master_token - Deprecated in Consul 1.4.0. See the acl.tokens.master field instead.
acl_replication_token - Deprecated in Consul 1.4.0. See the acl.tokens.replication field instead. Only used for servers outside the primary_datacenter running Consul 0.7 or later. When provided, this will enable ACL replication 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 and then set the token later using the agent token API on each server. If the acl_replication_token is set in the config, it will automatically set acl.enable_token_replication to true for backward compatibility.
If there's a partition or other outage affecting the authoritative datacenter, and the acl_down_policy is set to "extend-cache", tokens not in the cache can be resolved during the outage using the replicated set of ACLs.
acl_token - Deprecated in Consul 1.4.0. See the acl.tokens.default field instead.
acl_ttl - Deprecated in Consul 1.4.0. See the acl.token_ttl field instead.Used to control Time-To-Live caching of ACLs. By default, this is 30 seconds. This setting has a major performance impact: reducing it will cause more frequent refreshes while increasing it reduces the number of refreshes. However, because the caches are not actively invalidated, ACL policy may be stale up to the TTL value.
enable_acl_replication Deprecated in Consul 1.11. Use the acl.enable_token_replication field instead. When set on a Consul server, enables ACL replication without having to set the replication token via acl_replication_token. Instead, enable ACL replication and then introduce the token using the agent token API on each server. See acl_replication_token for more details.
Warning: When enabling ACL token replication on the secondary datacenter, policies and roles already present in the secondary datacenter will be lost. For production environments, consider configuring ACL replication in your initial datacenter bootstrapping process.

Examples

The following examples demonstrate common ACL configurations for Consul agents.

Managed service provider

managed_service_provider {
  accessor_id = "ed22003b-0832-4e48-ac65-31de64e5c2ff"
  secret_id = "cb6be010-bba8-4f30-a9ed-d347128dde17"
}