The information contained in this article has been verified as up-to-date on the date of the original publication of the article. HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.
All information contained in this article is for general information purposes only. Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.
Introduction
The ACL bootstrap token, also known as the initial management token or master token, is a powerful key, generated when you first establish your Consul access control system and it is shared with all of the Consul servers. Think of it as a master key granting unrestricted access to your Consul datacenter. Because this token has such broad privileges, it requires the utmost security.
We strongly recommend storing the bootstrap token in HashiCorp Vault to ensure this security. Vault provides a centralized and secure location for managing secrets, including this all-important token. You can find detailed instructions on how to do this in the HashiCorp developer documentation: Storing the ACL Bootstrap Token in Vault.
While the bootstrap token is typically created during the initial ACL setup, you can generate other tokens with unrestricted privileges if needed. However, remember that these tokens require careful handling and secure storage.
Expected Outcome
This document provides a methodology for identifying Consul bootstrap tokens within an existing ACL token set. This is particularly useful in situations where administrators need to verify the presence or absence of a bootstrap token without prior knowledge of its specific value.
Use Case
Administrators may need to identify tokens with global management privileges within their Consul deployment. This could involve:
- Discovering all global management tokens: Finding all tokens that have been granted unrestricted access to the Consul datacenter.
- Verifying a specific token's privileges: Confirming whether a given token has been assigned the global management policy and possesses the associated permissions.
Procedure
NOTE: When the token is generated through the consul acl bootstrap command, the token description is clearly labeled "Bootstrap Token (Global Management)" for easy identification.
| Find the Global Management tokens |
| Find the details of a token by AccessorID |
Find the Global Management tokens
The commands will output the SecretID. The initial management token, which has the global-management policy, functions as the bootstrap token. Note that the "Initial Management Token" description might be renamed. The SecretID value is an authentication token and should be secured accordingly.
- These commands will output all of the global-management tokens:
consul acl token list -token <token_with_acl_token_write_privileges_here> -format json | jq '.[] | select(.Policies)| select(.Policies[] | .Name=="global-management")'
Example output
{
"CreateIndex": 6,
"ModifyIndex": 6,
"AccessorID": "bca6fcab-6aae-1ce6-138a-4e155937901f",
"SecretID": "<bootstrap_token>",
"Description": "Initial Management Token",
"Policies": [
{
"ID": "00000000-0000-0000-0000-000000000001",
"Name": "global-management"
}
],
"Local": false,
"CreateTime": "2024-11-14T23:06:42.206168299Z",
"Hash": "a5y108eB8xI19PvumK2BeZG3u+asdlkjSADLKJD=",
"Namespace": "default",
"Partition": "default"
}
OR
consul acl token list -token <token_with_acl_token_write_privileges_here> | grep -B 8 global-management
Example output
AccessorID: bca6fcab-6aae-1ce6-138a-4e155937901f
SecretID: <bootstrap_token>
Partition: default
Namespace: default
Description: Initial Management Token
Local: false
Create Time: 2024-11-14 23:06:42.206168299 +0000 UTC
Policies:
00000000-0000-0000-0000-000000000001 - global-management
Find the details of a token by AccessorID
Useful to determine which policy a specific token has applied to it
- This command will lookup a specific token by its AccessorID if you want to see which policy is applied to it (the output of these will be similar to the above examples)
consul acl token list -token <token_with_acl_token_write_privileges_here> -format json | jq '.[] | select(.AccessorID=="<token_AccessorID_here>")
OR
consul acl token list -token <token_with_acl_token_write_privileges_here> | grep -A 8 <token_AccessorID_here>
Additional Information
| Resetting the ACL system |
| Rotate/Replace the Initial management token |
| Create an additional token with the global management policy |
Resetting the ACL system
If you encounter issues that are unresolvable, or misplace the bootstrap token, you can reset the ACL system by updating the index.
NOTE: ACL reset must be performed on the leader.
- Determine which server is the the leader and log into it
- Re-run the
consul acl bootstrapcommand on the leader to get the index number.
NOTE: If you don't receive an error message like below, but instead it gives an output with the token, that means the system wasn't bootstrapped
- Example output of a bootstrapped system
Failed ACL bootstrapping: Unexpected response code: 403 (Permission denied: ACL bootstrap no longer allowed (reset index: 13))
- Example output of a bootstrapped system
- Write the reset index into the bootstrap reset file: (in our example the reset index is 13)
$ echo 13 >> <data-directory>/acl-bootstrap-reset - After resetting the ACL system, you can initialize it again and recreate the bootstrap token.
Rotate/Replace the Initial management token
Create an additional token with the global management policy
NOTE: You need a token that can manage ACLs prior to creating a new token.
- The below command will create a new token with the global-management policy attached to it.
$ consul acl token create -policy-name=global-management -token <token_with_acl_token_write_privileges_here>