Configuration files

Learn how to configure Piiano Vault using files for the system configuration, IAM configuration, data types, and collections

note

If you're using the hosted version of Vault, you load the IAM configuration file using the SaaS console. System configuration, custom data types, and collections configuration files are not supported. You set details for custom data types and collections using the API and CLI.

When Vault loads, it uses several files to configure itself:

1. the system configuration file that loads from a default file and is merged with a custom file, if present, every time Vault starts.
2. the IAM configuration file that loads from a default file or, if present, a custom file the first time Vault starts and, optionally, on every start.
3. the custom data types configuration file that loads the first time Vault starts, if present, and, optionally, on every start.
4. the collections configuration file that loads the first time Vault starts, if present, and, optionally, on every start.

Whether the IAM configuration file is loaded every time Vault starts is controlled by the PVAULT_SERVICE_SET_IAM_ON_START_ONLY environment variable.

Whether the data types and collections configuration files are loaded every time Vault starts is controlled by the PVAULT_SERVICE_UPDATE_SCHEMA_ON_START environment variable.

To use an infrastructure as code approach:

1. Place the four files in the designated folder.
2. Set both environment variables to true: PVAULT_SERVICE_UPDATE_SCHEMA_ON_START and PVAULT_SERVICE_SET_IAM_ON_START_ONLY.
3. Do not attempt to modify any configuration using the runtime API calls.

System configuration file

The system configuration file contains the basic information needed to start Vault and is specified in the TOML format.

Default file

Vault provides a default file, stored in the /etc/pvault/default folder, containing:

[db]
hostname = "localhost"
name = "pvault"
user = "pvault"
password = "pvault"
port = 5432

[service]
listen_addr = "0.0.0.0:8123"

[log]
level = "info"

Overriding the system configuration file

You override some or all of the values in the default system configuration file by storing a custom configuration file named pvault.system.toml in the /etc/pvault/conf.d directory. For example, if you installed Piiano Vault server using Docker, store your custom file in a local directory and mount that directory to the container's configuration directory using:

-v /path/to/local/vault/config/directory:/etc/pvault/conf.d

Vault merges values from the default system configuration file with those from the custom system configuration file as follows:

• If a value is provided in only one of the files, the value provided is used.
• If a value is provided in both files, the value from the custom file is used.
• If a value is not provided in either file, the default value is used.

For example, if you create and mount a custom system configuration file with this content:

[log]
level = "debug"

The values for hostname, name, user, etc. are taken from the db section of the default system configuration file, whereas the log level, from the log section, is overridden and set to "debug".

note

If present, environment variables override the corresponding values in the default or custom system configuration file.

You can retrieve the system configuration using the get system configuration REST API operation or CLI command.

IAM configuration file

The IAM configuration file provides basic user details and access policies.

Default file

See Default IAM configuration for information on the default IAM configuration.

Vault stores the default file in the /etc/pvault/default folder.

This file is used to configure Vault the first time Vault starts. Vault does not load this file on subsequent starts. However, Vault may load the override file depending on environment variable settings.

You read and modify the IAM configuration using the REST API and CLI.

Overriding the IAM configuration file

You override the values in the default IAM configuration file by storing a custom configuration file named pvault.iam.toml in the /etc/pvault/conf.d folder. For example, if you installed Piiano Vault server using Docker, store a custom file in a local directory and mount that directory to the container's configuration directory using:

-v /path/to/local/vault/config/directory:/etc/pvault/conf.d

If you provide a custom IAM configuration file, Vault ignores the default IAM configuration file and uses the custom file instead.

By default, the custom IAM configuration file is loaded on the initial start of Vault only. To load the file on every start of Vault, set the PVAULT_SERVICE_SET_IAM_ON_START_ONLY environment variable to true.

If a custom IAM configuration file is provided, and Vault fails to load it, failures are reported and the start is aborted.

note

1. When overriding the IAM configuration file, the custom file replaces the default one. Therefore, you must provide all the values needed in the custom file. For example, suppose you want to include a policy defined in the default IAM configuration file in a role defined in the custom file. In that case, you must copy the policy definition into the Policies section of the custom file.
2. When PVAULT_SERVICE_SET_IAM_ON_START_ONLY environment variable is set to true:

• the values in Vault are replaced with the content of the custom file. Users defined in the configuration file already in Vault retain their API key.
• the Set IAM configuration REST API operation and CLI command are disabled.

See Update the IAM configuration for information on retrieving the IAM configuration.

Data types configuration file

You can define the custom data types to load when Vault starts using the data types configuration file.

If you provide this file, it is loaded the first time Vault starts but, by default, is not reloaded on subsequent starts. To load it on subsequent starts of Vault, set the PVAULT_SERVICE_UPDATE_SCHEMA_ON_START environment variable to true.

When the file is reloaded:

• bundles defined in the file but not in Vault are added.
• bundles in Vault, but not defined in the file, are left unchanged.
• bundles in Vault and redefined in the file are updated. However, the update fails if the bundle doesn't include exports defined in Vault.
• data types defined in the file but not in Vault are added.
• data types in Vault but not defined in the file are left unchanged.
• a data type in Vault redefined in the file must be identical to the one in Vault. (Support for updating data types will be included in a future release.)

If a data types configuration file is provided and Vault fails to load it, failures are reported and the start is aborted.

Collections configuration file

You can define the collections to load when Vault starts using a file containing PVSchemas called pvault.collections.pvschema and stored in the /etc/pvault/conf.d folder.

If you provide this file, it is loaded the first time Vault starts but, by default, is not reloaded on subsequent starts. To load it on subsequent starts of Vault, set the PVAULT_SERVICE_UPDATE_SCHEMA_ON_START environment variable to true.

When the file is loaded:

• collections defined in the file but not in Vault are added.
• collections in Vault but not defined in the file are left unchanged.
• collections in Vault and redefined in the file are updated using the Update collection REST API operation.

If a collections configuration file is provided and Vault fails to load it, failures are reported and the start is aborted.

Javascript bundle files

Every bundle file that appears in the [bundles] section of the pvault.types.toml must reside in the /etc/pvault/conf.d/pvault.bundles directory.