Configuring agents to communicate through a forward proxy

If your firewall rules do not allow transparent outbound HTTPS connections to external hosts, you can configure IBM® monitoring agents to send traffic to a forward proxy. Edit the KDH_FORWARDPROXY environment variable to configure agents to communicate through the forward proxy.

Before you begin

To determine the IP address of the Cloud APM data center that your data collectors connect to, see Validating connectivity to the data center. Then, adjust your firewall rules to allow requests to be sent to those IP addresses from your forward proxy.

You can use the openssl command to check whether the computer system where your agents are installed has connectivity to the Cloud APM data center servers. You can also use the openssl command to check whether your network supports the cipher suites that are used by Cloud APM. If the openssl command results indicate that the computer system cannot connect, you might need to set up a forward proxy. If the command results indicate that the Cloud APM server certificate could not be obtained, then work with your network team to determine why the required cipher suites are not supported. For the list of cipher suites that are used by Cloud APM, see Secure communication.

Run the openssl command, as shown in the following example:
echo quit | openssl s_client
-state -connect <domain-name>:443
-tls1_2 -cipher
ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384
where domain-name is the domain name for your Cloud APM subscription, such as 8b68ba1b9.agents.na.apm.ibmserviceengage.com.
To determine the domain name for your subscription, complete the following steps:
  1. Open the agent environment configuration file in a text editor:

    Linux or AIX/opt/ibm/apm/agent/config/global.environment

    Windowsinstall_dir\TMAITM6_x64\KpcENV for 64-bit Windows systems and install_dir\TMAITM6\KpcENV for 32-bit Windows systems, where pc is the agent product code.

    For a list of product codes, see Using agent commands.

  2. Find the IRA_ASF_SERVER_URL variable. The value is in the form: https://domain-name/ccm/asf/request. Use the domain name portion of the value with the openssl command.

    If the connection is successful, messages similar to the following example are displayed:
    CONNECTED(00000003)
    SSL_connect:before/connect initialization
    SSL_connect:SSLv3 write client hello A
    SSL_connect:SSLv3 read server hello A
    depth=2 C = US, O = IBM Service Engage,
    CN = ca_ec_384.ibmserviceengage.com
    verify error:num=19:self signed certificate in certificate chain
    verify return:0
    SSL_connect:SSLv3 read server certificate A
    SSL_connect:SSLv3 read server key exchange A
    SSL_connect:SSLv3 read server certificate request A
    SSL_connect:SSLv3 read server done A
    SSL_connect:SSLv3 write client certificate A
    SSL_connect:SSLv3 write client key exchange A
    SSL_connect:SSLv3 write change cipher spec A
    SSL_connect:SSLv3 write finished A
    SSL_connect:SSLv3 flush data
    SSL_connect:SSLv3 read finished A
    ---
    Certificate chain
    0 s:/C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN=*.agents.na.apm.ibmserviceengage.com
    i:/C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN =ca_ec_384.apm.ibmserviceengage.com
    1 s:/C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN=ca_ec_384.apm.ibmserviceengage.com
    i:/C=US/O=IBM Service Engage/CN=ca_ec_384.ibmserviceengage.com
    2 s:/C=US/O=IBM Service Engage/CN=ca_ec_384.ibmserviceengage.com
    i:/C=US/O=IBM Service Engage/CN=ca_ec_384.ibmserviceengage.com
    ---
    Server certificate
    -----BEGIN CERTIFICATE-----
    MIICkjCCAhegAwIBAgIIXlr284nLPaMwDAYIKoZIzj0EAwMFADCBhDELMAkGA1UE
    BgwCVVMxGzAZBgNVBAoMEklCTSBTZXJ2aWNlIEVuZ2FnZTErMCkGA1UECwwiQXBw
    bGljYXRpb24gUGVyZm9ybWFuY2UgTWFuYWdlbWVudDErMCkGA1UEAwwiY2FfZWNf
    Mzg0LmFwbS5pYm1zZXJ2aWNlZW5nYWdlLmNvbTAeFw0xMzEyMDIxNjM2MDlaFw0y
    MzEyMDExNjM2MDlaMIGGMQswCQYDVQQGDAJVUzEbMBkGA1UECgwSSUJNIFNlcnZp
    Y2UgRW5nYWdlMSswKQYDVQQLDCJBcHBsaWNhdGlvbiBQZXJmb3JtYW5jZSBNYW5h
    Z2VtZW50MS0wKwYDVQQDDCQqLmFnZW50cy5uYS5hcG0uaWJtc2VydmljZWVuZ2Fn
    ZS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAQmrGoCkAMoNAC3F6MIo1zR8fcO
    mczYXtUux2bhlOibn3jQdxamhDR91nr2RBerGjMIITKNXd2MaOr3b6m8euk1BAL3
    KsbN9lqvw94kXg0BTO1IHAcdsZQB+AuEVVhmDVGjUDBOMAwGA1UdEwEB/wQCMAAw
    HwYDVR0jBBgwFoAU/zpE5TOnQ8LSuvbSWRfpbiGea08wHQYDVR0OBBYEFHL0At4O
    GUdcOHVGg4Tfo4hl7LLGMAwGCCqGSM49BAMDBQADZwAwZAIwDWPHo5I04ZFVrkfk
    St6gwH2UNF37jBscRN1lOE4SIwezZAqVs42BNMkWRjJBgiHzAjBm4m3zOjsXzNL8
    +u8ALjQQCpBDT6dUHujzY5CRxG0xEHi5IXsXf4QwbctnjjvTeYA=
    -----END CERTIFICATE-----
    subject=/C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN=*.agents.na.apm.ibmserviceengage.com
    issuer=/C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN=ca_ec_384.apm.ibmserviceengage.com
    ---
    Acceptable client certificate CA names
    /C=US/O=IBM Service Engage/CN=ca_ec_384.ibmserviceengage.com
    /C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN=ca_ec_384.apm.ibmserviceengage.com
    /C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert
    Global Root CA/C=US/O=IBM Service Engage/OU=Application Performance
    Management/CN=*.agents.na.apm.ibmserviceengage.com
    Server Temp Key: ECDH, prime256v1, 256 bits
    ---
    SSL handshake has read 2659 bytes and written 261 bytes
    ---
    New, TLSv1/SSLv3, Cipher is ECDHE-ECDSA-AES128-GCM-SHA256
    Server public key is 384 bit
    Secure Renegotiation IS supported
    Compression: NONE
    Expansion: NONE
    SSL-Session:
    Protocol : TLSv1.2
    Cipher : ECDHE-ECDSA-AES128-GCM-SHA256
    Session-ID:
    A18C31D0B45A1166357C917E1CFCD86A9FBEDB4A0EB768EF5390AC28C95CB7EF
    Session-ID-ctx:
    Master-Key:
    252B8FE2731E51AC0B79A27C7BED33CA8B15AF4CFD015C98DBACA46EA01DC40B
    9E6B56E62E0F332FF6B56266B5ADD7B0
    Key-Arg : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    Start Time: 1510772474
    Timeout : 7200 (sec)
    Verify return code: 19 (self signed certificate in certificate chain)
    ---
    DONE
    SSL3 alert write:warning:close notify

If the computer system does not have connectivity to the Cloud APM server, messages similar to the following example are displayed:
getaddrinfo: Name or service not known
connect:errno=2

If the computer system cannot obtain the server certificate, because the cipher suites are being blocked somewhere in the network, messages similar to the following example are displayed:
SSL_connect:failed
---
no peer certificate available
---
No client certificate CA names sent

About this task

When a forward proxy is used, the agent first opens a TCP connection with the proxy. The agent sends an HTTP CONNECT request and the target endpoint (Cloud APM server) URL to the forward proxy. Then, the forward proxy establishes a TCP connection with the target endpoint and sets up an HTTPS tunneling session between the agent and the Cloud APM server.

Figure 1. Connection diagram for using a forward proxy
Connection diagram for using a forward proxy.

The monitoring agent does not support authenticating proxies, which means the agent does not support logging on to a forward proxy by using a configured proxy user ID and password.

Procedure

Complete these steps to configure agents to communicate through a forward proxy.

  1. Open the agent environment configuration file in a text editor:

    Linux or AIXinstall_dir/config/global.environment file, where install_dir is the installation home directory of the agents. The global.environment file configures all agents in the installation directory.

    The customized settings in the .global.environment file are lost after agent upgrade. To preserve your settings, make customization changes in the global.environment files. The settings in this file are not overwritten by agent upgrade.

    Windowsinstall_dir\TMAITM6_x64\KpcENV file for 64-bit agents, and install_dir\TMAITM6\KpcENV for 32-bit agents, where pc is the agent product code. Configure the KpcENV file for each agent.

    For a list of product codes, see Using agent commands.

  2. Edit the KDH_FORWARDPROXY environment variable to specify the proxy address and port:
    KDH_FORWARDPROXY=http://proxy-address:proxy-port-number
    For example:
    KDH_FORWARDPROXY=http://HostA:8085
  3. Restart the agent to implement your changes. See Using agent commands.