github.com/outbrain/consul@v1.4.5/website/source/api/acl/acl.html.md (about) 1 --- 2 layout: api 3 page_title: ACLs - HTTP API 4 sidebar_current: api-acl 5 description: |- 6 The /acl endpoints manage the Consul's ACL system. 7 --- 8 9 -> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html) 10 11 # ACL HTTP API 12 13 The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens.html) and [policies](/api/acl/policies.html) with the `/acl` endpoints. 14 15 For more information about ACLs, please see the [ACL Guide](/docs/guides/acl.html). 16 17 ## Bootstrap ACLs 18 19 This endpoint does a special one-time bootstrap of the ACL system, making the first 20 management token if the [`acl.tokens.master`](/docs/agent/options.html#acl_tokens_master) 21 configuration entry is not specified in the Consul server configuration and if the 22 cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later, 23 and requires all Consul servers to be upgraded in order to operate. 24 25 This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's 26 configuration files. 27 28 | Method | Path | Produces | 29 | ------ | ---------------------------- | -------------------------- | 30 | `PUT` | `/acl/bootstrap` | `application/json` | 31 32 The table below shows this endpoint's support for 33 [blocking queries](/api/index.html#blocking-queries), 34 [consistency modes](/api/index.html#consistency-modes), 35 [agent caching](/api/index.html#agent-caching), and 36 [required ACLs](/api/index.html#acls). 37 38 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 39 | ---------------- | ----------------- | ------------- | ------------ | 40 | `NO` | `none` | `none` | `none` | 41 42 ### Sample Request 43 44 ```text 45 $ curl \ 46 --request PUT \ 47 http://127.0.0.1:8500/v1/acl/bootstrap 48 ``` 49 50 ### Sample Response 51 52 -> **Deprecated** - The `ID` field in the response is for legacy compatibility and is a copy of the `SecretID` field. New 53 applications should ignore the `ID` field as it may be removed in a future major Consul version. 54 55 ```json 56 { 57 "ID": "527347d3-9653-07dc-adc0-598b8f2b0f4d", 58 "AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3", 59 "SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d", 60 "Description": "Bootstrap Token (Global Management)", 61 "Policies": [ 62 { 63 "ID": "00000000-0000-0000-0000-000000000001", 64 "Name": "global-management" 65 } 66 ], 67 "Local": false, 68 "CreateTime": "2018-10-24T10:34:20.843397-04:00", 69 "Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=", 70 "CreateIndex": 12, 71 "ModifyIndex": 12 72 } 73 ``` 74 75 You can detect if something has interfered with the ACL bootstrapping process by 76 checking the response code. A 200 response means that the bootstrap was a success, and 77 a 403 means that the cluster has already been bootstrapped, at which point you should 78 consider the cluster in a potentially compromised state. 79 80 The returned token will have unrestricted privileges to manage all details of the system. 81 It can then be used to further configure the ACL system. Please see the 82 [ACL Guide](/docs/guides/acl.html) for more details. 83 84 ## Check ACL Replication 85 86 This endpoint returns the status of the ACL replication processes in the 87 datacenter. This is intended to be used by operators or by automation checking 88 to discover the health of ACL replication. 89 90 Please see the [ACL Guide](/docs/guides/acl.html#replication) replication 91 section for more details. 92 93 | Method | Path | Produces | 94 | ------ | ---------------------------- | -------------------------- | 95 | `GET` | `/acl/replication` | `application/json` | 96 97 The table below shows this endpoint's support for 98 [blocking queries](/api/index.html#blocking-queries), 99 [consistency modes](/api/index.html#consistency-modes), 100 [agent caching](/api/index.html#agent-caching), and 101 [required ACLs](/api/index.html#acls). 102 103 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 104 | ---------------- | ----------------- | ------------- | ------------ | 105 | `NO` | `consistent` | `none` | `none` | 106 107 ### Parameters 108 109 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 110 the datacenter of the agent being queried. This is specified as part of the 111 URL as a query parameter. 112 113 ### Sample Request 114 115 ```text 116 $ curl \ 117 --request GET \ 118 http://127.0.0.1:8500/v1/acl/replication 119 ``` 120 121 ### Sample Response 122 123 ```json 124 { 125 "Enabled": true, 126 "Running": true, 127 "SourceDatacenter": "dc1", 128 "ReplicationType" : "tokens", 129 "ReplicatedIndex": 1976, 130 "ReplicatedTokenIndex": 2018, 131 "LastSuccess": "2018-11-03T06:28:58Z", 132 "LastError": "2016-11-03T06:28:28Z" 133 } 134 ``` 135 136 - `Enabled` - Reports whether ACL replication is enabled for the datacenter. 137 138 - `Running` - Reports whether the ACL replication process is running. The process 139 may take approximately 60 seconds to begin running after a leader election 140 occurs. 141 142 - `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being 143 replicated from and will match the 144 [`primary_datacenter`](/docs/agent/options.html#primary_datacenter) configuration. 145 146 - `ReplicationType` - The type of replication that is currently in use. 147 148 - `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens. 149 150 - `policies` - ACL replication is only replicating policies as token replication 151 is disabled. 152 153 - `tokens` - ACL replication is replicating both policies and tokens. 154 155 - `ReplicatedIndex` - The last index that was successfully replicated. Which data 156 the replicated index refers to depends on the replication type. For `legacy` 157 replication this can be compared with the value of the `X-Consul-Index` header 158 returned by the [`/v1/acl/list`](/api/acl/legacy.html#acl_list) endpoint to 159 determine if the replication process has gotten all available ACLs. When in either 160 `tokens` or `policies` mode, this index can be compared with the value of the 161 `X-Consul-Index` header returned by the [`/v1/acl/polcies`](/api/acl/policies.html#list-policies) 162 endpoint to determine if the policy replication process has gotten all available 163 ACL policies. Note that ACL replication is rate limited so the indexes may lag behind 164 the primary datacenter. 165 166 - `ReplicatedTokenIndex` - The last token index that was successfully replicated. 167 This index can be compared with the value of the `X-Consul-Index` header returned 168 by the [`/v1/acl/tokens`](/api/acl/tokens.html#list) endpoint to determine 169 if the replication process has gotten all available ACL tokens. Note that ACL 170 replication is rate limited so the indexes may lag behind the primary 171 datacenter. 172 173 - `LastSuccess` - The UTC time of the last successful sync operation. Since ACL 174 replication is done with a blocking query, this may not update for up to 5 175 minutes if there have been no ACL changes to replicate. A zero value of 176 "0001-01-01T00:00:00Z" will be present if no sync has been successful. 177 178 - `LastError` - The UTC time of the last error encountered during a sync 179 operation. If this time is later than `LastSuccess`, you can assume the 180 replication process is not in a good state. A zero value of 181 "0001-01-01T00:00:00Z" will be present if no sync has resulted in an error. 182 183 ## Translate Rules 184 185 -> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system. It 186 will be removed in a future major Consul version when support for legacy ACLs is removed. 187 188 This endpoint translates the legacy rule syntax into the latest syntax. It is intended 189 to be used by operators managing Consul's ACLs and performing legacy token to new policy 190 migrations. 191 192 | Method | Path | Produces | 193 | ------ | --------------------------- | -------------------------- | 194 | `POST` | `/acl/rules/translate` | `text/plain` | 195 196 The table below shows this endpoint's support for 197 [blocking queries](/api/index.html#blocking-queries), 198 [consistency modes](/api/index.html#consistency-modes), 199 [agent caching](/api/index.html#agent-caching), and 200 [required ACLs](/api/index.html#acls). 201 202 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 203 | ---------------- | ----------------- | ------------- | ------------ | 204 | `NO` | `none` | `none` | `acl:read` | 205 206 ### Sample Payload 207 208 ```text 209 agent "" { 210 policy = "read" 211 } 212 ``` 213 214 ### Sample Request 215 216 ```text 217 $ curl -X POST -d @rules.hcl http://127.0.0.1:8500/v1/acl/rules/translate 218 ``` 219 220 ### Sample Response 221 222 ```text 223 agent_prefix "" { 224 policy = "read" 225 } 226 ``` 227 228 ## Translate a Legacy Token's Rules 229 230 -> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.. It 231 will be removed in a future major Consul version when support for legacy ACLs is removed. 232 233 This endpoint translates the legacy rules embedded within a legacy ACL into the latest 234 syntax. It is intended to be used by operators managing Consul's ACLs and performing 235 legacy token to new policy migrations. Note that this API requires the auto-generated 236 Accessor ID of the legacy token. This ID can be retrieved using the 237 [`/v1/acl/token/self`](/api/acl/tokens.html#self) endpoint. 238 239 | Method | Path | Produces | 240 | ------ | ----------------------------------- | -------------------------- | 241 | `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` | 242 243 The table below shows this endpoint's support for 244 [blocking queries](/api/index.html#blocking-queries), 245 [consistency modes](/api/index.html#consistency-modes), 246 [agent caching](/api/index.html#agent-caching), and 247 [required ACLs](/api/index.html#acls). 248 249 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 250 | ---------------- | ----------------- | ------------- | ------------ | 251 | `NO` | `none` | `none` | `acl:read` | 252 253 ### Sample Request 254 255 ```text 256 $ curl -X GET http://127.0.0.1:8500/v1/acl/rules/translate/4f48f7e6-9359-4890-8e67-6144a962b0a5 257 ``` 258 259 ### Sample Response 260 261 ```text 262 agent_prefix "" { 263 policy = "read" 264 } 265 ```