» Consul ACL Tokens

Command: consul acl token

The acl token command is used to manage Consul's ACL tokens. There are subcommands for the individual operations that can be performed.

ACL tokens are also accessible via the HTTP API.

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

» Identitying Tokens

In several of the subcommands a token will have to be identified to be read, modified or deleted. Those subcommands support specifying the token by its ID using the -id parameter. The ID may be specified as a unique UUID prefix instead of the entire UUID. As long as it is unique it will be resolve to the full UUID and used. Additionally builtin token names will be accepted as the value of the -id.

Builtin Policies:

Token UUID Token Name
00000000-0000-0000-0000-000000000002 anonymous

» Common Subcommand Options

All of the consul acl token 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 token create

This command creates new tokens. When creating a new token, policies may be linked using either the -policy-id or the `-policy-name options. When specifying policies by IDs you may use a unique prefix of the UUID as a shortcut for specifying the entire UUID.

» Usage

» Options

» Examples

Create a new token:

$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965
AccessorID:   986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID:     ec15675e-2999-d789-832e-8c4794daa8d7
Description:  Read Nodes and Services
Local:        false
Create Time:  2018-10-22 15:33:39.01789 -0400 EDT
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read

Create a new local token:

$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local
AccessorID:   4fdf0ec8-d251-3865-079c-7247c974fc50
SecretID:     02143514-abf2-6c23-0aa1-ec2107e68f6b
Description:  Read Nodes and Services
Local:        true
Create Time:  2018-10-22 15:34:19.330265 -0400 EDT
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read

Create a new policy and link with policies by name:

$ consul acl token create -description "Super User" -policy-name global-management
AccessorID:   59f86a9b-d3b6-166c-32a0-be4ab3f94caa
SecretID:     ada7f751-f654-8872-7f93-498e799158b6
Description:  Super User
Local:        false
Create Time:  2018-10-22 15:35:28.787003 -0400 EDT
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

» clone

Command: consul acl token clone

This command clones an existing token.

» Usage

Usage: `consul acl token clone [options]

» Options

  • Common Subcommand Options

  • -description=<string> - A description of the new cloned token.

  • -id=<string> - The Accessor ID of the token to clone. It may be specified as a unique ID prefix but will error if the prefix matches multiple token Accessor IDs. The special value of 'anonymous' may be provided instead of the anonymous tokens accessor ID

» Examples

Clone a token:

$ consul acl token clone -id 59f8 -description "Clone of Super User"
Token cloned successfully.
AccessorID:   dcfa52ed-9288-b3ff-056d-255ef69d2d88
SecretID:     0005d17e-5bb2-7e8b-7bfa-15f2eee9ad14
Description:  Clone of Super User
Local:        false
Create Time:  2018-10-22 16:26:02.909096 -0400 EDT
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

» read

Command: consul acl token read

This command reads and displays a token details.

» Usage

Usage: consul acl token 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.

  • -self - Indicates that the current HTTP token should be read by secret ID instead of expecting a -id option.

» Examples

Get token details:

$ consul acl token read -id 986
AccessorID:   986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID:     ec15675e-2999-d789-832e-8c4794daa8d7
Description:  Read Nodes and Services
Local:        false
Create Time:  2018-10-22 15:33:39.01789 -0400 EDT
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read

Get token details using the token secret ID:

$consul acl token read -self
AccessorID:   4d123dff-f460-73c3-02c4-8dd64d136e01
SecretID:     86cddfb9-2760-d947-358d-a2811156bf31
Description:  Bootstrap Token (Global Management)
Local:        false
Create Time:  2018-10-22 11:27:04.479026 -0400 EDT
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

Get token details (Builtin Tokens)

$ consul acl token read -id anonymous
AccessorID:   00000000-0000-0000-0000-000000000002
SecretID:     anonymous
Description:  Anonymous Token
Local:        false
Create Time:  0001-01-01 00:00:00 +0000 UTC
Policies:

» update

Command: consul acl token update

This command will update a token. Some parts of the token like whether the token is local to the datacenter cannot be changed.

» Usage

Usage: consul acl token update [options]

» Options

  • Common Subcommand Options

  • -description=<string> - A description of the token

  • -id=<string> - The Accessor ID of the token to read. It may be specified as a unique ID prefix but will error if the prefix matches multiple token Accessor IDs

  • -merge-policies - Merge the new policies with the existing policies

  • -meta - Indicates that token metadata such as the content hash and Raft indices should be shown for each entry.

  • -policy-id=<value> - ID of a policy to use for this token. May be specified multiple times.

  • -policy-name=<value> - Name of a policy to use for this token. May be specified multiple times.

» Examples

Update the anonymous token:

$ consul acl token update -id anonymous -policy-id 06acc
Token updated successfully.
AccessorID:   00000000-0000-0000-0000-000000000002
SecretID:     anonymous
Description:  Anonymous Token
Local:        false
Create Time:  0001-01-01 00:00:00 +0000 UTC
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read

Update a token description and take the policies from the existing token:

$ consul acl token update -id 986193 -description "WonderToken" -merge-policies
Token updated successfully.
AccessorID:   986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID:     ec15675e-2999-d789-832e-8c4794daa8d7
Description:  WonderToken
Local:        false
Create Time:  2018-10-22 15:33:39.01789 -0400 EDT
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read

» delete

Command: consul acl token delete

This command deletes a token.

» Usage

Usage: consul acl token delete [options]

» Options

» Examples

Delete a token:

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

» list

Command: consul acl token list

This command lists all tokens. By default it will not show metadata.

» Usage

Usage: consul acl token list

» Options

» Examples

Default listing.

$ consul acl token list
AccessorID:   4d123dff-f460-73c3-02c4-8dd64d136e01
Description:  Bootstrap Token (Global Management)
Local:        false
Create Time:  2018-10-22 11:27:04.479026 -0400 EDT
Legacy:       false
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

AccessorID:   59f86a9b-d3b6-166c-32a0-be4ab3f94caa
Description:  Super User
Local:        false
Create Time:  2018-10-22 15:35:28.787003 -0400 EDT
Legacy:       false
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

AccessorID:   00000000-0000-0000-0000-000000000002
Description:  Anonymous Token
Local:        false
Create Time:  0001-01-01 00:00:00 +0000 UTC
Legacy:       false
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read

AccessorID:   986193b5-e2b5-eb26-6264-b524ea60cc6d
Description:  WonderToken
Local:        false
Create Time:  2018-10-22 15:33:39.01789 -0400 EDT
Legacy:       false
Policies:
   06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read