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
| 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_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. |
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_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_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_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_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_ALLOWED_HTTP_DESTINATIONS | string | "" | 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_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 | "logs,stats,config" | Enable Datadog logs and metrics. comma separated list of sources (logs,audit,stats,config,none). |
| 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 logging to stdout |
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 24h) |
| 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".
Docker Compose configurations
These environment variables can be used when installing Piiano Vault server using Docker Compose:
| Name | Type | Default | Details |
|---|---|---|---|
| SERVER_API_PORT | int | 8123 | Listener port for Vault Server and of the router (Traefik) for ServerX |
| CONTROL_API_PORT | int | 8123 | Listener port for the control plane of Vault |
| DATA_API_PORT | int | 8123 | Listener port for the data plane of Vault |
| TRAEFIK_DASH_PORT | int | 8080 | Listener port for the router (Traefik) dashboard |