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

433 lines
12 KiB
Plaintext

---
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.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.
## Identitying Polices
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 show for each entry.
* `-name=<string>` - The new policies 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 show 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 show 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
```