--- layout: "docs" page_title: "Commands: ACL Policy Management" sidebar_current: "docs-commands-acl-policy" --- # Consul ACL Policies Command: `consul acl policy` The `acl policy` command is used to manage Consul's ACL policies. There are subcommands for the individual operations that can be performed. * [`create`](#create) * [`read`](#read) * [`update`](#update) * [`delete`](#delete) * [`list`](#list) ACL policies are also accessible via the [HTTP API](/api/acl/acl.html). Usage: `consul acl policy [options] [args]` -> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions. Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token` parameter. ## Identifying Policies In several of the subcommands a policy will have to be identified to be read, modified or deleted. Those subcommands support specifying the policy by its ID using the `-id` parameter or by name using the `-name` parameter. When specifying the policy 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 to the full UUID and used. Additionally builtin policy names will be accepted as the value to the `-id` parameter. Even if the builtin policies are renamed their original name can be used to operate on them. Builtin Policies: | Policy UUID | Policy Name | | ------------------------------------ | ----------------- | | 00000000-0000-0000-0000-000000000001 | global-management | ## Common Subcommand Options All of the `consul acl policy` subcommands support the following options: <%= partial "docs/commands/http_api_options_client" %> <%= partial "docs/commands/http_api_options_server" %> ## `create` Command: `consul acl policy create` This command creates new policies. The policies rules can either be set explicitly or the `-from-token` parameter may be used to load the rules from a legacy ACL token. When loading the rules from an existing legacy ACL token, the rules get translated from the legacy syntax to the new syntax. Both the `-rules` and `-from-token` parameter values allow loading the value from stdin, a file or the raw value. To use stdin pass `-` as the value. To load the value from a file prefix the value with an `@`. Any other values will be used directly. -> **Deprecated:** The `-from-token` and `-token-secret` arguments exist only as a convenience to make legacy ACL migration easier. These will be removed in a future major release when support for the legacy ACL system is removed. ### Usage Usage: `consul acl policy create [options] [args]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-description=` - A description of the policy. * `-from-token=` - The legacy token to retrieve the rules for when creating this policy. When this is specified no other rules should be given. Similar to the -rules option the token to use can be loaded from stdin or from a file. * `-meta` - Indicates that policy metadata such as the content hash and raft indices should be shown for each entry. * `-name=` - The new policy's name. This flag is required. * `-rules=` - The policy rules. May be prefixed with '@' to indicate that the value is a file path to load the rules from. '-' may also be given to indicate that the rules are available on stdin. * `-token-secret` - Indicates the token provided with -from-token is a SecretID and not an AccessorID. * `-valid-datacenter=` - Datacenter that the policy should be valid within. This flag may be specified multiple times. ### Examples Create a new policy that is valid in all datacenters: ```sh $ consul acl policy create -name "acl-replication" -description "Policy capable of replicating ACL policies" -rules 'acl = "read"' ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 Name: acl-replication Description: Policy capable of replicating ACL policies Datacenters: Rules: acl = "read" ``` Create a new policy valid only in specific datacenters with rules read from a file: ```sh $ consul acl policy create -name "replication" -description "Replication" -rules @rules.hcl -valid-datacenter dc1 -valid-datacenter dc2 ID: ca44555b-a2d8-94de-d763-88caffdaf11f Name: replication Description: Replication Datacenters: dc1, dc2 Rules: acl = "read" service_prefix "" { policy = "read" intentions = "read" } ``` Create a new policy with rules equivalent to that of a legacy ACL token: ```sh $ consul acl policy create -name "node-services-read" -from-token 5793a5ce -description "Can read any node and service" ID: 06acc965-df4b-5a99-58cb-3250930c6324 Name: node-services-read Description: Can read any node and service Datacenters: Rules: service_prefix "" { policy = "read" } node_prefix "" { policy = "read" } ``` ## `read` Command: `consul acl policy read` This command reads and displays a policies details. ### Usage Usage: `consul acl policy read [options] [args]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-id=` - The ID of the policy to read. It may be specified as a unique ID prefix but will error if the prefix matches multiple policy IDs. * `-meta` - Indicates that policy metadata such as the content hash and raft indices should be shown for each entry. * `-name=` - The name of the policy to read. ### Examples Get policy details: ```sh $ consul acl policy read -id 00000000-0000-0000-0000-000000000001 ID: 00000000-0000-0000-0000-000000000001 Name: global-management Description: Builtin Policy that grants unlimited access Datacenters: Rules: acl = "write" agent_prefix "" { policy = "write" } event_prefix "" { policy = "write" } key_prefix "" { policy = "write" } keyring = "write" node_prefix "" { policy = "write" } operator = "write" query_prefix "" { policy = "write" } service_prefix "" { policy = "write" intentions = "write" } session_prefix "" { policy = "write" } ``` Get policy details by name: ```sh $ consul acl policy read -name "acl-replication" ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 Name: acl-replication Description: Token capable of replicating ACL policies Datacenters: Rules: acl = "read" ``` Get policy details (Builtin Policies): Builtin policies can be accessed by specifying their original name as the value to the `-id` parameter. ```sh $ consul acl policy read -id global-management ID: 00000000-0000-0000-0000-000000000001 Name: global-management Description: Builtin Policy that grants unlimited access Datacenters: Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69 Create Index: 4 Modify Index: 4 Rules: acl = "write" agent_prefix "" { policy = "write" } event_prefix "" { policy = "write" } key_prefix "" { policy = "write" } keyring = "write" node_prefix "" { policy = "write" } operator = "write" query_prefix "" { policy = "write" } service_prefix "" { policy = "write" intentions = "write" } session_prefix "" { policy = "write" } ``` ## `update` Command: `consul acl policy update` This command is used to update a policy. The default operations is to merge the current policy with those values provided to the command invocation. Therefore to update just one field, only the `-id` or `-name` options and the option to modify must be provided. Note that renaming policies requires both the `-id` and `-name` as the new name cannot yet be used to lookup the policy. ### Usage Usage: `consul acl policy update [options] [args]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-description=` - A description of the policy. * `-id=` - The ID of the policy to update. It may be specified as a unique ID prefix but will error if the prefix matches multiple policy IDs * `-meta` - Indicates that policy metadata such as the content hash and raft indices should be shown for each entry * `-name=` - The policies name. * `-no-merge` - Do not merge the current policy information with what is provided to the command. Instead overwrite all fields with the exception of the policy ID which is immutable. * `-rules=` - The policy rules. May be prefixed with `@` to indicate that the value is a file path to load the rules from. `-` may also be given to indicate that the rules are available on stdin. * `-valid-datacenter=` - Datacenter that the policy should be valid within. This flag may be specified multiple times. ### Examples Update a policy: ```sh $ consul acl policy update -id 35b8 -name "replication" -description "Policy capable of replication ACL policies and Intentions" -rules @rules.hcl Policy updated successfully ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 Name: replication Description: Policy capable of replication ACL policies and Intentions Datacenters: Rules: acl = "read" service_prefix "" { policy = "read" intentions = "read" } ``` Rename a policy: ```sh $ consul acl policy update -id 35b8 -name "dc1-replication" Policy updated successfully ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 Name: dc1-replication Description: Policy capable of replication ACL policies and Intentions Datacenters: dc1 Rules: acl = "read" service_prefix "" { policy = "read" intentions = "read" } ``` ## `delete` Command: `consul acl policy delete` This command deletes a policy. Policies may be deleted by their ID or by name. ### Usage Usage: `consul acl policy delete [options]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-id=` - The ID of the policy to delete. It may be specified as a unique ID prefix but will error if the prefix matches multiple policy IDs. * `-name=` - The Name of the policy to delete. ### Examples Delete a policy: ```sh $ consul acl policy delete -id 35b8 Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully ``` Delete a policy by name: ```sh $ consul acl policy delete -name acl-replication Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully ``` ## `list` Command: `consul acl policy list` This command lists all policies. By default it will not show metadata. ### Usage Usage: `consul acl policy list` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-meta` - Indicates that policy metadata such as the content hash and Raft indices should be shown for each entry. ### Examples Default listing. ```sh $ consul acl policy list global-management: ID: 00000000-0000-0000-0000-000000000001 Description: Builtin Policy that grants unlimited access Datacenters: acl-replication: ID: 35b8ecb0-707c-ee18-2002-81b238b54b38 Description: Policy capable of replicating ACL policies Datacenters: ``` Show Metadata. ```sh $ consul acl policy list -meta global-management: ID: 00000000-0000-0000-0000-000000000001 Description: Builtin Policy that grants unlimited access Datacenters: Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69 Create Index: 4 Modify Index: 4 node-services-read: ID: 06acc965-df4b-5a99-58cb-3250930c6324 Description: Can read any node and service Datacenters: Hash: 19d2a73dcd315506af73bfff1492779a0dc0235066fcac07f432fb2cc3402133 Create Index: 244 Modify Index: 244 acl-replication: ID: ca44555b-a2d8-94de-d763-88caffdaf11f Description: Token capable of replicating ACL policies Datacenters: dc1, dc2 Hash: b94669679cc24e0d064412e4aa90b470b7f900a8e0801f65feaf1f7d716a5390 Create Index: 198 Modify Index: 198 ```