mirror of https://github.com/hashicorp/consul
433 lines
12 KiB
Plaintext
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
|
|
``` |