mirror of https://github.com/hashicorp/consul
66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Create tokens for service registration
|
|
description: >-
|
|
Learn how to create ACL tokens to enable Consul DNS.
|
|
---
|
|
|
|
# Create a DNS token
|
|
|
|
This topic describes how to create a token that enables the Consul DNS to query services in the network when ACLs are enabled.
|
|
|
|
## Introduction
|
|
|
|
The Consul binary ships with a DNS server that you can use for service discovery in your network. The agent that fulfills DNS lookups requires appropriate ACL permissions to discover services, nodes, and prepared queries registered in Consul.
|
|
|
|
A Consul agent must be configured with a token linked to policies that grant the appropriate set of permissions.
|
|
|
|
Specify the [`default`](/consul/docs/agent/config/config-files#acl_tokens_default) token to the Consul agent to authorize the agent to respond to DNS queries. Refer to [DNS usage overview](/consul/docs/services/discovery/dns-overview) for details on configuring and using Consul DNS.
|
|
|
|
## Requirements
|
|
|
|
Core ACL functionality is available in all versions of Consul.
|
|
|
|
The DNS token must be linked to policies that grant the following permissions:
|
|
|
|
* `service:read`: Enables the agent to perform service lookups for DNS
|
|
* `node:read`: Enables node lookups over DNS
|
|
* `query:read`: Enables the agent to perform prepared query lookups for DNS
|
|
|
|
@include 'create-token-requirements.mdx'
|
|
|
|
## Create a DNS token
|
|
|
|
Run the `consul acl token create` CLI command and specify the `builtin/dns` templated policy to create a DNS token.
|
|
|
|
```shell-session
|
|
$ consul acl token create -name "dns-token" -templated-policy "builtin/dns"
|
|
```
|
|
|
|
## Apply the token
|
|
|
|
Configure the Consul agent with the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command.
|
|
|
|
### Apply the token in a file
|
|
|
|
Specify the token in the [`dns`](/consul/docs/agent/config/config-files#acl_tokens_dns) field of the agent configuration file so that the agent can present it and register into the catalog on startup.
|
|
|
|
```hcl
|
|
acl = {
|
|
enabled = true
|
|
tokens = {
|
|
dns = "<token>"
|
|
...
|
|
}
|
|
...
|
|
}
|
|
```
|
|
|
|
### Apply the token with a command
|
|
|
|
Set the `dns` token using the [`acl.token.dns`](/consul/docs/agent/config/config-files#acl_tokens_dns) command. The following command configures a running Consul agent token with the specified token.
|
|
|
|
```shell-session
|
|
$ consul set-agent-token dns <acl-token-secret-id>
|
|
```
|