OMEGAMON Data Broker configuration parameters

OMEGAMON Data Broker configuration parameters link data sources to OMEGAMON Data Connect.

OMEGAMON Data Broker receives data from a data source and then forwards the data to OMEGAMON Data Connect — Figure 1. OMEGAMON Data Broker configuration points: store, forwarder, and sink

In the context of the TCP connection between OMEGAMON Data Broker and OMEGAMON Data Connect, OMEGAMON Data Broker is the client and OMEGAMON Data Connect is the server.

OMEGAMON Data Broker receives data from a data source into an internal store, and then forwards the data to OMEGAMON Data Connect.

To configure OMEGAMON Data Broker, you define a forwarder with a store as its source and an instance of OMEGAMON Data Connect as its sink.

A basic configuration has a single store, forwarder, and sink. Advanced configurations can have multiple stores, forwarders, and sinks.

An OMEGAMON Data Broker configuration consists of the following types of parameters:

General parameters: Register Zowe™ cross-memory server plug-ins, including OMEGAMON Data Broker.
Store parameters: Define the stores that data sources write to. When a data source sends data to OMEGAMON Data Broker, the data source specifies a store name. The OMEGAMON Data Broker configuration must include store parameters that define a store with that name. A data source can specify a store name that is used only by that data source, or a store name that is also used by other data sources.
Sink parameters: Define a connection to OMEGAMON Data Connect.
Forwarder parameters: Link stores to sinks. Each forwarder links one store to one sink.

Format

Only a few parameters are required; most are optional.

The following listing shows a minimal complete set of required parameters for a basic configuration:

ZWES.PLUGIN.KAY.ZISDYNAMIC=KAYSISDL
ZWES.PLUGIN.KAY.CIDB=KAYB0001
KAY.CIDB.STORE.<store_id>.NAME=<store_name>
KAY.CIDB.FWD=ON
KAY.CIDB.FWD.<forwarder_id>.SOURCE_STORE=<store_name>
KAY.CIDB.FWD.<forwarder_id>.SINK_HOST=<connect_hostname>
KAY.CIDB.FWD.<forwarder_id>.SINK_PORT=<connect_port>

The order of parameters in the configuration member is not significant. The order presented here is a typical order only.

OMEGAMON Data Broker configuration parameter names are case-sensitive.

The following listings show the comprehensive set of required and optional parameters.

General parameters:

* General parameters: required
ZWES.PLUGIN.KAY.ZISDYNAMIC=KAYSISDL
ZWES.PLUGIN.KAY.CIDB=KAYB0001

Store parameters:

* Store parameters: required
KAY.CIDB.STORE.<store_id>.NAME=<store_name>

* Store parameters: optional
KAY.CIDB.STORE.<store_id>.CELL.<cell_id>.SIZE=<bytes>
KAY.CIDB.STORE.<store_id>.CELL.<cell_id>.CAPACITY=<number>
KAY.CIDB.STORE.<store_id>.QUEUE.CAPACITY=<number>

Forwarder and sink parameters have two alternative formats:

Forwarder parameters with forwarder-scope sink parameters

Forwarder-scope parameters apply only to that forwarder:

* Forwarder parameters: required
KAY.CIDB.FWD=ON
KAY.CIDB.FWD.<forwarder_id>.SOURCE_STORE=<store_name>

* Forwarder-scope sink parameters: required
KAY.CIDB.FWD.<forwarder_id>.SINK_HOST=<connect_hostname>
KAY.CIDB.FWD.<forwarder_id>.SINK_PORT=<connect_port>

* Forwarder parameters: optional
KAY.CIDB.FWD.<forwarder_id>.CONNECT_RETRY_INTERVAL=<seconds>
KAY.CIDB.FWD.<forwarder_id>.MAX_CONNECT_RETRY_ATTEMPTS=<number>
KAY.CIDB.FWD.<forwarder_id>.RECORD_QUEUE_LIMIT=<records>
KAY.CIDB.FWD.<forwarder_id>.MAX_BATCH_SIZE=<records>
KAY.CIDB.FWD.<forwarder_id>.LOGOPTS=--verbosity <log_level>

* Forwarder-scope sink parameters: optional
KAY.CIDB.FWD.<forwarder_id>.CONNECT_TIMEOUT=<seconds>
KAY.CIDB.FWD.<forwarder_id>.RECEIVE_TIMEOUT=<seconds>
KAY.CIDB.FWD.<forwarder_id>.SEND_TIMEOUT=<seconds>
KAY.CIDB.FWD.<forwarder_id>.PROTOCOL_VERSION=<protocol_version>

* Forwarder-scope sink SSL parameters: only required if sink connection uses SSL/TLS
KAY.CIDB.FWD.<forwarder_id>.SECURITY=<string>
KAY.CIDB.FWD.<forwarder_id>.FIPS=<ON|OFF>
KAY.CIDB.FWD.<forwarder_id>.KEYRING=<string>
KAY.CIDB.FWD.<forwarder_id>.STASH=<string>
KAY.CIDB.FWD.<forwarder_id>.PASSWORD=<string>
KAY.CIDB.FWD.<forwarder_id>.CIPHERS=<string>
KAY.CIDB.FWD.<forwarder_id>.CERTLABEL=<string>
KAY.CIDB.FWD.<forwarder_id>.KEYSHARES=<string>
KAY.CIDB.FWD.<forwarder_id>.ECURVES=<string>

* Optional: More forwarders...

Forwarder parameters that refer to reusable sink parameters

Multiple forwarders can refer to the same set of reusable sink parameters:

* Reusable sink parameters: required
KAY.CIDB.SINK.<sink_id>.HOST=<connect_hostname>
KAY.CIDB.SINK.<sink_id>.PORT=<connect_port>

* Reusable sink parameters: optional
KAY.CIDB.SINK.<sink_id>.CONNECT_TIMEOUT=<seconds>
KAY.CIDB.SINK.<sink_id>.RECEIVE_TIMEOUT=<seconds>
KAY.CIDB.SINK.<sink_id>.SEND_TIMEOUT=<seconds>
KAY.CIDB.SINK.<sink_id>.PROTOCOL_VERSION=<protocol_version>

* Reusable sink SSL parameters: only required if sink connection uses SSL/TLS
KAY.CIDB.SINK.<sink_id>.SECURITY=<string>
KAY.CIDB.SINK.<sink_id>.FIPS=<ON|OFF>
KAY.CIDB.SINK.<sink_id>.KEYRING=<string>
KAY.CIDB.SINK.<sink_id>.STASH=<string>
KAY.CIDB.SINK.<sink_id>.PASSWORD=<string>
KAY.CIDB.SINK.<sink_id>.CIPHERS=<string>
KAY.CIDB.SINK.<sink_id>.CERTLABEL=<string>
KAY.CIDB.SINK.<sink_id>.KEYSHARES=<string>
KAY.CIDB.SINK.<sink_id>.ECURVES=<string>

* Optional: More sinks...

* Forwarder parameters: required
KAY.CIDB.FWD=ON
KAY.CIDB.FWD.<forwarder_id>.SOURCE_STORE=<store_name>

* Reference to reusable sink parameters: required
KAY.CIDB.FWD.<forwarder_id>.SINK=<sink_id>

* Forwarder parameters: optional
KAY.CIDB.FWD.<forwarder_id>.CONNECT_RETRY_INTERVAL=<seconds>
KAY.CIDB.FWD.<forwarder_id>.MAX_CONNECT_RETRY_ATTEMPTS=<number>
KAY.CIDB.FWD.<forwarder_id>.RECORD_QUEUE_LIMIT=<records>
KAY.CIDB.FWD.<forwarder_id>.MAX_BATCH_SIZE=<records>
KAY.CIDB.FWD.<forwarder_id>.LOGOPTS=--verbosity <log_level>

* Optional: More forwarders...

Reusable sink parameters are useful when you want multiple forwarders to use the same sink: you don't need to duplicate the sink parameters for each forwarder.

Forwarder-scope sink parameters take precedence over reusable sink parameters.

Tip: You can use forwarder-scope sink parameters to complete or individually override reusable sink parameters. For details, see Example: Completing or overriding reusable sink parameters with forwarder-scope sink parameters.

Location

OMEGAMON Data Broker configuration parameters are stored in the configuration member of the Zowe cross-memory server.

The configuration member name matches the following pattern:

ppppIPxx

where:

pppp: The first four characters of the Zowe cross-memory server load module name. OMEGAMON Data Provider supplies the Zowe cross-memory server load module in TKANMODP(KAYSIS01). The same load module is supplied with Zowe as ZWESIS01.
xx: The value of the optional MEM runtime parameter in the startup JCL for the Zowe cross-memory server. Default: 00.

For example:

Zowe cross-memory server load module name	MEM parameter in JCL	Configuration member name
KAYSIS01 (as supplied with OMEGAMON Data Provider)	`00` (default)	KAYSIP00
KAYSIS01	`01`	KAYSIP01
ZWESIS01 (as supplied with Zowe)	`00`	ZWESIP00
ZWESIS01	`01`	ZWESIP01

The configuration member must be in a PARMLIB data set. Either:

The data set specified by the PARMLIB ddname of the job step that runs the Zowe cross-memory server program.
If that job step does not specify a PARMLIB ddname, the system PARMLIB. For example, SYS1.PARMLIB.

For example, given the following JCL after any symbol substitution:

//BROKER    EXEC PGM=KAYSIS01,REGION=0M,
//          PARM='NAME=ODP_BROKER,MEM=02'
//PARMLIB   DD DSNAME=MY.ODP.PARMLIB

the fully qualified dsname of the configuration member is MY.ODP.PARMLIB(KAYSIP02).

A sample member is supplied in TKANSAM(KAYSIP00).

Parameter namespaces and IDs

OMEGAMON Data Broker configuration parameters are namespaced. Each parameter name is prefixed by a sequence of period-delimited qualifiers that specify the context of the parameter.

For example, in the following parameter name:

KAY.CIDB.FWD.<forwarder_id>.SINK_HOST

KAY: Specifies that the parameter belongs to OMEGAMON Data Provider.
CIDB: Specifies that the parameter belongs to the OMEGAMON Data Broker component of OMEGAMON Data Provider.
FWD: Specifies that the parameter belongs to a forwarder.
<forwarder_id>: Specifies which forwarder the parameter belongs to.

A parameter namespace can include one or more IDs, such as <store_id>, <sink_id>, or <forwarder_id>.

An ID specifies an instance of an object and groups the parameters for that object. The qualifier preceding the ID specifies the object type, such as store (STORE), sink (SINK), or forwarder (FWD). Objects of the same type must use different IDs.

An ID is a case-sensitive string of 1 - 8 alphanumeric characters (a - z, A - Z, 0 - 9).

Example IDs: STORE1, SINK2, FWD3, OM, 1, 2, 3, A, B, C.

Note: A forwarder and a store can use the same ID, such as OM, but this does not imply any relationship between them. Each forwarder specifies the name of the store to use as its source.

No other Zowe cross-memory server configuration parameters required

If you're only using the Zowe cross-memory server to host OMEGAMON Data Broker, then the Zowe cross-memory server configuration member only needs to contain the following parameters:

ZWES.PLUGIN.KAY.ZISDYNAMIC=KAYSISDL, to register the ZIS dynamic linkage base plug-in that is required by OMEGAMON Data Broker.
ZWES.PLUGIN.KAY.CIDB=KAYB0001, to register the OMEGAMON Data Broker plug-in.
KAY.CIDB-namespace OMEGAMON Data Broker configuration parameters described here.

You don't need to specify any other ZWES-namespace parameters for the Zowe cross-memory server itself.

Splitting long parameter values over multiple lines

Some parameters can have long values. However, the Zowe cross-memory server and OMEGAMON Data Broker use only the first 71 characters of each record in the configuration member.

To split long parameter values over multiple lines, use a backslash (\) as a line continuation character. Example:

KAY.CIDB.FWD.FWD1.KEYRING=\
  /u/my/long/directory/path/to/\
  a-long-file-name.p12

Leading spaces on continuation lines are ignored.

General parameters

Required general parameters:

ZWES.PLUGIN.KAY.ZISDYNAMIC=KAYSISDL

Registers ZISDYNAMIC, the ZIS dynamic linkage base plug-in.

OMEGAMON Data Broker requires the ZISDYNAMIC plug-in.

OMEGAMON Data Provider supplies the ZISDYNAMIC plug-in load module in TKANMODP(KAYSISDL). The same load module is supplied with Zowe as ZWESISDL.

If you are running OMEGAMON Data Broker in a Zowe cross-memory server in a separate installation of Zowe instead of the server supplied with OMEGAMON Data Provider, then use the following parameter name, without the KAY qualifier, and refer to the plug-in load module name as supplied with Zowe:

ZWES.PLUGIN.ZISDYNAMIC=ZWESISDL

ZWES.PLUGIN.KAY.CIDB=KAYB0001

Registers OMEGAMON Data Broker as a plug-in of the Zowe cross-memory server.

OMEGAMON Data Provider supplies the OMEGAMON Data Broker plug-in load module in TKANMODP(KAYB0001).

These plug-in load modules must be available to the Zowe cross-memory server. To be available to the server, the load modules must be members of a data set that is specified by the STEPLIB ddname of the job step that runs the server program, KAYSIS01.

Store parameters

Required store parameter:

KAY.CIDB.STORE.<store_id>.NAME=<store_name>

Defines a store.

The store name depends on the data source. When a data source sends data to OMEGAMON Data Broker, the data source specifies a store name.

You must define stores to match the store names used by your data sources.

If you use OMEGAMON monitoring agents as a data source, you must define a store named OMEGAMON.

For store names used by other data sources, see the separate documentation for that software.

Different data sources can use the same store name.

Optional store parameters:

Tip: The optional store parameters expose details that users typically don't need to know. The default values work for typical data sources. These parameters are documented here only in case a data source requires values that are different to the defaults. Even in that case, you don't need to understand these parameters in enough detail to determine their values: the documentation for the data source will supply parameter values for you to copy into your configuration member.

KAY.CIDB.STORE.<store_id>.CELL.<cell_id>.SIZE=<bytes>

Cell size, in bytes.

A store consists of cells. OMEGAMON Data Broker puts each incoming record into a cell in the named store. Cells can be various sizes, to accommodate different sizes of incoming records. Record sizes depend on the data source.

The <cell_id> qualifier groups the parameters for this cell size.

KAY.CIDB.STORE.<store_id>.CELL.<cell_id>.CAPACITY=<number>

The initial number of cells of this <cell_id>; this size.

OMEGAMON Data Broker uses this value to preallocate memory for cells. During processing, OMEGAMON Data Broker allocates additional memory as required.

Store parameters define cells as pairs of SIZE and CAPACITY.

The default parameter values for cells specify various sizes and capacities. For example (actual default values do not necessarily exactly match this example):

KAY.CIDB.STORE.STORE1.CELL.1.SIZE=128
KAY.CIDB.STORE.STORE1.CELL.1.CAPACITY=1000

KAY.CIDB.STORE.STORE1.CELL.2.SIZE=256
KAY.CIDB.STORE.STORE1.CELL.2.CAPACITY=5000

KAY.CIDB.STORE.STORE1.CELL.3.SIZE=512
KAY.CIDB.STORE.STORE1.CELL.3.CAPACITY=5000

KAY.CIDB.STORE.STORE1.CELL.4.SIZE=1024
KAY.CIDB.STORE.STORE1.CELL.4.CAPACITY=1000

KAY.CIDB.STORE.STORE1.CELL.5.SIZE=2048
KAY.CIDB.STORE.STORE1.CELL.5.CAPACITY=1000

KAY.CIDB.STORE.STORE1.CELL.6.SIZE=4096
KAY.CIDB.STORE.STORE1.CELL.6.CAPACITY=1000

KAY.CIDB.STORE.STORE1.CELL.7.SIZE=8192
KAY.CIDB.STORE.STORE1.CELL.7.CAPACITY=200

You cannot override default values individually for each cell ID. Specifying any cell parameters for a store overrides the default values for all cell IDs for that store. If you specify any cell parameters, then you must specify a complete set.

KAY.CIDB.STORE.<store_id>.QUEUE.CAPACITY=<number>

The initial number of cells that the store's queues can contain. Default: 10000 (ten thousand).

A store can have multiple forwarders. Each forwarder has its own queue. This capacity is shared across all of the store's queues.

OMEGAMON Data Broker expands this capacity as required. However, while the total shared capacity can expand, each forwarder's queue has a maximum number of records, set by the forwarder's RECORD_QUEUE_LIMIT parameter.

Sink parameters

The namespace of a sink parameter determines its context: forwarder-scope or reusable.

Context	Namespace
Forwarder-scope	`KAY.CIDB.FWD.<forwarder_id>`
Reusable	`KAY.CIDB.SINK.<sink_id>`

Note: Forwarder-scope sink parameters and reusable sink parameters have the same names (trailing qualifiers), with two exceptions: SINK_HOST and SINK_PORT in forwarder-scope sink parameters versus HOST and PORT, without the SINK_ prefix, in reusable sink parameters.

Required forwarder-scope sink parameters:

KAY.CIDB.FWD.<forwarder_id>.SINK_HOST=<connect_hostname>

Hostname or IP address of the OMEGAMON Data Connect instance that is listening for data from OMEGAMON Data Broker.

In the context of the OMEGAMON Data Broker forwarder, OMEGAMON Data Connect is a sink: a destination.

If you plan to run OMEGAMON Data Connect on the same z/OS® instance as OMEGAMON Data Broker, then you can specify the value localhost or the local loopback IP address. The typical local loopback IPv4 address is 127.0.0.1.

KAY.CIDB.FWD.<forwarder_id>.SINK_PORT=<connect_port>

The port on which OMEGAMON Data Connect is listening. Follow your site-specific standards for assigning port numbers.

Required reusable sink parameters:

KAY.CIDB.SINK.<sink_id>.HOST=<connect_hostname>: See the previous description of the corresponding forwarder-scope parameter, SINK_HOST.
KAY.CIDB.SINK.<sink_id>.PORT=<connect_port>: See the previous description of the corresponding forwarder-scope parameter, SINK_PORT.

Optional forwarder-scope or reusable sink parameters:

<forwarder_or_sink_namespace>.CONNECT_TIMEOUT=<seconds>

Time in seconds to wait to establish a connection to OMEGAMON Data Connect. Default: 5.

<forwarder_or_sink_namespace>.RECEIVE_TIMEOUT=<seconds>

Receive timeout in seconds. Default: 300 (5 minutes).

<forwarder_or_sink_namespace>.SEND_TIMEOUT=<seconds>

Send timeout in seconds. Default: 0 (indefinite).

<forwarder_or_sink_namespace>.PROTOCOL_VERSION=<protocol_version>

The protocol version that OMEGAMON Data Broker uses to communicate with OMEGAMON Data Connect:

2: Version 2 (default). Sends a batch of records in each message, and waits for acknowledgment from OMEGAMON Data Connect before sending the next message.
Attention: If PROTOCOL_VERSION is set to 2, but the instance of OMEGAMON Data Connect does not support protocol version 2, then OMEGAMON Data Broker does not send data to that instance of OMEGAMON Data Connect.
1: Version 1. Sends only a single record in each message, and does not wait for acknowledgment from OMEGAMON Data Connect before sending the next message.
AUTO: Use the latest protocol version supported by OMEGAMON Data Connect.
Where possible, set a specific protocol version number instead of AUTO. In some cases, AUTO can inaccurately choose protocol version 1 when OMEGAMON Data Connect supports version 2. For example, if a proxy or load balancer is between OMEGAMON Data Broker and OMEGAMON Data Connect.

Sink SSL parameters

Sink SSL parameters are relevant only if you use TLS to secure the connection between OMEGAMON Data Broker and OMEGAMON Data Connect.

<forwarder_or_sink_namespace>.SECURITY=<string>

List of enabled security protocols. Allowed values: TLSv1.3, TLSv1.2, or blank (no value). Default: no value; no security protocol.

Note: To use TLS 1.3, either the z/OS System SSL Security Level 3 FMID or the CPACF Feature 3863 must be installed.

The list can specify one or both values. Examples:

TLSv1.3
TLSv1.3,TLSv1.2
TLSv1.2

The order of values in the list is not significant. OMEGAMON Data Broker and OMEGAMON Data Connect use the latest version of TLS that is enabled by both. For example, if OMEGAMON Data Broker specifies SECURITY=TLSv1.3,TLSv1.2, but OMEGAMON Data Connect enables only TLSv1.2, then the connection uses TLSv1.2.

Tip: For a connection without TLS, omit or comment-out the SECURITY parameter.

<forwarder_or_sink_namespace>.FIPS=ON|OFF

Sets z/OS System SSL Federal Information Processing Standards (FIPS) mode. Default: OFF. For information about FIPS mode, see the z/OS System SSL documentation for your version of z/OS. For example, FIPS 140-2 support in z/OS 2.5.0.

<forwarder_or_sink_namespace>.KEYRING=<string>

Identifies the collection of security certificates required for this connection. Can be one of the following values:

SAF key ring

Specified in the format <owner_user_id>/<key_ring_name>. For example:

my/kay_keyring

If the current user owns the key ring, the current user must have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class. If another user owns the key ring, the current user must have UPDATE access to that resource.

Certificate private keys are not available when using a SAF key ring owned by another user, except for SITE certificates where CONTROL authority is given to IRR.DIGTCERT.GENCERT in the FACILITY class or for user certificates where READ or UPDATE authority is given to <ring_owner>.<ring_name>.LST resource in the RDATALIB class.

Key database

A key database created by the z/OS gskkyman utility. The key database is specified as a z/OS UNIX file path. For example:

/u/my/security/certs/kay.kdb

PKCS #12 file

Specified as a z/OS UNIX file path. For example:

/u/my/security/certs/kay.p12

PKCS #11 token

Specified in the format *TOKEN*/<token_name>. For example:

*TOKEN*/kay.pkcs11.token

The *TOKEN* qualifier indicates that the value refers to a PKCS #11 token rather than a SAF key ring.

If you specify a key database or PKCS #12 file, but you do not specify either a STASH parameter or a PASSWORD parameter, then OMEGAMON Data Broker looks for a stash file in the same directory as the key database or PKCS #12 file, and with the same base file name, but with .sth extension. For example, if the KEYRING parameter specifies the following z/OS UNIX file path:

/u/my/security/certs/kay.kdb

or:

/u/my/security/certs/kay

(with no extension)

then OMEGAMON Data Broker looks for a stash file at the following path:

/u/my/security/certs/kay.sth

<forwarder_or_sink_namespace>.STASH=<path>

z/OS UNIX file path of the stash file that contains the password for the key database or PKCS #12 file.

If PASSWORD is specified, STASH is ignored.

<forwarder_or_sink_namespace>.PASSWORD=<string>

Password for the key database or PKCS #12 file.

If KEYRING specifies a SAF key ring or PKCS #11 token, PASSWORD is ignored.

<forwarder_or_sink_namespace>.CIPHERS=<hex_string>

List of candidate cipher suites to try, in order of preference. The list is a concatenation of 4-digit hexadecimal cipher suite numbers supported by z/OS System SSL.

Default:

003500380039002F00320033130113021303

Note: All of the cipher suites in this default list meet security level 3. To use security level 3 cipher suites, either the z/OS System SSL Security Level 3 FMID or the CPACF Feature 3863 must be installed. Otherwise, you must specify cipher suites that are supported by the base z/OS security level.

Default, itemized in list order:

List order	4-character cipher number	Short name	TLS 1.2	TLS 1.3
1	`0035`	`TLS_RSA_WITH_AES_256_CBC_SHA`	X
2	`0038`	`TLS_DHE_DSS_WITH_AES_256_CBC_SHA`	X
3	`0039`	`TLS_DHE_RSA_WITH_AES_256_CBC_SHA`	X
4	`002F`	`TLS_RSA_WITH_AES_128_CBC_SHA`	X
5	`0032`	`TLS_DHE_DSS_WITH_AES_128_CBC_SHA`	X
6	`0033`	`TLS_DHE_RSA_WITH_AES_128_CBC_SHA`	X
7	`1301`	`TLS_AES_128_GCM_SHA256`		X
8	`1302`	`TLS_AES_256_GCM_SHA384`		X
9	`1303`	`TLS_CHACHA20_POLY1305_SHA256`		X

Tip: To match a z/OS System SSL cipher suite number to the corresponding OpenSSL cipher suite name, go to the z/OS System SSL documentation and look up the short name for that cipher suite in the table of cipher suite definitions. The short name is the name that is defined in the associated Request for Comments (RFC) by the Internet Engineering Task Force (IETF). Then go to the OpenSSL documentation for the ciphers command, and use the RFC name to find the corresponding OpenSSL name.

For more information on cipher suite definitions, see the z/OS System SSL documentation for your version of z/OS. For example, the cipher suite definitions supported by z/OS 2.5.0.

<forwarder_or_sink_namespace>.CERTLABEL=<string>

Specifies the label (also known as alias) of the client certificate that is used to authenticate OMEGAMON Data Broker (the client) to OMEGAMON Data Connect (server). The client certificate, and its private key, must be in the collection that is specified by the KEYRING parameter.

Default: no label.

CERTLABEL is only used if OMEGAMON Data Connect requires client authentication.

If OMEGAMON Data Connect requires client authentication, but you omit CERTLABEL, then OMEGAMON Data Broker uses the default certificate from the collection that is specified by the KEYRING parameter.

<forwarder_or_sink_namespace>.KEYSHARES=<string>

List of key share groups that OMEGAMON Data Broker supports during a TLS 1.3 handshake. During a TLS 1.3 handshake, OMEGAMON Data Broker (the client) sends the key share groups that are in common and in the same order as the supported groups list (ECURVES). OMEGAMON Data Connect (the server) selects from this ordered list the first group that it supports. OMEGAMON Data Broker and OMEGAMON Data Connect use the selected group to encrypt and decrypt TLS 1.3 handshake messages.

The list is a concatenation of 4-digit decimal values that are supported by z/OS System SSL. These values match the values in the IANA registry of TLS supported groups.

Default:

00230029

Default, itemized in list order:

List order	Value	Description
1	`0023`	secp256r1
2	`0029`	x25519

For more information on supported groups, see the z/OS System SSL documentation for your version of z/OS. For example, the elliptic curve (group) definitions supported by z/OS 2.5.

<forwarder_or_sink_namespace>.ECURVES=<string>

The usage and default value of ECURVES depends on the security protocol (SECURITY parameter):

TLSv1.2: ECURVES specifies a list of preferred elliptic curves when using an ECC-based cipher suite.
TLSv1.3: ECURVES specifies a list of preferred supported groups to encrypt and decrypt TLS handshake messages.
OMEGAMON Data Broker (the client) finds supported groups that are specified by both ECURVES and KEYSHARES and sends them to OMEGAMON Data Connect (the server) in the order specified in ECURVES. The order of groups in ECURVES determines the order of key share groups that OMEGAMON Data Broker sends to OMEGAMON Data Connect.

In both cases:

The list is a concatenation of 4-digit decimal values that are supported by z/OS System SSL. These values match the values in the IANA registry of TLS supported groups.
The default is the value of the z/OS System SSL environment variable GSK_CLIENT_ECURVE_LIST.

Example (default value of GSK_CLIENT_ECURVE_LIST for TLS 1.3 in z/OS 2.5):

002100230024002500190029

Forwarder parameters

You can define one or more forwarders. Use a different <forwarder_id> to group the parameters for each forwarder.

Required forwarder parameters:

KAY.CIDB.FWD=ON

Enables the forwarder subsystem of OMEGAMON Data Broker. The forwarder enables OMEGAMON Data Broker to send data over a TCP/IP network to a sink (forwarding destination) such as OMEGAMON Data Connect.

Values:

ON: Enables the forwarder. This value is case-sensitive.

If you omit this parameter, or specify any value other than ON in all uppercase, then the forwarder subsystem is disabled, and OMEGAMON Data Broker will not forward data.

You only need to specify this parameter once in the configuration member, not once per forwarder.

KAY.CIDB.FWD.<forwarder_id>.SOURCE_STORE=<store_name>

The name of an OMEGAMON Data Broker store to which a data source sends data.

The value of this parameter must match the value of a NAME store parameter.

The forwarder sends data from this store to the forwarder sink.

For OMEGAMON Data Provider, you must specify the store name OMEGAMON.

Optional forwarder parameters:

KAY.CIDB.FWD.<forwarder_id>.SINK=<sink_id>

Refers to a set of reusable sink parameters.

KAY.CIDB.FWD.<forwarder_id>.CONNECT_RETRY_INTERVAL=<seconds>

Number of seconds to wait before retrying connection to OMEGAMON Data Connect. Default: 20.

KAY.CIDB.FWD.<forwarder_id>.MAX_CONNECT_RETRY_ATTEMPTS=<number>

Maximum number of attempts to retry connection to OMEGAMON Data Connect. Default: no value; unlimited.

KAY.CIDB.FWD.<forwarder_id>.RECORD_QUEUE_LIMIT=<records>

The maximum number of records allowed in this forwarder's queue. The default value is 1000000 (one million) records.

When a queue is full, each new incoming record overwrites the oldest remaining record in the queue.

If OMEGAMON Data Connect is unavailable, then older records in the queue might be lost, overwritten by new records before they can be forwarded.

KAY.CIDB.FWD.<forwarder_id>.MAX_BATCH_SIZE=<records>

Maximum number of records that OMEGAMON Data Broker sends in a single message to OMEGAMON Data Connect. Must be an integer between 1 and 1000000 (one million). Default: 1000 (one thousand).

Does not apply to protocol version 1: see the sink parameter PROTOCOL_VERSION.

KAY.CIDB.FWD.<forwarder_id>.LOGOPTS=--verbosity <log_level>

The logging level of network activity for this forwarder. The default level is 0 (none).

Typically, you only need to set the logging level if IBM® Software Support requests you to do so for troubleshooting. The logging level does not affect KAYB-prefix messages from OMEGAMON Data Broker.

Allowed values:

`<log_level>`	Description	Notes
0	None	Default value
1	Fatal	Only log fatal errors
2	Error	Log all errors
3	Warning	Log any warnings
4	Info	Log informational messages
5	Verbose	Log verbose informational messages
6	Debug	Log messages useful for debugging
7	Trace	Log low-level trace messages
8	All	Log all messages

Higher logging levels include all messages from lower levels. For example, level 4 (info) includes all warnings and errors.

The details in messages at levels 6 and higher are intended for use only by IBM Software Support.

OMEGAMON Data Broker logs network activity messages to the Zowe cross-memory server job step output data set with ddname SYSOUT (//SYSOUT DD) or, if the server job step does not define that ddname, then to data sets with the ddname SYS<nnnnn> (SYS00001, SYS00002, etc.).

Example parameter:

KAY.CIDB.FWD.FWD1.LOGOPTS=--verbosity 7

Tip: You can override the value of this parameter dynamically, while OMEGAMON Data Broker is running. For details, see Changing OMEGAMON Data Broker network activity logging level.