github.com/KyaXTeam/consul@v1.4.5/website/source/docs/commands/acl/acl-policy.html.md.erb (about) 1 --- 2 layout: "docs" 3 page_title: "Commands: ACL Policy Management" 4 sidebar_current: "docs-commands-acl-policy" 5 --- 6 7 # Consul ACL Policies 8 9 Command: `consul acl policy` 10 11 The `acl policy` command is used to manage Consul's ACL policies. There are 12 subcommands for the individual operations that can be performed. 13 14 * [`create`](#create) 15 * [`read`](#read) 16 * [`update`](#update) 17 * [`delete`](#delete) 18 * [`list`](#list) 19 20 ACL policies are also accessible via the [HTTP API](/api/acl/acl.html). 21 22 Usage: `consul acl policy <subcommand> [options] [args]` 23 24 -> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions. 25 Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token` 26 parameter. 27 28 ## Identitying Polices 29 30 In several of the subcommands a policy will have to be identified to be read, modified or deleted. Those subcommands support 31 specifying the policy by its ID using the `-id` parameter or by name using the `-name` parameter. When specifying the policy 32 by its ID a unique policy ID prefix may be specified instead of the entire UUID. As long as it is unique it will be resolved 33 to the full UUID and used. Additionally builtin policy names will be accepted as the value to the `-id` parameter. Even if 34 the builtin policies are renamed their original name can be used to operate on them. 35 36 Builtin Policies: 37 38 | Policy UUID | Policy Name | 39 | ------------------------------------ | ----------------- | 40 | 00000000-0000-0000-0000-000000000001 | global-management | 41 42 ## Common Subcommand Options 43 44 All of the `consul acl policy` 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 policy create` 52 53 This command creates new policies. The policies rules can either be set explicitly or the 54 `-from-token` parameter may be used to load the rules from a legacy ACL token. When loading 55 the rules from an existing legacy ACL token, the rules get translated from the legacy syntax 56 to the new syntax. 57 58 Both the `-rules` and `-from-token` parameter values allow loading the value 59 from stdin, a file or the raw value. To use stdin pass `-` as the value. 60 To load the value from a file prefix the value with an `@`. Any other 61 values will be used directly. 62 63 -> **Deprecated:** The `-from-token` and `-token-secret` arguments exist only as a convenience 64 to make legacy ACL migration easier. These will be removed in a future major release when 65 support for the legacy ACL system is removed. 66 67 ### Usage 68 69 Usage: `consul acl policy create [options] [args]` 70 71 #### Options 72 73 * [Common Subcommand Options](#common-subcommand-options) 74 75 * `-description=<string>` - A description of the policy. 76 77 * `-from-token=<string>` - The legacy token to retrieve the rules for when creating this 78 policy. When this is specified no other rules should be given. 79 Similar to the -rules option the token to use can be loaded from 80 stdin or from a file. 81 82 * `-meta` - Indicates that policy metadata such as the content hash and raft 83 indices should be shown for each entry. 84 85 * `-name=<string>` - The new policy's name. This flag is required. 86 87 * `-rules=<string>` - The policy rules. May be prefixed with '@' to indicate that the 88 value is a file path to load the rules from. '-' may also be given 89 to indicate that the rules are available on stdin. 90 91 * `-token-secret` - Indicates the token provided with -from-token is a SecretID and not 92 an AccessorID. 93 94 * `-valid-datacenter=<value>` - Datacenter that the policy should be valid within. 95 This flag may be specified multiple times. 96 97 98 ### Examples 99 100 Create a new policy that is valid in all datacenters: 101 102 ```sh 103 $ consul acl policy create -name "acl-replication" -description "Policy capable of replicating ACL policies" -rules 'acl = "read"' 104 ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 105 Name: acl-replication 106 Description: Policy capable of replicating ACL policies 107 Datacenters: 108 Rules: 109 acl = "read" 110 ``` 111 112 Create a new policy valid only in specific datacenters with rules read from a file: 113 114 ```sh 115 $ consul acl policy create -name "replication" -description "Replication" -rules @rules.hcl -valid-datacenter dc1 -valid-datacenter dc2 116 ID: ca44555b-a2d8-94de-d763-88caffdaf11f 117 Name: replication 118 Description: Replication 119 Datacenters: dc1, dc2 120 Rules: 121 acl = "read" 122 service_prefix "" { 123 policy = "read" 124 intentions = "read" 125 } 126 ``` 127 128 Create a new policy with rules equivalent to that of a legacy ACL token: 129 130 ```sh 131 $ consul acl policy create -name "node-services-read" -from-token 5793a5ce -description "Can read any node and service" 132 ID: 06acc965-df4b-5a99-58cb-3250930c6324 133 Name: node-services-read 134 Description: Can read any node and service 135 Datacenters: 136 Rules: 137 service_prefix "" { 138 policy = "read" 139 } 140 141 node_prefix "" { 142 policy = "read" 143 } 144 145 ``` 146 147 ## `read` 148 149 Command: `consul acl policy read` 150 151 This command reads and displays a policies details. 152 153 ### Usage 154 155 Usage: `consul acl policy read [options] [args]` 156 157 #### Options 158 159 * [Common Subcommand Options](#common-subcommand-options) 160 161 * `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID 162 prefix but will error if the prefix matches multiple policy IDs. 163 164 * `-meta` - Indicates that policy metadata such as the content hash and raft 165 indices should be shown for each entry. 166 167 * `-name=<string>` - The name of the policy to read. 168 169 ### Examples 170 171 Get policy details: 172 173 ```sh 174 $ consul acl policy read -id 00000000-0000-0000-0000-000000000001 175 ID: 00000000-0000-0000-0000-000000000001 176 Name: global-management 177 Description: Builtin Policy that grants unlimited access 178 Datacenters: 179 Rules: 180 181 acl = "write" 182 agent_prefix "" { 183 policy = "write" 184 } 185 event_prefix "" { 186 policy = "write" 187 } 188 key_prefix "" { 189 policy = "write" 190 } 191 keyring = "write" 192 node_prefix "" { 193 policy = "write" 194 } 195 operator = "write" 196 query_prefix "" { 197 policy = "write" 198 } 199 service_prefix "" { 200 policy = "write" 201 intentions = "write" 202 } 203 session_prefix "" { 204 policy = "write" 205 } 206 ``` 207 208 Get policy details by name: 209 210 ```sh 211 $ consul acl policy read -name "acl-replication" 212 ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 213 Name: acl-replication 214 Description: Token capable of replicating ACL policies 215 Datacenters: 216 Rules: 217 acl = "read" 218 ``` 219 220 Get policy details (Builtin Policies): 221 222 Builtin policies can be accessed by specifying their original name as the value to the `-id` parameter. 223 224 ```sh 225 $ consul acl policy read -id global-management 226 ID: 00000000-0000-0000-0000-000000000001 227 Name: global-management 228 Description: Builtin Policy that grants unlimited access 229 Datacenters: 230 Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69 231 Create Index: 4 232 Modify Index: 4 233 Rules: 234 235 acl = "write" 236 agent_prefix "" { 237 policy = "write" 238 } 239 event_prefix "" { 240 policy = "write" 241 } 242 key_prefix "" { 243 policy = "write" 244 } 245 keyring = "write" 246 node_prefix "" { 247 policy = "write" 248 } 249 operator = "write" 250 query_prefix "" { 251 policy = "write" 252 } 253 service_prefix "" { 254 policy = "write" 255 intentions = "write" 256 } 257 session_prefix "" { 258 policy = "write" 259 } 260 ``` 261 262 ## `update` 263 264 Command: `consul acl policy update` 265 266 This command is used to update a policy. The default operations is to merge the current policy 267 with those values provided to the command invocation. Therefore to update just one field, only 268 the `-id` or `-name` options and the option to modify must be provided. Note that renaming 269 policies requires both the `-id` and `-name` as the new name cannot yet be used to lookup the 270 policy. 271 272 ### Usage 273 274 Usage: `consul acl policy update [options] [args]` 275 276 #### Options 277 278 * [Common Subcommand Options](#common-subcommand-options) 279 280 * `-description=<string>` - A description of the policy. 281 282 * `-id=<string>` - The ID of the policy to update. It may be specified as a 283 unique ID prefix but will error if the prefix matches multiple policy IDs 284 285 * `-meta` - Indicates that policy metadata such as the content hash and raft 286 indices should be shown for each entry 287 288 * `-name=<string>` - The policies name. 289 290 * `-no-merge` - Do not merge the current policy information with what is provided 291 to the command. Instead overwrite all fields with the exception of 292 the policy ID which is immutable. 293 294 * `-rules=<string>` - The policy rules. May be prefixed with `@` to indicate that 295 the value is a file path to load the rules from. `-` may also be given to 296 indicate that the rules are available on stdin. 297 298 * `-valid-datacenter=<value>` - Datacenter that the policy should be valid within. 299 This flag may be specified multiple times. 300 301 ### Examples 302 303 Update a policy: 304 305 ```sh 306 $ consul acl policy update -id 35b8 -name "replication" -description "Policy capable of replication ACL policies and Intentions" -rules @rules.hcl 307 Policy updated successfully 308 ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 309 Name: replication 310 Description: Policy capable of replication ACL policies and Intentions 311 Datacenters: 312 Rules: 313 acl = "read" 314 315 service_prefix "" { 316 policy = "read" 317 intentions = "read" 318 } 319 ``` 320 321 Rename a policy: 322 323 ```sh 324 $ consul acl policy update -id 35b8 -name "dc1-replication" 325 Policy updated successfully 326 ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 327 Name: dc1-replication 328 Description: Policy capable of replication ACL policies and Intentions 329 Datacenters: dc1 330 Rules: 331 acl = "read" 332 333 service_prefix "" { 334 policy = "read" 335 intentions = "read" 336 } 337 338 ``` 339 340 ## `delete` 341 342 Command: `consul acl policy delete` 343 344 This command deletes a policy. Policies may be deleted by their ID or by name. 345 346 ### Usage 347 348 Usage: `consul acl policy delete [options]` 349 350 #### Options 351 352 * [Common Subcommand Options](#common-subcommand-options) 353 354 * `-id=<string>` - The ID of the policy to delete. It may be specified as a 355 unique ID prefix but will error if the prefix matches multiple policy IDs. 356 357 * `-name=<string>` - The Name of the policy to delete. 358 359 ### Examples 360 361 Delete a policy: 362 363 ```sh 364 $ consul acl policy delete -id 35b8 365 Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully 366 ``` 367 368 Delete a policy by name: 369 370 ```sh 371 $ consul acl policy delete -name acl-replication 372 Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully 373 ``` 374 375 ## `list` 376 377 Command: `consul acl policy list` 378 379 This command lists all policies. By default it will not show metadata. 380 381 ### Usage 382 383 Usage: `consul acl policy list` 384 385 #### Options 386 387 * [Common Subcommand Options](#common-subcommand-options) 388 389 * `-meta` - Indicates that policy metadata such as the content hash and 390 Raft indices should be shown for each entry. 391 392 ### Examples 393 394 Default listing. 395 396 ```sh 397 $ consul acl policy list 398 global-management: 399 ID: 00000000-0000-0000-0000-000000000001 400 Description: Builtin Policy that grants unlimited access 401 Datacenters: 402 acl-replication: 403 ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 404 Description: Policy capable of replicating ACL policies 405 Datacenters: 406 ``` 407 408 Show Metadata. 409 410 ```sh 411 $ consul acl policy list -meta 412 global-management: 413 ID: 00000000-0000-0000-0000-000000000001 414 Description: Builtin Policy that grants unlimited access 415 Datacenters: 416 Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69 417 Create Index: 4 418 Modify Index: 4 419 node-services-read: 420 ID: 06acc965-df4b-5a99-58cb-3250930c6324 421 Description: Can read any node and service 422 Datacenters: 423 Hash: 19d2a73dcd315506af73bfff1492779a0dc0235066fcac07f432fb2cc3402133 424 Create Index: 244 425 Modify Index: 244 426 acl-replication: 427 ID: ca44555b-a2d8-94de-d763-88caffdaf11f 428 Description: Token capable of replicating ACL policies 429 Datacenters: dc1, dc2 430 Hash: b94669679cc24e0d064412e4aa90b470b7f900a8e0801f65feaf1f7d716a5390 431 Create Index: 198 432 Modify Index: 198 433 ```