Configure NGINX Instance Manager to use a forward proxy

Overview

This guide explains how to configure NGINX Instance Manager to use a third-party forward proxy for outbound internet access. Many organizations require a proxy for security and compliance, restricting direct internet connections. This feature allows NGINX Instance Manager to send outbound traffic, such as license verification, telemetry, and updates, through a configured HTTP or HTTPS proxy.

Before you begin

Ensure you have:

• NGINX Instance Manager 2.19 or later
• Access to a configured HTTP or HTTPS forward proxy
• Permissions to modify /etc/nms/nms.conf
• Proxy authentication credentials, if required

Important considerations:

Proxy SSL verification

• proxy_ssl_verify applies only when proxy_protocol is set to https.
• If not explicitly set, proxy_ssl_verify defaults to true. The proxy’s root CA certificate must be in the system’s trusted CA store for verification to succeed.
• To disable SSL verification, set proxy_ssl_verify: false (not recommended).

OpenShift limitation for HTTPS forward proxies

On OpenShift, pods run as non-root users, which prevents the use of update-ca-certificates or update-ca-trust to add custom CA certificates for HTTPS forward proxies. As a result, HTTPS proxy configurations (with or without authentication) may not work if the proxy requires a trusted CA certificate.

Workarounds:

• Recommended: Use an HTTP proxy instead of HTTPS.
• Alternative (not recommended): Disable certificate verification by setting proxy_ssl_verify: false, which allows connections to proxies with untrusted or self-signed certificates.

Feature limitations

• Mutual TLS (mTLS) authentication is not supported.
• OpenID Connect (OIDC) authentication is not supported in forward-proxy mode.
• OpenTelemetry (OTel) telemetry is not supported in forward-proxy mode.

Proxy configuration parameters

The following table describes the available proxy configuration parameters in /etc/nms/nms.conf:

Configure the forward proxy

VM or bare-metal

In a VM or bare-metal deployment, configure a forward proxy by updating the nms.conf file on the NGINX Instance Manager host.

To configure a forward proxy:

1. Edit the /etc/nms/nms.conf file.

2. Add or modify the proxy_config section to include the proxy configuration:

   proxy_config:
       proxy_enable: true
       proxy_host: <proxy-ip>
       proxy_port: <proxy-port>
       proxy_protocol: [http|https]
       proxy_auth_required: [true|false]
       proxy_ssl_verify: [true|false]
   

   • If the proxy requires authentication, set proxy_auth_required to true, and add the following fields:

        proxy_username: "<username>"
        proxy_password: "<password>"
     

   • Set proxy_protocol to either http or https, depending on your proxy type.

   • If not explicitly set, proxy_ssl_verify defaults to true, meaning the proxy must have a valid certificate from a trusted Certificate Authority (CA). Note: This setting applies only when proxy_protocol is https.

     If the proxy uses a self-signed or untrusted certificate, you have two options:

     • Recommended: Follow the steps in the Trust proxy certificates section to add the proxy’s CA certificate to the system’s trusted store.
     • Alternative (not recommended): Disable SSL verification by setting proxy_ssl_verify=false, which allows connections to proxies with untrusted or self-signed certificates.

3. Save the configuration file.

4. Restart NGINX Instance Manager to apply changes:

   sudo systemctl restart nms
   

Kubernetes

In a Kubernetes deployment, configure a forward proxy by modifying the nms-conf ConfigMap.

To edit the ConfigMap, run:

kubectl edit cm nms-conf -n <namespace>

• Replace <namespace> with the namespace where NGINX Instance Manager is installed.
• Update the proxy_config section to match your proxy settings. See the examples under “Configure the forward proxy”.

Docker Compose

If you’re deploying NGINX Instance Manager with Docker Compose, update the docker-compose.yaml file to configure a forward proxy.

1. Before you begin: Follow the Docker Compose deployment guide to set up Docker for the NGINX container registry. The deployment guide also covers additional environment variables you may want to consider before deployment.

2. Download the preconfigured docker-compose.yaml file

3. Update docker-compose.yaml with the proxy settings:

   Modify the services.nim.environment section to include the proxy configuration:

   services:
     nim:
     image: private-registry.nginx.com/nms/nim-standalone-compose:<version>
     depends_on:
       clickhouse:
         condition: service_healthy
     hostname: nim
     ports:
       - 443:443
     networks:
       - external_network
       - clickhouse
     environment:
       - PROXY_ENABLE=true
       - PROXY_HOST=<proxy-ip>
       - PROXY_PORT=<proxy-port>
       - PROXY_PROTOCOL=[http|https]
       - PROXY_AUTH_REQUIRED=[true|false]
       - PROXY_SSL_VERIFY=[true|false]
    volumes:
       - nim-data:/data
       - proxy-certs:/usr/local/share/ca-certificates
       - ./<proxy-ca-cert-file>:/usr/local/share/ca-certificates/<proxy-ca-cert-file>
   

   • If the proxy requires authentication, set PROXY_AUTH_REQUIRED to true, and add the following fields:

         - PROXY_AUTH_USERNAME=<username>
         - PROXY_PASSWORD=<password>
     

   • Replace <proxy-ca-cert-file> with the filename of the proxy CA certificate.

   • Set PROXY_PROTOCOL to either http or https, depending on your proxy type.

   • If not explicitly set, PROXY_SSL_VERIFY defaults to true, meaning the proxy must have a valid certificate issued by a trusted Certificate Authority (CA). Note: This setting applies only when PROXY_PROTOCOL is https.

     If the proxy uses a self-signed or untrusted certificate, you have two options:

     • Recommended: Follow the steps in the Trust proxy certificates section to add the proxy’s CA certificate to the system’s trusted store.
     • Alternative (not recommended): Disable SSL verification by setting PROXY_SSL_VERIFY=false, which allows connections to proxies with untrusted or self-signed certificates.

4. Deploy NGINX Instance Manager:

   docker compose up -d
   

Trust proxy certificates (if required)

If your proxy uses HTTPS and proxy_ssl_verify is set to true, NGINX Instance Manager expects the proxy’s CA certificate to be trusted. If the proxy certificate is self-signed or issued by an untrusted Certificate Authority (CA), you must manually add it to the system’s trusted store.

Note:
For Kubernetes deployments, perform these steps inside the integrations pod.

1. Copy the proxy CA certificate into the system’s trusted certificate directory. The path varies by distribution:

   • Debian/Ubuntu: /usr/local/share/ca-certificates/
   • RHEL/CentOS: /etc/ssl/certs/

2. Run the appropriate command to update the system’s trusted certificates:

   • Debian/Ubuntu:

     sudo update-ca-certificates
     

   • RHEL/CentOS:

     sudo update-ca-trust
     

3. Apply the changes:

   • VM/bare-metal: Restart NGINX Instance Manager:

     sudo systemctl restart nms
     

   • Kubernetes: Restart the integrations pod.

Verify proxy connectivity

After applying the configuration, verify that NGINX Instance Manager is using the proxy:

• Check system logs: Review logs for messages confirming that traffic is being routed through the proxy. The exact log message may vary but should indicate the configured proxy details.

• Test outbound connectivity: Use a tool such as curl or wget to confirm that requests are routed through the proxy. The exact command depends on your proxy configuration.

• Monitor network traffic: If needed, use network debugging tools like tcpdump or netstat to verify that outbound requests are sent through the proxy.

If proxy traffic is not working as expected, review the troubleshooting section for possible causes.

Troubleshoot common issues