Secure Communications

Introduction Copied

This user guide provides procedural instructions to enable secure communications across the various Geneos functional areas and components such as Gateway, Netprobe, Active Console.

Geneos components communicate using a proprietary stream-based protocol known internally as EMF2. It uses standard TCP/IP (IPv4 only). Connections are unencrypted by default but can be protected by enabling TLS between components.

All Geneos components can accept inbound connections but access can be controlled using configuration options which depend on the specific component. Depending on the configurations used, each Geneos component may act as an active initiator of EMF2 connections or as a passive listener, or as both.

Additionally, all Geneos components accept HTTP (HTTPS if TLS is enabled) on the same listening port, primarily for diagnostic purposes but also to support remote APIs such as REST, XML-RPC and others. As with EMF2, this access can be controlled through configuration options.

Interoperability with firewalls and other network appliances cannot be guaranteed as many devices may misclassify the connections. Administrators must account for this when designing and deploying Geneos.

Beginning with Geneos 5.5.x, there is support for SNI (Service Name Indication) when TLS is enabled to assist in routing connections correctly based on destination host names.

Secure communications technical reference material for these components can be found here:

• Introduction to Netprobe and Netprobe Command-line Options
• Introduction to Active Console
• Geneos Licence Daemon
• Webslinger
• Enabling SSL in Web Dashboard
• Auditor

Overview Copied

The Geneos Enterprise Management Framework (EMF) protocol that is used to transmit data between Geneos components supports a secure protocol that encrypts data before transmitting it. The protocol used is Transport Layer Security (TLS). TLS versions 1.0, 1.1, 1.2 and 1.3 are supported.

Most Geneos components act as both clients and servers:

• A Geneos server is any Geneos component that listens on a prescribed port and accepts connections from other Geneos components on that port.
• A client is a component that connects to a server at a specified IP address and port.

To establish secure communications, each Geneos server must be provided with a key pair composed of a signed X.509 certificate and a private key.

Certificate requirements Copied

A certificate with a signed X.509 extension must meet the following requirements:

• If the certificate contains the extendedKeyUsage extension, this must include both the serverAuth and clientAuth usages.
• If the certificate contains the keyUsage extension, this must include the digitalSignature and keyEncipherment usages.

Both server and client usages are needed, considering the following scenarios:

• A Gateway connecting to a normal Netprobe needs clientAuth.
• A Gateway connecting to a Netprobe using secure with reversed roles needs serverAuth (the Gateway presents its certificate as the TLS server after it dials the Netprobe).
• A Gateway being connected to by a SAN needs serverAuth.
• A Gateway exporting its data to an AC2, Web Server, or importing Gateway needs serverAuth.
• A Gateway importing data from another Gateway needs clientAuth.
• A Gateway Hot Standby setup needs clientAuth and serverAuth.
• A normal probe needs serverAuth to service a Gateway connection when using Secure. With secure with reversed roles, the Netprobe does not present a certificate.
• A SAN or floating probe needs:
  • clientAuth to connect to a Gateway
  • serverAuth to allow XML-RPC connections
  • serverAuth to provide debug web pages

Note

Geneos cannot validate the certificate if a certificate chain file is missing. Refer to certificate verification.

Sample setup Copied

Given the following setup:

• 1 probe listening on port 7036
• 1 Gateway listening securely on port 7038, which connects to the probe
• 1 Active Console connecting to the Gateway

The Netprobe is a server providing a service to the Gateway, and the Gateway is a server providing a service to the Active Console. To set this up using secure ports, a key pair must be provided for both the Netprobe and the Gateway.

If self-announcing probes are used, the setup of servers is simpler.

• 0 self-announcing probe which connects to the Gateway
• 1 Gateway listening securely on port 7038
• 1 Active Console connecting to the Gateway

Here, the Gateway is the only server. Both the Active Console and the Netprobe connect to the Gateway using the TCP port that it makes available. To set this up securely, a key pair need only be provided for the Gateway.

With secure with reversed TLS roles, a normal (listening) Netprobe also needs no key pair. The Gateway dials the probe, then presents its certificate as the TLS server. Only the Gateway requires a certificate and private key for that EMF2 session.

Minimum TLS versions Copied

TLS connections are supported up to TLS 1.3.

Note

Beginning Geneos 5.6.x, you can run SSL/TLS connections on RHEL 8 platform. The minimum Geneos version for SSL/TLS connections to work on RHEL 8 is 4.9.x or higher.

A minimum supported TLS version can be specified on the Gateway, Licence Daemon, Netprobe and Webslinger using the command line argument -minTLSversion and the TLS version value. The accepted values are:

• 1
• 1.0
• 1.1
• 1.2

  Note

  Beginning Geneos 7.7.x, the default minimum TLS version is 1.2.

• 1.3

A minimum supported TLS version can be specified for Netprobe and Gateway Recorder using the MIN_TLS_VERSION environment variable.

Active Console negotiates the best possible version on connection. Attempting connections with an Active Console earlier than v4.9 with a minimum TLS version higher than 1.0 fail to connect.

Failed attempts to connect securely result in the error message:

-ERROR: SSLConnector:accept SSL Error:[140760fc] SSL23_GET_CLIENT_HELLO:unknown protocolWarning

Caution

When a connection fails, Active Console continually tries to reconnect. This results in a large number of error messages in the Gateway log if the connection keeps failing.

TLS ciphers Copied

When using TLS version 1.3 or lower, you can now control the TLS ciphers that are available for components that provide secure EMF2 connections.

To control the available TLS ciphers use the -openssl-cipher <ciphers> command-line option, replacing <ciphers> with a comma separated list of ciphers. This limits the TLS ciphers used in both outgoing and incoming TLS connections to those listed.

The list of possible ciphers depends on the version of TLS that is being used. For a full list of ciphers, see the Open SSL ciphers documentation.

Note

To manually disable older TLS versions or other weak ciphers for Java applications, add the cipher you want to disable to the jdk.tls.disabledAlgorithms property of the java.security file. For example, adding TLSv1, TLSv1.1, and CBC to the list disables the TLSv1 and TLSv1.1 protocols, and the CBC ciphers.

 #Example:
  jdk.tls.disabledAlgorithms=TLSv1, TLSv1.1, CBC

The location of the java.security file is as follows:

• For Java 8, it is located in <Java location>/lib/security.
• For Java11, it is located in <Java location>/conf/security.

Creating secure Geneos servers Copied

Geneos server components read the key pairs at start up. Their locations are provided using the following command line options;

-ssl-certificate <file>
-ssl-certificate-key <file>

The ssl-certificate command line option points to a file that can either contain just the TLS certificate, or both the TLS certificate and the server’s private key. If the private key is not provided in the certificate file it can be provided in a separate file using the ssl-certificate-key option. Both of these files are expected to have their contents stored using PEM (Privacy-enhanced Electronic Mail) format.

To enable proper trust chain verification, it is recommended that the certificate file contains the full certificate chain. The certificates should be ordered from the most specific to least specific: the leaf certificate (the server’s certificate), followed by all intermediate certificates, and then the root certificate (optional).

When the server provides the full certificate chain, client components only need the root certificate (trust anchor) to be included in the certificate chain file or local trust stores to verify the server’s certificate successfully. Client components are not expected to hold the full verification chain beyond the root certificate. Refer to Validating Geneos Components for more information.

Note

Java 21 does not support PKCS#1 private key files. If a key file has -----BEGIN RSA PRIVATE KEY----- at the start, then it is a PKCS#1/RSA private key. Newer keys are in PKCS#8 format and usually indicate -----BEGIN PRIVATE KEY----- at the start.

To convert a PKCS#1 key to PKCS#8 format, use:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in old_key.pem -out new_key.pem

The key pair provides the Geneos servers with the ability to provide a TLS-encrypted connection to their clients. In order to enable this, the secure service must be turned on. The way that the secure service is turned on differs for different Geneos components.

Netprobe Copied

For normal Netprobes (not self-announcing or floating), enable TLS with the -secure command-line option or with secure with reversed TLS roles.

If you do not specify -secure, -secure-with-reversed-tls-roles, -secure-port, or -secure-with-reversed-tls-roles-port, the Netprobe opens an unencrypted TCP socket. Traffic between the Gateway and the Netprobe is not encrypted.

If you specify -secure at Netprobe startup, the Netprobe provides TLS-encrypted communication only if a readable key pair is also available. If a readable key pair is not available, the Netprobe does not start. Use -secure-port when the Netprobe also listens in other modes. -port N -secure remains a legacy single-port form.

Secure with reversed TLS roles Copied

Starting in Geneos 7.12.x, normal Netprobes support secure with reversed TLS roles. The Gateway dials the Netprobe as the TCP and Geneos client. TLS roles then reverse: the Gateway acts as the TLS server and presents its certificate, and the Netprobe acts as the TLS client. The Netprobe does not need a private key.

Enable this on the Netprobe with -secure-with-reversed-tls-roles (legacy single-port form with -port) or -secure-with-reversed-tls-roles-port. On the Gateway, set Connection Security on the probe or probe group to Secure with reversed roles (connectionSecurity = secureWithReversedRoles). The Gateway must have a certificate and private key. Otherwise, setup validation rejects the probe. For an example, see Example 3.

Caution

Secure with reversed roles encrypts the Gateway–Netprobe EMF2 session in transit. It does not identify the Netprobe at the Gateway, because the Netprobe does not present a certificate. To authenticate the probe, use Secure with a Gateway -ssl-certificate-chain, or use floating or self-announcing probes that connect securely to the Gateway.

Certificate identity in Geneos uses a CA chain, a fingerprint of the presented certificate, or both. Geneos does not compare the server name in a certificate with a hostname in this mode or with Secure. If a chain is configured on the Netprobe, the Netprobe can check that the Gateway certificate is trusted. That check is the same mechanism as any other Geneos TLS client.

Note

This mode is supported for Netprobe only. It is not supported for FIX Analyser 2. Self-announcing and floating Netprobes ignore reverse-TLS listen options because they dial the Gateway. Outbound <secure> to a Gateway listen port is unchanged.

Dual listen and traffic policy Copied

A Netprobe can listen on distinct ports for insecure, secure, and secure with reversed roles. For example, use -port, -secure-port, and -secure-with-reversed-tls-roles-port. Listen ports must be distinct. Do not combine -secure with -secure-port. Do not combine -secure-with-reversed-tls-roles with -secure-with-reversed-tls-roles-port.

For an example that listens on an insecure port and a reverse-TLS port, see Example 3.

Gateway Copied

For Gateways, TLS is enabled or disabled using the Gateway setup. The security of the Gateway ports is controlled via the operating environment ListenPorts setting. This allow the Gateway to be configured to listen on a secure port, an insecure port or both. In the example below, the Gateway has been configured to listen securely on the default port (which is 7038).

File Agent Copied

For File Agent, TLS is enabled using the -secure command line option.

If the -secure option is not provided then the File Agent provides a normal TCP socket for communication, and data sent between the File Agent and the Fix Analyser 2 Netprobe is unencrypted.

If the -secure option is provided at File Agent start-up then the File Agent will provide TLS-encrypted communications so long as a key pair is also provided. If a readable key pair is not provided the File Agent does not start.

Licence Daemon Copied

For Licence Daemon (licd), TLS is enabled using the -secure command line flag. If the -secure option is provided then licd will serve pages across a TLS encrypted socket so long as a key pair is also provided. If the -secure option is provided at licd start-up without a readable key pair then the licd will not start.

Webslinger Copied

For Webslingers, TLS is enabled using the -secure command line flag. If the -secure option is provided then webslinger will serve pages across a TLS encrypted socket so long as a key pair is also provided. If the -secure option is provided at Webslinger start-up without a readable key pair then the webslinger will not start. Web browsers connecting to it will need to use HTTPS rather than HTTP in order to view the web pages.

Geneos Clients Copied

When a Geneos client connects to a Geneos server it may connect securely or insecurely. The connection type of the client must match the connection type of the server. Different clients configure this in different ways.

Active Console Copied

The Active Console has two different ways to configure a connection to a Gateway. The most common way is to add the connection to the connections list in the Active Console settings. This connection has a secure connections check box that is used to indicate if the Active Console should connect securely or insecurely to the Gateway in question.

The second method of specifying Gateway connections is to use a Connections file. This file is specified in the Active Console guide, and each connection entry specifies the Gateway host(s), port, login details and the connection security setting.ccc.

Gateway Copied

When specifying a Netprobe connection in the Gateway, along with the host and port for the connection, set Connection Security on the probe or probe group. The settings are:

• Insecure — the Gateway connects to the Netprobe without TLS.
• Secure — the Netprobe must listen with -secure or -secure-port and present a certificate and private key.
• Secure with reversed roles — the Gateway dials the Netprobe, then acts as the TLS server and presents its certificate. The Netprobe must listen with -secure-with-reversed-tls-roles or -secure-with-reversed-tls-roles-port and needs no private key.
  • The Gateway must have a certificate and private key when using Secure with reversed roles, otherwise, the probe is rejected in setup validation.
  • This mode encrypts the EMF2 session but does not identify the Netprobe at the Gateway. It is supported for Netprobe only, not FIX Analyser 2. See Secure with reversed TLS roles. For an example, see Example 3 in Secure Communications.

The following samples show probe set with secure connection and probe group set with secure with reversed roles. For setting reference, see Probes.

Netprobe Copied

When specifying a Gateway connection in the self announcing (or floating) Netprobe setup file the security of the connection can be set using the tag as shown below. This tag is optional. If it is not supplied, the probe will attempt to connect to the Gateway insecurely.

<?xml version="1.0" encoding="ISO-8859-1"?>
<Netprobe
   compatibility= 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA2011.2-110303/netprobe.xsd">
   <selfAnnounce>
      <enabled>true</enabled>
      <probeName>Probe</probeName>
      <managedEntity>
         <name>ME</name>
         <types>
            <type>HW</type>
         </types>
      </managedEntity>
      <gateways>
         <gateway>
            <hostname>localhost</hostname>
            <port>7038</port>
            <secure>true</secure>
         </gateway>
      </gateways>
   </selfAnnounce>
</Netprobe>

Note

The link for the schema in the XML file, such as http://schema.itrsgroup.com/GA7.7.1-251203/netprobe.xsd, is provided to uniquely identify the schema. The schema is not available for download from a public website.

The schema can be extracted from the Netprobe binary by running the Netprobe with the -extract command-line option to write the embedded schema to a file.

For example, on Linux 64-bit:

netprobe.linux_64 -extract npschema netprobe.xsd

Replace netprobe.xsd with the path or filename where you want to save the schema. On other platforms, use the appropriate Netprobe executable (for example, netprobe.exe on Windows).

Fix Analyser 2 Netprobe Copied

When specifying a File Agent connection in the Fix Analyser plugin, along with the host and port for the connection, you must indicate if this connection is secure by using the secure checkbox.

Caution

Secure with reversed TLS roles is not supported on the FIX Analyser 2 Netprobe. Gateway to FIX Analyser 2 TLS still uses -secure or probe Secure. File Agent secure connections remain a separate hop and are not affected.

Web Dashboard Copied

Web Dashboard is able to connect to both secure and insecure gateways. To connect to a secure Gateway, use the Configuration > Connections menu in the application and tick the Secure checkbox when adding a connection.

Alternatively, you can edit config.xml and add a secure tag as shown below.

...
<gatewayConnections>
     <gatewayConnection name="Gateway 1">
         <enabled>true</enabled>
         <secure>true</secure>
         <primary>
             <host>gateway-host</host>
             <port>7039</port>
         </primary>
         <secondary>
             <host>gateway-host-2</host>
             <port>7040</port>
         </secondary>
         <description/>
         <user/>
         <password/>
     </gatewayConnection>
             ...
</gatewayConnections>
...

Webslinger Copied

Webslinger is able to connect to both secure and insecure gateways. It has two different lines in its configuration file for connections. Those that start GATEWAY=are used to specify connections to insecure gateways, while those that startSECURE\_GATEWAY= are used to connect to secure gateways.

Auditor Copied

Auditor is able to connect to both secure and insecure gateways. It has two different lines in its configuration file for connections. Those that start GATEWAY=are used to specify connections to insecure gateways, while those that startSECURE\_GATEWAY= are used to connect to secure gateways.

Validating Geneos Components Copied

As well as specifying the TLS certificates to use when creating a secure connection, some Geneos components support the verification of certificates used by the other party. This is done by providing a key chain of signing certificates via a PEM file to the Geneos component. This file is specified using the -ssl-certificate-chain command line option.

-ssl-certificate-chain <file>

The following Geneos components support this feature:

• Gateway
• Netprobe
• WebSlinger
• Licence Daemon

The Geneos component will check that all certificates presented to it during the establishment of a secure connection were signed by one of the signing certificates in the chain.

When a client connects to a server securely, the server must provide its certificate in order for a secure connection to be established. The client will always verify this certificate against it’s certificate chain (if it was provided one). If the certificate cannot be verified then the connection will be rejected.

When a server is connected securely to by a client, the client does not need to provide a certificate to the server. A Geneos component will provide this certificate if it has one but other clients (web browsers, API clients) may not. If the client does provided a certificate and the server has been provided with a chain of signing certificates, then the server will verify the client’s certificate against its certificate chain and reject the connection if the certificate cannot be verified. If the client does not provide a certificate, the server has nothing to check and will accept the secure connection.

Some Geneos servers can be configured to require that certificates are provided for certain types of connection. Currently the Gateway and Netprobe provide this functionality.

The Netprobe can be configured to ensure that all incoming EMF2 connections to be established with a certificate. This allows the netprobes to ensure that they only accept connections from machines whose SSL certificate has been signed by the certificate authority used by the Netprobe to verify certificates.

This is enabled by using the command line option with EMF2 as the argument:

-require-ssl-certificate-for emf2

If this setting is enabled then all Geneos components connecting to the Netprobe will be required to provide a valid certificate. (There is one exception which is netprobes connection using the XMLRPC protocol which can be enabled as part of the Message Tracker plugin).

The Gateway can be configured to ensure that require certificates for different incoming Geneos components. These are netprobes, secondary gateways and importing gateways. The requirements are controlled from a section of the Gateway setup. (In the Operating Enviroment section under the Connections tab)

Note

If either Gateway or Netprobe require certificates for an incoming connection of a specific type, then all insecure connections of the specified type will be rejected as insecure connections do not provide a certificate.

Debugging Client Connections Copied

If an error occurs connecting to a secure server, the server log is the place to look to understand the issue. The server is sent a message, and even if the message is sent to the incorrect port it can try to identify the type and place a useful message in its log.

Server log messages for a client trying to connect insecurely to a server using its secure port. This will occur both for SSL aware clients that have been mis-configured and old clients that predate the SSL enhancement:

ERROR: SSLConnector:accept SSL Error:[1408f10b] SSL3_GET_RECORD:wrong version number
WARN: SSLConnector:accept Possible attempt to connect insecurely to a secure port

Server log messages for a client trying to connect securely to a server using its insecure port:

ERROR: CONNECTOR ERROR: Secure Connection from '...' received on insecure port. Dropping connection

If the server being connected to is old and predates SSL support then the server will not print any log message. The SSL handshake will time out because the server has not responded correctly to the client. In this case there will be an error in the client log of the form:

ERROR: SSLConnector SSL Connection(=>127.0.0.1:19067) failed to complete handshake in 70s : Dropping connection

Connection details on Geneos Copied

This section covers the list of all incoming connections from and outgoing connections to each component of Geneos. Also, this list identifies if the components require an SSL encryption or not, and other information relevant to Geneos connections.

Incoming connections Copied

Component	Incoming connection from	SSL encryption	SSL verification of connecting components	Port	Service	Source IP	Destination IP	Purpose
Netprobe	Gateway			User-defined Default: 7036	Netprobe	Any Gateway node	Any Netprobe node	Netprobe-Gateway communication (normal probes). This supports two-way SSL verification when using Secure. Beginning Geneos 7.12.x, secure with reversed roles encrypts using the Gateway certificate and does not authenticate the Netprobe.
Netprobe	ORB debug page		N/A	Same as listen port for Netprobe Default: 7036	ORB debug	Web browser	Any Netprobe node	ORB debug
Plugins	API Plug-in (XML-RPC)		N/A	User-defined Default: 7036	Netprobe XML-RPC API	Any external client	Any Netprobe node	Manipulates dataviews using XML-RPC API
Plugins	REST API		N/A	User-defined Default: HTTP-only server at port 7136	Netprobe REST API	Any external client	Any Netprobe node	Manipulate dataviews and streams using Netprobe REST API
Plugins	Message Tracker plugin real-time Checkpoint		N/A	User-defined Default: 7036	Netprobe XML-RPC API	Any external client	Any Netprobe node	External real-time checkpoint for Message Tracker
Plugins	Message Tracker plugin XML-RPC Source		N/A	User-defined Default: 7036	Netprobe XML-RPC API	Any external client	Any Netprobe node	External data source for Message Tracker
Plugins	Trapmon	N/A	N/A	On Unix: User-defined Default: 162 On Windows: None	SNMP	Any external client	Any Netprobe node	Monitors incoming SNMP traps
File Agent	Fix Analyser 2 Netprobe			User-defined Default: 7030	File Agent	Any FIX Analyser 2 Netprobe	Any File Agent node	Sends contents of monitored files
File Agent	ORB debug page	N/A	N/A	Same as listen port for Gateway Default: 7030	ORB debug	Web browser	Any File Agent node	ORB debug
FIX Analyser 2 Netprobe	Gateway			User-defined Default: 7030	Fix Analyser 2 Netprobe	Any Gateway node	Any FIX Analyser 2 Netprobe node	Fix Analyser 2 Netprobe-Gateway communication
FIX Analyser 2 Netprobe	ORB debug page		N/A	Same as listen port for Gateway Default: 7030	ORB debug	Web browser	Any FIX Analyser 2 Netprobe node	ORB debug
FIX Analyser 2 Netprobe	Order reports browser interface	N/A	N/A	Same as listen port for Gateway Default: 7030	HTTP	Web browser or Active Console	Any FIX Analyser 2 Netprobe node	Provides HTML-based report regarding FIX orders
Gateway	Self-Announcing Netprobe			User-defined Default: 7039	Netprobe	Any Self-Announcing Netprobe	Any Gateway node	Netprobe-Gateway communication (SAN probes). This supports two-way SSL verification
Gateway	Floating Netprobe			User-defined Default: 7039	Netprobe	Any Floating Probe	Any Gateway node	Netprobe-Gateway communication (Floating probes). This supports two-way SSL verification
Gateway	Active Console		N/A	User-defined Default: 7039	Gateway Client (Active Console and GSE)	Any Active Console or GSE	Any Gateway node	Active Console-Gateway communication
Gateway	Gateway Sharing			User-defined Default: 7039	Gateway Sharing	Any Gateway node	Any Gateway node	Gateway sharing. This supports two-way SSL verification
Gateway	Web Dashboard		N/A	User-defined Default: 7039	Gateway Client (Web Dashboard)	Any Web Dashboard	Any Gateway node	Web Dashboard-Gateway communications
Gateway	Webslinger		N/A	User-defined Default: 7039	Gateway Client (Webslinger)	Any Webslinger	Any Gateway node	Webslinger-Gateway communications
Gateway	ORB debug page		N/A	Same as listen port for Gateway Default: 7039	ORB debug	Web browser	Any Gateway node	ORB debug
Gateway	Gateway as Web server		N/A	Same as listen port for Gateway Default: 7039	HTTP serving of static pages	Web browser	Any Gateway node	Serving of helper pages (Knowledge base)
Gateway	Gateway REST Command		N/A	Same as listen port for Gateway Default: 7039	REST API for commands and other REST services	Any external client	Any Gateway node	Running commands through REST
Active Console	ORB debug page		N/A	User-defined Default: 7040	ORB Debug	Web browser	Active Console host	ORB debug
Web Dashboard	Browser interface		N/A	User-defined Default: 8080	Web Dashboard	Web browser	Web Dashboard host	Web Dashboard application
Web Dashboard	JMX metrics		N/A	User-defined JMX port (run script specifies 50505)	JMX client	JMX client node	Web Dashboard host	JMX monitoring
Webslinger	Browser interface		N/A	User-defined Default: 8080	Webslinger	Web browser	Webslinger host	Webslinger application
Licence Daemon	Gateway		N/A	User-defined Default: 7041	Licence Daemon	Gateway node	Licence Daemon node	Get licences
Licence Daemon	Browser interface		N/A	User-defined Default: 7041	Licence Daemon reporting	Web browser	Licence Daemon node	Get licence details
SSO Agent	Active Console		N/A	User-defined Default: 8080	SSO Agent	Active Console node	SSO Agent node	SSO Agent application
SSO Agent	Web Dashboard		N/A	User-defined Default: 8080	SSO Agent	Web Dashboard node	SSO Agent node	SSO Agent application
SSO Agent	Webslinger		N/A	User-defined Default: 8080	SSO Agent	Webslinger node	SSO Agent node	SSO Agent application
SSO Agent	Gateway		N/A	User-defined Default: 8080	SSO Agent	Gateway node	SSO Agent node	SSO Agent application
Collection Agent	Health check	N/A	N/A	User-defined Default: 9136	Collection Agent health check	Netprobe node	Collection Agent node	Collection Agent health check
Collection Agent plugins	Health check	N/A	N/A	User-defined Default: 8125	StatsD server	StatsD client node	Collection Agent node	Publishing for StatsD clients

Outgoing connections Copied

Component	Outgoing connection to	SSL encryption	SSL verification of connecting components	Port	Service	Source IP	Destination IP	Purpose
Netprobe	Gateway			User-defined	Gateway	Any Netprobe node	Any Gateway node	Netprobe-Gateway communication (Self-Announcing Netprobes and floating probes). This supports two-way SSL verification.
Netprobe	SAN/Floating config from URL			User-defined	HTTP/HTTPS	Any Netprobe node	Any Web server	Gets the Netprobe setup file from a Web server
Plugins	Bloomberg-bpipe	N/A	N/A	User-defined Default: 8194	B-PIPE	Any Netprobe node	Bloomberg B-PIPE server	Bloomberg monitoring
Plugins	Control-M			User-defined	HTTPS	Any Netprobe node	Any Control-M server	Gets information regarding jobs in a Control-M sever (only the built-in plug-in for REST API version)
Plugins	E4JMS (Tibco EMS)		N/A	User-defined	EMS server port	Any Netprobe node	Any Tibco EMS server	Monitors Tibco EMS server
Plugins	IBM-i plugins	N/A	N/A	Refer to JT400 Ports	Refer to JT400 Ports	Any Netprobe node	IBM-i node	Monitors IBM-i
Plugins	JMX Server	N/A	N/A	User-defined	JMX	Any external client	Any server running an JMX-enabled application
Plugins	JMX ThreadInfo	N/A	N/A	User-defined	JMX	Any external client	Any server running an JMX-enabled application
Plugins	Mibmon	N/A	N/A	User-defined Default: 161	SNMP	Any Netprobe node	Any SNMP server	Gets the MIBS information from a SNMP server
Plugins	MQ (IBM MQ)	N/A	N/A	User-defined	MQ	Any Netprobe node	MQ server	Gets information from MQ server
Plugins	Oracle	N/A	N/A	User-defined	Database	Any Netprobe node	Any database server	Performs queries on a database
Plugins	REST Extractor		N/A	User-defined	HTTP/HTTPS	Any Netprobe node	Any web server	Performs queries on a database
Plugins	SQL Toolkit	N/A	N/A	User-defined Default for MySQL, SQL Server, Postgre SQL: 3306	Database	Any Netprobe node	Any web server	Performs queries on a database
Plugins	Sybase	N/A	N/A	User-defined	Database	Any Netprobe node	Any database server	Performs queries on a database
Plugins	Web-mon	N/A	N/A	User-defined Default on HTTP: 80 Default on HTTPS: 443	HTTP/HTTPS	Any Netprobe node	Any web server	Performs queries on a database
Plugins	Publisher		N/A	User-defined	Elasticsearch	Any Netprobe node	Elasticsearch server	Publishes data to Elasticsearch
FIX Analyser 2 Netprobe	Database	N/A	N/A	User-defined	MySQL	Any Fix Analyser 2 Netprobe	Any MySQL server	Augments HTML-based order reports to display drill-down message level data
FIX Analyser 2Netprobe	File Agent	N/A	N/A	User-defined Default: 7030	File Agent	Any FIX Analyser 2Netprobe	Any File Agent node	Sends contents of monitored files
Gateway	Netprobe			User-defined	Netprobe	Any Gateway	Any Netprobe	Netprobe-Gateway communication
Gateway	Licence Daemon			User-defined	License Server	Any Gateway	Any Licence Daemon	Requests licenses for Gateway and its probes and samplers
Gateway	Database Logging	N/A	N/A	User-defined	Database	Any Gateway	Any database server	Inserts data on the database
Gateway	Valo Stream Data Plug-in
Gateway	Kafka (Publishing)		N/A	User-defined	Kafka	Any Gateway	Any Kafka server	Pushes Geneos metrics into Kafka queues
Gateway	Remote Include files		N/A	User-defined	HTTP/HTTPS	Any Gateway	Any web server	Requests remote include files
Gateway	Gateway Sharing			User-defined	Gateway	Any Gateway	Any Gateway node	Shares Gateway data
Gateway	Gateway Hub	N/A	N/A	User-defined	Gateway Hub (Publishing) Gateway Hub REST (HTTP/HTTPS)	Any Gateway	Any Gateway node	Interacts with Gateway Hub
Gateway Hub	Kafka (Publishing)		N/A	User-defined	Kafka	Any Gateway Hub node	Any Kafka server	External Kafka Publishing
Active Console	Gateway		N/A	User-defined	Gateway	Active Console node	Any Gateway Hub node	Connection to secure Gateways
Active Console	Database		N/A	User-defined	Database	Active Console node	Any Gateway Hub node
Active Console	Gateway Hub		N/A	User-defined	Gateway Hub Rest (HTTP/HTTPS)	Active Console node	Any Gateway Hub node
Web Dashboard	Gateway			User-defined	Gateway	Web Dashboard node	Any Gateway Hub node	Supports two-way SSL authentication
Webslinger	Gateway			User-defined	Gateway	Webslinger node	Any Gateway Hub node
SSO Agent	AD server		N/A	User-defined	AD service	SSO Agent node	Active Directory server	Gets user details and permissions from Active Directory

Web services Copied

Certain Geneos Components provide web services. These web services can be accessed via HTTP or HTTPS depending on whether the service is published on a secure or an insecure port. Any web service that is published via the same port that is used for EMF connections will inherit the security settings from the EMF settings. So, for example if a Netprobe is started with the -secure flag or -secure-port, then its web services will also be secure. The ORB debug pages will only be viewable via HTTPS. XML-API connections to the probe will need to use HTTPS rather than HTTP.

HTTP and HTTPS do not use a reverse-TLS listen port. For API and debug access with secure with reversed TLS roles, the Netprobe must also listen on -port, -secure-port, or both. For more information, see Dual listen and traffic policy. To limit which hosts can use those HTTP, debug, and API endpoints, set TRUSTED_HTTP_HOSTS, TRUSTED_DEBUG_HOSTS, and TRUSTED_API_HOSTS. For more information, see Restrict HTTP hosts.

Hot Standby Gateways Copied

Hot standby gateways connect to one another using Geneos’ EMF protocol. If one Gateway is configured to use TLS security then both must be. If a secondary Gateway is configured to listen on a secure port, then when it is connecting to the primary Gateway it will attempt to connect securely. If the primary Gateway is not also configured to listen on a secure port then the Gateway will fail to connect.

Load balancers Copied

Geneos client components using the Geneos EMF protocol supply a Server Name Indication (SNI) in their TLS ClientHello message, except when the destination address is a numeric IP or localhost.

Providing an SNI allows routing components such as load balancers or ingress servers to identify the target destination. Many routing components are able to use this information to route TLS connections correctly.

Examples Copied

The following examples show how to set up secure communications between Geneos components. Example 1 uses certificates on both the Gateway and the Netprobe. Example 2 uses a self-announcing Netprobe. Example 3 uses secure with reversed TLS roles (Geneos 7.12.x and later). To try these examples you will need a Gateway, Netprobe, and Active Console, all of version 3.1.X or higher. You will also need a copy of openssl to generate a set of certificates.

Note

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit.

Following this example you will generate a pair of self signed certificates, however in production it is assumed that genuine certificates signed by a recognized certificate authority will be used.

Example 1 Copied

Example 1 has a Netprobe and Gateway running on the same Linux machine, and an Active Console connected to them.

If you are running a different platform, replace the names of the Gateway and Netprobe binaries in the commands below with its corresponding platform binary.

First, create a pair of certificates using OpenSSL. One for the Netprobe (np.pem) and one for the Gateway (gw.pem).

Generate your own self-signed Certificate Authority:

> openssl genrsa -out rootCA.key 2048
> openssl req -x509 -new -nodes -key rootCA.key -days 1024 -out rootCA.pem -subj "/CN=certificateAuthority"

Generate a certificate for your Netprobe:

> openssl genrsa -out np.key 2048
> openssl req -new -key np.key -out np.csr -subj "/CN=<Netprobe server host name>"
> openssl x509 -req -in np.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out np.crt -days 30
> cat np.crt np.key > np.pem

For the common name ("/CN= "), specify the Netprobe server host name, without the angle brackets.

Generate a certificate for your Gateway:

> openssl genrsa -out gw.key 2048
> openssl req -new -key gw.key -out gw.csr -subj "/CN=<Gateway server host name>"
> openssl x509 -req -in gw.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out gw.crt -days 30
> cat gw.crt gw.key > gw.pem

For the common name ("/CN= "), specify the Gateway server host name, without the angle brackets.

Next, copy the setup (eg1.setup.xml) into the Gateway directory, the newly generated certificate (gw.pem), and the certificate of the CA (rootCA.pem). Then, start the Gateway as follows (replace <LICD-HOST> by the location of your Licence Daemon).

> gateway2.linux -setup eg1.setup.xml -licd-host <LICD-HOST> -ssl-certificate ./gw.pem -ssl-certificate-chain ./rootCA.pem

This will start a directory running on the default port. You can connect to this Gateway using the Active Console. Note that you will have to tick the Secure Connection option in the Gateway connections dialog as the Gateway has been configured only to listen on a secure port. See below:

You should find that you are connected to the Gateway (which will be red). Looking at the Gateway Managed Entity you will see in the client view that the Active Console has connected securely to the Gateway.

Looking at the GW view you will see that there are two Gateway ports are listed. The insecurePort is set to 7039, indicating that the Gateway is listening insecurely on that default insecure port, while the securePort value is 7038 indicating that the Gateway is listening securely on the default secure Gateway port.

Now you can start the Netprobe. Copy the Netprobe certificate (np.pem) and the certificate of the CA (rootCA.pem) into the Netprobe directory start the Netprobe by typing;

> netprobe.linux -ssl-certificate ./np.pem -secure -ssl-certificate-chain ./rootCA.pem

The Gateway will now connect to the probe and go green. If you now look Probes view on the Gateway Managed Entity you will see that the Gateway has connected to the probe and the connection is secure.

The Netprobe is now connected and all the Netprobe functionality is available to the user via the Gateway and the Active Console.

Example 2 Copied

Example 2 has a Netprobe and Gateway running on the same computer, and a Active Console connected to them.

The difference is that the Netprobe is configured to be a self announcing Netprobe and so the Netprobe will not require a certificate in order to perform secure communications. Again, all 3 components will need to be version 3.1.X or better. The assumption is that you are using the linux version of the Gateway and Netprobe.

If you use a different version, please replace the names of the Gateway and Netprobe binaries in the commands below with the ones appropriate for your system.

Please follow the instructions from Example 1 to create the key pairs (you will only be using the gw.pem key pair).

Next copy the setup (eg2.setup.xml) into the Gateway directory and the newly generated certificate (gw.pem). Now start the Gateway as follows (please replace by the location of your licence daemon);

> gateway2.linux -setup eg2.setup.xml -licd-host <LICD-HOST> -ssl-certificate ./gw.pem

This will start a directory running on the default port. You can connect to this Gateway using the Active Console. Note that you will have to tick the Secure Connection option in the Gateway connections dialog as the Gateway has been configured only to listen on a secure port. See below:

You should find that you are connected to the Gateway. Looking at the Gateway Managed Entity you will see in the client view that the Active Console has connected securely to the Gateway.

Looking at the GW view you will see that there are two Gateway ports are listed, just as in example 1. The insecurePort is set to 7039, indicating that the Gateway is listening insecurely on that default insecure port, while the securePort value is 7038 indicating that the Gateway is listening securely on the default secure Gateway port.

Now you can start the self-announcing Netprobe. Copy the Netprobe setup from (eg2_np.setup.xml) into the Netprobe directory and start the Netprobe by typing;

> netprobe.linux -setup eg2_np.setup.xml

Looking at eg2.np.xml you will see that the Gateway section specifies to connect securely to the Gateway on port 7038.

<?xml version="1.0" encoding="ISO-8859-1"?>
<netprobe
   compatibility= 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA2011.2-110303/netprobe.xsd">
   <selfAnnounce>
      <enabled>true</enabled>
      <retryInterval>20</retryInterval>
      <probeName>Probe</probeName>
      <managedEntity>
         <name>ME</name>
         <types>
            <type>HW</type>
         </types>
      </managedEntity>
      <gateways>
         <gateway>
            <hostname>localhost</hostname>
            <port>7038</port>
            <secure>true</secure>
         </gateway>
      </gateways>
   </selfAnnounce>
</netprobe>

The Netprobe will connect to the Gateway and a new row will appear in the Probes view indicating that a new Self-Announcing probe has connected and that it is connected securely.

Example 3 Copied

You can encrypt the Gateway–Netprobe EMF2 session with the Gateway certificate and without a Netprobe private key.

1. Provide a Gateway certificate and private key (for example, gw.pem from Example 1).
2. Start the Gateway with that key pair. In the probe definition, set Connection Security to Secure with reversed roles, and set Port to the Netprobe reverse-TLS listen port (for example, 7036).
3. Start the Netprobe without a private key:

> netprobe.linux -secure-with-reversed-tls-roles-port 7036 -ssl-certificate-chain ./rootCA.pem

-ssl-certificate-chain is optional. If you specify it, the Netprobe checks that the Gateway certificate is trusted. That check is the same as for any other Geneos TLS client. Geneos does not compare the server name in the certificate with a hostname.

To keep HTTP, API, and debug endpoints available, also listen on an insecure port, a Secure port, or both. For example:

> netprobe.linux -port 7037 -secure-with-reversed-tls-roles-port 7036 -ssl-certificate-chain ./rootCA.pem

In this dual-listen setup, set Port in the Gateway probe definition to 7036 (the reverse-TLS port). The Gateway does not accept EMF2 on 7037.

Verifying a certificate Copied

To verify that a certificate is valid for its intended purpose, run:

openssl x509 -purpose -noout -text -in certificate.pem

To verify that a certificate has been correctly signed by the given CA, run:

openssl verify -CAfile ca-cert.pem certificate.pem

Get the fingerprint and subject of an SSL Certificate Copied

When connecting to the Gateway an SSL Identity may be required for authentication if an SSL Certificate is used. The identity can be the fingerprint or subject of an SSL Certificate. How to generate a fingerprint or subject (using Webslinger as an example) is shown below:

Fingerprint generation Copied

> openssl x509 -in webslinger.pem -fingerprint -noout | sed 's/://g'
SHA1 Fingerprint=78B6CE43DF1D8C7A62BEAFFC988AFFA1EFC9DC7C

The fingerprint is all characters after ‘=’. Copy this to the Gateway config.

Subject generation Copied

> openssl x509 -in webslinger.pem -subject -noout
subject= /CN=Webslinger/C=UK/L=London/O=ITRS

The subject is all characters after “subject= “. Ensure there are no leading or trailing spaces. Copy this to the Gateway config.