# Use a third-party forward proxy > Configure F5 NGINX Instance Manager to route outbound traffic through a third-party forward proxy for license verification, telemetry, and updates. ## Overview This guide explains how to configure F5 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 **Note:** #### 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: ```yaml proxy_config: proxy_enable: true proxy_host: 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: ```yaml proxy_username: "" proxy_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](#trust-proxy-certificates-if-required) 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: ```shell sudo systemctl restart nms ``` ### Kubernetes In a Kubernetes deployment, configure a forward proxy by modifying the `nms-conf` ConfigMap. To edit the ConfigMap, run: ```shell kubectl edit cm nms-conf -n ``` - Replace `` 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"](#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](nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md) 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. [icon: download] [Download the preconfigured docker-compose.yaml file](/scripts/docker-compose/docker-compose.yaml) 3. Update `docker-compose.yaml` with the proxy settings: Modify the `services.nim.environment` section to include the proxy configuration: ```yaml services: nim: image: private-registry.nginx.com/nms/nim-standalone-compose: depends_on: clickhouse: condition: service_healthy hostname: nim ports: - 443:443 networks: - external_network - clickhouse environment: - PROXY_ENABLE=true - PROXY_HOST= - 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 - ./:/usr/local/share/ca-certificates/ ``` - If the proxy requires authentication, set `PROXY_AUTH_REQUIRED` to `true`, and add the following fields: ```yaml - PROXY_AUTH_USERNAME= - PROXY_PASSWORD= ``` - Replace `` 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](#trust-proxy-certificates-if-required) 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: ```shell 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**: ```shell sudo update-ca-certificates ``` - **RHEL/CentOS**: ```shell sudo update-ca-trust ``` 3. Apply the changes: - **VM/bare-metal**: Restart NGINX Instance Manager: ```shell 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](#troubleshoot-common-issues) 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: ` | 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 - ` | 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). |