Skip to main content

Environment variables

Learn how to configure Piiano Vault using environment variables

note

If you're using the hosted version of Vault, you cannot amend the values of environment variables and your Vault uses the default values listed. If you need alter environment variables values, contact us.

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

NameTypeDefault (Dev / Server)Details
PVAULT_SERVICE_LICENSEstringnoneA 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

note

If you're using the hosted version of Vault, you cannot amend the values of environment variables and your Vault uses the default values listed. If you need alter environment variables values, contact us.

NameTypeDefaultDetails
PVAULT_DEVMODEbooltrue for pvault-dev

false otherwise
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.

NameDefault when PVAULT_DEVMODE is trueDefault when PVAULT_DEVMODE is false
PVAULT_SERVICE_ADMIN_MAY_READ_DATAtruefalse
PVAULT_TLS_ENABLEfalsetrue
PVAULT_DB_REQUIRE_TLSfalsetrue
PVAULT_KMS_ALLOW_LOCALtruefalse

Database

note

If you're using the hosted version of Vault, you cannot amend the values of environment variables and your Vault uses the default values listed. If you need alter environment variables values, contact us.

NameTypeDefault (Dev / Server)Details
PVAULT_DB_HOSTNAMEstring"localhost"Hostname of the running database
PVAULT_DB_NAMEstring"pvault"Name of the database to connect to
PVAULT_DB_USERstring"pvault"Username for the database
PVAULT_DB_PASSWORDstring"pvault"Password for the database
PVAULT_DB_PORTint5432Port of the running database
PVAULT_DB_REQUIRE_TLSboolMode dependentVault 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_CONNSint16Maximum number of open connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_IDLE_CONNSint16Maximum 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_MINUTESint5The 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_LENGTHint64The maximum length of data types based on strings, including STRING, NAME, GENDER, CC_HOLDER_NAME, US_BANK_ACCOUNT_NUMBER, and TENANT_ID.
PVAULT_DB_MAX_BLOB_LENGTHint5242880The maximum length of data types based on blobs.
PVAULT_DB_MAX_TOKEN_TAGSint10The maximum amount of tags per token
PVAULT_DB_MIGRATION_AUTO_RUNbooltrueWhether Vault sets up the database during migration. Set to false when performing the database migration externally
PVAULT_DB_MIGRATION_ENABLE_CLEAN_DATABASE_VALIDATIONbooltrueWhether Vault validates on first startup if there are other applications that uses the database, by checking for tables and views that are not built-in with Postgres installation
PVAULT_DB_GC_RETENTION_PERIODstring720hThe 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

NameTypeDefaultDetails
PVAULT_BACKING_STOREstringpsqlThe backing store for Vault:
PVAULT_GENERATE_SECRETSboolfalseWhether to generate secrets for stateless operation. Only applicable when PVAULT_BACKING_STORE is set to none. See Create secrets and tokens in the Run Vault in stateless mode guide for details

Key management service

note

If you're using the hosted version of Vault, you cannot amend the values of environment variables and your Vault uses the default values listed. If you need alter environment variables values, contact us.

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.

NameTypeDefault (Dev / Server)Details
PVAULT_KMS_URIstring""The KMS key URI used for property encryption
PVAULT_KMS_SEEDstring""Generate a local KMS using this seed (KMS_URI can be unset)
PVAULT_KMS_EXPORT_URIstring""The KMS key URI used for encryption by the Vault export procedure. See data import and export for more details.
PVAULT_KMS_EXPORT_SEEDstring""The seed for generating a local KMS for the Vault export procedure (KMS_EXPORT_URI can be unset). See data import and export for more details.
PVAULT_KMS_ALLOW_LOCALboolMode dependentWhether to use a local KMS. When enabled, set PVAULT_KMS_SEED

Service and features

note

If you're using the hosted version of Vault, you cannot amend the values of environment variables and your Vault uses the default values listed. If you need alter environment variables values, contact us.

NameTypeDefault (Dev / Server)Details
PVAULT_SERVICE_LISTEN_ADDRstring"0.0.0.0:8123"Listener address of Vault
PVAULT_SERVICE_ADMIN_API_KEYstring"pvaultauth"The admin API key for authentication
PVAULT_SERVICE_ALLOW_ORIGINSstring""Comma separated list of origins or a single wildcard ("*") that define which origins are allowed to call the vault from the browser. The vault will return relavant CORS headers when called from these origins. Note, wildcard option can not be used when PVAULT_DEVMODE is 'false'
PVAULT_SERVICE_SET_IAM_ON_START_ONLYboolfalseWhether to load the IAM configuration file every time Vault starts.
PVAULT_SERVICE_UPDATE_SCHEMA_ON_STARTboolfalseWhether to load the types configuration file and the collections configuration file every time Vault starts.
PVAULT_SERVICE_FORCE_ACCESS_REASONbooltrueWhether Vault requires a valid access reason to be provided with calls
PVAULT_SERVICE_ADMIN_MAY_READ_DATAboolMode dependentWhether Admin is allowed to read data
PVAULT_SERVICE_PCI_RESTRICTIONSboolfalseWhether Vault runs with PCI restrictions
PVAULT_FEATURES_ENCRYPTIONbooltrueWhether to store all properties unencrypted when in development mode ( PVAULT_DEVMODE is 'true'). Ignored in production (PVAULT_DEVMODE is 'false'): in production, properties set as is_encrypted are always stored encrypted.
PVAULT_FEATURES_MASK_LICENSEboolfalseWhether Vault's service license is masked when retrieved using Get license API or Get license CLI
PVAULT_FEATURES_DISABLE_JAVASCRIPTboolfalseWhether Vault compiles and runs JavaScript functions (in the validators, normalizers, and transformers provided in bundler) or returns an error when these are invoked.
PVAULT_FEATURES_ANTI_TAMPERINGstringlogSupported values are off, log, and enforce. See Anti-Tampring modes for more information.
PVAULT_SERVICE_TIMEOUT_SECONDSfloat30Timeout in seconds for REST API calls
PVAULT_SERVICE_DEFAULT_PAGE_SIZEint100The 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_SIZEint1000The 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_MAX_PAGINATION_REMAINING_COUNTint100000The maximum remaining count that returns in pagination. Use a lower figure to improve performance. Use a higher figure to improve the accuracy of the count returned by a query in a large-scale Vault.
PVAULT_SERVICE_CACHE_REFRESH_INTERVALstring30sThe 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_INTERVALstring0The 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.
PVAULT_SERVICE_ALLOWED_HTTP_DESTINATIONSstring""A comma-separated list of destinations the http_call action is allowed to call. Each destination must be a valid base URL. When PVAULT_DEVMODE is false only destinations with the https scheme are allowed, while in development mode calls can be made to URLs using the HTTP scheme.
PVAULT_SERVICE_ACTIONS_HTTP_CALL_ROLEstring"VaultHTTPCallAction"The role for the http_call built-in action.

Logs and telemetry

See Logs for more information on logs and telemetry.

NameTypeDefault (Dev / Server)Details
PVAULT_LOG_LEVELstring"info"Log level (supports debug, info, warn, and error)
PVAULT_LOG_DATADOG_ENABLEstring"logs,stats,config"Enable Datadog logs and metrics. comma separated list of sources (logs,audit,stats,config,none).
PVAULT_SENTRY_ENABLEbooltrueEnable Sentry telemetry logging
PVAULT_LOG_CUSTOMER_IDENTIFIERstring Identifies the customer in all the observability platforms
PVAULT_LOG_CUSTOMER_ENVstring Identifies the environment in all the observability platforms. Recommended values are PRODUCTION, STAGING, and DEV
PVAULT_LOG_AUDIT_ENABLEbooltrueEnable audit logging to stdout

TLS

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

NameTypeDefault (Dev / Server)Details
PVAULT_TLS_SELFSIGNEDboolfalseWhether Vault runs with a self-signed TLS key (valid for 24h)
PVAULT_TLS_ENABLEboolMode dependentWhether 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_FILEstring""Path to the TLS certificate file. Must be valid to enable listening on HTTPS (TLS)
PVAULT_TLS_KEY_FILEstring""Path to the TLS key file. Must be valid to enable listening on HTTPS (TLS)

Expiration

note

If you're using the hosted version of Vault, you cannot amend the values of environment variables and your Vault uses the default values listed. If you need alter environment variables values, contact us.

NameTypeDefault (Dev / Server)Details
PVAULT_EXPIRATION_TOKENSstring""
Objects don't expire
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_OBJECTSstring""
Objects don't expire
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_OBJECTSstring""
Objects don't expire
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:

NameTypeDefaultDetails
SERVER_API_PORTint8123Listener port for Vault Server and of the router (Traefik) for ServerX
CONTROL_API_PORTint8123Listener port for the control plane of Vault
DATA_API_PORTint8123Listener port for the data plane of Vault
TRAEFIK_DASH_PORTint8080Listener port for the router (Traefik) dashboard