In this article, we'll walk you through the environment variables that configure the Virtru Customer Hosted Gateway Docker image. Most deployments only need the required variables. The rest support specific mail-flow, security, and logging needs. You can update any of them to fit your organization. Variables are split into two categories: SMTP variables and Virtru variables.
Jump to:
SMTP Variables
These variables control how the Gateway receives, processes, and sends email.
Please note:
Earlier versions of this article listed GATEWAY_SMTPD_SASL_ENABLED_UPSTREAM. The Gateway doesn't read that variable. To require authentication from servers that connect to the Gateway, use GATEWAY_SMTPD_SASL_ENABLED.
| Variable | Description | Details |
|---|---|---|
GATEWAY_HOSTNAME |
Hostname of the Gateway. It must match the common name (CN) on the Gateway's Transport Layer Security (TLS) certificate. | Required: Yes |
GATEWAY_RELAY_ADDRESSES |
Comma-separated list of trusted networks, in Classless Inter-Domain Routing (CIDR) notation, that can connect to the Gateway. For Gmail and Microsoft 365 starting values, see Reference: Kubernetes Variables. | Required: Yes Example: 2.2.2.2/32,2.2.2.3/32
|
GATEWAY_RELAY_DOMAINS |
Comma-separated list of domains the Gateway relays mail for. | Required: No Example: example.com,example.net
|
GATEWAY_SMTP_ALLOW_DOMAINS |
Restricts the domains the Gateway accepts mail for. The restriction applies in both inbound and outbound modes. Use a comma-separated list with no spaces and no @ prefix. |
Required: No Example: example.com,example.orgApplies to both inbound and outbound modes in v2.79.0 and later. |
GATEWAY_TRANSPORT_MAPS |
Next-hop destinations, as a comma-separated list of domain=>host rules with optional ports. Use * to match all domains. If you don't set it, the Gateway delivers mail directly to each recipient's mail exchanger (MX). |
Required: No Example: *=>[smtp-relay.gmail.com]:587
|
GATEWAY_PROXY_PROTOCOL |
Enables PROXY protocol for SMTP. Set it to 1 only when a load balancer in front of the Gateway sends PROXY protocol. Most deployments use 0. |
Default: 1Values: 0, 1
|
GATEWAY_DKIM_DOMAINS |
DomainKeys Identified Mail (DKIM) signing records, as a comma-separated list. Each value is the full record name: selector._domainkey.domain. This helps with email validation and delivery. |
Required: No Example: gw._domainkey.example.com
|
GATEWAY_HEADER_ALLOW_RULES |
Comma-separated list of header and value pairs used to allow mail downstream. | Required: No |
GATEWAY_XHEADER_AUTH_ENABLED |
Requires every message sent to the Gateway to carry the X-Header-Virtru-Auth header with the shared secret. |
Default: 0Values: 0 (disabled), 1 (enabled) |
GATEWAY_XHEADER_AUTH_SECRET |
The shared secret the Gateway expects in the X-Header-Virtru-Auth header. |
Required only when GATEWAY_XHEADER_AUTH_ENABLED=1Example header: X-Header-Virtru-Auth=123456789
|
GATEWAY_SMTPD_SASL_ENABLED |
Requires mail servers that connect to the Gateway (upstream) to authenticate with Simple Authentication and Security Layer (SASL). The container won't start if you enable this without setting accounts. | Default: 0Values: 0, 1
|
GATEWAY_SMTPD_SASL_ACCOUNTS |
Credentials that upstream mail servers use to authenticate to the Gateway, as a comma-separated list. | Format: user1=>password1,user2=>password2Used only when GATEWAY_SMTPD_SASL_ENABLED=1
|
GATEWAY_SMTPD_SASL_MECHANISMS |
Space-separated list of SASL mechanisms the Gateway accepts from upstream servers. | Default: CRAM-MD5 DIGEST-MD5Values: PLAIN, LOGIN, CRAM-MD5, DIGEST-MD5
|
GATEWAY_SMTP_SASL_ENABLED_DOWNSTREAM |
Makes the Gateway authenticate with SASL when it connects to the next-hop (downstream) mail server. | Default: 0Values: 0, 1
|
GATEWAY_SMTP_SASL_ACCOUNTS |
Credentials the Gateway uses for each next-hop server. Each entry is keyed by the next-hop host, not by recipient domain. A host entry also matches host:port, but a host:port entry matches only that port. |
Format: host[:port]=>user=>password, comma-separatedUsed only when GATEWAY_SMTP_SASL_ENABLED_DOWNSTREAM=1
|
GATEWAY_SMTP_SASL_SECURITY_OPTIONS |
Postfix SMTP client SASL security options for downstream authentication. | Default: noanonymousUsed only when GATEWAY_SMTP_SASL_ENABLED_DOWNSTREAM=1
|
GATEWAY_SMTPD_USE_TLS |
Enables TLS for connections into the Gateway. | Default: 1Values: 0, 1
|
GATEWAY_SMTPD_SECURITY_LEVEL |
Minimum transport security for connections into the Gateway. | Default: opportunistic (mandatory on the Federal Information Processing Standards (FIPS) image)Values: mandatory, opportunisticUsed only when GATEWAY_SMTPD_USE_TLS=1
|
GATEWAY_SMTPD_TLS_COMPLIANCE_UPSTREAM |
TLS compliance level for connections into the Gateway. We recommend HIGH. See Recommended TLS Settings. |
Required: No Value: HIGH
|
GATEWAY_SMTPD_TLS_LOGLEVEL |
TLS log level for connections into the Gateway. | Default: 2Values: 0 through 4
|
GATEWAY_SMTP_USE_TLS |
Enables TLS for connections the Gateway makes to other servers. | Default: 1Values: 0, 1
|
GATEWAY_SMTP_SECURITY_LEVEL |
Minimum transport security for connections from the Gateway. | Default: opportunistic (mandatory on the FIPS image)Values: mandatory, opportunisticUsed only when GATEWAY_SMTP_USE_TLS=1
|
GATEWAY_SMTP_TLS_COMPLIANCE_DOWNSTREAM |
TLS compliance level for connections from the Gateway. We recommend HIGH. See Recommended TLS Settings. |
Required: No Value: HIGH
|
GATEWAY_SMTP_TLS_LOGLEVEL |
TLS log level for connections from the Gateway. | Default: 1Values: 0 through 4
|
GATEWAY_SMTP_TLS_POLICY_MAPS |
Per-domain outbound TLS requirements, as a comma-separated list of domains and the requirement for each. | Required: No Example: example.com=>none,example.net=>maybe
|
GATEWAY_SMTP_CACHE_CONNECTIONS |
Whether to cache outgoing connections to mail servers. 1 caches on demand, 0 turns caching off, and a list of domains caches per destination. |
Default: 1Example: example.org,hotmail.com,gmail.com
|
GATEWAY_SMTP_CONNECTION_CACHE_TIME_LIMIT |
How long to cache an SMTP connection, in Postfix time units (s, m, h, d). |
Default: 2sExample: 5m
|
GATEWAY_VERBOSE_LOGGING |
Enables verbose Postfix logging. Leave it at 0 unless you're troubleshooting. |
Default: 0Values: 0, 1
|
GATEWAY_LOG_LEVEL |
Minimum level of Gateway application log messages to display. | Default: infoValues: info, warn, debug
|
MAX_QUEUE_LIFETIME |
How long a message can stay in the queue after temporary delivery failures before it's returned as undeliverable. Set it to 0 to try delivery only once. Time units: s (seconds), m (minutes), h (hours), d (days). |
Default: 5dRecommended: 5m
|
MAX_BACKOFF_TIME |
Maximum time between delivery attempts for a deferred message. Set it to a value greater than or equal to MIN_BACKOFF_TIME. |
Default: 4000sRecommended: 45s
|
MIN_BACKOFF_TIME |
Minimum time between delivery attempts for a deferred message. | Default: 300sRecommended: 30s
|
QUEUE_RUN_DELAY |
Time between scans of the deferred queue. | Default: 300sRecommended: 30s
|
GATEWAY_JVM_INITIAL_HEAP_SIZE |
Initial Java heap size, in bytes or with a k, m, or g suffix. Leave it empty to keep the default. |
Example: 256m
|
GATEWAY_JVM_MAX_HEAP_SIZE |
Maximum Java heap size, in bytes or with a k, m, or g suffix. Leave room for non-heap memory within the container's memory limit. Leave it empty to keep the default. |
Example: 1g
|
GATEWAY_JVM_HEAP_DUMP_ON_OOM |
Writes a heap dump when the Java heap runs out of memory. Leave it empty to keep the default. | Values: true, false
|
GATEWAY_JVM_HEAP_DUMP_PATH |
Writable directory or file name for heap dumps. It doesn't turn on heap dumps by itself. | Example: /tmp
|
Virtru Variables
These variables control how the Gateway encrypts and decrypts with Virtru.
| Variable | Description | Details |
|---|---|---|
GATEWAY_ORGANIZATION_DOMAIN |
Your organization's primary email domain. | Required: Yes Example: example.com
|
GATEWAY_MODE |
The Gateway's mode. dlp applies the Security Rules your organization has set up. |
Default: encrypt-everythingRequired: Yes Values: encrypt-everything, decrypt-everything, dlp
|
GATEWAY_TOPOLOGY |
Whether the Gateway processes outbound or inbound mail. | Default: outboundRequired: Yes Values: outbound, inbound
|
GATEWAY_API_TOKEN_NAME |
Name of the hash-based message authentication code (HMAC) token that authenticates the Gateway to Virtru. | Required: Yes Contact Virtru Support to get your token. |
GATEWAY_API_TOKEN_SECRET |
Secret for the HMAC token that authenticates the Gateway to Virtru. | Required: Yes Contact Virtru Support to get your token. |
GATEWAY_AMPLITUDE_API_KEY |
Amplitude token used to authenticate the Virtru tenant in Amplitude. Amplitude is an events platform used to store general performance metrics. | Required: Yes Virtru sends you this value during onboarding. If you don't have it, contact Virtru Support. |
GATEWAY_ACCOUNTS_URL |
URL of Virtru's Accounts service. Don't change it. | Required: Yes Value: https://api.virtru.com/accounts
|
GATEWAY_ACM_URL |
URL of Virtru's Access Control Manager (ACM) service. Don't change it. | Required: Yes Value: https://api.virtru.com/acm
|
GATEWAY_REMOTE_CONTENT_BASE_URL |
Base URL for remote content. Don't change it unless we direct you to. If your organization uses a custom Secure Reader URL, this value must match it. | Required: Yes Value: https://secure.virtru.com/start/
|
GATEWAY_DLP_CACHE_DURATION |
The interval of time between refreshing the Security Rules. To refresh on every request, set it to 0. |
Default: 30Minimum: 0Required: No Values: number in minutes |
GATEWAY_DECRYPT_PERSISTENT_PROTECTED_ATTACHMENTS |
Decrypt mode only. Set it to 1 to decrypt attachments that have persistent protection. When it's off, those attachments arrive as links that open in Secure Reader. |
Default: 0Values: 0, 1
|
GATEWAY_DECRYPT_THEN_ENCRYPT |
Set it to 1 on both Gateways when your mail flow decrypts, scans, and then re-encrypts messages. |
Default: 0Values: 0, 1
|
GATEWAY_REPLACEMENT_FROM_ENABLED |
Inbound topology only. Rewrites the From address so the Gateway can support DKIM. | Default: 1Values: 0, 1
|
GATEWAY_DKIM_REMOVE_ENABLED |
Inbound topology only. Removes DKIM headers from processed messages. | Default: 1Values: 0, 1
|
GATEWAY_ROUTING_XHEADERS |
SMTP X-Headers the Gateway adds to every message it processes, as a comma-separated list. | Example: X-Header-1: value1, X-Header-2: value2
|
GATEWAY_HEADER_REWRITES |
Comma-separated header rewrite rules in the form <field to rewrite>: <if this content is present> => <with this field>. For example, From: secure-reply@virtru.com => Reply-To replaces the contents of the From header with the contents of the Reply-To header when From contains secure-reply@virtru.com. To always rewrite, leave out the content part: From => Reply-To. |
Example: GATEWAY_HEADER_REWRITES=From: secure-reply@virtru.com => Reply-To
|
GATEWAY_ENCRYPTION_KEY_PROVIDER |
The source of encryption keys. To use the Virtru Private Keystore (for Virtru Solutions), set it to CKS. |
Required for inbound modes Example: CKS
|
GATEWAY_CKS_SESSION_KEY_EXPIRY_IN_MINS |
How long, in minutes, each CKS session key lasts. | Default: 360
|
GATEWAY_HTTP_PROXY_HOST |
HTTP proxy hostname or IP address the Gateway uses to reach Virtru. The setting persists through container upgrades. Available in Gateway v2.72.0 and later. For details, see Customer Hosted: Gateway - Behind a Proxy. | Required: No Example: proxy.example.com
|
GATEWAY_HTTP_PROXY_PORT |
HTTP proxy port. Used only when GATEWAY_HTTP_PROXY_HOST is set. |
Default: 80Required: No |
GATEWAY_HTTPS_PROXY_HOST |
HTTPS proxy hostname or IP address the Gateway uses to reach Virtru. The setting persists through container upgrades. Available in Gateway v2.72.0 and later. | Required: No Example: proxy.example.com
|
GATEWAY_HTTPS_PROXY_PORT |
HTTPS proxy port. Used only when GATEWAY_HTTPS_PROXY_HOST is set. |
Default: 443Required: No |
Recommended TLS Settings
We recommend one of two configurations.
Forced TLS (recommended). This setting requires TLS with a strong set of ciphers on every connection into and out of the Gateway. Set all of these variables:
Forced TLS configuration
# .env (excerpt)
GATEWAY_SMTPD_USE_TLS=1
GATEWAY_SMTPD_SECURITY_LEVEL=mandatory
GATEWAY_SMTPD_TLS_COMPLIANCE_UPSTREAM=HIGH
GATEWAY_SMTP_USE_TLS=1
GATEWAY_SMTP_SECURITY_LEVEL=mandatory
GATEWAY_SMTP_TLS_COMPLIANCE_DOWNSTREAM=HIGH
Defaults. Leave the TLS variables unset. The Gateway uses TLS when the other server supports it.
Please note:
Upstream settings (SMTPD) apply to connections into the Gateway. Downstream settings (SMTP) apply to connections the Gateway makes. The FIPS image (gateway-fips) requires TLS by default. You're still responsible for following other National Institute of Standards and Technology (NIST) and Open Worldwide Application Security Project (OWASP) recommendations, such as using signed certificates and rotating keys regularly.