» 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.

ACL policies are also accessible via the HTTP API.

Usage: consul acl policy <subcommand> [options] [args]

» 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:

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

» 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.

» Usage

Usage: consul acl policy create [options] [args]

» 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 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:

$ 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:

$ 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:

$ 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

  • -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:

$ 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:

$ 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.

$ 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

  • -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:

$ 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:

$ 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

» Examples

Delete a policy:

$ consul acl policy delete -id 35b8
Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully

Delete a policy by name:

$ 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

» Examples

Default listing.

$ 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.

$ 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