github.com/outbrain/consul@v1.4.5/website/source/docs/commands/acl/acl-token.html.md.erb (about) 1 --- 2 layout: "docs" 3 page_title: "Commands: ACL Token Management" 4 sidebar_current: "docs-commands-acl-token" 5 --- 6 7 # Consul ACL Tokens 8 9 Command: `consul acl token` 10 11 The `acl token` command is used to manage Consul's ACL tokens. There are 12 subcommands for the individual operations that can be performed. 13 14 * [`create`](#create) 15 * [`clone`](#clone) 16 * [`read`](#read) 17 * [`update`](#update) 18 * [`delete`](#delete) 19 * [`list`](#list) 20 21 ACL tokens are also accessible via the [HTTP API](/api/acl/acl.html). 22 23 Usage: `consul acl token <subcommand> [options] [args]` 24 25 -> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions. 26 Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token` 27 parameter. 28 29 ## Identitying Tokens 30 31 In several of the subcommands a token will have to be identified to be read, modified or deleted. Those subcommands support 32 specifying the token by its ID using the `-id` parameter. The ID may be specified as a unique UUID prefix instead of the entire 33 UUID. As long as it is unique it will be resolve to the full UUID and used. Additionally builtin token names will be accepted as 34 the value of the `-id`. 35 36 Builtin Policies: 37 38 | Token UUID | Token Name | 39 | ------------------------------------ | ----------------- | 40 | 00000000-0000-0000-0000-000000000002 | anonymous | 41 42 ## Common Subcommand Options 43 44 All of the `consul acl token` subcommands support the following options: 45 46 <%= partial "docs/commands/http_api_options_client" %> 47 <%= partial "docs/commands/http_api_options_server" %> 48 49 ## `create` 50 51 Command: `consul acl token create` 52 53 This command creates new tokens. When creating a new token, policies may be linked using 54 either the `-policy-id` or the `-policy-name options. When specifying policies by IDs you 55 may use a unique prefix of the UUID as a shortcut for specifying the entire UUID. 56 57 ### Usage 58 59 #### Options 60 61 * [Common Subcommand Options](#common-subcommand-options) 62 63 * `-description=<string>` - A description of the token. 64 65 * `-local` - Create this as a datacenter local token. 66 67 * `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times. 68 69 * `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times. 70 71 * `-meta` - Indicates that token metadata such as the content hash and raft indices should be shown 72 for each entry. 73 74 ### Examples 75 76 Create a new token: 77 78 ```sh 79 $ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 80 AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d 81 SecretID: ec15675e-2999-d789-832e-8c4794daa8d7 82 Description: Read Nodes and Services 83 Local: false 84 Create Time: 2018-10-22 15:33:39.01789 -0400 EDT 85 Policies: 86 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 87 ``` 88 89 Create a new local token: 90 91 ```sh 92 $ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local 93 AccessorID: 4fdf0ec8-d251-3865-079c-7247c974fc50 94 SecretID: 02143514-abf2-6c23-0aa1-ec2107e68f6b 95 Description: Read Nodes and Services 96 Local: true 97 Create Time: 2018-10-22 15:34:19.330265 -0400 EDT 98 Policies: 99 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 100 ``` 101 102 Create a new policy and link with policies by name: 103 104 ```sh 105 $ consul acl token create -description "Super User" -policy-name global-management 106 AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa 107 SecretID: ada7f751-f654-8872-7f93-498e799158b6 108 Description: Super User 109 Local: false 110 Create Time: 2018-10-22 15:35:28.787003 -0400 EDT 111 Policies: 112 00000000-0000-0000-0000-000000000001 - global-management 113 ``` 114 115 ## `clone` 116 117 Command: `consul acl token clone` 118 119 This command clones an existing token. 120 121 ### Usage 122 123 Usage: `consul acl token clone [options] 124 125 #### Options 126 127 * [Common Subcommand Options](#common-subcommand-options) 128 129 * `-description=<string>` - A description of the new cloned token. 130 131 * `-id=<string>` - The Accessor ID of the token to clone. It may be specified 132 as a unique ID prefix but will error if the prefix matches multiple token 133 Accessor IDs. The special value of 'anonymous' may be provided instead of 134 the anonymous tokens accessor ID 135 136 ### Examples 137 138 Clone a token: 139 140 ```sh 141 $ consul acl token clone -id 59f8 -description "Clone of Super User" 142 Token cloned successfully. 143 AccessorID: dcfa52ed-9288-b3ff-056d-255ef69d2d88 144 SecretID: 0005d17e-5bb2-7e8b-7bfa-15f2eee9ad14 145 Description: Clone of Super User 146 Local: false 147 Create Time: 2018-10-22 16:26:02.909096 -0400 EDT 148 Policies: 149 00000000-0000-0000-0000-000000000001 - global-management 150 ``` 151 152 ## `read` 153 154 Command: `consul acl token read` 155 156 This command reads and displays a token details. 157 158 ### Usage 159 160 Usage: `consul acl token read [options] [args]` 161 162 #### Options 163 164 * [Common Subcommand Options](#common-subcommand-options) 165 166 * `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID 167 prefix but will error if the prefix matches multiple policy IDs. 168 169 * `-meta` - Indicates that policy metadata such as the content hash and raft 170 indices should be shown for each entry. 171 172 * `-self` - Indicates that the current HTTP token should be read by secret ID 173 instead of expecting a -id option. 174 175 176 ### Examples 177 178 Get token details: 179 180 ```sh 181 $ consul acl token read -id 986 182 AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d 183 SecretID: ec15675e-2999-d789-832e-8c4794daa8d7 184 Description: Read Nodes and Services 185 Local: false 186 Create Time: 2018-10-22 15:33:39.01789 -0400 EDT 187 Policies: 188 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 189 ``` 190 191 Get token details using the token secret ID: 192 193 ```sh 194 $consul acl token read -self 195 AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01 196 SecretID: 86cddfb9-2760-d947-358d-a2811156bf31 197 Description: Bootstrap Token (Global Management) 198 Local: false 199 Create Time: 2018-10-22 11:27:04.479026 -0400 EDT 200 Policies: 201 00000000-0000-0000-0000-000000000001 - global-management 202 ``` 203 204 Get token details (Builtin Tokens) 205 206 ```sh 207 $ consul acl token read -id anonymous 208 AccessorID: 00000000-0000-0000-0000-000000000002 209 SecretID: anonymous 210 Description: Anonymous Token 211 Local: false 212 Create Time: 0001-01-01 00:00:00 +0000 UTC 213 Policies: 214 ``` 215 216 ## `update` 217 218 Command: `consul acl token update` 219 220 This command will update a token. Some parts of the token like whether the 221 token is local to the datacenter cannot be changed. 222 223 ### Usage 224 225 Usage: `consul acl token update [options]` 226 227 #### Options 228 229 * [Common Subcommand Options](#common-subcommand-options) 230 231 * `-description=<string>` - A description of the token 232 233 * `-id=<string>` - The Accessor ID of the token to read. It may be specified as a 234 unique ID prefix but will error if the prefix matches multiple token Accessor IDs 235 236 * `-merge-policies` - Merge the new policies with the existing policies 237 238 * `-meta` - Indicates that token metadata such as the content hash and Raft indices should be 239 shown for each entry. 240 241 * `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times. 242 243 * `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times. 244 245 ### Examples 246 247 Update the anonymous token: 248 249 ```sh 250 $ consul acl token update -id anonymous -policy-id 06acc 251 Token updated successfully. 252 AccessorID: 00000000-0000-0000-0000-000000000002 253 SecretID: anonymous 254 Description: Anonymous Token 255 Local: false 256 Create Time: 0001-01-01 00:00:00 +0000 UTC 257 Policies: 258 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 259 ``` 260 261 Update a token description and take the policies from the existing token: 262 263 ```sh 264 $ consul acl token update -id 986193 -description "WonderToken" -merge-policies 265 Token updated successfully. 266 AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d 267 SecretID: ec15675e-2999-d789-832e-8c4794daa8d7 268 Description: WonderToken 269 Local: false 270 Create Time: 2018-10-22 15:33:39.01789 -0400 EDT 271 Policies: 272 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 273 ``` 274 275 ## `delete` 276 277 Command: `consul acl token delete` 278 279 This command deletes a token. 280 281 ### Usage 282 283 Usage: `consul acl token delete [options]` 284 285 #### Options 286 287 * [Common Subcommand Options](#common-subcommand-options) 288 289 * `-id=<string>` - The ID of the token to delete. It may be specified as a 290 unique ID prefix but will error if the prefix matches multiple token IDs. 291 292 ### Examples 293 294 Delete a token: 295 296 ```sh 297 $ consul acl token delete -id 35b8 298 Token "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully 299 ``` 300 301 ## `list` 302 303 Command: `consul acl token list` 304 305 This command lists all tokens. By default it will not show metadata. 306 307 ### Usage 308 309 Usage: `consul acl token list` 310 311 #### Options 312 313 * [Common Subcommand Options](#common-subcommand-options) 314 315 * `-meta` - Indicates that token metadata such as the content hash and 316 Raft indices should be shown for each entry. 317 318 ### Examples 319 320 Default listing. 321 322 ```sh 323 $ consul acl token list 324 AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01 325 Description: Bootstrap Token (Global Management) 326 Local: false 327 Create Time: 2018-10-22 11:27:04.479026 -0400 EDT 328 Legacy: false 329 Policies: 330 00000000-0000-0000-0000-000000000001 - global-management 331 332 AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa 333 Description: Super User 334 Local: false 335 Create Time: 2018-10-22 15:35:28.787003 -0400 EDT 336 Legacy: false 337 Policies: 338 00000000-0000-0000-0000-000000000001 - global-management 339 340 AccessorID: 00000000-0000-0000-0000-000000000002 341 Description: Anonymous Token 342 Local: false 343 Create Time: 0001-01-01 00:00:00 +0000 UTC 344 Legacy: false 345 Policies: 346 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 347 348 AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d 349 Description: WonderToken 350 Local: false 351 Create Time: 2018-10-22 15:33:39.01789 -0400 EDT 352 Legacy: false 353 Policies: 354 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read 355 ```