Use a third-party 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:

Parameter Description
proxy_enable Defines whether NGINX Instance Manager routes outbound traffic through a forward proxy.
Supported values: true (routes certain outbound requests through the proxy) or false (sends data directly to servers).
proxy_host IP address of the third-party forward proxy.
proxy_port Port on which the third-party proxy is running.
proxy_protocol Protocol used to interact with the proxy.
Supported values: http, https.
proxy_auth_required Determines whether authentication is enforced for proxy access.
Supported values: true (proxy requires authentication) or false (proxy does not require authentication).
proxy_username Username for authentication with the proxy (if proxy_auth_required: true).
proxy_password Password for authentication with the proxy (if proxy_auth_required: true).
proxy_ssl_verify Controls SSL certificate verification when proxy_protocol is https.
Default value: true.
Supported values: true (only trusted proxies allowed) or false (allows untrusted/self-signed certificates).

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>

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

Issue Log Message Possible Cause Resolution
Authentication failed N/A Incorrect proxy credentials. Double-check proxy_username and proxy_password.
Invalid proxy configuration Error: failed to initialize LLM:
invalid forward proxy config: <reason>		 The proxy configuration section is missing or improperly formatted. - Ensure the proxy configuration is correct in /etc/nms/nms.conf.
- Verify all required parameters (proxy_enable, proxy_host, proxy_port, proxy_protocol) are set.
Proxy initialization failure unable to add proxy support,
err - <err>		 The proxy settings are misconfigured, or the proxy service is unavailable. - Ensure that the proxy service is running and accessible.
- Verify that proxy_enable is set to true and all required parameters are correctly configured.
Proxy not reachable N/A Incorrect proxy IP or port. Verify proxy_host and proxy_port in /etc/nms/nms.conf.
TLS certificate verification error proxyconnect tcp: tls:
failed to verify certificate:
x509: certificate signed by unknown authority		 SSL verification is enabled (default), but the proxy certificate is untrusted. - Add the proxy’s CA certificate to the system’s trusted CA store.
- If necessary, disable SSL verification by setting proxy SSL verify to false (not recommended).