mirror of https://github.com/hashicorp/consul
75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
---
|
|
layout: commands
|
|
page_title: 'Commands: ACL Set Agent Token'
|
|
description: >-
|
|
The `consul acl set-agent-token` command updates an agent's ACL tokens to introduce the agent ACL tokens for the first time or to update tokens.
|
|
---
|
|
|
|
# Consul ACL Set Agent Token
|
|
|
|
Command: `consul acl set-agent-token`
|
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/token/:type](/consul/api-docs/agent#update-acl-tokens)
|
|
|
|
This command updates the ACL tokens currently in use by the agent. It can be used to introduce
|
|
ACL tokens to the agent for the first time, or to update tokens that were initially loaded from
|
|
the agent's configuration. Tokens are not persisted unless
|
|
[`acl.enable_token_persistence`](/consul/docs/agent/config/config-files#acl_enable_token_persistence)
|
|
is `true`, so tokens will need to be updated again if that option is `false` and
|
|
the agent is restarted.
|
|
|
|
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
|
|
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
| ACL Required |
|
|
| ------------ |
|
|
| `acl:write` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul acl set-agent-token [options] token_type token_secret_id`
|
|
|
|
The token types are:
|
|
|
|
- `agent` - The token that the agent will use for internal agent operations.
|
|
If not given then the default token is used for these operations.
|
|
|
|
- `dns` - Specifies the token that agents use to request information needed to respond to DNS queries.
|
|
If the `dns` token is not set, Consul uses the `default` token by default.
|
|
Because the `default` token allows unauthenticated HTTP API access to list nodes and services, we
|
|
strongly recommend using the `dns` token. Create DNS tokens using the [templated policy](/consul/docs/security/acl/tokens/create/create-a-dns-token#create_a_dns_token) option
|
|
to ensure that the token has the permissions needed to respond to all DNS queries.
|
|
|
|
- `config_file_service_registration` - This is the token that the agent uses to
|
|
register services and checks defined in config files. This token needs to be
|
|
configured with write permissions for the services or checks being registered.
|
|
If not set, the `default` token is used. If a service or check definition
|
|
contains a `token` field, then that token is used to register that service or
|
|
check instead of the `config_file_service_registration` token.
|
|
|
|
- `replication` - This is the token that the agent uses for replication
|
|
operations. This token must be configured with read access to
|
|
all data that the agent replicates.
|
|
|
|
- `recovery` - This sets the token that allows access to the agent APIs when the ACL datacenter is unreachable.
|
|
|
|
- `default` - The default token is the token that the agent uses for
|
|
both internal agent operations and operations initiated by the HTTP
|
|
and DNS interfaces when no specific token is provided. If not set the
|
|
agent uses the anonymous token.
|
|
|
|
### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|
|
|
|
## Examples
|
|
|
|
Set the `default` token:
|
|
|
|
```shell-session
|
|
$ consul acl set-agent-token default c4d0f8df-3aba-4ab6-a7a0-35b760dc29a1
|
|
```
|