Environment variables

Learn how to configure Piiano Vault using environment variables

You can set environment variables to configure Piiano Vault, which take precedence over the configuration file of the Piiano Vault settings.

info

The Set configuration variable REST API call and Set configuration variable CLI command enable some environment variables to be configured dynamically. Refer to the REST API or CLI documentation for details of the supported environment variables.

Piiano Vault license

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_SERVICE_LICENSE	string	none	All	A valid Piiano Vault license is required to start your Vault. The license is a string of characters. See License management for more information.

Production and development mode

Name	Type	Default	Edition	Details
PVAULT_DEVMODE	bool	true for pvault-dev false otherwise	All	Whether Vault runs in development mode. This setting also determines the default values for several environment variables.

Variables whose default values depend on PVAULT_DEVMODE

If PVAULT_DEVMODE is true, these variables override the defaults set by development mode.

Name	Default when PVAULT_DEVMODE is true	Default when PVAULT_DEVMODE is false
PVAULT_SERVICE_ADMIN_MAY_READ_DATA	true	false
PVAULT_TLS_ENABLE	false	true
PVAULT_DB_REQUIRE_TLS	false	true

Database

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_DB_HOSTNAME	string	"localhost"	All	Hostname of the running database
PVAULT_DB_NAME	string	"pvault"	All	Name of the database to connect to
PVAULT_DB_USER	string	"pvault"	All	Username for the database
PVAULT_DB_PASSWORD	string	"pvault"	All	Password for the database
PVAULT_DB_PORT	int	5432	All	Port of the running database
PVAULT_DB_REQUIRE_TLS	bool	Mode dependent	All	Vault tries to connect to the database with TLS. If this value is true and the connection fails, Vault does not start. If this value is false and the connection fails, Vault starts and connects without TLS
PVAULT_DB_MAX_OPEN_CONNS	int	16	All	Maximum number of open connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_IDLE_CONNS	int	16	All	Maximum number of idle connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_CONN_MAX_LIFETIME_MINUTES	int	5	All	The limit on the time, in minutes, a connection to the backend database is maintained–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_STRING_LENGTH	int	64	All	The maximum length of data types based on strings, including STRING, NAME, GENDER, CC_HOLDER_NAME, US_BANK_ACCOUNT_NUMBER, OBJECT_ID and TENANT_ID.
PVAULT_DB_MAX_BLOB_LENGTH	int	5242880	All	The maximum length of data types based on blobs.
PVAULT_DB_MAX_TOKEN_TAGS	int	10	All	The maximum amount of tags per token
PVAULT_DB_MIGRATION_AUTO_RUN	bool	true	All	Whether Vault sets up the database during migration. Set to false when performing the database migration externally
PVAULT_DB_MIGRATION_ENABLE_RETRIES	bool	true	All	Whether Vault performs retries for the database migration. When running the migration in Vault and multiple instances are running, this option must be true to handle race conditions. When running the migration externally, this can be set to false
PVAULT_DB_MIGRATION_INITIAL_WAIT_BETWEEN_RETRIES	string	20ms	All	The initial wait duration between retries for the migration exponential backoff
PVAULT_DB_MIGRATION_MAX_WAIT_BETWEEN_RETRIES	string	5s	All	The maximum wait duration between retries for the migration exponential backoff
PVAULT_DB_MIGRATION_MAX_RETRIES	int	25	All	The maximum number of retries attempts for the migration exponential backoff
PVAULT_DB_GC_RETENTION_PERIOD	string	720h	All	The period for which archived objects and tokens are retained before becoming eligible for deletion by the prune job, delete objects and tokens REST API operation, and CLI delete objects and tokens command.

Stateless mode

Name	Type	Default	Edition	Details
PVAULT_BACKING_STORE	string	psql	Server	The backing store for Vault. By default it is 'psql' which tells Vault to store its state in the POSTGRES DB. The value 'none' tells Vault to run in stateless mode. In stateless mode Vault does not connect to a database. State is stored in memory. In stateless mode some methods are disabled.
PVAULT_GENERATE_SECRETS	bool	false	Server	This variable is only applicable when PVAULT_BACKING_STORE is set to none. In this mode, Vault is a stateless server which stores all state in memory. When running Vault for the first time, this variable should be set to true. Vault will then write all keys needed for stateless operations, and the hashes of all user tokens into a file called pvault.secrets.json in the current directory. It will also print the user tokens to the console and then exit. Having done so once, you can then start Vault with this variable set to 0, false (or not set). Vault will then read and load the secrets from the file, allowing it to run in stateless mode.

Key management service

A key management service (KMS) should be configured. For more information on using a KMS and property encryption, see Key management service on the encryption page.

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_KMS_URI	string	""	All	The KMS key URI used for property encryption
PVAULT_KMS_SEED	string	""	All	Generate a local KMS using this seed (KMS_URI can be unset)

Service and features

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_SERVICE_LISTEN_ADDR	string	"0.0.0.0:8123"	All	Listener address of Vault
PVAULT_SERVICE_ADMIN_API_KEY	string	"pvaultauth"	All	The admin API key for authentication
PVAULT_SERVICE_FORCE_ACCESS_REASON	bool	true	All	Whether Vault should force a valid access reason to be provided with calls
PVAULT_SERVICE_ADMIN_MAY_READ_DATA	bool	Mode dependent	All	Whether Admin is allowed to read data
PVAULT_FEATURES_ENCRYPTION	bool	true	All	This variable is ignored in production. In production, properties set as is_encrypted are always stored encrypted. When this variable is set to false (only in PVAULT_DEVMODE), properties stored unencrypted.
PVAULT_FEATURES_POLICY_ENFORCEMENT	bool	true	All	Whether policy management is enforced
PVAULT_FEATURES_MASK_LICENSE	bool	false	All	Whether Vault's service license will be masked while retrieving it using Get license API or Get license CLI
PVAULT_SERVICE_TIMEOUT_SECONDS	float	30	All	Timeout in seconds for REST API calls
PVAULT_SERVICE_DEFAULT_PAGE_SIZE	int	100	All	The default page size for object queries when the page size is not specified. The page size is the maximum number of objects that may be requested in one call.
PVAULT_SERVICE_MAX_PAGE_SIZE	int	1000	All	The maximum page size that can be specified for a call. The page size is the maximum number of objects that may be requested in one call.
PVAULT_SERVICE_CACHE_REFRESH_INTERVAL	string	30s	All	The refresh interval of the control data cache that serves the data APIs (under /api/pvlt/1.0/data/). If this value is zero the cache is disabled.
PVAULT_SERVICE_ARCHIVE_PRUNE_INTERVAL	string	0	All	The non-negative run interval for the prune job as a duration string. (See the definition of a duration string in the details for PVAULT_EXPIRATION_TOKENS.) Each time it runs, the pruning job deletes archived objects and tokens for which the retention period has elapsed. If the value is 0, the prune job is disabled.

Logs and telemetry

See Logs for more information on logs and telemetry.

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_LOG_LEVEL	string	"info"	All	Log level (supports debug, info, warn, and error)
PVAULT_LOG_DATADOG_ENABLE	string	"logs,stats,config"	All	Enable Datadog logs and metrics. comma seperated list of sources (logs,audit,stats,config,none).
PVAULT_SENTRY_ENABLE	bool	true	All	Enable Sentry telemetry logging
PVAULT_LOG_CUSTOMER_IDENTIFIER	string		All	Identifies the customer in all the observability platforms
PVAULT_LOG_CUSTOMER_ENV	string		All	Identifies the environment in all the observability platforms. Recommended values are PRODUCTION, STAGING, and DEV
PVAULT_LOG_AUDIT_ENABLE	bool	true	All	Enable audit logging to stdout

TLS

See TLS for more information on configuring Piiano Vault to use TLS.

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_TLS_SELFSIGNED	bool	false	All	Whether Vault runs with a self-signed TLS key (valid for 24h)
PVAULT_TLS_ENABLE	bool	Mode dependent	All	Whether Vault listens on HTTPS (TLS). If false, Vault listens on HTTP. If PVAULT_TLS_SELFSIGNED is true, this setting is ignored and Vault listens on HTTPS.
PVAULT_TLS_CERT_FILE	string	""	All	Path to the TLS certificate file. Must be valid to enable listening on HTTPS (TLS)
PVAULT_TLS_KEY_FILE	string	""	All	Path to the TLS key file. Must be valid to enable listening on HTTPS (TLS)

Expiration

Name	Type	Default (Dev / Server)	Edition	Details
PVAULT_EXPIRATION_TOKENS	string	"" Objects don't expire	All	Default expiration time for tokens as a duration string. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
PVAULT_EXPIRATION_ASSOCIATED_OBJECTS	string	"" Objects don't expire	All	Default expiration time for associated objects as a duration string. (See the definition of a duration string in the details for PVAULT_EXPIRATION_TOKENS.)
PVAULT_EXPIRATION_UNASSOCIATED_OBJECTS	string	"" Objects don't expire	All	Default expiration time for unassociated objects as a duration string. (See the definition of a duration string in the details for PVAULT_EXPIRATION_TOKENS.)

info

The duration string is a decimal fraction with a time unit suffix, such as "300ms", "-1.5h", or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", and "h".

Docker Compose configurations

These environment variables can be used when installing Piiano Vault server using Docker Compose:

Name	Type	Default	Edition	Details
SERVER_API_PORT	int	8123	Server / ServerX	Listener port for Vault Server and of the router (Traefik) for ServerX
CONTROL_API_PORT	int	8123	ServerX	Listener port for the control plane of Vault
DATA_API_PORT	int	8123	ServerX	Listener port for the data plane of Vault
TRAEFIK_DASH_PORT	int	8080	ServerX	Listener port for the router (Traefik) dashboard