Using a Proxy Server

You can configure Data Collector to use a proxy server for outbound network requests.

You define proxy properties when you set up the deployment. In Control Hub, edit the deployment, and in the Configure Engine section, click Advanced Configuration. Then, click Proxy.

Important: You cannot define proxy properties while a deployment is active. You must stop the deployment to change the proxy properties. For detailed instructions on defining proxy properties for an existing deployment, see the Control Hub documentation.

Use the following guidelines to define the proxy user and password properties:

  • Define the user and password properties only when the proxy server requires authentication. Leave the properties blank when the proxy server does not require authentication.
  • You can include special characters in the user and password values, except for an exclamation point (!), a backward slash (\), a leading number sign (#), or a leading or trailing space. You can include number signs in the middle or end of a value, and include spaces in the middle of a value.
  • When defined, Control Hub displays the user and password values as REDACTED after you save the deployment.
Note: If using a man-in-the-middle proxy server with a self-managed deployment, you must also provide Data Collector with the custom certificate required by the server.

Data Collector includes the following proxy configuration properties:

Proxy Property Description
http.proxyHost IP address or hostname of the proxy server used by the HTTP protocol handler.
http.proxyPort Port of the proxy server used by the HTTP protocol handler.
http.proxyUser Optional user name to authenticate with the proxy server used by the HTTP protocol handler.
http.proxyPassword Optional password to authenticate with the proxy server used by the HTTP protocol handler.
https.proxyHost IP address or hostname of the proxy server used by the HTTPS protocol handler.
https.proxyPort Port of the proxy server used by the HTTPS protocol handler.
https.proxyUser Optional user name to authenticate with the proxy server used by the HTTPS protocol handler.
https.proxyPassword Optional password to authenticate with the proxy server used by the HTTPS protocol handler.
http.nonProxyHosts Optional list of hosts that Data Collector can connect to without going through the proxy server. Specify each host using an IP address or hostname. Separate multiple entries with the pipe character ( | ).

You can specify a CIDR block, such as 10.0.0.0/8, to define a collection of IP addresses.

You can also use the asterisk character (*) as a wildcard at the beginning or end of each entry for pattern matching. For example, if you define the property as follows: http.nonProxyHosts=*.foo.com|111.222.33.*

Then Data Collector can directly access every host in the foo.com domain and every IP address matching the pattern 111.222.33.* even when a proxy server is defined.

Note: Control Hub automatically adds some required hosts, such as localhost and the Data Collector hostname.
jdk.http.auth.tunneling.disabledSchemes Authentication schemes that are disabled when tunneling HTTPS over an HTTP-based proxy.

Oracle JDK disabled Basic authentication in JDK 8 update 111 and later. As a result, proxy servers that require Basic authentication will no longer succeed by default.

If the proxy server requires Basic authentication, define the proxy user and password properties, and then set this property to an empty string. For example: jdk.http.auth.tunneling.disabledSchemes=

Note: Use Basic authentication with caution since it potentially exposes credentials by sending them through an unencrypted connection to the proxy.

If the proxy server does not require Basic authentication, do not define the proxy user and password properties, and use the default value of Basic for this property.

Example: Proxy Server without Authentication

The following property definitions configure Data Collector to use the same proxy server for both the HTTP and HTTPS protocol handler when the proxy server does not require authentication. Data Collector is not configured to use any additional non-proxy hosts.
http.proxyHost=111.22.3.444
http.proxyPort=3128
http.proxyUser=
http.proxyPassword=
https.proxyHost=111.22.3.444
https.proxyPort=3128
https.proxyUser=
https.proxyPassword=
http.nonProxyHosts=
jdk.http.auth.tunneling.disabledSchemes=Basic

Example: Proxy Server with Authentication

The following property definitions configure Data Collector to use the same proxy server for both the HTTP and HTTPS protocol handler when the proxy server requires authentication. Note that after the deployment is saved, values defined for the user and password properties display as REDACTED, as shown below. Data Collector is configured to use additional non-proxy hosts. 

http.proxyHost=111.22.3.444
http.proxyPort=3128
http.proxyUser=REDACTED
http.proxyPassword=REDACTED
https.proxyHost=111.22.3.444
https.proxyPort=3128
https.proxyUser=REDACTED
https.proxyPassword=REDACTED
http.nonProxyHosts=111.222.33.*
jdk.http.auth.tunneling.disabledSchemes=

Man-in-the-middle Proxy Server

If using a man-in-the-middle proxy server such as ZScaler with a self-managed deployment, you must provide Data Collector with the custom certificate required by the server.

In addition to defining the proxy properties when you set up the deployment, you must complete additional steps based on the Data Collector installation type:
Tarball installation
When using a tarball installation of Data Collector, you must manually install the certificate on each Data Collector machine, for both the curl command line tool and the Java JDK truststore.
Docker installation
When using a Docker image installation of Data Collector, you must paste the full contents of the PEM certificate when you set up the deployment.
In Control Hub, edit the deployment, and in the Configure Engine section, click Advanced Configuration. Click Certificate to paste the full contents of the PEM certificate. When you launch the engine, the Docker container includes the certificate.