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.
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 thisenabled
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
or127.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, followsafkeyring:
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
isneed
orwant
. 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 valuepassword
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...