consul/website/content/docs/security/acl/tokens/create/create-a-dns-token.mdx

66 lines
2.3 KiB
Plaintext

---
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>
```