Configure the .NET Agent Connection to the Enterprise Manager

To report metrics, the agent must connect to an Enterprise Manager. The default communication settings enable an agent to connect to a local Enterprise Manager using port 5001. However, the agent and the Enterprise Manager do not typically reside on the same system. You can modify the default settings when you install the agent, or after installing the agent. Configure settings by modifying the IntroscopeAgent.profile that is located in the <Agent_Home> directory.
apmdevops106
To report metrics, the agent must connect to an Enterprise Manager. The default communication settings enable an agent to connect to a local Enterprise Manager using port 5001. However, the agent and the Enterprise Manager do not typically reside on the same system. You can modify the default settings when you install the agent, or after installing the agent. Configure settings by modifying the IntroscopeAgent.profile that is located in the <
Agent_Home
> directory.
Depending on your requirements, you can configure the communication between the agent and Enterprise Manager to use:
  • Direct socket connections
  • HTTP tunneling connections
  • HTTP tunneling through a proxy server
  • HTTP over Secure Sockets Layer connections (HTTPS)
  • Secure Socket Layer (SSL) connections
Connect to the Enterprise Manager Using a Direct Socket Connection
The most common way for the agent to connect to the Enterprise Manager is through a direct socket connection. We recommend using a direct socket connection to the Enterprise Manager when possible. Use the following system properties to supply the URL of the Enterprise Manager, Collector, or MOM to which the agent should connect:
System property name
: agentManager.url.1
Abbreviated name
: agentManager
The fully qualified system property name takes precedence over the abbreviated name and be specified on the Java command line or in the agent profile. The abbreviated name is an alias for the first connection entry
agentManager.url.1
(refer to “Specifying one or more managers in the agent profile”). The abbreviated form should only be used on the JVM command line. The property value is a URL.
The
serverHostOrIP
value can be either an IP address (IPv4 or IPv6), a host name, or a fully qualified domain name. Provide the optimal value for your environment. In all cases, the port must be specified as part of the property because no default is inferred.
Follow these steps:
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Locate the
    agentManager.url.1
    property. Specify the host name or IP address and the default listening port of the Enterprise Manager to which the agent connects. For example:
    agentManager.url.1=sfcollect01:5001
    If you use a cluster with more than one Enterprise Manager, be sure to specify the MOM. The MOM then assigns the agent to a Collector.
  3. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to in case the primary Enterprise Manager connection is lost.
  4. Save and close the IntroscopeAgent.profile file.
Direct TCP connection
To use a direct TCP connection, specify either of the following formats. The
agentManager=serverHostOrIP:Port
format assumes the
tcp://
prefix for the namespace.
agentManager=serverHostOrIP:Port
agentManager=tcp://serverHostOrIP:Port
Connect to the Enterprise Manager with HTTP Tunneling
If a direct socket connection to the Enterprise Manager is not feasible, you can configure agents to connect to an Enterprise Manager over HTTP. This configuration allows communication to pass through firewalls that only permit HTTP traffic.
You can configure agents to send information using tunneling technology, enabling agents to connect to an Enterprise Manager remotely. In this case, you must configure the agent to connect to the Enterprise Manager embedded web server, where the HTTP tunneling web service is hosted.
HTTP tunneling imposes more CPU and memory overhead on the application server and Enterprise Manager than a direct socket connection.
Follow these steps:
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Set the
    agentManager.url.1
    property to the host name or the IP address of the Enterprise Manager to which the agent connects by default. Follow the host name or IP address with a colon and the HTTP listening port of the Enterprise Manager embedded web server. For example:
    agentManager.url.1=http://webhost:8081/
    Ensure that the port number matches the
    introscope.enterprisemanager.webserver.port
    property value in  the <
    EM_Hom
    e>/config/IntroscopeEnterpriseManager.properties file. The default port value is 8081.
  3. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to in case the connection to the primary Enterprise Manager is lost.
  4. Save and close the IntroscopeAgent.profile file.
Configure a Proxy Server for HTTP Tunneling
You can configure the HTTP tunneled agent to connect through a proxy server to the Enterprise Manager. This configuration is necessary for a forwarding proxy server. You make this configuration when  the agent is running behind a firewall that only allows outbound HTTP traffic routing through the proxy server.
The proxy server configuration properties apply only if the agent is configured to tunnel over HTTP. The proxy server configuration applies to any configured HTTP tunneled connection on the agent, not to a single connection. This configuration is especially important to consider when configuring failover between multiple Enterprise Managers, where the connection to each Enterprise Manager is over HTTP.
  • HTTP/1.1 is required to enable agent HTTP tunneling. In addition, the proxy server must support HTTP Post.
  • If the proxy is not reachable, the agent bypasses the proxy and the agent makes a direct connection with the Enterprise Manager. If the proxy is reachable but its authentication fails, the agent keeps retrying to connect to the Enterprise Manager through the proxy.
Follow these steps:
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Set the
    agentManager.httpProxy.host
    property to the host name or IP address of the proxy server.
  3. Set the
    agentManager.httpProxy.port
    property to the port number of the proxy server.
  4. (Optional) If the proxy server requires user credentials for authentication, carry out one of the following options.
    • To use clear text authentication, set the following properties:
      agentManager.httpProxy.username=<user_name>
      agentManager.httpProxy.password=<user_password>
    • To encrypt the password, follow these steps:
      1. Access the encryption tool from wily\tools\PropertiesUtil.jar.
      2. Run the tool using the following command
        java -jar <
        directory path
        >\wily\tools\PropertiesUtil.jar encrypt <user_password>
        The encrypted password is provided.
      3. In the IntroscopeAgent.profile file, set the following properties:
        agentManager.httpProxy.username=<user_name>
        agentManager.httpProxy.password=<encrypted_password>
  5. Save and close the IntroscopeAgent.profile.
Connect to the Enterprise Manager with HTTPS Tunneling
The agent can connect to the Enterprise Manager using HTTP over Secure Sockets Layer (SSL) by configuring properties in the IntroscopeAgent.profile file.
Follow these steps:
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Set the
    agentManager.url.1
    property to the either of these settings: Specify the host name or the IP address of the target Enterprise Manager. Follow the host name or IP address with a colon and the Enterprise Manager embedded web server HTTPS listening port. For example:
    agentManager.url.1=https://172.31.255.255:8444/
  3. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to in case the connection to the primary Enterprise Manager is lost.
  4. Save and close the IntroscopeAgent.profile.
Connect to the Enterprise Manager over SSL
apmsaas
dxapm111
To report metrics, the agent must connect to an Enterprise Manager.
2
2
Connect to the Enterprise Manager with HTTP Tunneling
We support the capability to configure .NET agents to connect to an Enterprise Manager over HTTP. This configuration allows communication to pass through firewalls that only permit HTTP traffic.
Connect Using WebSocket Protocol
The agent is configured to automatically send information using the WebSocket protocol. This protocol combines the efficiency of binary socket communication with the compatibility of HTTP network proxies and firewalls. The WebSocket Connection URL supports the following versions:
  • .NET 4.5 and above
  • .NET Core 2.0 and 3.1
Configure a Proxy Server for HTTP Tunneling
You can configure the HTTP tunneled agent to connect through a proxy server to the Enterprise Manager. This configuration is necessary for a forwarding proxy server. You make this configuration when the agent is running behind a firewall that only allows outbound HTTP traffic routing through the proxy server.
The proxy server configuration properties apply only if the agent is configured to tunnel over HTTP. The proxy server configuration applies to any configured HTTP tunneled connection on the agent, not to a single connection. This configuration is especially important to consider when configuring failover between multiple Enterprise Managers, when the connection to each Enterprise Manager is over HTTP.
  • HTTP/1.1 is required to enable agent HTTP tunneling. In addition, the proxy server must support HTTP Post.
  • If the proxy is not reachable, the agent bypasses the proxy and the agent makes a direct connection with the Enterprise Manager. If the proxy is reachable but its authentication fails, the agent keeps retrying to connect to the Enterprise Manager through the proxy.
Follow these steps:
  1. Navigate to the
    <Agent_Home>
    directory and open the
    IntroscopeAgent.profile
    in a text editor.
  2. Set the
    agentManager.httpProxy.host
    property to the host name or IP address of the proxy server.
  3. Set the
    agentManager.httpProxy.port
    property to the port number of the proxy server.
  4. (Optional) If the proxy server requires user credentials for authentication, carry out one of these options.
    • To use clear text authentication, set these properties:
      agentManager.httpProxy.username=<user_name>
      agentManager.httpProxy.password=<user_password>
    • To encrypt the password, follow these steps:
      1. Access the encryption tool from the
        <Agent_Home>\tools\PropertiesUtil.jar
        file.
      2. Run the tool using this command:
        java -jar <directory path>\wily\tools\PropertiesUtil.jar encrypt <user_password>
        The encrypted password is provided.
      3. In the
        IntroscopeAgent.profile
        file, set these properties:
        agentManager.httpProxy.username=<user_name>
        agentManager.httpProxy.password=<encrypted_password>
  5. Save and close the
    IntroscopeAgent.profile
    .
Connect to the Enterprise Manager with HTTPS Tunneling
We support the capability to configure .NET agents to connect to an Enterprise Manager using HTTP over Secure Sockets Layer (SSL). However, the .NET Agent can only connect to the Enterprise Manager over SSL by tunneling through the Enterprise Manager web server HTTPS port.
Follow these steps
:
This procedure uses an example in which you create a self-signed certificate that is used in the agent-to-Enterprise Manager SSL handshake.
  1. Use the Java keytool utility to create a new keystore file containing a self-signed certificate (PrivateKeyEntry) with the alias named
    myhost
    . For example:
    <
    EM_Home
    >\jre\bin\keytool -genkey -alias myhost -keyalg RSA -keysize 2048 -validity 365 -keypass password -keystore keystore -storepass password
  2. When prompted for values, set the
    CN
    value to the fully qualified domain name (FQDN) of the server hosting the Enterprise Manager. For example a value of
    myhost.ca.com
    .
  3. Export the public key for the new certificate from the keystore. For example:
    <
    EM_Home
    >\jre\bin\keytool -export -alias myhost -keystore keystore -file myhost.crt
  4. Transfer the
    myhost.crt
    file to the agent computer.
  5. Import the
    myhost.crt
    file into the Trusted Root Certification Authorities using the Windows Certification Manager (CERTMGR.MSC).
    Import the file into the certificates for the
    Local Computer
    rather than
    Current User
    . Otherwise, ASP.NET does not pick up the certificates and the agent-Enterprise Manager connection fails with an error. Here is an example error message:
    System.Net.WebException: The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel. ---> System.Security.Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure.
  6. Update the
    IntroscopeEnterpriseManager.properties
    file.
    1. On the computer on which the Enterprise Manager is installed, navigate to the
      <
      EM_Home
      >/config
      directory.
    2. Open the
      IntroscopeEnterpriseManager.properties
      file in a text editor.
    3. Enable this line:
      introscope.enterprisemanager.webserver.jetty.configurationFile=em-jetty-config.xml
    4. Save and close the file.
  7. Update the
    em-jetty-config.xml
    file.
    1. Navigate to the
      <
      EM_Home
      >/config
      directory.
    2. Open the
      em-jetty-config.xml
      file in a text editor.
    3. Edit the
      em-jetty-config.xml
      file to use the new keystore file in its SSL connector (default port 8444).
    4. If you are using an alias different from
      wily
      , modify the
      certAlias
      value.
    5. Save and close the file.
  8. Restart the Enterprise Manager.
  9. Update the
    IntroscopeAgent.profile
    file.
    1. Navigate to the
      <
      Agent_Home
      >
      directory and open the
      IntroscopeAgent.profile
      file in a text editor.
    2. Comment out these lines as shown:
      #introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost #introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001 #introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.DefaultSocketFactory
    3. Uncomment and edit these lines as shown:
      introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=myhost.ca.com introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=8444 introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.HttpsTunnelingSocketFactory
    4. Save and close the file.
  10. Start the agent.
    The agent should connect successfully to the Enterprise Manager using HTTPS tunneling.
    Here is a successful connection message example from the Performance Monitor (Perfmon) Collector Agent log:
    [INFO] [IntroscopeAgent.IsengardServerConnectionManager] Connected controllable Agent to the Introscope Enterprise Manager at WILLY03-E7440B.ca.com:8081,com.wily.isengard.postofficehub.link.net.HttpsTunnelingSocketFactory. Host = "WILLY03-E7440B", Process = ".NET Process", Agent Name = "PerfMonCollectorAgent.exe", Active = "True".