TCP input parameters

OMEGAMON® Data Connect TCP input parameters specify how OMEGAMON Data Connect listens for data over a TCP network from OMEGAMON Data Broker.

Figure 1. OMEGAMON Data Connect configuration: TCP input
OMEGAMON Data Connect receives data from OMEGAMON Data Broker over TCP

In the context of OMEGAMON Data Connect receiving data from OMEGAMON Data Broker, OMEGAMON Data Connect is the server and OMEGAMON Data Broker is the client.

connect:
  input:
    tcp:
      enabled: <true|false> # Default at this level: false
      hostname: <string>
      port: <number>
      ssl: # Optional
        <SSL parameters>
enabled
Whether this function is enabled. Allowed values: true, false. This key is optional. Default: false.

To enable this function, you must specify enabled: true.

Specifying enabled: false has the same effect as commenting-out the parent key of this enabled key and all descendants of that parent key.

hostname
Hostname or IP address on which the OMEGAMON Data Connect host listens for data from OMEGAMON Data Broker.

Some typical values:

0.0.0.0
All IPv4 addresses on the local machine.
localhost or 127.0.0.1
Loopback address.

This hostname or IP address must correspond to the hostname or IP address to which OMEGAMON Data Broker sends data, specified by the OMEGAMON Data Broker parameter SINK_HOST.

If you run OMEGAMON Data Connect and OMEGAMON Data Broker on the same z/OS® instance (LPAR), then you can specify localhost for both this hostname and the OMEGAMON Data Broker sink hostname.

port
Port on which to listen for data from OMEGAMON Data Broker.

This value must match the OMEGAMON Data Broker parameter SINK_PORT.

SSL parameters

connect.input.tcp.ssl:

enabled: <true|false>
ciphers: <ciphers_list>
client-auth: <need|none|want>
enabled-protocols: <protocols_list>
protocol: <protocol>
key-alias: <string>
key-password: <string>
key-store: <string>
key-store-password: <string>
key-store-type: <JKS|PKCS12|JCERACFKS>
trust-store: <string>
trust-store-password: <string>
trust-store-type: <JKS|PKCS12|JCERACFKS>
enabled
Whether to enable SSL/TLS:
true
Enable SSL/TLS.
false
Disable SSL/TLS.

This key is optional. Default: true.

Use enabled: false as a convenient single-line method for disabling SSL/TLS, as an alternative to using YAML comment syntax to comment-out all of the SSL parameters.

ciphers
A list of candidate ciphers for the connection, in one of the following formats:
  • OpenSSL cipher list
  • A comma-separated list of ciphers using the standard OpenSSL cipher names or the standard JSSE cipher names

This key is optional. Example, in OpenSSL cipher list format:

HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!kRSA

client-auth
Client authentication. Whether to request a client certificate from the client, and then whether to allow the connection based on the client response.
need
Request a client certificate. Allow the connection only if the client responds with a valid certificate.
none
Do not request a client certificate. Allow the connect without client authentication.
want
Request a client certificate. If the client responds with a certificate, allow the connection only if the certificate is valid. If the client does not respond with a certificate, allow the connection.
enabled-protocols
List of protocols to enable.

This key is optional. Example:

TLSv1.3,TLSv1.2

protocol
Protocol to use.

If this protocol is not supported by both ends of the connection, then the connection can fall back (downgrade) to one of the other enabled protocols.

This key is optional. Default in Java™ 17: TLSv1.3.

key-alias
Alias of the server private key and associated server certificate in the keystore. On z/OS, the alias is also known as the certificate label.

This key is optional. Default: the default certificate in the keystore.

key-password
Password required to access the server private key in the keystore.

This key is optional. Default: the value of key-store-password.

key-store-password
Password to access the keystore.

If the keystore type is JCERACFKS, then specify the fixed value:

password

RACF® does not use this value for authentication; this value is required only for compatibility with the JCE requirement for a password.

key-store
Location of the keystore that contains the server certificate.

The location format depends on the keystore type:

JKS
Keystore file path. Example:
/u/my/security/certs/certs.jks
PKCS12
Keystore file path. Example:
/u/my/security/certs/certs.p12
JCERACFKS
Only valid if OMEGAMON Data Connect runs on z/OS.

RACF key ring, in the following format:

safkeyring://<owner_user_id>/<key_ring_name>
Note: In this specific context, follow safkeyring: with two (2) consecutive slashes.

where <owner_user_id> is the RACF user ID that owns the key ring and <key_ring_name> is the RACF key ring name. Example:

safkeyring://STCOMDP/OMDPring
key-store-type
Keystore type. Supported types depend on the security providers in the JRE. Examples:
JKS
Java keystore.
PKCS12
Public-Key Cryptography Standards (PKCS) #12.
JCERACFKS
Java Cryptography Standards (JCE) RACF keystore (key ring). Only available if OMEGAMON Data Connect is running on z/OS and the IBMZSecurity provider is available in the JRE.
trust-store
Location of the truststore that contains trusted client certificates. See the list of example locations for key-store.

A truststore is required only for client authentication; that is, when the value of client-auth is need or want.

trust-store-password
Password to access the truststore.

If the truststore type is JCERACFKS, then specify the fixed value:

password

RACF does not use this value for authentication; this value is required only for compatibility with the JCE requirement for a password.

trust-store-type
Truststore type. See the list of example types for key-store-type.

Example: Connection to OMEGAMON Data Broker running on the same z/OS LPAR as OMEGAMON Data Connect, with no TLS

This example listens for data from OMEGAMON Data Broker on the localhost loopback address. In this case, OMEGAMON Data Connect and OMEGAMON Data Broker must be running on the same z/OS instance (LPAR). The data is not exposed on a network; there is no TLS.

connect:
  input:
    tcp:
      enabled: true
      hostname: localhost
      port: 15379

  output:
    # One or more outputs...

Example: Secure connection over TLS using the same RACF key ring as both keystore and truststore

In this example:

  • OMEGAMON Data Connect is running on z/OS, so it can use the JCERACFKS keystore and truststore type, and refer to RACF key rings. Note the fixed value password for the keystore and truststore passwords.
  • OMEGAMON Data Connect requires client authentication: OMEGAMON Data Broker must provide a valid certificate.
connect:
  input:
    tcp:
      enabled: true
      hostname: 0.0.0.0
      port: 15379
      ssl:
        enabled-protocols: TLSv1.2
        protocol: TLS
        client-auth: need
        # Certificates of trusted clients (instances of OMEGAMON Data Broker)
        trust-store: safkeyring://STCOMDP/OMDPring
        trust-store-type: JCERACFKS
        trust-store-password: password
        # Server certificate
        key-store: safkeyring://STCOMDP/OMDPring
        key-store-type: JCERACFKS
        key-store-password: password
        key-alias: OMDPcert

  output:
    # One or more outputs...

Example: Secure connection over TLS using PKCS12 keystore and JKS truststore

In this example:

  • OMEGAMON Data Connect might be running on or off z/OS.
  • OMEGAMON Data Connect requires client authentication: OMEGAMON Data Broker must provide a valid certificate.
  • OMEGAMON Data Connect uses the default certificate in the keystore.
connect:
  input:
    tcp:
      enabled: true
      hostname: 0.0.0.0
      port: 15379
      ssl:
        enabled-protocols: TLSv1.2
        protocol: TLS
        client-auth: need
        # Trusted client certificates
        trust-store: /u/my/security/certs/omdp-broker.jks
        trust-store-type: JKS
        trust-store-password: Pa$$w0rdTS
        # Server certificate
        key-store: /u/my/security/certs/omdp-connect.p12
        key-store-type: PKCS12
        key-store-password: Pa$$w0rdKS

  output:
    # One or more outputs...