Start the Vault server

On this page you learn how to:

With vHSM installed and configured, the next step is to start a Vault server.

Vault operates as a client-server application. The Vault server is the only piece of the Vault architecture that interacts with the data storage and backends. All operations done via the vHSM CLI interact with the server over a TLS connection.

Starting the Server

Quickstart: Dev Server in local environment

Use the -help flag to list available command options for vhsm server.

vhsm server -help

Scroll down to the Dev Options section.

Dev Options:

-dev
      Enable development mode. In this mode, Vault runs in-memory and starts
      unsealed. As the name implies, do not run "dev" mode in production. The
      default is false.

-dev-listen-address=<string>
      Address to bind to in "dev" mode. The default is 127.0.0.1:8200. This
      can also be specified via the VAULT_DEV_LISTEN_ADDRESS environment
      variable.

-dev-no-store-token
      Do not persist the dev root token to the token helper (usually the local
      filesystem) for use in future requests. The token will only be displayed
      in the command output. The default is false.

-dev-root-token-id=<string>
      Initial root token. This only applies when running in "dev" mode.
      This can also be specified via the VAULT_DEV_ROOT_TOKEN_ID environment
      variable.

-dev-tls
      Enable TLS development mode. In this mode, Vault runs in-memory and
      starts unsealed, with a generated TLS CA, certificate and key. As the
      name implies, do not run "dev-tls" mode in production. The default is
      false.

-dev-tls-cert-dir=<string>
      Directory where generated TLS files are created if `-dev-tls` is
      specified. If left unset, files are generated in a temporary directory.

Start a Vault server in development mode (dev server). The dev server is a built-in, pre-configured server that is not very secure but useful for playing with Vault locally.

ENCLAIVE_LICENCE=<licencekey> vhsm server -dev

docker run --cap-add=IPC_LOCK -p 8200:8200 \
    -e ENCLAIVE_LICENCE=<licencekey> \
    harbor.enclaive.cloud/enclaive-dev/vhsm:latest \
    server -dev -dev-listen-address="0.0.0.0:8200"

services:
  vault:
    image: harbor.enclaive.cloud/enclaive-dev/vhsm:latest
    command: server -dev -dev-listen-address="0.0.0.0:8200"
    environment:
      - ENCLAIVE_LICENCE=<licencekey>
    volumes:
      - ./vhsm:/vhsm
      - ./vhsm/data:/vhsm/data
    ports:
      - 8200:8201
    cap_add:
      - IPC_LOCK

Example output:

==> Vault server configuration:

            Api Address: http://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
            Go Version: go1.21.4
            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.0.0-dev1, built 2023-11-12T14:39:49Z
            Version Sha: 2a7c3f2f76e6fd6a7f8622ea68d82bcf9dcf9686

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

# ...snip...

WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

You may need to set the following environment variables:

   $ export VAULT_ADDR='http://127.0.0.1:8200'

The unseal key and root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.

Unseal Key: PLV0OXO9VmF5VB8qAnq4pQIGzWkzzYypRNcDtrhSSgU=
Root Token: hvs.6j4cuewowBGit65rheNoceI7

Development mode should NOT be used in production installations!

You should see an output similar to that above. Notice that Unseal Key and Root Token values are displayed.

The dev server stores all its data in memory (but still encrypted), listens on localhost without TLS, and automatically unseals and shows you the unseal key and root access key.

Insecure operation

Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.

Server with TLS enabled in staging environments

If you wish to run a Vault dev server with TLS enabled, use the -dev-tls flag instead of -dev.

ENCLAIVE_LICENCE=<licencekey> vhsm server -dev-tls

Example output:

==> Vault server configuration:

             Api Address: https://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
              Go Version: go1.21.4
              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: "enabled")
               Log Level: info
                   Mlock: supported: false, enabled: false
           Recovery Mode: false
                 Storage: inmem
                 Version: Vault v1.0.0-dev1, built 2023-11-12T14:39:49Z
             Version Sha: 2a7c3f2f76e6fd6a7f8622ea68d82bcf9dcf9686

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

#...snip...

WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

You may need to set the following environment variables:

    $ export VAULT_ADDR='https://127.0.0.1:8200'
    $ export VAULT_CACERT='/var/folders/bz/nvj1yk7j411frmff3198l8_c0000gp/T/vault-tls1123544318/vault-ca.pem'

The unseal key and root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.

Unseal Key: Lylgnqrv+0W6ZO8gzhbnqsaOXcx9Mlgqxxlv641nwZ0=
Root Token: hvs.kvlITyyikUb8bPwqS1Nfjx7f

Development mode should NOT be used in production installations!

Starting the server in production environments

When running in production, additional considerations must be made beyond development mode.

Security: Enable TLS secure communication between the client and server.
Access Control: Enable (role based) authentication and authorization mechanisms.
High availability storage: Consider using a more secure storage backend (e.g., Consul, DynamoDB).
Binding: Encrypt the persistent storage to the platform.

Refer to the configuration documentation for more advanced options and examples.

Store the configuration in config.json and run the vhsm server command with the parameter -config

vhsm server -config /path/to/confing.json

docker run --cap-add=IPC_LOCK -p 8200:8200 \
    -e ENCLAIVE_LICENCE=<licencekey> \
    harbor.enclaive.cloud/enclaive-dev/vhsm:latest \
    server -config /path/to/config.json

services:
  vault:
    image: harbor.enclaive.cloud/enclaive-dev/vhsm:latest
    command: server -config=/path/to/config.json
    environment:
      - ENCLAIVE_LICENCE=<licencekey>
    volumes:
      - ./vhsm:/vhsm
      - ./vhsm/data:/vhsm/data
    ports:
      - 8200:8201
    cap_add:
      - IPC_LOCK

Verify the server is running

Verify the server is running by running the vhsm status command. If it ran successfully, the output should look like the following:

vhsm status

Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    1
Threshold       1
Version         1.0.0
Build Date      2023-11-12T10:27:10Z
Storage Type    inmem
Cluster Name    vault-cluster-2b0b44fd
Cluster ID      a6f87c32-fe6a-6647-0d22-e814d125a5c4
HA Enabled      false

If the output looks different, restart the dev server and try again. The only reason these would ever be different is if you're running a dev server from going through this tutorial previously.

Set environment variables

For ease of use, it is helpful to set the environment variables VAULT_ADDR, VAULT_TOKEN and ENCLAIVE_LICENCE

Launch a new terminal session.
Copy and run the export VAULT_ADDR ... command from the terminal output. This will configure the Vault client to talk to the dev server.
```
export VAULT_ADDR='http://127.0.0.1:8200'
```
Vault CLI determines which Vault servers to send requests using the VAULT_ADDR environment variable.
Save the unseal key somewhere. Don't worry about how to save this securely. For now, just save it anywhere.
Set the VAULT_TOKEN environment variable value to the generated Root Token value displayed in the terminal output.
Example:
```
export VAULT_TOKEN="hvs.6j4cuewowBGit65rheNoceI7"
```
To interact with Vault, you must provide a valid token. Setting this environment variable is a way to provide the token to Vault via CLI. Later, in the Authentication tutorial, you will learn to use the vault login <token_value> command to authenticate with Vault.
Set the ENCLAIVE_LICENCE environment variable value to the licence key
Example:
```
export ENCLAIVE_LICENCE="abcd-efgh-ijkl-mnop"
```

Congratulations! You've started your first Vault server.

You can continue with Activate Nitride tutorial, where you learn how to enable the workload identity management.

PreviousGet Started NextActivate Nitride

Last updated 3 months ago