Install a HashiCorp Enterprise license

12min
|
Enterprise
Consul
Nomad
Vault
Boundary

Note

This guidance for enabling an enterprise license applies to both production and development environments.

To use a HashiCorp Enterprise product, you need a valid HashiCorp license. This tutorial will guide you on the steps to enable your enterprise license to start the server. By the end of this tutorial, you will have a server instance with enterprise features enabled. If you don't have a license, see the request a license section.

Tip

This tutorial is applicable to the following HashiCorp enterprise product versions or greater. Nomad v1.1.0, Consul v1.10.0, Vault v1.8.0, and Boundary v0.13.0.

Prerequisites

Enterprise binary

Each server needs to register the enterprise license as described below. In earlier versions of HashiCorp enterprise products, one server could distribute a license to other servers via the Raft protocol. This will no longer work since each server must be able to find a valid license during the startup process.

The tutorial below describes the most basic steps needed to register a license. You may need to design other steps to integrate this process into your build pipelines (such as building private disk images with Packer or using a configuration management system to distribute and install the enterprise binary and license file to your compute instances).

Install the enterprise binary

Install the enterprise binary before continuing with the tutorial. All HashiCorp binaries are in releases.hashicorp.com, look for a binary that has +ent in the suffix of the filename.

Review the installation tutorials for each HashiCorp product:

Request a trial license

Your customer support contact can generate a trial license for any HashiCorp enterprise product. If you are an existing HashiCorp enterprise customer, you may contact your organization's customer success manager (CSM) for information on how to get your organization's enterprise license.

Enable the license

You have three options for enabling an enterprise license.

Provide the enterprise license as a string in an environment variable.
Save the license string to a file and reference the path with an environment variable.
Save the license string in a file and specify the path to the file in the server's configuration file.

Add an environment variable (optional)

You can set the enterprise license for Consul by using an environment variable. Use the enterprise license you received in the previous step and set the environment variable CONSUL_LICENSE to the license key value.

$ export CONSUL_LICENSE=02MV4UU43BK5....

You can set the enterprise license for Nomad by using an environment variable. The environment variable name is NOMAD_LICENSE.

Use the enterprise license you received in the previous step and set the environment variable NOMAD_LICENSE to the license key value.

$ export NOMAD_LICENSE=02MV4UU43BK5....

You can set the enterprise license for Vault by using an environment variable. Use the enterprise license you received in the previous step and set the environment variable VAULT_LICENSE to the license key value.

$ export VAULT_LICENSE=02MV4UU43BK5....

You can set the enterprise license for Boundary by using an environment variable. Use the enterprise license you received in the previous step and set the environment variable BOUNDARY_LICENSE to the license key value.

$ export BOUNDARY_LICENSE=02MV4UU43BK5....

Read from a file (optional)

The enterprise license can be read from a file. If you add the enterprise license to a file, you have two options for how to point the server instance to the file location. The two options are an environment variable or a server instance configuration file.

Use the enterprise license key you received in the previous step and create a file that will hold the enterprise license.

You can use the echo command to copy the content from your system's clipboard into a file.

$ echo "02MV4UU43BK5..." >> license.hclic

Verify the content copied correctly to the specified file before you move onto the next step.

$ cat license.hclic
02MV4UU43BK5...

Note

You must provide an absolute path. You can use shell variables like $HOME, but not relative paths like ~/.

The environment variable name is CONSUL_LICENSE_PATH. Use the license file you created earlier and set the environment variable CONSUL_LICENSE_PATH to the license key path.

$ export CONSUL_LICENSE_PATH=/etc/consul.d/license.hclic

The Consul server instance accepts a configuration file. In the server instance configuration file, you may specify the enterprise license key file path through the license_path attribute.

{
  "server": true,
  "license_path": "/etc/consul.d/license.hclic"
}

Validate the license

Run the following command to validate the contents of the license file on disk.

$ consul license inspect /etc/consul.d/license.hclic
Source: /etc/consul.d/license.hclic
Product: consul
License ID: 00000000-0000-0000-0000-000000000000
Customer ID: 00000000-0000-0000-0000-000000000000
Installation ID: *
Issue Time: 2021-04-27 10:17:21.653194654 +0000 UTC
Start Time: 2021-04-27 00:00:00 +0000 UTC
Expiration Time: 2022-04-27 00:00:00 +0000 UTC
Termination Time: 2023-04-27 00:00:00 +0000 UTC
Modules:
    Global Visibility, Routing and Scale
    Governance and Policy
Features:
    Automated Backups
    Automated Upgrades
    Enhanced Read Scalability
    Network Segments
    Redundancy Zone
    Advanced Network Federation
    Namespaces
    SSO
    Audit Logging
    Admin Partitions

License is valid

The environment variable name is NOMAD_LICENSE_PATH. Use the license file you created earlier and set the environment variable NOMAD_LICENSE_PATH to the license key path.

$ export NOMAD_LICENSE_PATH=/etc/nomad.d/license.hclic

The Nomad server instance accepts a configuration file. In the server instance configuration file, you may also specify the enterprise license key file path in the server stanza block.

server {
 enabled = true
 license_path = "/etc/nomad.d/license.hclic"
}

The environment variable name is VAULT_LICENSE_PATH. Use the license file you created earlier and set the environment variable VAULT_LICENSE_PATH to the license key path.

$ export VAULT_LICENSE_PATH=/etc/vault.d/license.hclic

Use the license subcommand to validate the license.

Note

The license subcommand is only available with the Vault Enterprise binary.

$ vault license inspect $VAULT_LICENSE_PATH
Source: /etc/vault.d/license.hclic
Product: vault
License ID: S3sAm3st-8c10-9db0-2e8f-aB34Ef78
Customer ID: aB34Ef78-dc55-cb2c-ca2d-ef7ae4c2e080
Installation ID: *
Issue Time: 2023-02-15 13:57:46.677406153 +0000 UTC
Start Time: 2023-02-15 00:00:00 +0000 UTC
Expiration Time: 2024-02-15 23:59:59.999 +0000 UTC
Termination Time: 2024-02-15 23:59:59.999 +0000 UTC
{"license_id":"S3sAm3st-8c10-9db0-2e8f-aB34Ef78","customer_id":...snip...}

License is valid

License setting priority

When both VAULT_LICENSE and VAULT_LICENSE_PATH environment variables exist, VAULT_LICENSE takes precedence. In addition, if the license_path is defined in the server configuration file and VAULT_LICENSE or VAULT_LICENSE_PATH exists, the environment variables take precedence over license_path.

License file reload

Use the sys/config/reload/license endpoint to reload your Vault Enterprise license if needed. Vault reads the license from a file if specified using the license_path configuration parameter or the VAULT_LICENSE_PATH environment variable.

$ vault write -force sys/config/reload/license

Once the updated license is applied, Vault will enable or disable licensed features if the features allowed by the license are different.

The environment variable name is BOUNDARY_LICENSE with file:// prepended to the license path. Use the license file you created earlier and set the environment variable BOUNDARY_LICENSE to the license key path.

$ export BOUNDARY_LICENSE=file:///etc/boundary.d/license.hclic

You can specify the enterprise license key file path in the Boundary server configuration using the license_path attribute with file:// prepended to the license path.

license_path = "file:///etc/boundary.d/license.hclic"

Validating the server

Start the Consul server instance.

$ consul agent -dev
==> Starting Consul agent...
         Version: '1.10.0+ent'
         Node ID: '93a230f3-888e-7fd7-81ea-04f6d43ab199'
       Node name: 'defaultNode'
      Datacenter: 'dc1' (Segment: '<all>')
          Server: true (Bootstrap: false)
     Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: -1, gRPC: 8502, DNS: 8600)
    Cluster Addr: 127.0.0.1 (LAN: 8301, WAN: 8302)
         Encrypt: Gossip: false, TLS-Outgoing: false, TLS-Incoming: false, Auto-Encrypt-TLS: false

==> Log data will now stream in as it occurs:

If the server instance started successfully, then you will receive a message stating the Consul agent started.

Look for the lines Server: true and Version: 1.10.0+ent to verify that an enterprise server is running.

Error message

The server instance will notify you if the enterprise license key is not found. If you encounter the error message below or similar, please revisit the steps above.

$ consul agent -dev
...
2021-06-03T07:29:30.220-0700 [ERROR] agent: Error starting agent: error="server agents require a license to be loaded via the configuration"
2021-06-03T07:29:30.220-0700 [INFO]  agent: Exit code: code=1

Start the Nomad server instance.

$ sudo nomad agent -dev
==> No configuration files loaded
==> Starting Nomad agent...
==> Nomad agent configuration:

       Advertise Addrs: HTTP: 127.0.0.1:4646; RPC: 127.0.0.1:4647; Serf: 127.0.0.1:4648
            Bind Addrs: HTTP: 127.0.0.1:4646; RPC: 127.0.0.1:4647; Serf: 127.0.0.1:4648
                Client: true
             Log Level: DEBUG
                Region: global (DC: dc1)
                Server: true
               Version: 1.1.0+ent

==> Nomad agent started! Log data will stream in below:

If the server instance started successfully, then you will receive a message stating the Nomad agent started.

Look for the lines Server: true and Version: 1.1.0+ent to verify that an enterprise server is running.

Error message

The server instance will notify you if the enterprise license key is not found. If you encounter the error message below or similar, please revisit the steps above.

$ sudo nomad agent -dev
==> No configuration files loaded
==> Starting Nomad agent...
==> Error starting agent: server setup failed: failed to initialize enterprise licensing: failed to read license: license is missing. To add a license, configure "license_path" in your server configuration file, use the NOMAD_LICENSE environment variable, or use the NOMAD_LICENSE_PATH environment variable.

Start the Vault server in dev mode for testing.

$ vault server -dev -dev-root-token-id=root
==> Vault server configuration:

             Api Address: http://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
              Go Version: go1.16.5
              Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
               Log Level: info
                   Mlock: supported: false, enabled: false
           Recovery Mode: false
                 Storage: inmem
                 Version: Vault v1.8.0+rc1
             Version Sha: ce481f21f5a76bfc5717f43ac7362f1240e1aaff

==> Vault server started! Log data will stream in below:

If the server instance started successfully, you will receive a message stating the Vault server started.

Now, you should be able to login.

$ vault login root

Read the license status information.

$ vault license get

Example output:

Key                          Value
---                          -----
expiration_time              2024-02-15T23:59:59.999Z
features                     [HSM Performance Replication DR Replication MFA Sentinel Seal Wrapping Control Groups Performance Standby Namespaces KMIP Entropy Augmentation Transform Secrets Engine Lease Count Quotas Key Management Secrets Engine Automated Snapshots]
license_id                   S3sAm3st-8c10-9db0-2e8f-aB34Ef78
performance_standby_count    9999
start_time                   2023-02-15T00:00:00Z
termination_time             2024-02-15T23:59:59.999Z

Error message

When the enterprise license is missing, the following error will be displayed.

Error initializing core: no autoloaded license provided and storage is not initialized. Licenses can be obtained at https://vaultproject.io/trial
[INFO]  proxy environment: http_proxy="" https_proxy="" no_proxy=""
[WARN]  no `api_addr` value specified in config or in VAULT_API_ADDR; falling back to detection if possible, but this value should be manually set
[INFO]  core: security barrier not initialized
[WARN]  core: A valid license is required to be loaded but none was found. Licenses can be obtained at https://vaultproject.io/trial

Be sure to set your enterprise license to be read from an environment variable or read from a file.

Tip

Refer to the Vault Enterprise License Frequently Asked Questions (FAQs) to learn more about the changes introduced in Vault 1.8.

Start the Boundary server instance.

$ boundary dev
==> Boundary server configuration:

                        [Bsr] AEAD Key Bytes: iL6unSVX3YryBrpd/hL1pjRBsXpJKuMX
                 [Controller] AEAD Key Bytes: /tFhIn0aA3GOyTcK1GDpVhmyGKq51ueS
                   [Recovery] AEAD Key Bytes: 0aQfmA1/wrgYsDjKCWJmD21FWSJIvcpM
                [Worker-Auth] AEAD Key Bytes: 0cSBAGCiZXtZw68H1+KIxh3lRJJo702J
                             [Bsr] AEAD Type: aes-gcm
                        [Recovery] AEAD Type: aes-gcm
                            [Root] AEAD Type: aes-gcm
             [Worker-Auth-Storage] AEAD Type: aes-gcm
                     [Worker-Auth] AEAD Type: aes-gcm
                                         Cgo: disabled
              Controller Public Cluster Addr: 127.0.0.1:9201
                      Dev Database Container: unruffled_bhaskara
                            Dev Database Url: postgres://postgres:password@localhost:32770/boundary?sslmode=disable
                  Generated Admin Login Name: admin
                    Generated Admin Password: password
                   Generated Host Catalog Id: hcst_1234567890
                           Generated Host Id: hst_1234567890
                       Generated Host Set Id: hsst_1234567890
  Generated Ldap Auth Method Base Search DNs: users="ou=people,dc=example,dc=org" groups="ou=groups,dc=example,dc=org"
        Generated Ldap Auth Method Host:Port: 127.0.0.1:63906 (does not have a root DSE; use simple bind)
               Generated Ldap Auth Method Id: amldap_1234567890
               Generated Oidc Auth Method Id: amoidc_1234567890
                      Generated Org Scope Id: o_1234567890
           Generated Password Auth Method Id: ampw_1234567890
                  Generated Project Scope Id: p_1234567890
            Generated Target With Address Id: ttcp_1234567890
        Generated Target With Host Source Id: ttcp_0987654321
           Generated Unprivileged Login Name: user
             Generated Unprivileged Password: password
                                  Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")
                                  Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")
                                  Listener 3: tcp (addr: "127.0.0.1:9203", max_request_duration: "1m30s", purpose: "ops")
                                  Listener 4: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")
                                   Log Level: info
                                       Mlock: supported: false, enabled: false
                                     Version: Boundary v0.13.0+ent
                                 Version Sha: e38ecf04f5a2a60850be2190b0607f93f0ae61a7
                  Worker Auth Current Key Id: disorder-eardrum-impeach-race-caregiver-remix-freestyle-immodest
                    Worker Auth Storage Path: /var/folders/lx/dq871x7x3rv2ghc0fwg_z1y40000gq/T/nodeenrollment837482576
                    Worker Public Proxy Addr: 127.0.0.1:9202

==> Boundary server started! Log data will stream in below:

Look for the line Version: Boundary v0.13.0+ent to verify that an enterprise server is running.

Error message

The server instance will notify you if the enterprise license key is not found. If you encounter the error message below or similar, please revisit the steps above.

$ boundary dev
Error creating controller dev config: error parsing dev config: No license supplied in controller block or BOUNDARY_LICENSE env var

Next steps

In this tutorial, you deployed a server instance for an enterprise HashiCorp product using a valid enterprise license key. You may now continue exploring other enterprise tutorials for Consul, Nomad, or Vault.

Consul Enterprise Tutorials

Nomad Enterprise Tutorials

Vault Enterprise Tutorials

Collection Overview

Enterprise

Secure multi-tenancy with namespaces

This tutorial also appears in:

5 tutorials

Boundary Enterprise
Learn operational tasks specific to creating and operating a Boundary Enterprise environment.
- Boundary
9 tutorials

Nomad Enterprise
Learn about Nomad Enterprise features and how to use them at scale.
- Nomad