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. Environment variables are cached in instances of Vault, meaning that environment variable changes don't affect all instances immediately. See metadata caching for more information.
info
The Set configuration variable REST API operation 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) | Details |
|---|---|---|---|
| PVAULT_SERVICE_LICENSE | string | none | 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
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.
| Name | Type | Default | Details |
|---|---|---|---|
| PVAULT_DEVMODE | bool | true for pvault-devfalse 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.
| Name | Default when PVAULT_DEVMODE is true | Default when PVAULT_DEVMODE is false |
|---|---|---|
| PVAULT_FEATURES_DISABLE_DOCS | true | false |
| PVAULT_SERVICE_ADMIN_MAY_READ_DATA | true | false |
| PVAULT_SERVICE_ALLOW_ORIGINS | "*" | "" |
| PVAULT_TLS_ENABLE | false | true |
| PVAULT_DB_REQUIRE_TLS | false | true |
| PVAULT_KMS_ALLOW_LOCAL | true | false |
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.
| Name | Type | Default (Dev / Server) | Details |
|---|---|---|---|
| PVAULT_DB_HOSTNAME | string | "localhost" | Hostname of the running database |
| PVAULT_DB_NAME | string | "pvault" | Name of the database to connect to |
| PVAULT_DB_USER | string | "pvault" | Username for the database |
| PVAULT_DB_PASSWORD | string | "pvault" | Password for the database |
| PVAULT_DB_PORT | int | 5432 | Port of the running database |
| PVAULT_DB_REQUIRE_TLS | bool | Mode dependent | 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 | 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 | 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 | 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 | The 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_LENGTH | int | 5242880 | The maximum length of data types based on blobs. |
| PVAULT_DB_MAX_TOKEN_TAGS | int | 10 | The maximum amount of tags per token |
| PVAULT_DB_MIGRATION_AUTO_RUN | bool | true | Whether Vault sets up the database during migration. Set to false when performing the database migration externally |
| PVAULT_DB_MIGRATION_ENABLE_CLEAN_DATABASE_VALIDATION | bool | true | Whether 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_PERIOD | string | 720h | 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. |
| PVAULT_DB_READ_REPLICA_HOSTNAME | string | "" | Hostname of the read replica database, which helps reduce the load on the primary database instance for some operations. Requires PVAULT_DB_READ_REPLICA_PORT to be set, otherwise is ignored. Optional. |
| PVAULT_DB_READ_REPLICA_PORT | int | "" | Port of the read replica database. Is required if PVAULT_DB_READ_REPLICA_HOSTNAME is set. |
Stateless mode
| Name | Type | Default | Details |
|---|---|---|---|
| PVAULT_BACKING_STORE | string | psql | The backing store for Vault:
|
| PVAULT_GENERATE_SECRETS | bool | false | Whether 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.
| Name | Type | Default (Dev / Server) | Details |
|---|---|---|---|
| PVAULT_KMS_URI | string | "" | The KMS key URI used for property encryption |
| PVAULT_KMS_SEED | string | "" | Generate a local KMS using this seed (KMS_URI can be unset) |
| PVAULT_KMS_EXPORT_URI | string | "" | The KMS key URI used for encryption by the Vault export procedure. See data import and export for more details. |
| PVAULT_KMS_EXPORT_SEED | string | "" | 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_LOCAL | bool | Mode dependent | Whether 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.
| Name | Type | Default (Dev / Server) | Details |
|---|---|---|---|
| PVAULT_SERVICE_LISTEN_ADDR | string | "0.0.0.0:8123" | Listener address of Vault |
| PVAULT_SERVICE_ADMIN_API_KEY | string | "pvaultauth" | The admin API key for authentication |
| PVAULT_SERVICE_COMPONENTS | string | "data,control" | The Vault components to run on this instance. By default, data and control are enabled, and the instance runs as described by the server container architecture. |
| PVAULT_SERVICE_WORKER_PRIORITY | int | 10 for Dev / Server, 20 for Data-only | When running in a cluster with multiple Vault instances, the Vault instance priority in picking up the background job. The value must be greater than 0. Set this configuration only when instructed by the Piiano team. |
| PVAULT_SERVICE_OVERRIDE_ADMIN_API_KEY_ON_RESTART | bool | true | Weather to override the admin API key when Vault restarts. Default is true. |
| PVAULT_SERVICE_ALLOW_ORIGINS | string | Mode dependent | 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 relevant 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_ONLY | bool | false | Whether to load the IAM configuration file every time Vault starts. |
| PVAULT_SERVICE_UPDATE_SCHEMA_ON_START | bool | false | Whether to load the types configuration file and the collections configuration file every time Vault starts. |
| PVAULT_SERVICE_FORCE_ACCESS_REASON | bool | true | Whether Vault requires a valid access reason to be provided with calls |
| PVAULT_SERVICE_ADMIN_MAY_READ_DATA | bool | Mode dependent | Whether Admin is allowed to read data |
| PVAULT_SERVICE_PCI_RESTRICTIONS | bool | false | Whether Vault runs with PCI restrictions |
| PVAULT_FEATURES_ENCRYPTION | bool | true | Whether 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_LICENSE | bool | false | Whether Vault's service license is masked when retrieved using Get license API or Get license CLI |
| PVAULT_FEATURES_DISABLE_DOCS | bool | Mode dependent | Whether Vault serves the documentation on the /docs path. |
| PVAULT_FEATURES_DISABLE_JAVASCRIPT | bool | false | Whether 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_DISABLE_IDP_JWKS | bool | false | Whether Vault allows IAM IDP (direct-jwt) to use JWKS URI to fetch the cryptographic keys for JWT validation. Note, this feature requires Vault to have outbound access to the JWKS endpoint. |
| PVAULT_FEATURES_DISABLE_CC_LUHN_VALIDATION | bool | false | Whether Vault validates values of CC_NUMBER data type to ensure they pass a Luhn algorithm check. |
| PVAULT_FEATURES_ANTI_TAMPERING | string | log | Supported values are off, log, and enforce. See Anti-Tampering modes for more information. |
| PVAULT_SERVICE_TIMEOUT_SECONDS | float | 30 | Timeout in seconds for REST API calls |
| PVAULT_SERVICE_DEFAULT_PAGE_SIZE | int | 100 | 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 | 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_MAX_PAGINATION_REMAINING_COUNT | int | 100000 | The 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_INTERVAL | string | 30s | 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_CACHE_REFRESH_TIMEOUT | string | 15s | The timeout for the cache refreshing task. |
| PVAULT_SERVICE_ARCHIVE_PRUNE_INTERVAL | string | 0 | 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. |
| PVAULT_SERVICE_ARCHIVE_PRUNE_TIMEOUT | string | 15s | The timeout for the prune job. |
| PVAULT_SERVICE_SUBSTRING_INDEX_REFRESH_INTERVAL | string | 10s | The refresh interval for the substring index. See Substring search objects for more details. If this value is zero, the substring query feature is disabled. |
| PVAULT_SERVICE_ALLOWED_HTTP_DESTINATIONS | string | "" | A comma-separated list of destinations the http_call action is allowed to call with non-PCI data types. 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_ALLOWED_PCI_HTTP_DESTINATIONS | string | "" | A comma-separated list of destinations the http_call action is allowed to call with PCI data types. 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_ROLE | string | "VaultHTTPCallAction" | The role for the http_call built-in action. |
Logs and telemetry
See Logs for more information on logs and telemetry.
| Name | Type | Default (Dev / Server) | Details |
|---|---|---|---|
| PVAULT_LOG_LEVEL | string | "info" | Log level (supports debug, info, warn, and error). |
| PVAULT_LOG_DATADOG_ENABLE | string | Self hosted: "logs,stats,config" SaaS: "logs,stats,audit,config" | Enable Datadog logs and metrics. Takes a comma-separated list of sources, being all or a subset of logs, audit, stats, and config. To disable all logging and metrics, set it to none. However, be aware that this will significantly limit Piiano's ability to support your deployment and may impact troubleshooting. |
| PVAULT_SENTRY_ENABLE | bool | true | Enable Sentry telemetry logging. |
| PVAULT_LOG_CUSTOMER_IDENTIFIER | string | "" | Identifies the customer in all the observability platforms. |
| PVAULT_LOG_CUSTOMER_ENV | string | "" | Identifies the environment in all the observability platforms. Recommended values are PRODUCTION, STAGING, and DEV |
| PVAULT_LOG_CUSTOMER_REGION | string | "" | Identifies the region for this environment in all the observability platforms. Examples: us-east-1, europe-west1 |
| PVAULT_LOG_AUDIT_ENABLE | bool | true | Enable audit logs. |
| PVAULT_LOG_AUDIT_REMOTE_ADDR_ENABLE | bool | false | Enable remote address (IP) logging in the audit logs. |
| PVAULT_LOG_AUDIT_REMOTE_ADDR_XFF | bool | false | Add the remote address parsed from the X-Forwarded-For header to the audit logs. Should be set to true only if the proxy or load balancer forwarding the request is trusted. |
| PVAULT_LOG_AUDIT_DELETE_TOKENS_DISABLE | bool | false | Disable auditing of token deletions. Set this parameter to true if you have objects that own a lot of tokens that are being deleted regularly. |
| PVAULT_LOG_DESTINATION | string | stdout | Destination for request logs and audit logs (supports stdout and stderr). |
TLS
See TLS for more information on configuring Piiano Vault to use TLS.
| Name | Type | Default (Dev / Server) | Details |
|---|---|---|---|
| PVAULT_TLS_SELFSIGNED | bool | false | Whether Vault runs with a self-signed TLS key (valid for 1 year) |
| PVAULT_TLS_ENABLE | bool | Mode dependent | 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 | "" | Path to the TLS certificate file. Must be valid to enable listening on HTTPS (TLS) |
| PVAULT_TLS_KEY_FILE | string | "" | 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.
| Name | Type | Default (Dev / Server) | Details |
|---|---|---|---|
| PVAULT_EXPIRATION_TOKENS | string | "" 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_OBJECTS | string | "" 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_OBJECTS | string | "" 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".
IAM secrets replacement
For security reasons, sensitive values such as passwords, symmetric keys, etc., should not be defined directly in the IAM configuration file. Instead, use IAM secret replacement to reference sensitive secrets.
Environment variables following the pattern PVAULT_SECRETS_IAM_<env_name> can be referenced in the IAM configuration as ${secret:<env_name>}.
note
Secret replacement is supported only for IAM JWT IDP keys configuration field.
See the JWT IDP configuration guide for usage example.