2021-06-09 22:08:45 +00:00
---
layout: docs
2022-09-09 19:57:15 +00:00
page_title: Enterprise Licenses
description: >-
2022-09-16 15:28:32 +00:00
Consul Enterprise server, client, and snapshot agents require a license on startup in order to use Enterprise features. Learn how to apply licenses using environment variables or configuration files.
2021-06-09 22:08:45 +00:00
---
# Consul Enterprise License
2022-07-22 21:45:53 +00:00
## Licensing Overview
2021-06-09 22:08:45 +00:00
All Consul Enterprise agents must be licensed when they are started. Where that license comes from will depend
2022-07-22 21:45:53 +00:00
on which binary is in use, whether the agent is a server, client or snapshot agent, and whether ACLs have been
2021-06-09 22:08:45 +00:00
enabled for the cluster.
2022-07-22 21:45:53 +00:00
-> ** Consul Enterprise 1.10.0 removed temporary licensing.** Prior to 1.10.0, Consul Enterprise
2021-06-09 22:08:45 +00:00
agents could start without a license and then have a license applied to them later on via the CLI
or API. That functionality has been removed and replaced with the ability to load licenses from the
2022-07-22 21:45:53 +00:00
agent's configuration or environment. Also, prior to 1.10.0, server agents would automatically propagate
the license between themselves. This no longer occurs and the license must be present on each server agent
when it is started.
2021-06-09 22:08:45 +00:00
2022-09-06 15:35:01 +00:00
-> Visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/consul/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key.
2021-06-11 17:46:14 +00:00
2022-07-22 21:45:53 +00:00
### Applying a License
2021-06-09 22:08:45 +00:00
2022-07-22 21:45:53 +00:00
For Consul Enterprise 1.10.0 or greater, a license must be available at the time the agent starts.
2022-01-11 01:30:50 +00:00
For server agents this means that they must either have the [`license_path`](/docs/agent/config/config-files#license_path)
2021-06-09 22:08:45 +00:00
configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or
`CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH`
environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment
2022-07-22 21:45:53 +00:00
variable should contain the license as the value. If multiple variables are set,
the following order of precedence applies:
2021-06-09 22:08:45 +00:00
1. `CONSUL_LICENSE` environment variable
2. `CONSUL_LICENSE_PATH` environment variable
3. `license_path` configuration item.
2022-07-22 21:45:53 +00:00
Client agents and [snapshot agents](/docs/enterprise/backups)
may also be licensed in the very same manner.
However, to avoid the need to configure the license on many client agents and snapshot agents,
those agents have the capability to retrieve the license automatically under the conditions described below.
2021-06-09 22:08:45 +00:00
2022-09-07 01:39:07 +00:00
Updating the license for an agent depends on the method you used to apply the license.
- **If you used the `CONSUL_LICENSE`
environment variable**: After updating the environment variable, restart the affected agents.
- **If you used the
`CONSUL_LICENSE_PATH` environment variable**: Update the license file first. Then, restart the affected agents.
- **If you used the `license_path` configuration item**: Update the license file first. Then, run [`consul reload`](/commands/reload) for the affected agents.
2021-06-09 22:08:45 +00:00
#### Client Agent License Retrieval
When a client agent starts without a license in its configuration or environment, it will try to retrieve the
license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the
request but the token doesn't need any particular permissions. As the license is required before the client
2022-01-11 01:30:50 +00:00
actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/config/config-files#start_join)
or [`retry_join`](/docs/agent/config/config-files#retry_join) configurations. If those are both unset or no
[`agent` token](/docs/agent/config/config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down.
2021-06-11 17:46:14 +00:00
2021-06-09 22:08:45 +00:00
If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to
request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a
license within that time frame it will shut itself down.
2021-06-11 17:46:14 +00:00
If ACLs are disabled then the license must be provided to the client agent through one of the three methods listed below.
Failure in providing the client agent with a licence will prevent the client agent from joining the cluster.
1. `CONSUL_LICENSE` environment variable
2. `CONSUL_LICENSE_PATH` environment variable
3. `license_path` configuration item.
2021-06-09 22:08:45 +00:00
#### Snapshot Agent License Retrieval
The snapshot agent has similar functionality to the client agent for automatically retrieving the license. However,
instead of requiring a server agent to talk to, the snapshot agent can request the license from the server or
client agent it would use for all other operations. It still requires an ACL token to authorize the request. Also
like client agents, the snapshot agent will shut itself down after being unable to retrieve the license for 5
minutes.
