---
layout: docs
page_title: ACL parameters for Consul agent configuration files
description: >-
  Use agent configuration files to assign attributes to agents and configure multiple agents at once. Learn about agent configuration file parameters and formatting with this reference page and sample code.
---

# ACL parameters for Consul agent configuration files

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

## ACL Parameters

- `acl` ((#acl)) - This object allows a number of sub-keys to be set which
  controls the ACL system. Configuring the ACL system within the ACL stanza was added
  in Consul 1.4.0

  The following sub-keys are available:

  - `enabled` ((#acl_enabled)) - Enables ACLs.

  - `policy_ttl` ((#acl_policy_ttl)) - Used to control Time-To-Live caching
    of ACL policies. By default, this is 30 seconds. This setting has a major performance
    impact: reducing it will cause more frequent refreshes while increasing it reduces
    the number of refreshes. However, because the caches are not actively invalidated,
    ACL policy may be stale up to the TTL value.

  - `role_ttl` ((#acl_role_ttl)) - Used to control Time-To-Live caching
    of ACL roles. By default, this is 30 seconds. This setting has a major performance
    impact: reducing it will cause more frequent refreshes while increasing it reduces
    the number of refreshes. However, because the caches are not actively invalidated,
    ACL role may be stale up to the TTL value.

  - `token_ttl` ((#acl_token_ttl)) - Used to control Time-To-Live caching
    of ACL tokens. By default, this is 30 seconds. This setting has a major performance
    impact: reducing it will cause more frequent refreshes while increasing it reduces
    the number of refreshes. However, because the caches are not actively invalidated,
    ACL token may be stale up to the TTL value.

  - `down_policy` ((#acl_down_policy)) - Either "allow", "deny", "extend-cache"
    or "async-cache"; "extend-cache" is the default. In the case that a policy or
    token cannot be read from the [`primary_datacenter`](/consul/docs/reference/agent/configuration-file/general#primary_datacenter) or
    leader node, the down policy is applied. In "allow" mode, all actions are permitted,
    "deny" restricts all operations, and "extend-cache" allows any cached objects
    to be used, ignoring the expiry time of the cached entry. If the request uses an
    ACL that is not in the cache, "extend-cache" falls back to the behavior of
    `default_policy`.
    The value "async-cache" acts the same way as "extend-cache"
    but performs updates asynchronously when ACL is present but its TTL is expired,
    thus, if latency is bad between the primary and secondary datacenters, latency
    of operations is not impacted.

  - `default_policy` ((#acl_default_policy)) - Either "allow" or "deny";
    defaults to "allow" but this will be changed in a future major release. The default
    policy controls the behavior of a token when there is no matching rule. In "allow"
    mode, ACLs are a denylist: any operation not specifically prohibited is allowed.
    In "deny" mode, ACLs are an allowlist: any operation not specifically
    allowed is blocked. **Note**: this will not take effect until you've enabled ACLs.

  - `enable_key_list_policy` ((#acl_enable_key_list_policy)) - Boolean value, defaults to false.
    When true, the `list` permission will be required on the prefix being recursively read from the KV store.
    Regardless of being enabled, the full set of KV entries under the prefix will be filtered
    to remove any entries that the request's ACL token does not grant at least read
    permissions. This option is only available in Consul 1.0 and newer.

  - `enable_token_replication` ((#acl_enable_token_replication)) - By default
    secondary Consul datacenters will perform replication of only ACL policies and
    roles. Setting this configuration will will enable ACL token replication and
    allow for the creation of both [local tokens](/consul/api-docs/acl/tokens#local) and
    [auth methods](/consul/docs/secure/acl/auth-method) in connected secondary datacenters.

    ~> **Warning:** When enabling ACL token replication on the secondary datacenter,
    global tokens already present in the secondary datacenter will be lost. For
    production environments, consider configuring ACL replication in your initial
    datacenter bootstrapping process.

  - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either
    `true` or `false`. When `true` tokens set using the API will be persisted to
    disk and reloaded when an agent restarts.

  - `tokens` ((#acl_tokens)) - This object holds all of the configured
    ACL tokens for the agents usage.

    - `initial_management` ((#acl_tokens_initial_management)) - This is available in
      Consul 1.11 and later. In prior versions, use [`acl.tokens.master`](#acl_tokens_master).

      Only used for servers in the [`primary_datacenter`](/consul/docs/reference/agent/configuration-file/general#primary_datacenter).
      This token will be created with management-level permissions if it does not exist.
      It allows operators to bootstrap the ACL system with a token Secret ID that is
      well-known.

      The `initial_management` token is only installed when a server acquires cluster
      leadership. If you would like to install or change it, set the new value for
      `initial_management` in the configuration for all servers. Once this is done,
      restart the current leader to force a leader election. If the `initial_management`
      token is not supplied, then the servers do not create an initial management token.
      When you provide a value, it should be a UUID. To maintain backwards compatibility
      and an upgrade path this restriction is not currently enforced but will be in a
      future major Consul release.

    - `master` ((#acl_tokens_master)) **Renamed in Consul 1.11 to
      [`acl.tokens.initial_management`](#acl_tokens_initial_management).**

    - `default` ((#acl_tokens_default)) - When provided, this agent will
      use this token by default when making requests to the Consul servers
      instead of the [anonymous token](/consul/docs/security/acl/tokens#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](/consul/api-docs/api-structure#authentication).

    - `agent` ((#acl_tokens_agent)) - Used for clients and servers to perform
      internal operations. If this isn't specified, then the
      [`default`](#acl_tokens_default) will be used.

      This token must at least have write access to the node name it will
      register as in order to set any of the node-level information in the
      catalog such as metadata, or the node's tagged addresses.

    - `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11
      and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master).

      Used to access [agent endpoints](/consul/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.

    - `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to
      [`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).**

    - `config_file_service_registration` ((#acl_tokens_config_file_service_registration)) - Specifies the ACL
      token the agent uses to register services and checks from [service](/consul/docs/register/service/vm/define) and [check](/consul/docs/register/health-check/vm) 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`](#acl_tokens_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](/consul/docs/concept/consistency). 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](/consul/commands/acl/set-agent-token) CLI command.

    - `dns` ((#acl_tokens_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](/consul/docs/secure/acl/token/dns)
      option to ensure that the token has the permissions needed to respond to all DNS queries.

    - `replication` ((#acl_tokens_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`](/consul/docs/reference/agent/configuration-file/general#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/consul/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 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` ((#acl_tokens_managed_service_provider)) <EnterpriseAlert inline /> - An
      array of ACL tokens used by Consul managed service providers for cluster
      operations. Refer to the [managed service provider
      example](#managed-service-provider) for more information.

- `acl_datacenter` - **This field is deprecated in Consul 1.4.0. See the [`primary_datacenter`](/consul/docs/reference/agent/configuration-file/general#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](/consul/tutorials/security/access-control-setup-production) for more details.

- `acl_default_policy` ((#acl_default_policy_legacy)) - **Deprecated in Consul 1.4.0. See the [`acl.default_policy`](#acl_default_policy) field instead.**
  Either "allow" or "deny"; defaults to "allow". The default policy controls the
  behavior of a token when there is no matching rule. In "allow" mode, ACLs are a
  denylist: any operation not specifically prohibited is allowed. In "deny" mode,
  ACLs are an allowlist: any operation not specifically allowed is blocked. **Note**:
  this will not take effect until you've set `primary_datacenter` to enable ACL support.

- `acl_down_policy` ((#acl_down_policy_legacy)) - **Deprecated in Consul
  1.4.0. See the [`acl.down_policy`](#acl_down_policy) field instead.** Either "allow",
  "deny", "extend-cache" or "async-cache"; "extend-cache" is the default. In the
  case that the policy for a token cannot be read from the [`primary_datacenter`](/consul/docs/reference/agent/configuration-file/general#primary_datacenter)
  or leader node, the down policy is applied. In "allow" mode, all actions are permitted,
  "deny" restricts all operations, and "extend-cache" allows any cached ACLs to be
  used, ignoring their TTL values. If a non-cached ACL is used, "extend-cache" acts
  like "deny". The value "async-cache" acts the same way as "extend-cache" but performs
  updates asynchronously when ACL is present but its TTL is expired, thus, if latency
  is bad between ACL authoritative and other datacenters, latency of operations is
  not impacted.

- `acl_agent_master_token` ((#acl_agent_master_token_legacy)) - **Deprecated
  in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master)
  field instead.** Used to access [agent endpoints](/consul/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
  was added in Consul 0.7.2 and is only used when [`acl_enforce_version_8`](#acl_enforce_version_8) is set to true.

- `acl_agent_token` ((#acl_agent_token_legacy)) - **Deprecated in Consul
  1.4.0. See the [`acl.tokens.agent`](#acl_tokens_agent) field instead.** Used for
  clients and servers to perform internal operations. If this isn't specified, then
  the [`acl_token`](#acl_token) will be used. This was added in Consul 0.7.2.

  This token must at least have write access to the node name it will register as in order to set any
  of the node-level information in the catalog such as metadata, or the node's tagged addresses.

- `acl_enforce_version_8` - **Deprecated in
  Consul 1.4.0 and removed in 1.8.0.** Used for clients and servers to determine if enforcement should
  occur for new ACL policies being previewed before Consul 0.8. Added in Consul 0.7.2,
  this defaults to false in versions of Consul prior to 0.8, and defaults to true
  in Consul 0.8 and later. This helps ease the transition to the new ACL features
  by allowing policies to be in place before enforcement begins.

- `acl_master_token` ((#acl_master_token_legacy)) - **Deprecated in Consul
  1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.**

- `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated
  in Consul 1.4.0. See the [`acl.tokens.replication`](#acl_tokens_replication) field
  instead.** Only used for servers outside the [`primary_datacenter`](/consul/docs/reference/agent/configuration-file/general#primary_datacenter)
  running Consul 0.7 or later. When provided, this will enable [ACL replication](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters)
  using this ACL replication using this token to retrieve and replicate the ACLs
  to the non-authoritative local datacenter. In Consul 0.9.1 and later you can enable
  ACL replication using [`acl.enable_token_replication`](#acl_enable_token_replication) and then
  set the token later using the [agent token API](#update-acl-tokens)
  on each server. If the `acl_replication_token` is set in the config, it will automatically
  set [`acl.enable_token_replication`](#acl_enable_token_replication) to true for backward compatibility.

  If there's a partition or other outage affecting the authoritative datacenter, and the
  [`acl_down_policy`](#acl_down_policy) is set to "extend-cache", tokens not
  in the cache can be resolved during the outage using the replicated set of ACLs.

- `acl_token` ((#acl_token_legacy)) - **Deprecated in Consul 1.4.0. See
  the [`acl.tokens.default`](#acl_tokens_default) field instead.**

- `acl_ttl` ((#acl_ttl_legacy)) - **Deprecated in Consul 1.4.0. See the
  [`acl.token_ttl`](#acl_token_ttl) field instead.**Used to control Time-To-Live
  caching of ACLs. By default, this is 30 seconds. This setting has a major performance
  impact: reducing it will cause more frequent refreshes while increasing it reduces
  the number of refreshes. However, because the caches are not actively invalidated,
  ACL policy may be stale up to the TTL value.

- `enable_acl_replication` **Deprecated in Consul 1.11. Use the [`acl.enable_token_replication`](#acl_enable_token_replication) field instead.**
  When set on a Consul server, enables ACL replication without having to set
  the replication token via [`acl_replication_token`](#acl_replication_token). Instead, enable ACL replication
  and then introduce the token using the [agent token API](#update-acl-tokens) on each server.
  See [`acl_replication_token`](#acl_replication_token) for more details.

  ~> **Warning:** When enabling ACL token replication on the secondary datacenter,
  policies and roles already present in the secondary datacenter will be lost. For
  production environments, consider configuring ACL replication in your initial
  datacenter bootstrapping process.


## Examples

The following examples demonstrate common ACL configurations for Consul agents.

### Managed service provider

<EnterpriseAlert product="consul" inline /><br/><br/>

<CodeTabs>

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

```json
"managed_service_provider": [
  {
    "accessor_id": "ed22003b-0832-4e48-ac65-31de64e5c2ff",
    "secret_id": "cb6be010-bba8-4f30-a9ed-d347128dde17"
  }
]
```
</CodeTabs>
