Skip to main content
Perform the following tasks in this section to install and configure Vault:
  1. Download Vault.
  2. Install Vault.
  3. Configure systemd.
  4. Configure Vault.
  5. Configure Managed Keys.
  6. Start the Vault Server.
The Vault HSM Managed Keys feature requires Vault Enterprise with the Advanced Data Protection Module.

​
Download Vault

Download precompiled Vault binaries at https://releases.hashicorp.com/vault/, and download Vault Enterprise binaries by following the instructions available to HashiCorp Vault customers. This integration requires theVault Enterprise HSM binary, version1.10 or later. You can use the following link for testing: https://releases.hashicorp.com/vault/1.10.0+ent.hsm/

​
Install Vault

Perform the following steps to install Vault:
1
Unzip the downloaded package and move the vault binary to /usr/local/bin/.
Shell
$ unzip vault_${VAULT_VERSION}+ent.hsm_linux_amd64.zip
2
Set the owner of the Vault binary.
Shell
$ sudo chown root:root vault
3
Ensure that Vault is available on the system path.
Shell
$ sudo mv vault /usr/local/bin/
4
Verify the Vault version.
Shell
$ vault --version
5
Thevault command features opt-in autocompletion for flags, subcommands, and arguments, where supported. Install autocompletion by using the following command.
Shell
$ vault -autocomplete-install
6
Enable autocompletion.
Shell
$ complete -C /usr/local/bin/vault vault
7
Enable Vault to use the mlock syscall without running the process as root. The mlock syscall prevents memory from being swapped to disk.
Shell
$ sudo setcap cap_ipc_lock=+ep /usr/local/bin/vault
8
Create a unique, non-privileged system user to run Vault.
Shell
$ sudo useradd --system --home /etc/vault.d --shell /bin/bash vault

​
Configure systemd

Systemd uses documented sane defaults ( www.freedesktop.org/software/systemd/man/systemd.directives.html), so you must set only non-default values in the configuration file.
1
Create a Vault service file in /etc/systemd/system/vault.service.
Shell
$ sudo touch /etc/systemd/system/vault.service
2
Add the following configuration details to the Vault service file:
Text
[Unit]
Description="HashiCorp Vault - A tool for managing secrets"
Documentation=https://www.vaultproject.io/docs/
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/vault.d/vault.hcl
StartLimitIntervalSec=60
StartLimitBurst=3

[Service]
User=vault
Group=vault
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
Capabilities=CAP_IPC_LOCK+ep
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
StartLimitInterval=60
StartLimitIntervalSec=60
StartLimitBurst=3
LimitNOFILE=65536
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

​
Configure Vault

Vault uses documented sane defaults, so you must set only non-default values in the configuration file.
1
Create /etc/vault.d directory.
Shell
$ sudo mkdir --parents /etc/vault.d
2
Create a Vault configuration file, vault.hcl.
Shell
$ sudo touch /etc/vault.d/vault.hcl
3
Set the ownership of the /etc/vault.d directory.
Shell
$ sudo chown --recursive vault:vault /etc/vault.d
4
Set the required file permissions.
Shell
$ sudo chmod 640 /etc/vault.d/vault.hcl

​
Configure Managed Keys

The kms_library stanza isolates platform-specific configurations for managed keys. It defines logical names referenced within an API configuration, keeping separated cluster and node-specific details and deployment concerns for each. To support theManaged Keys feature by integrating the Vault Enterprise server with an HSM, the configuration file must define the kms_library stanza ( www.vaultproject.io/docs/configuration/kms-library), providing the necessary connection information. Example: vault.hcl
Text
# Provide your CryptoHub connection information
kms_library "pkcs11" {
name="hsm1"
library = "/usr/local/bin/fxpkcs11/libfxpkcs11.so"
}

storage "file" {
path    = "/tmp/vault"
}

listener "tcp" {
address     = "0.0.0.0:8200"
tls_disable = "true"
}

disable_mlock = true
license_path = "/usr/local/bin/License.txt"

api_addr = "http://127.0.0.1:8200"
cluster_addr = "https://127.0.0.1:8201"
ui = true
This guide sets the storage backend to the local file system (/tmp/vault) to make verification easier.
Save your Vault license to a file on disk. The preceding configuration file specifies it as License.txt.
The example configuration defines the following elements in itskms_library stanza.
  • name: The logical name to be referenced by a managed key
  • library: The path to the PKCS #11 library shared object file.
You can define multiple kms_library stanzas, with the only limitation being that the value for the name key must be unique across all the stanza definitions in a case-insensitive manner.
For the full list of configuration parameters, refer to the Vault documentation here.

​
Start the Vault Server

Perform the following steps to start the Vault Server:
1
Log in with thevault user.
2
Set the PKCS #11 PIN for the login with the following command (the value is the CryptoHub identity password configured inside the <CRYPTO-OPR-PASS> tag in the fxpkcs11.cfg file):
Shell
$ export VAULT_HSM_PIN='identity_password'
3
Start the Vault server.
Shell
$ vault server -config=/etc/vault.d/vault.hcl
If the command succeeds, you should see output similar to the following example:
None
==> Vault server configuration:

             Api Address: http://127.0.0.1:8200
                     Cgo: enabled
         Cluster Address: https://127.0.0.1:8201
              Go Version: go1.17.7
              Listener 1: tcp (addr: "0.0.0.0:8200", cluster address: "0.0.0.0:8201", maxrequestduration: "1m30s", maxrequestsize: "33554432", tls: "disabled")
               Log Level: info
                   Mlock: supported: true, enabled: false
           Recovery Mode: false
                 Storage: file
                 Version: Vault v1.10.0+ent.hsm
             Version Sha: d71d7710888891761ce43ec4e5f9d9fdeff31d8e

==> Vault server started! Log data will stream in below:
4
Open a new terminal window and leave the terminal running where you started the Vault server.