Connecting services and agents with a secure tunnel

This topic describes how connections between the TrueSight Middleware and Transaction Monitor Service tier and the TrueSight Middleware and Transaction Monitor Agent tier can, optionally, be routed via a secure tunnel, and includes:

- Service initiated tunnels for connecting services and agents
- Services configuration examples

Using the secure tunnel, all network traffic between a TrueSight Middleware and Transaction Monitor Agent and the TrueSight Middleware and Transaction Monitor Services is tunneled via a single TCP/IP connection and the traffic is encrypted using TLS. This both protects the data from eavesdropping and simplifies the network management because the only port requirements are for the TLS tunnel itself (on port 15010 by default).

Notes

Always consult with local IT security policy owners to ensure configuration complies with the security requirements for your environment.
Tunneling is not a supported configuration for Agents and Services located on the same host.
If an agent is using a tunnel to connect to a Service Tier, and the agent is then added to another Service Tier (e.g. by using agentpref), the agent reverts to using no tunnel (ConnectionInitiation is set to 0). The agent must then be configured to work against the new Service Tier (protocol and cipher settings, certificate distribution, etc).

Related topic

Working-with-the-subscriber-services

Defining-configuration-options-in-services-cfg

Certificate-management

Agent connections that route via a tunnel offer three levels of security, each offering an incrementally more secure communication pathway:

End-to-End encryption
Server Authentication
Server and Agent Authentication

To allow authentication of Services or Agents, keys and certificates must be available. TrueSight Middleware and Transaction Monitor supports either:

End-user provided keys and certificates
Internally generated keys and certificates

When using end-user provided materials they must be imported into Java key stores and made available to the Agents and Services. This is likely to be required when you have strict security requirements that are not met by the internally generated certificates, or when you must integrate tightly with an existing authentication infrastructure (e.g. certificates for trusted entities are already available and must be used).

When using internally generated keys and certificates, the Java key stores are populated for you. This is likely suitable for environments where Server or Server and Agent authentication is required, but there is no need for integration with an existing authentication infrastructure.

Tunnel connections can be initiated either by the Service Tier (to a particular agent) or by the agent (to the Service Tier). This is likely to be useful in environments where firewalls or intrusion detection products are in place, and restrict the routing options between the Agent and Service Tiers.

The tunnel connection initiation can be configured per-agent via the "ConnectionInitiation" preference. It can also be set to an initial value when a bootstrap package is provisioned.

ConnectionInitiation preference	Description
0	No tunnel
1	Agent initiated (TCP connection originates from the Agent tier).
2	Service Initiation (TCP connection originates from the Service tier).

Service Tier tunnel configuration parameters are described in the Tunnel_Service section of the services.cfg file.

Agent Tier tunnel configuration parameters are described in Post-core-component-installation-and-configuration.

In all cases, the TrueSight Middleware and Transaction Monitor Services tier assumes the role of a TLS Server, and TrueSight Middleware and Transaction Monitor Agent tier assume the role of TLS clients.

Service initiated tunnels for connecting services and agents

Bootstrap packages that are provisioned with a "ConnectionInitiation" preference of "2" (equivalent to selecting the TrueSight Middleware and Transaction Monitor Services initiate Secure Tunnel Connection to Agent option on the Agent Distribution site) must be introduced to the Subscriber Services using "hosttool". This utility is required in order that the Subscriber Services know that a tunnel must be initiated. See Managing hosts for details.

This step is not required if you deploy the Agent in a different connection initiation mode, and then later switch to a Service-initiated tunnel mode (since, at that point, the Agent is already known to the Services).

When migrating an Agent to an alternate Subscriber Service tier and the Agent is running a Service-Initiated tunnel, the Agent must be explicitly removed from the previous Subscriber Service tier. Use the Object Repository tab in the Monitor Console, or the hosttool utility.

Services configuration examples

The following examples cover various configuration scenarios, all of which are performed by editing the Tunnel_Service section of the services.cfg file. In each case, only the minimum required configuration is documented. Additional parameters can be used to further refine the configuration.

Anonymous, end-to-end encryption

In this mode, traffic is encrypted, but no authentication of either party is required. An anonymous cipher is used. This requires only that the tunnel is enabled, and the tunnel host name is set:

[Tunnel_Service]
tunnel_enabled=true

All other values can be left to default, unless an alternate configuration is required.

Agent authenticates services using internal certificates

With this configuration Agents can assert that they are connecting to trusted Services.

This is achieved by enabling internal certificates, defining an authenticating cipher suite and, after key store generation, changing the key and trust store passwords to "changedit" (and OBF encoding the password).

[Tunnel_Service]
tunnel_enabled=true
use_internal_certificates=true
ssl_include_cipher=TLS_ECDHE_RSA_WITH_RC4_128_SHA
ssl_truststore_password=OBF:1vn21ugu1s3g1uvc1tvj1uuu1s3m1ugw1vo0
ssl_keystore_password=OBF:1vn21ugu1s3g1uvc1tvj1uuu1s3m1ugw1vo0

Note that the key and trust store names are not required – internally generated certificates use fixed store names.

Mutual authentication using internal certificates

With this configuration, Agents assert that they can trust the Services, and the Services assert that the connecting Agent is trusted.

This is achieved by using the previous example, and by adding a setting to require client authentication (clients, in this context, being TrueSight Middleware and Transaction Monitor Agents).

[Tunnel_Service]
tunnel_enabled=true
use_internal_certificates=true
ssl_client_auth=true
ssl_include_cipher=TLS_ECDHE_RSA_WITH_RC4_128_SHA
ssl_truststore_password=OBF:1vn21ugu1s3g1uvc1tvj1uuu1s3m1ugw1vo0
ssl_keystore_password=OBF:1vn21ugu1s3g1uvc1tvj1uuu1s3m1ugw1vo0

Agent authenticates services using provided certificates

With this configuration Agents can assert that they are connecting to trusted Services, using key and trust stores provided by the end-user.

[Tunnel_Service]
tunnel_enabled=true
use_internal_certificates=false
ssl_include_cipher=TLS_ECDHE_RSA_WITH_RC4_128_SHA
ssl_truststore_file=myTrustStore.jks
ssl_truststore_password=OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
ssl_keystore_file=myKeyStore.jks
ssl_keystore_password=OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v

Note that this assumes default values for parameters such as store-types and key and trust management algorithms. Additional parameters are available to configure alternatives.

Mutual authentication using provided certificates

With this configuration Agents assert that they can trust the Services, and the Services assert that the connecting Agent is trusted.

This is achieved by using the previous example, but adding a setting to require client authentication (clients, in this context, being TrueSight Middleware and Transaction Monitor Agents).