1--- 2layout: docs 3page_title: ACL System (Legacy Mode) 4description: >- 5 Consul provides an optional Access Control List (ACL) system which can be used 6 to control access to data and APIs. The ACL system is a Capability-based 7 system that relies on tokens which can have fine grained rules applied to 8 them. It is very similar to AWS IAM in many ways. 9--- 10 11# ACL System in Legacy Mode 12 13-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system). 14 15~> **Alert: Deprecation Notice** 16The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0 17the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/tutorials/consul/access-control-token-migration) tutorial. 18 19The legacy documentation has two sections. 20 21- The [New ACL System Differences](#new-acl-system-differences) section 22 details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/acl/acl-migrate-tokens) tokens. 23- The [Legacy ACL System documentation](#legacy-acl-system) section details the 24 ACL system in Consul 1.3.0 and older. 25 26# New ACL System Differences 27 28The [ACL System documentation](/docs/acl/acl-system) and [legacy ACL 29documentation](/docs/acl/acl-legacy) describes the new and old systems in 30detail. Below is a summary of the changes that need to be considered when 31migrating legacy tokens to the new system. 32 33### Token and Policy Separation 34 35You can use a single policy in the new system for all tokens that share access 36rules. For example, all tokens created using the clone endpoint in the legacy 37system can be represented with a single policy and a set of tokens that map to 38that policy. 39 40### Rule Syntax Changes 41 42The most significant change is that rules with selectors _no longer prefix match 43by default_. In the legacy system the following rules would grant access to 44nodes, services and keys _prefixed_ with foo. 45 46```hcl 47node "foo" { policy = "write" } 48service "foo" { policy = "write" } 49key "foo" { policy = "write" } 50``` 51 52In the new system the same syntax will only perform _exact_ match on the whole 53node name, service name or key. 54 55In general, exact match is what most operators intended most of the time so the 56same policy can be kept, however if you rely on prefix match behavior then using 57the same syntax will break behavior. 58 59Prefix matching can be expressed in the new ACL system explicitly, making the 60following rules in the new system exactly the same as the rules above in the 61old. 62 63```hcl 64node_prefix "foo" { policy = "write" } 65service_prefix "foo" { policy = "write" } 66key_prefix "foo" { policy = "write" } 67``` 68 69### API Separation 70 71The "old" API endpoints below continue to work for backwards compatibility but 72will continue to create or show only "legacy" tokens that can't take full 73advantage of the new ACL system improvements. They are documented fully under 74[Legacy Tokens](/api/acl/legacy). 75 76- [`PUT /acl/create` - Create Legacy Token](/api/acl/legacy#create-acl-token) 77- [`PUT /acl/update` - Update Legacy Token](/api/acl/legacy#update-acl-token) 78- [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/api/acl/legacy#delete-acl-token) 79- [`GET /acl/info/:uuid` - Read Legacy Token](/api/acl/legacy#read-acl-token) 80- [`PUT /acl/clone/:uuid` - Clone Legacy Token](/api/acl/legacy#clone-acl-token) 81- [`GET /acl/list` - List Legacy Tokens](/api/acl/legacy#list-acls) 82 83The new ACL system includes new API endpoints to manage 84the [ACL System](/api/acl/acl), [Tokens](/api/acl/tokens) 85and [Policies](/api/acl/policies). 86 87# Legacy ACL System 88 89~> **Warning**: In this document we use the deprecated 90configuration parameter `acl_datacenter`. In Consul 1.4 and newer the 91parameter has been updated to [`primary_datacenter`](/docs/agent/options#primary_datacenter). 92 93Consul provides an optional Access Control List (ACL) system which can be used to control 94access to data and APIs. The ACL is 95[Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying 96on tokens to which fine grained rules can be applied. It is very similar to 97[AWS IAM](http://aws.amazon.com/iam/) in many ways. 98 99## ACL System Overview 100 101The ACL system is designed to be easy to use, fast to enforce, and flexible to new policies, 102all while providing administrative insight. 103 104#### ACL Tokens 105 106The ACL system is based on tokens, which are managed by Consul operators via Consul's 107[ACL API](/api/acl/acl), or systems like 108[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul). 109 110Every token has an ID, name, type, and rule set. The ID is a randomly generated 111UUID, making it infeasible to guess. The name is opaque to Consul and human readable. 112The type is either "client" (meaning the token cannot modify ACL rules) or "management" 113(meaning the token is allowed to perform all actions). 114 115The token ID is passed along with each RPC request to the servers. Consul's 116[HTTP endpoints](/api) can accept tokens via the `token` 117query string parameter, or the `X-Consul-Token` request header, or Authorization Bearer 118token [RFC6750](https://tools.ietf.org/html/rfc6750). Consul's 119[CLI commands](/docs/commands) can accept tokens via the 120`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. 121 122If no token is provided, the rules associated with a special, configurable anonymous 123token are automatically applied. The anonymous token is managed using the 124[ACL API](/api/acl/acl) like any other ACL token, but using `anonymous` for the ID. 125 126#### ACL Rules and Scope 127 128Tokens are bound to a set of rules that control which Consul resources the token 129has access to. Policies can be defined in either an allowlist or denylist mode 130depending on the configuration of 131[`acl_default_policy`](/docs/agent/options#acl_default_policy). If the default 132policy is to "deny" all actions, then token rules can be set to allowlist specific 133actions. In the inverse, the "allow" all default behavior is a denylist where rules 134are used to prohibit actions. By default, Consul will allow all actions. 135 136The following table summarizes the ACL policies that are available for constructing 137rules: 138 139| Policy | Scope | 140| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 141| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent), other than service and check registration | 142| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event) | 143| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv) | 144| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring) | 145| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), [Network Coordinate API](/api/coordinate), and [Agent API](/api/agent) | 146| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring) | 147| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query) | 148| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), and [Agent API](/api/agent) | 149| [`session`](#session-rules) | Session operations in the [Session API](/api/session) | 150 151Since Consul snapshots actually contain ACL tokens, the 152[Snapshot API](/api/snapshot) requires a management token for snapshot operations 153and does not use a special policy. 154 155The following resources are not covered by ACL policies: 156 1571. The [Status API](/api/status) is used by servers when bootstrapping and exposes 158 basic IP and port information about the servers, and does not allow modification 159 of any state. 160 1612. The datacenter listing operation of the 162 [Catalog API](/api/catalog#list-datacenters) similarly exposes the names of known 163 Consul datacenters, and does not allow modification of any state. 164 165Constructing rules from these policies is covered in detail in the 166[Rule Specification](#rule-specification) section below. 167 168#### ACL Datacenter 169 170All nodes (clients and servers) must be configured with a 171[`acl_datacenter`](/docs/agent/options#acl_datacenter) which enables ACL 172enforcement but also specifies the authoritative datacenter. Consul relies on 173[RPC forwarding](/docs/internals/architecture) to support multi-datacenter 174configurations. However, because requests can be made across datacenter boundaries, 175ACL tokens must be valid globally. To avoid consistency issues, a single datacenter 176is considered authoritative and stores the canonical set of tokens. 177 178When a request is made to an agent in a non-authoritative datacenter, it must be 179resolved into the appropriate policy. This is done by reading the token from the 180authoritative server and caching the result for a configurable 181[`acl_ttl`](/docs/agent/options#acl_ttl). The implication of caching is that 182the cache TTL is an upper bound on the staleness of policy that is enforced. It is 183possible to set a zero TTL, but this has adverse performance impacts, as every 184request requires refreshing the policy via an RPC call. 185 186During an outage of the ACL datacenter, or loss of connectivity, the cache will be 187used as long as the TTL is valid, or the cache may be extended if the 188[`acl_down_policy`](/docs/agent/options#acl_down_policy) is set accordingly. 189This configuration also allows the ACL system to fail open or closed. 190[ACL replication](#replication) is also available to allow for the full set of ACL 191tokens to be replicated for use during an outage. 192 193## Configuring ACLs 194 195ACLs are configured using several different configuration options. These are marked 196as to whether they are set on servers, clients, or both. 197 198| Configuration Option | Servers | Clients | Purpose | 199| --------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- | 200| [`acl_datacenter`](/docs/agent/options#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | 201| [`acl_default_policy`](/docs/agent/options#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | 202| [`acl_down_policy`](/docs/agent/options#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | 203| [`acl_ttl`](/docs/agent/options#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | 204 205There are some additional configuration items related to [ACL replication](#replication) and 206[Version 8 ACL support](#version_8_acls). These are discussed in those respective sections 207below. 208 209A number of special tokens can also be configured which allow for bootstrapping the ACL 210system, or accessing Consul in special situations: 211 212| Special Token | Servers | Clients | Purpose | 213| ----------------------------------------------------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 214| [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | 215| [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | 216| [`acl_master_token`](/docs/agent/options#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | 217| [`acl_token`](/docs/agent/options#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | 218 219In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the 220[/v1/agent/token API](/api/agent#update-acl-tokens). 221 222#### ACL Agent Master Token 223 224Since the [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): 225 226```hcl 227agent "<node name of agent>" { 228 policy = "write" 229} 230node "" { 231 policy = "read" 232} 233``` 234 235In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the 236[/v1/agent/token API](/api/agent#update-acl-tokens). 237 238#### ACL Agent Token 239 240The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/options#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: 241 2421. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates 2432. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog 2443. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands 245 246Here's an example policy sufficient to accomplish the above for a node called `mynode`: 247 248```hcl 249node "mynode" { 250 policy = "write" 251} 252service "" { 253 policy = "read" 254} 255key "_rexec" { 256 policy = "write" 257} 258``` 259 260The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key` policy can be omitted. 261 262In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the 263[/v1/agent/token API](/api/agent#update-acl-tokens). 264 265## Bootstrapping ACLs 266 267Bootstrapping ACLs on a new cluster requires a few steps, outlined in the examples in this 268section. 269 270#### Enable ACLs on the Consul Servers 271 272The first step for bootstrapping ACLs is to enable ACLs on the Consul servers in the ACL 273datacenter. In this example, we are configuring the following: 274 2751. An ACL datacenter of "dc1", which is where these servers are 2762. An ACL master token of "b1gs33cr3t"; see below for an alternative using the [/v1/acl/bootstrap API](/api/acl/acl#bootstrap-acls) 2773. A default policy of "deny" which means we are in allowlist mode 2784. A down policy of "extend-cache" which means that we will ignore token TTLs 279 during an outage 280 281Here's the corresponding JSON configuration file: 282 283```json 284{ 285 "acl_datacenter": "dc1", 286 "acl_master_token": "b1gs33cr3t", 287 "acl_default_policy": "deny", 288 "acl_down_policy": "extend-cache" 289} 290``` 291 292The servers will need to be restarted to load the new configuration. Please take care 293to start the servers one at a time, and ensure each server has joined and is operating 294correctly before starting another. 295 296The [`acl_master_token`](/docs/agent/options#acl_master_token) will be created 297as a "management" type token automatically. The 298[`acl_master_token`](/docs/agent/options#acl_master_token) is only installed when 299a server acquires cluster leadership. If you would like to install or change the 300[`acl_master_token`](/docs/agent/options#acl_master_token), set the new value for 301[`acl_master_token`](/docs/agent/options#acl_master_token) in the configuration 302for all servers. Once this is done, restart the current leader to force a leader election. 303 304In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api/acl/acl#bootstrap-acls) 305to make the initial master token, so a token never needs to be placed into a configuration 306file. To use this approach, omit `acl_master_token` from the above config and then call the API: 307 308```shell-session 309$ curl \ 310 --request PUT \ 311 http://127.0.0.1:8500/v1/acl/bootstrap 312 313{"ID":"fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1"} 314``` 315 316The returned token is the initial management token, which is randomly generated by Consul. 317It's only possible to bootstrap one time, and bootstrapping will be disabled if a master 318token was configured and created. 319 320Once the ACL system is bootstrapped, ACL tokens can be managed through the 321[ACL API](/api/acl/acl). 322 323#### Create an Agent Token 324 325After the servers are restarted above, you will see new errors in the logs of the Consul 326servers related to permission denied errors: 327 328```text 3292017/07/08 23:38:24 [WARN] agent: Node info update blocked by ACLs 3302017/07/08 23:38:44 [WARN] agent: Coordinate update blocked by ACLs 331``` 332 333These errors are because the agent doesn't yet have a properly configured 334[`acl_agent_token`](/docs/agent/options#acl_agent_token) that it can use for its 335own internal operations like updating its node information in the catalog and performing 336[anti-entropy](/docs/internals/anti-entropy) syncing. We can create a token using the 337ACL API, and the ACL master token we set in the previous step: 338 339```shell-session 340$ curl \ 341 --request PUT \ 342 --header "X-Consul-Token: b1gs33cr3t" \ 343 --data \ 344'{ 345 "Name": "Agent Token", 346 "Type": "client", 347 "Rules": "node \"\" { policy = \"write\" } service \"\" { policy = \"read\" }" 348}' http://127.0.0.1:8500/v1/acl/create 349 350{"ID":"fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1"} 351``` 352 353The returned value is the newly-created token. We can now add this to our Consul server 354configuration and restart the servers once more to apply it: 355 356```json 357{ 358 "acl_datacenter": "dc1", 359 "acl_master_token": "b1gs33cr3t", 360 "acl_default_policy": "deny", 361 "acl_down_policy": "extend-cache", 362 "acl_agent_token": "fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1" 363} 364``` 365 366In Consul 0.9.1 and later you can also introduce the agent token using an API, 367so it doesn't need to be set in the configuration file: 368 369```shell-session 370$ curl \ 371 --request PUT \ 372 --header "X-Consul-Token: b1gs33cr3t" \ 373 --data \ 374'{ 375 "Token": "fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1" 376}' http://127.0.0.1:8500/v1/agent/token/acl_agent_token 377``` 378 379With that ACL agent token set, the servers will be able to sync themselves with the 380catalog: 381 382```text 3832017/07/08 23:42:59 [INFO] agent: Synced node info 384``` 385 386See the [ACL Agent Token](#acl-agent-token) section for more details. 387 388#### Enable ACLs on the Consul Clients 389 390Since ACL enforcement also occurs on the Consul clients, we need to also restart them 391with a configuration file that enables ACLs: 392 393```json 394{ 395 "acl_datacenter": "dc1", 396 "acl_down_policy": "extend-cache", 397 "acl_agent_token": "fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1" 398} 399``` 400 401Similar to the previous example, in Consul 0.9.1 and later you can also introduce the 402agent token using an API, so it doesn't need to be set in the configuration file: 403 404```shell-session 405$ curl \ 406 --request PUT \ 407 --header "X-Consul-Token: b1gs33cr3t" \ 408 --data \ 409'{ 410 "Token": "fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1" 411}' http://127.0.0.1:8500/v1/agent/token/acl_agent_token 412``` 413 414We used the same ACL agent token that we created for the servers, which will work since 415it was not specific to any node or set of service prefixes. In a more locked-down 416environment it is recommended that each client get an ACL agent token with `node` write 417privileges for just its own node name prefix, and `service` read privileges for just the 418service prefixes expected to be registered on that client. 419 420[Anti-entropy](/docs/internals/anti-entropy) syncing requires the ACL agent token 421to have `service` read privileges for all services that may be registered with the agent, 422so generally an empty `service` prefix can be used, as shown in the example. 423 424Clients will report similar permission denied errors until they are restarted with an ACL 425agent token. 426 427#### Set an Anonymous Policy (Optional) 428 429At this point ACLs are bootstrapped with ACL agent tokens configured, but there are no 430other policies set up. Even basic operations like `consul members` will be restricted 431by the ACL default policy of "deny": 432 433```shell-session 434$ consul members 435``` 436 437We don't get an error since the ACL has filtered what we see, and we aren't allowed to 438see any nodes by default. 439 440If we supply the token we created above we will be able to see a listing of nodes because 441it has write privileges to an empty `node` prefix, meaning it has access to all nodes: 442 443```shell-session 444$ CONSUL_HTTP_TOKEN=fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1 consul members 445Node Address Status Type Build Protocol DC 446node-1 127.0.0.1:8301 alive server 0.9.0dev 2 dc1 447node-2 127.0.0.2:8301 alive client 0.9.0dev 2 dc1 448``` 449 450It's pretty common in many environments to allow listing of all nodes, even without a 451token. The policies associated with the special anonymous token can be updated to 452configure Consul's behavior when no token is supplied. The anonymous token is managed 453like any other ACL token, except that `anonymous` is used for the ID. In this example 454we will give the anonymous token read privileges for all nodes: 455 456```shell-session 457$ curl \ 458 --request PUT \ 459 --header "X-Consul-Token: b1gs33cr3t" \ 460 --data \ 461'{ 462 "ID": "anonymous", 463 "Type": "client", 464 "Rules": "node \"\" { policy = \"read\" }" 465}' http://127.0.0.1:8500/v1/acl/update 466 467{"ID":"anonymous"} 468``` 469 470The anonymous token is implicitly used if no token is supplied, so now we can run 471`consul members` without supplying a token and we will be able to see the nodes: 472 473```shell-session 474$ consul members 475Node Address Status Type Build Protocol DC 476node-1 127.0.0.1:8301 alive server 0.9.0dev 2 dc1 477node-2 127.0.0.2:8301 alive client 0.9.0dev 2 dc1 478``` 479 480The anonymous token is also used for DNS lookups since there's no way to pass a 481token as part of a DNS request. Here's an example lookup for the "consul" service: 482 483```shell-session 484$ dig @127.0.0.1 -p 8600 consul.service.consul 485 486; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul 487; (1 server found) 488;; global options: +cmd 489;; Got answer: 490;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 9648 491;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 0 492;; WARNING: recursion requested but not available 493 494;; QUESTION SECTION: 495;consul.service.consul. IN A 496 497;; AUTHORITY SECTION: 498consul. 0 IN SOA ns.consul. postmaster.consul. 1499584110 3600 600 86400 0 499 500;; Query time: 2 msec 501;; SERVER: 127.0.0.1#8600(127.0.0.1) 502;; WHEN: Sun Jul 9 00:08:30 2017 503;; MSG SIZE rcvd: 89 504``` 505 506Now we get an `NXDOMAIN` error because the anonymous token doesn't have access to the 507"consul" service. Let's add that to the anonymous token's policy: 508 509```shell-session 510$ curl \ 511 --request PUT \ 512 --header "X-Consul-Token: b1gs33cr3t" \ 513 --data \ 514'{ 515 "ID": "anonymous", 516 "Type": "client", 517 "Rules": "node \"\" { policy = \"read\" } service \"consul\" { policy = \"read\" }" 518}' http://127.0.0.1:8500/v1/acl/update 519 520{"ID":"anonymous"} 521``` 522 523With that new policy in place, the DNS lookup will succeed: 524 525```shell-session 526$ dig @127.0.0.1 -p 8600 consul.service.consul 527 528; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul 529; (1 server found) 530;; global options: +cmd 531;; Got answer: 532;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 46006 533;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0 534;; WARNING: recursion requested but not available 535 536;; QUESTION SECTION: 537;consul.service.consul. IN A 538 539;; ANSWER SECTION: 540consul.service.consul. 0 IN A 127.0.0.1 541 542;; Query time: 0 msec 543;; SERVER: 127.0.0.1#8600(127.0.0.1) 544;; WHEN: Sun Jul 9 00:11:14 2017 545;; MSG SIZE rcvd: 55 546``` 547 548The next section shows an alternative to the anonymous token. 549 550#### Set Agent-Specific Default Tokens (Optional) 551 552An alternative to the anonymous token is the [`acl_token`](/docs/agent/options#acl_token) 553configuration item. When a request is made to a particular Consul agent and no token is 554supplied, the [`acl_token`](/docs/agent/options#acl_token) will be used for the token, 555instead of being left empty which would normally invoke the anonymous token. 556 557In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the 558[/v1/agent/token API](/api/agent#update-acl-tokens). 559 560This behaves very similarly to the anonymous token, but can be configured differently on each 561agent, if desired. For example, this allows more fine grained control of what DNS requests a 562given agent can service, or can give the agent read access to some key-value store prefixes by 563default. 564 565If using [`acl_token`](/docs/agent/options#acl_token), then it's likely the anonymous 566token will have a more restrictive policy than shown in the examples here. 567 568#### Create Tokens for UI Use (Optional) 569 570If you utilize the Consul UI with a restrictive ACL policy, as above, the UI will 571not function fully using the anonymous ACL token. It is recommended 572that a UI-specific ACL token is used, which can be set in the UI during the 573web browser session to authenticate the interface. 574 575```shell-session 576$ curl \ 577 --request PUT \ 578 --header "X-Consul-Token: b1gs33cr3t" \ 579 --data \ 580'{ 581 "Name": "UI Token", 582 "Type": "client", 583 "Rules": "key \"\" { policy = \"write\" } node \"\" { policy = \"read\" } service \"\" { policy = \"read\" }" 584}' http://127.0.0.1:8500/v1/acl/create 585{"ID":"d0a9f330-2f9d-0a8c-d2af-1e9ceda354e6"} 586``` 587 588The token can then be set on the "settings" page of the UI. 589 590#### Next Steps 591 592The examples above configure a basic ACL environment with the ability to see all nodes 593by default, and limited access to just the "consul" service. The [ACL API](/api/acl/acl) 594can be used to create tokens for applications specific to their intended use, and to create 595more specific ACL agent tokens for each agent's expected role. 596 597Also see [HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul), which 598has an integration with Consul that allows it to generate ACL tokens on the fly and to manage 599their lifetimes. 600 601## Rule Specification 602 603A core part of the ACL system is the rule language which is used to describe the policy 604that must be enforced. Most of the ACL rules are prefix-based, allowing operators to 605define different namespaces within Consul's resource areas like the catalog and key/value 606store, in order to delegate responsibility for these namespaces. Policies can have several 607dispositions: 608 609- `read`: allow the resource to be read but not modified 610- `write`: allow the resource to be read and modified 611- `deny`: do not allow the resource to be read or modified 612 613With prefix-based rules, the most specific prefix match determines the action. This 614allows for flexible rules like an empty prefix to allow read-only access to all 615resources, along with some specific prefixes that allow write access or that are 616denied all access. 617 618We make use of the 619[HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl/) to specify 620rules. This language is human readable and interoperable with JSON making it easy to 621machine-generate. Rules can make use of one or more policies. 622 623Specification in the HCL format looks like: 624 625```hcl 626# These control access to the key/value store. 627key "" { 628 policy = "read" 629} 630key "foo/" { 631 policy = "write" 632} 633key "foo/private/" { 634 policy = "deny" 635} 636 637# This controls access to cluster-wide Consul operator information. 638operator = "read" 639``` 640 641This is equivalent to the following JSON input: 642 643```javascript 644{ 645 "key": { 646 "": { 647 "policy": "read" 648 }, 649 "foo/": { 650 "policy": "write" 651 }, 652 "foo/private/": { 653 "policy": "deny" 654 } 655 }, 656 "operator": "read" 657} 658``` 659 660The [ACL API](/api/acl/acl) allows either HCL or JSON to be used to define the content 661of the rules section. 662 663Here's a sample request using the HCL form: 664 665```shell-session 666$ curl \ 667 --request PUT \ 668 --data \ 669'{ 670 "Name": "my-app-token", 671 "Type": "client", 672 "Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\"" 673}' http://127.0.0.1:8500/v1/acl/create?token=<management token> 674``` 675 676Here's an equivalent request using the JSON form: 677 678```shell-session 679$ curl \ 680 --request PUT \ 681 --data \ 682'{ 683 "Name": "my-app-token", 684 "Type": "client", 685 "Rules": "{\"key\":{\"\":{\"policy\":\"read\"},\"foo/\":{\"policy\":\"write\"},\"foo/private\":{\"policy\":\"deny\"}},\"operator\":\"read\"}" 686}' http://127.0.0.1:8500/v1/acl/create?token=<management token> 687``` 688 689On success, the token ID is returned: 690 691```json 692{ 693 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 694} 695``` 696 697This token ID can then be passed into Consul's HTTP APIs via the `token` 698query string parameter, or the `X-Consul-Token` request header, or Authorization 699Bearer token header, or Consul's CLI commands via the `token` argument, 700or the `CONSUL_HTTP_TOKEN` environment variable. 701 702#### Agent Rules 703 704The `agent` policy controls access to the utility operations in the [Agent API](/api/agent), 705such as join and leave. All of the catalog-related operations are covered by the [`node`](#node-rules) 706and [`service`](#service-rules) policies instead. 707 708Agent rules look like this: 709 710```hcl 711agent "" { 712 policy = "read" 713} 714agent "foo" { 715 policy = "write" 716} 717agent "bar" { 718 policy = "deny" 719} 720``` 721 722Agent rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In 723the example above, the rules allow read-only access to any node name with the empty prefix, allow 724read-write access to any node name that starts with "foo", and deny all access to any node name that 725starts with "bar". 726 727Since [Agent API](/api/agent) utility operations may be required before an agent is joined to 728a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be 729configured with [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) to allow 730write access to these operations even if no ACL resolution capability is available. 731 732#### Event Rules 733 734The `event` policy controls access to event operations in the [Event API](/api/event), such as 735firing events and listing events. 736 737Event rules look like this: 738 739```hcl 740event "" { 741 policy = "read" 742} 743event "deploy" { 744 policy = "write" 745} 746``` 747 748Event rules are keyed by the event name prefix they apply to, using the longest prefix match rule. 749In the example above, the rules allow read-only access to any event, and firing of any event that 750starts with "deploy". 751 752The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during 753operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to 754give agents a token with access to this event prefix, in addition to configuring 755[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`. 756 757#### Key/Value Rules 758 759The `key` policy controls access to key/value store operations in the [KV API](/api/kv). Key 760rules look like this: 761 762```hcl 763key "" { 764 policy = "read" 765} 766key "foo" { 767 policy = "write" 768} 769key "bar" { 770 policy = "deny" 771} 772``` 773 774Key rules are keyed by the key name prefix they apply to, using the longest prefix match rule. In 775the example above, the rules allow read-only access to any key name with the empty prefix, allow 776read-write access to any key name that starts with "foo", and deny all access to any key name that 777starts with "bar". 778 779#### List Policy for Keys 780 781Consul 1.0 introduces a new `list` policy for keys that is only enforced when opted in via the boolean config param "acl_enable_key_list_policy". 782`list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl_enable_key_list_policy", 783recursive reads via [the KV API](/api/kv#recurse) with an invalid token result in a 403. Example: 784 785```hcl 786key "" { 787 policy = "deny" 788} 789 790key "bar" { 791 policy = "list" 792} 793 794key "baz" { 795 policy = "read" 796} 797``` 798 799In the example above, the rules allow reading the key "baz", and only allow recursive reads on the prefix "bar". 800 801A token with `write` access on a prefix also has `list` access. A token with `list` access on a prefix also has `read` access on all its suffixes. 802 803#### Sentinel Integration <EnterpriseAlert inline /> 804 805Consul Enterprise supports additional optional fields for key write policies for 806[Sentinel](https://docs.hashicorp.com/sentinel/consul/) integration. An example key rule with a 807Sentinel code policy looks like this: 808 809```hcl 810key "foo" { 811 policy = "write" 812 sentinel { 813 code = <<EOF 814import "strings" 815main = rule { strings.has_suffix(value, "bar") } 816EOF 817 enforcementlevel = "hard-mandatory" 818 } 819} 820``` 821 822For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel). 823 824#### Keyring Rules 825 826The `keyring` policy controls access to keyring operations in the 827[Keyring API](/api/operator/keyring). 828 829Keyring rules look like this: 830 831```text 832keyring = "write" 833``` 834 835There's only one keyring policy allowed per rule set, and its value is set to one of the policy 836dispositions. In the example above, the keyring may be read and updated. 837 838#### Node Rules 839 840The `node` policy controls node-level registration and read access to the [Catalog API](/api/catalog), 841service discovery with the [Health API](/api/health), and filters results in [Agent API](/api/agent) 842operations like fetching the list of cluster members. 843 844Node rules look like this: 845 846```hcl 847node "" { 848 policy = "read" 849} 850node "app" { 851 policy = "write" 852} 853node "admin" { 854 policy = "deny" 855} 856``` 857 858Node rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In 859the example above, the rules allow read-only access to any node name with the empty prefix, allow 860read-write access to any node name that starts with "app", and deny all access to any node name that 861starts with "admin". 862 863Agents need to be configured with an [`acl_agent_token`](/docs/agent/options#acl_agent_token) 864with at least "write" privileges to their own node name in order to register their information with 865the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent 866will print an error to the console when it tries to sync its state with the catalog. 867 868Consul's DNS interface is also affected by restrictions on node rules. If the 869[`acl_token`](/docs/agent/options#acl_token) used by the agent does not have "read" access to a 870given node, then the DNS interface will return no records when queried for it. 871 872When reading from the catalog or retrieving information from the health endpoints, node rules are 873used to filter the results of the query. This allows for configurations where a token has access 874to a given service name, but only on an allowed subset of node names. 875 876Node rules come into play when using the [Agent API](/api/agent) to register node-level 877checks. The agent will check tokens locally as a check is registered, and Consul also performs 878periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require an 879ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens 880to use for registration events: 881 8821. Using the [acl_token](/docs/agent/options#acl_token) configuration 883 directive. This allows a single token to be configured globally and used 884 during all check registration operations. 8852. Providing an ACL token with service and check definitions at 886 registration time. This allows for greater flexibility and enables the use 887 of multiple tokens on the same agent. Examples of what this looks like are 888 available for both [services](/docs/agent/services) and 889 [checks](/docs/agent/checks). Tokens may also be passed to the 890 [HTTP API](/api) for operations that require them. 891 892In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with 893[`enable_script_checks`](/docs/agent/options#_enable_script_checks) set to `true` in order to enable 894script checks. 895 896#### Operator Rules 897 898The `operator` policy controls access to cluster-level operations in the 899[Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring). 900 901Operator rules look like this: 902 903```text 904operator = "read" 905``` 906 907There's only one operator policy allowed per rule set, and its value is set to one of the policy 908dispositions. In the example above, the token could be used to query the operator endpoints for 909diagnostic purposes but not make any changes. 910 911#### Prepared Query Rules 912 913The `query` policy controls access to create, update, and delete prepared queries in the 914[Prepared Query API](/api/query). Executing queries is subject to `node` and `service` 915policies, as will be explained below. 916 917Query rules look like this: 918 919```hcl 920query "" { 921 policy = "read" 922} 923query "foo" { 924 policy = "write" 925} 926``` 927 928Query rules are keyed by the query name prefix they apply to, using the longest prefix match rule. In 929the example above, the rules allow read-only access to any query name with the empty prefix, and allow 930read-write access to any query name that starts with "foo". This allows control of the query namespace 931to be delegated based on ACLs. 932 933There are a few variations when using ACLs with prepared queries, each of which uses ACLs in one of two 934ways: open, protected by unguessable IDs or closed, managed by ACL policies. These variations are covered 935here, with examples: 936 937- Static queries with no `Name` defined are not controlled by any ACL policies. 938 These types of queries are meant to be ephemeral and not shared to untrusted 939 clients, and they are only reachable if the prepared query ID is known. Since 940 these IDs are generated using the same random ID scheme as ACL Tokens, it is 941 infeasible to guess them. When listing all prepared queries, only a management 942 token will be able to see these types, though clients can read instances for 943 which they have an ID. An example use for this type is a query built by a 944 startup script, tied to a session, and written to a configuration file for a 945 process to use via DNS. 946 947- Static queries with a `Name` defined are controlled by the `query` ACL policy. 948 Clients are required to have an ACL token with a prefix sufficient to cover 949 the name they are trying to manage, with a longest prefix match providing a 950 way to define more specific policies. Clients can list or read queries for 951 which they have "read" access based on their prefix, and similar they can 952 update any queries for which they have "write" access. An example use for 953 this type is a query with a well-known name (eg. `prod-primary-customer-db`) 954 that is used and known by many clients to provide geo-failover behavior for 955 a database. 956 957- [Template queries](/api/query#prepared-query-templates) 958 queries work like static queries with a `Name` defined, except that a catch-all 959 template with an empty `Name` requires an ACL token that can write to any query 960 prefix. 961 962When prepared queries are executed via DNS lookups or HTTP requests, the ACL 963checks are run against the service being queried, similar to how ACLs work with 964other service lookups. There are several ways the ACL token is selected for this 965check: 966 967- If an ACL Token was captured when the prepared query was defined, it will be 968 used to perform the service lookup. This allows queries to be executed by 969 clients with lesser or even no ACL Token, so this should be used with care. 970 971- If no ACL Token was captured, then the client's ACL Token will be used to 972 perform the service lookup. 973 974- If no ACL Token was captured and the client has no ACL Token, then the 975 anonymous token will be used to perform the service lookup. 976 977In the common case, the ACL Token of the invoker is used 978to test the ability to look up a service. If a `Token` was specified when the 979prepared query was created, the behavior changes and now the captured 980ACL Token set by the definer of the query is used when looking up a service. 981 982Capturing ACL Tokens is analogous to 983[PostgreSQL’s](http://www.postgresql.org/docs/current/static/sql-createfunction.html) 984`SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL 985Token is similar to the complementary `SECURITY INVOKER` attribute. 986 987Prepared queries were originally introduced in Consul 0.6.0, and ACL behavior remained 988unchanged through version 0.6.3, but was then changed to allow better management of the 989prepared query namespace. 990 991These differences are outlined in the table below: 992 993| Operation | Version <= 0.6.3 | Version > 0.6.3 | 994| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 995| Create static query without `Name` | The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. | No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query. | 996| Create static query with `Name` | The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. | The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query. | 997| Manage static query without `Name` | The ACL Token used to create the query, or a management token must be supplied in order to perform these operations. | Any client with the ID of the query can perform these operations. | 998| Manage static query with a `Name` | The ACL token used to create the query, or a management token must be supplied in order to perform these operations. | Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed. | 999| List queries | A management token is required to list any queries. | The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`. | 1000| Execute query | Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored. | The captured token, client's token, or anonymous token is used to filter the results, as described above. | 1001 1002#### Service Rules 1003 1004The `service` policy controls service-level registration and read access to the [Catalog API](/api/catalog) 1005and service discovery with the [Health API](/api/health). 1006 1007Service rules look like this: 1008 1009```hcl 1010service "" { 1011 policy = "read" 1012} 1013service "app" { 1014 policy = "write" 1015} 1016service "admin" { 1017 policy = "deny" 1018} 1019``` 1020 1021Service rules are keyed by the service name prefix they apply to, using the longest prefix match rule. In 1022the example above, the rules allow read-only access to any service name with the empty prefix, allow 1023read-write access to any service name that starts with "app", and deny all access to any service name that 1024starts with "admin". 1025 1026Consul's DNS interface is affected by restrictions on service rules. If the 1027[`acl_token`](/docs/agent/options#acl_token) used by the agent does not have "read" access to a 1028given service, then the DNS interface will return no records when queried for it. 1029 1030When reading from the catalog or retrieving information from the health endpoints, service rules are 1031used to filter the results of the query. 1032 1033Service rules come into play when using the [Agent API](/api/agent) to register services or 1034checks. The agent will check tokens locally as a service or check is registered, and Consul also 1035performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require an 1036ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens 1037to use for registration events: 1038 10391. Using the [acl_token](/docs/agent/options#acl_token) configuration 1040 directive. This allows a single token to be configured globally and used 1041 during all service and check registration operations. 10422. Providing an ACL token with service and check definitions at registration 1043 time. This allows for greater flexibility and enables the use of multiple 1044 tokens on the same agent. Examples of what this looks like are available for 1045 both [services](/docs/agent/services) and 1046 [checks](/docs/agent/checks). Tokens may also be passed to the [HTTP 1047 API](/api) for operations that require them. **Note:** all tokens 1048 passed to an agent are persisted on local disk to allow recovery from 1049 restarts. See [`-data-dir` flag 1050 documentation](/docs/agent/options#acl_token) for notes on securing 1051 access. 1052 1053In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with 1054[`enable_script_checks`](/docs/agent/options#_enable_script_checks) or 1055[`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks) 1056set to `true` in order to enable script checks. 1057 1058#### Session Rules 1059 1060The `session` policy controls access to [Session API](/api/session) operations. 1061 1062Session rules look like this: 1063 1064```hcl 1065session "" { 1066 policy = "read" 1067} 1068session "app" { 1069 policy = "write" 1070} 1071session "admin" { 1072 policy = "deny" 1073} 1074``` 1075 1076Session rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In 1077the example above, the rules allow read-only access to sessions on node name with the empty prefix, allow 1078creating sessions on any node name that starts with "app", and deny all access to any sessions on a node 1079name that starts with "admin". 1080 1081## Advanced Topics 1082 1083#### Outages and ACL Replication ((#replication)) 1084 1085The Consul ACL system is designed with flexible rules to accommodate for an outage 1086of the [`acl_datacenter`](/docs/agent/options#acl_datacenter) or networking 1087issues preventing access to it. In this case, it may be impossible for 1088agents in non-authoritative datacenters to resolve tokens. Consul provides 1089a number of configurable [`acl_down_policy`](/docs/agent/options#acl_down_policy) 1090choices to tune behavior. It is possible to deny or permit all actions or to ignore 1091cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs 1092for any previously resolved tokens and to deny any uncached tokens. 1093 1094Consul 0.7 added an ACL Replication capability that can allow non-authoritative 1095datacenter agents to resolve even uncached tokens. This is enabled by setting an 1096[`acl_replication_token`](/docs/agent/options#acl_replication_token) in the 1097configuration on the servers in the non-authoritative datacenters. In Consul 10980.9.1 and later you can enable ACL replication using 1099[`enable_acl_replication`](/docs/agent/options#enable_acl_replication) and 1100then set the token later using the 1101[agent token API](/api/agent#update-acl-tokens) on each server. This can 1102also be used to rotate the token without restarting the Consul servers. 1103 1104With replication enabled, the servers will maintain a replica of the authoritative 1105datacenter's full set of ACLs on the non-authoritative servers. The ACL replication 1106token needs to be a valid ACL token with management privileges, it can also be the 1107same as the master ACL token. 1108 1109Replication occurs with a background process that looks for new ACLs approximately 1110every 30 seconds. Replicated changes are written at a rate that's throttled to 1111100 updates/second, so it may take several minutes to perform the initial sync of 1112a large set of ACLs. 1113 1114If there's a partition or other outage affecting the authoritative datacenter, 1115and the [`acl_down_policy`](/docs/agent/options#acl_down_policy) 1116is set to "extend-cache", tokens will be resolved during the outage using the 1117replicated set of ACLs. An [ACL replication status](/api/acl/acl#check-acl-replication) 1118endpoint is available to monitor the health of the replication process. 1119Also note that in recent versions of Consul (greater than 1.2.0), using 1120`acl_down_policy = "async-cache"` refreshes token asynchronously when an ACL is 1121already cached and is expired while similar semantics than "extend-cache". 1122It allows to avoid having issues when connectivity with the authoritative is not completely 1123broken, but very slow. 1124 1125Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options#acl_ttl) 1126setting of the non-authoritative datacenter, so these entries may persist in the 1127cache for up to the TTL, even after the authoritative datacenter comes back online. 1128 1129ACL replication can also be used to migrate ACLs from one datacenter to another 1130using a process like this: 1131 11321. Enable ACL replication in all datacenters to allow continuation of service 1133 during the migration, and to populate the target datacenter. Verify replication 1134 is healthy and caught up to the current ACL index in the target datacenter 1135 using the [ACL replication status](/api/acl/acl#check-acl-replication) 1136 endpoint. 11372. Turn down the old authoritative datacenter servers. 11383. Rolling restart the agents in the target datacenter and change the 1139 `acl_datacenter` servers to itself. This will automatically turn off 1140 replication and will enable the datacenter to start acting as the authoritative 1141 datacenter, using its replicated ACLs from before. 11424. Rolling restart the agents in other datacenters and change their `acl_datacenter` 1143 configuration to the target datacenter. 1144 1145#### Complete ACL Coverage in Consul 0.8 ((#version_8_acls)) 1146 1147Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consul 1148agents for the first time. To ease the transition to Consul 0.8 for existing ACL 1149users, there's a configuration option to disable these new features. To disable 1150support for these new ACLs, set the 1151[`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) configuration 1152option to `false` on Consul clients and servers. 1153 1154Here's a summary of the new features: 1155 1156- Agents now check [`node`](#node-rules) and [`service`](#service-rules) ACL policies 1157 for catalog-related operations in `/v1/agent` endpoints, such as service and check 1158 registration and health check updates. 1159- Agents enforce a new [`agent`](#agent-rules) ACL policy for utility operations in 1160 `/v1/agent` endpoints, such as joins and leaves. 1161- A new [`node`](#node-rules) ACL policy is enforced throughout Consul, providing a 1162 mechanism to restrict registration and discovery of nodes by name. This also applies 1163 to service discovery, so provides an additional dimension for controlling access to 1164 services. 1165- A new [`session`](#session-rules) ACL policy controls the ability to create session 1166 objects by node name. 1167- Anonymous prepared queries (non-templates without a `Name`) now require a valid 1168 session, which ties their creation to the new [`session`](#session-rules) ACL policy. 1169- The existing [`event`](#event-rules) ACL policy has been applied to the 1170 `/v1/event/list` endpoint. 1171 1172Two new configuration options are used once version 8 ACLs are enabled: 1173 1174- [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) is used as 1175 a special access token that has `agent` ACL policy `write` privileges on each agent where 1176 it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token 1177 should only be used by operators during outages when Consul servers aren't available to 1178 resolve ACL tokens. Applications should use regular ACL tokens during normal operation. 1179- [`acl_agent_token`](/docs/agent/options#acl_agent_token) is used internally by 1180 Consul agents to perform operations to the service catalog when registering themselves 1181 or sending network coordinates to the servers. This token must at least have `node` ACL 1182 policy `write` access to the node name it will register as in order to register any 1183 node-level information like metadata or tagged addresses. 1184 1185Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/options#acl_down_policy) 1186now applies to Consul clients as well as Consul servers. This will determine what the 1187client will do in the event that the servers are down. 1188 1189Consul clients must have [`acl_datacenter`](/docs/agent/options#acl_datacenter) configured 1190in order to enable agent-level ACL features. If this is set, the agents will contact the Consul 1191servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not 1192enabled, they will check at most every 2 minutes to see if they have become enabled, and will 1193start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will 1194need to use the [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) to 1195perform agent-level operations if the Consul servers aren't present (such as for a manual join 1196to the cluster), unless the [`acl_down_policy`](/docs/agent/options#acl_down_policy) on the 1197agent is set to "allow". 1198 1199Non-server agents do not need to have the 1200[`acl_master_token`](/docs/agent/options#acl_master_token) configured; it is not 1201used by agents in any way. 1202