Skip to main content

Install the Piiano Vault binary

Learn how to install and run the Piiano Vault binary in stateless mode​

The binary version of Vault provides for simplified set up and easy interaction from the command line. It is well-suited to running tests in a CI or CD environment.

note

Vault binary runs in production mode by default. The binary version of Vault is not recommended for stateless workloads in production. The binary version is supplied mostly for testing, CI, and local development purposes. Contact us if you wish to use the binary version in production.

Install and prepare the binary version​

To install the binary version of Vault, visit github.com/piiano/vault-releases. Follow the instructions there to download and install the appropriate version.

note

When you wish to upgrade the version of Vault, download and install the new version from GitHub.

Running in stateless mode​

Create Vault configuration files​

In stateless mode, Vault does not include the default IAM configuration file needed to start Vault. The stateful version of Vault also uses a system configuration file to define the initial state of Vault. This file is optional for stateless mode.

The binary version of Vault provides for generating and storing these files locally. To do this, run Vault like this:

./pvault-server -s -d -c

Flags used: -d for development mode, -c to create default configuration and -s for stateless. This process creates the pvault-conf directory in your current working directory and stores the following files in it:

  1. pvault.system.toml
  2. pvault.iam.toml
  3. pvault.collections.pvschema

Make the required changes to these configuration files. In particular, add your users to the IAM configuration (changes to the schema will be done in the next section).

Define data types and bundles​

When Vault encrypts data, it uses information about the external files defined in collection schemas. You define these collections to Vault in a file containing PVSchemas. If you also have custom data types, you can include a file to define these too.

Modify the template PVSchema file pvault.collections.pvschema with your collection structure. Without the specification of at least one collection, Vault does not start.

Create secrets and tokens​

Vault has no storage in stateless mode. Therefore, it must generate and store details of the secrets used for encryption and other features locally.

To do this, run Vault like this, omitting the -d flag to run in production mode:

./pvault-server -s -d -x

Vault starts and generates secrets and user tokens.

In development mode, the secrets are stored in a file called pvault.secrets.json and the tokens in api_tokens.txt in the pvault-conf directory. The Vault continues running after the secrets generation and is ready to work.

In production mode, the secrets are stored in a file called pvault.secrets.json in the pvault-conf directory and the tokens are output to stdout. The Vault shuts down after completing the secrets generation. This allows the usage in your CI/CD scripts.

note

Do not edit the pvault.secrets.json file. Altering the secret values could prevent Vault from starting or mean Vault cannot decrypt data.

Vault is now available to execute any of the crypto REST API operations or CLI commands. You can also perform read operations in the control side, and set and clear configuration variables for the session.

Run Vault in stateless mode​

You start Vault in stateless mode like this, omitting the -d flag to run in production mode:

./pvault-server -s -d

Updating configuration details​

Add users​

If you need to add users, update the pvault.iam.toml file with the new user details and run Vault with the -x flag. Vault updates the secrets file with a hash of the users' token and outputs the users' tokens on stdout.

note

If you misplace a user's token, the recommended approach to obtaining a new token is to:

  • remove the user details from the pvault.iam.toml file.
  • run Vault with the -x flag (which removes the hash of the user's token from the secrets file and, in development mode, details of the user from the tokens file).
  • add the user's details back to the pvault.iam.toml file.
  • run Vault with the -x flag to update the secrets file and obtain a new token for the user.
Add and update collections​

If you need to add or update collections, update the PVSchema file with the new or updated collection details and run Vault with the -x flag. Vault updates the secrets file with secrets relevant to the collections.

Vault binary flags​

The Vault binary supports these flags:

  • -a STRING , --listen-addr STRING: change the address of the server.
  • -d , --dev-mode: run in dev mode.
  • -h , --help: show help information.
  • -l STRING , --license STRING: provide the Vault license.
  • -v , --verbose: change the debug level.
  • -s , --stateless: run in stateless mode.
  • -c , --create-conf: creates the configuration files (system.toml and iam.toml) and two default collections in collection.pvschema, then exits,
  • -x special mode where the Vault creates or updates secrets for your configuration.

On this page