Skip to main content
Welcome to Virtru's support portal. As we work to make this page more accessible to screen readers, please contact us at support@virtru.com for technical support.

Customer Hosted: Gateway - Behind a Proxy

  • Updated

Summary

Virtru supports the Gateway deployed behind a proxy. There are two areas that require configuration to ensure traffic is properly routed through the proxy:

  1. Docker Traffic – Allows Docker to pull images via proxy
  2. Container Traffic – Allows Gateway containers to reach Virtru endpoints via proxy

Note

Gateway v2.72.0+ supports simplified proxy configuration via environment variables. For earlier versions (v2.71.0 and below), use the legacy configuration method described below.

For additional Docker proxy documentation, refer to the Docker Site.

Table of Contents

Prerequisites

Before proceeding, ensure you have:

  • Root or sudo access to the Gateway host
  • Your proxy server information:
    • Proxy IP address or hostname
    • Proxy port (HTTP and HTTPS)
  • Internal DNS server addresses (if different from default)

Docker Traffic Configuration

Docker must be configured to pull images through the proxy.

Step 1: Create HTTP Proxy Configuration File

mkdir -p /etc/systemd/system/docker.service.d
nano /etc/systemd/system/docker.service.d/http-proxy.conf

Add the following to the file (replace with your proxy address):

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:80/"

Step 2: Create HTTPS Proxy Configuration File

nano /etc/systemd/system/docker.service.d/https-proxy.conf

Add the following to the file (replace with your proxy address):

Note

Even for HTTPS_PROXY, the proxy URL typically uses http:// because the connection to the proxy itself is HTTP — the HTTPS traffic is tunneled through via CONNECT.

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:443/"

Step 3: Reload Services

Warning

Restarting Docker will briefly interrupt Gateway services.

systemctl daemon-reload
systemctl restart docker

Container Traffic Configuration

Container traffic does not follow host traffic settings and must be configured separately. Choose the appropriate section below based on your Gateway version and configuration needs.

DNS Configuration

Verify current DNS settings:

docker ps
docker exec -it <container id> cat /etc/resolv.conf

If your environment uses internal DNS servers, you'll need to configure them for the containers.

First, obtain your Docker version:

docker version

Docker Versions Less Than 17.09

Edit or create the Docker daemon configuration file:

nano /etc/docker/daemon.json

Add your DNS servers:

{ "dns": ["10.0.0.1", "10.0.0.2"] }

Note

Replace the example IPs above with your internal DNS server addresses.

Docker Versions 17.09 and Above

Update the docker run commands by editing the appropriate setup script:

cd /var/virtru/vg/scripts
ls -la

Locate the setup script for your configuration. Files follow the naming convention setup-<mode>-<port>.sh (e.g., setup-oe-9001.sh).

nano setup-<mode>-<port>.sh

Add DNS entries to the script (one line per DNS server):

--dns=10.0.0.1 \
--dns=10.0.0.2 \

Note

Replace the example IPs above with your internal DNS server addresses.

Proxy Configuration (v2.72.0+)

Recommended Method for v2.72.0+

Gateway v2.72.0 and later supports proxy configuration via the .env file. This method is recommended as it persists through container upgrades and eliminates manual container modification.

Configure Proxy via .env File

Edit the Gateway environment configuration file:

nano /var/virtru/vg/env

Add the following proxy configuration variables (replace with your proxy details):

GATEWAY_HTTP_PROXY_HOST=proxy.example.com
GATEWAY_HTTP_PROXY_PORT=80
GATEWAY_HTTPS_PROXY_HOST=proxy.example.com
GATEWAY_HTTPS_PROXY_PORT=443

Environment Variable Details

  • GATEWAY_HTTP_PROXY_HOST – HTTP proxy hostname or IP address
  • GATEWAY_HTTP_PROXY_PORT – HTTP proxy port (defaults to 80 if not specified)
  • GATEWAY_HTTPS_PROXY_HOST – HTTPS proxy hostname or IP address
  • GATEWAY_HTTPS_PROXY_PORT – HTTPS proxy port (defaults to 443 if not specified)

Note: If you only specify the host without a port, the Gateway will use default ports (80 for HTTP, 443 for HTTPS).

Apply Configuration

After updating the .env file, restart your Gateway containers to apply the changes:

cd /var/virtru/vg/scripts
./stop-<mode>-<port>.sh
./setup-<mode>-<port>.sh

For example, if you have an outbound encrypt-everything Gateway on port 9001:

./stop-oe-9001.sh
./setup-oe-9001.sh

Verify Proxy Configuration

After restarting your containers, verify the proxy settings are active:

docker logs <container id> | grep -i proxy

You should see log entries similar to:

setting http proxy http.proxyHost = proxy.example.com, http.proxyPort = 80
setting https proxy https.proxyHost = proxy.example.com, https.proxyPort = 443

Proxy Configuration (Legacy Method for v2.71.0 and Earlier)

Legacy Method - Use Only for v2.71.0 and Earlier

This method requires manual container modification and must be repeated after each Gateway upgrade. If you are running Gateway v2.72.0 or later, use the .env file method above instead.

Each Gateway container must be configured to use the proxy to contact Virtru endpoints.

Important

These steps must be repeated for each Gateway container. Settings applied via docker exec persist through container restarts, but are lost when containers are recreated (e.g., during Gateway upgrades). You will need to reapply these settings after upgrades.

Identify Containers

docker ps -a

View Current Proxy Settings

For Gateway v2.71.0 (Java 21):

docker exec -it <container id> cat /etc/java-21-openjdk/net.properties | grep -E 'http.proxy|https.proxy'

For Gateway v2.70.0 and earlier (Java 11):

docker exec -it <container id> cat /etc/java-11-openjdk/net.properties | grep -E 'http.proxy|https.proxy'

Set Proxy Host

Replace X.X.X.X with your proxy IP address.

For Gateway v2.71.0 (Java 21):

docker exec -it <container id> sed -i 's/# http.proxyHost=/http.proxyHost=X.X.X.X/g' /etc/java-21-openjdk/net.properties
docker exec -it <container id> sed -i 's/# https.proxyHost=/https.proxyHost=X.X.X.X/g' /etc/java-21-openjdk/net.properties

For Gateway v2.70.0 and earlier (Java 11):

docker exec -it <container id> sed -i 's/# http.proxyHost=/http.proxyHost=X.X.X.X/g' /etc/java-11-openjdk/net.properties
docker exec -it <container id> sed -i 's/# https.proxyHost=/https.proxyHost=X.X.X.X/g' /etc/java-11-openjdk/net.properties

Set Proxy Port

Replace X with your proxy port (e.g., 80 for HTTP or 443 for HTTPS).

For Gateway v2.71.0 (Java 21):

docker exec -it <container id> sed -i 's/# http.proxyPort=80/http.proxyPort=X/g' /etc/java-21-openjdk/net.properties
docker exec -it <container id> sed -i 's/# https.proxyPort=443/https.proxyPort=X/g' /etc/java-21-openjdk/net.properties

For Gateway v2.70.0 and earlier (Java 11):

docker exec -it <container id> sed -i 's/# http.proxyPort=80/http.proxyPort=X/g' /etc/java-11-openjdk/net.properties
docker exec -it <container id> sed -i 's/# https.proxyPort=443/https.proxyPort=X/g' /etc/java-11-openjdk/net.properties

Verify and Restart

Verify the proxy settings were applied.

For Gateway v2.71.0 (Java 21):

docker exec -it <container id> cat /etc/java-21-openjdk/net.properties | grep -E 'http.proxy|https.proxy'

For Gateway v2.70.0 and earlier (Java 11):

docker exec -it <container id> cat /etc/java-11-openjdk/net.properties | grep -E 'http.proxy|https.proxy'

Restart the container:

docker restart <container id>

Troubleshooting

Verify Proxy Connectivity

Test that the container can reach Virtru endpoints through the proxy:

docker exec -it <container id> curl -x http://proxy.example.com:80 https://api.virtru.com

Verify Proxy Environment Variables (v2.72.0+)

Check that the proxy environment variables are set correctly in the container:

docker exec -it <container id> env | grep GATEWAY_.*PROXY

You should see your configured proxy settings:

GATEWAY_HTTP_PROXY_HOST=proxy.example.com
GATEWAY_HTTP_PROXY_PORT=80
GATEWAY_HTTPS_PROXY_HOST=proxy.example.com
GATEWAY_HTTPS_PROXY_PORT=443

Verify .env File Configuration (v2.72.0+)

Check that the .env file contains your proxy settings:

cat /var/virtru/vg/env | grep PROXY

Log Locations

  • Container logs: docker logs <container id>

  • Proxy configuration logs: Check container startup logs for proxy-related messages:

    docker logs <container id> | grep -i proxy

Related articles