consul/website/source/docs/commands/acl/acl-policy.html.md.erb

---
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 <subcommand> [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=<string>` - A description of the policy.

* `-from-token=<string>` - 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=<string>` - The new policy's name. This flag is required.

* `-rules=<string>` - 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=<value>` - 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=<string>` - 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=<string>` - 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=<string>` - A description of the policy.

* `-id=<string>` - 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=<string>` - 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=<string>` - 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=<value>` - 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=<string>` - 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=<string>` - 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
```