Configuration validator

The OMEGAMON® Data Provider configuration validator is a command-line tool that you can use to validate the OMEGAMON Data Provider configuration files that are in YAML format: the OMEGAMON Data Connect configuration file and, if you are using OMEGAMON monitoring agents as a data source, the OMEGAMON Data Provider collection configuration member, RKANPARU(KAYOPEN).

Whenever you edit one of these configuration files, use the configuration validator as a preflight check before using the edited file to configure your system.

The configuration validator is a Java™ application. To run the configuration validator on operating systems such as z/OS® UNIX and Linux, use the supplied shell script.

Note: OMEGAMON Data Provider does not supply a corresponding preflight tool to validate OMEGAMON Data Broker configuration parameters.

Prerequisites

The configuration validator requires Java 17 or later, 64-bit edition.

Location

The configuration validator is supplied in the OMEGAMON Data Connect installation directory.

More specifically, the shell script to run the configuration validator is supplied under the OMEGAMON Data Connect installation directory in the relative file path:

bin/validate

The script file name validate has no file extension (no trailing .sh).

Example absolute file path:

/usr/lpp/omdp/kay-110/bin/validate

Tip: Run the script from its supplied location in the installation directory. Don't copy the script to a different directory and try to run it from there. The script uses its own path to locate files in the installation directory. If you try to run the script from a different directory, the script won't find those files. If you want to make the script available in a directory that is already listed in your PATH environment variable, then, in that other directory, create a symbolic link that refers to the script in the installation directory. Running the symbolic link will run the script in the installation directory.

Syntax

Read syntax diagramSkip visual syntax diagramvalidate-t=connect-c-e=ISO8859-1-e= encoding-t=kayopen-c-e=IBM-1047-e= encodingfile-h

Options

-t=connect|kayopen
The type of file to be validated:
connect
OMEGAMON Data Connect configuration file
kayopen
OMEGAMON Data Provider collection configuration member
-c, --case-sensitive
Sets the validation to be case-sensitive.

The default validation case-sensitivity depends on the type of file to be validated:

  • When -t=connect, validation is case-sensitive by default. Validation of OMEGAMON Data Connect configuration files is always case-sensitive.
  • When -t=kayopen, validation is case-insensitive by default. If you set validation of the KAYOPEN member to be case-sensitive, then the following items must be all lowercase:
    • Keys (parameter names).
    • Values that are constrained to an enumerated list. For example, values of the product key.
-e, --encoding=encoding
Overrides the default character encoding that the configuration validator uses to interpret the file to be validated.
The default encoding depends on the type of file to be validated:
  • When -t=connect, the default encoding is the EBCDIC code page IBM-1047.
  • When -t=kayopen, the default encoding is the extended ASCII code page ISO8859-1.
file
The configuration file to be validated.

To refer to a file in a z/OS UNIX or Linux file system, specify the file path. For example:

/var/omdp/prod-a/config/connect.yaml

To refer to a z/OS MVS data set name, begin with a double quotation mark, followed by two slashes, then the fully qualified data set name enclosed in single quotation marks, and then end with another double quotation mark. For example:

"//'OMEGHLQ.RTENAME.RKANPARU(KAYOPEN)'"

-h, --help
Display help information and then exit.

Usage

After editing a configuration file, run the configuration validator shell script. See the examples at the end of this topic.

If the configuration file is valid, the configuration validator reports the following message:

This configuration file is valid.

Otherwise, the configuration validator reports the following message:

Validation failed.

followed by one or messages describing validation errors.

Limitations

The configuration validator is a useful preflight tool that catches many issues that can cause errors at run time. However, there are limitations to this validation. Issues not caught by the configuration validator can still cause errors at run time.

When the validator reports that a configuration file is valid, it means that the file meets the following two conditions:

  • The configuration file is a well-formed YAML document. The configuration file follows YAML syntax rules, independent of any rules specific to OMEGAMON Data Provider.
  • The configuration file follows the limited set of rules, specific to OMEGAMON Data Provider, such as required keys and values, defined in a schema that is built into the validator.

The following limitation applies to validating any configuration file:

Most values are checked for data type, some values are checked for constraints
For most keys in the configuration file, the validator checks that the value matches the expected data type. For example, if you specify a string value for a key that expects an integer, the validator reports string found, integer expected.

For some keys, the validator also performs more specific constraint checks. For example:

  • The validator checks whether the value of the product key in the KAYOPEN member matches the product code of a supported OMEGAMON monitoring agent.
  • The validator does not check whether the value of the product key in the OMEGAMON Data Connect configuration file matches the product code of a supported OMEGAMON monitoring agent. In the context of OMEGAMON Data Connect, the product key can refer to other data sources, not just OMEGAMON monitoring agents.

The following limitations apply only to validating OMEGAMON Data Connect configuration files:

Only some Spring Boot server properties checked
The root-level server key sets Spring Boot server properties. The validator only checks the few Spring Boot server properties that are described in this OMEGAMON Data Provider documentation. The validator does not check the many other server properties that you can specify.
Spring Boot logging properties not checked
Descendants of logging.level are not checked.
Kafka producer properties not checked
Descendants of connect.output.kafka.properties are not checked.
Filter include files not checked
OMEGAMON Data Connect configuration files can refer to filters that are defined in separate filter include files. The validator checks neither the contents of those files nor whether those files exist.

To validate the contents of a filter include file, you can insert the contents under a filter key in a minimal configuration file. For example:

connect:
  input:
    tcp:
      hostname: none
      port: 1
  output:
    stdout:
      filter:
        # Insert contents of filter include file here

When you insert the contents of the filter include file, remember to indent it under the filter key.

Example: Validating an OMEGAMON Data Connect configuration file

At a shell prompt, change to the bin directory under the OMEGAMON Data Connect installation directory, and then enter the following command:

./validate -t=connect /var/omdp/prod-a/config/connect.yaml

Example: Validating RKANPARU(KAYOPEN)

At a shell prompt, change to the bin directory under the OMEGAMON Data Connect installation directory, and then enter the following command:

./validate -t=kayopen "//'OMEGHLQ.RTENAME.RKANPARU(KAYOPEN)'"

Example: Incorrect indentation invalidates a configuration file

Given the following OMEGAMON Data Connect configuration file:

connect:
  input:
    tcp:
      enabled: true
      hostname: 0.0.0.0
      port: 15379
  output:
    stdout:
    enabled: true # Incorrectly indented

the configuration validator reports the following messages:

Validation failed.
$.connect.output.stdout: null found, object expected
$.connect.output.enabled: is not defined in the schema and the schema does not allow additional properties

Here, the message phrase not defined in the schema means, more specifically, not defined in the schema at this indent level.

The enabled key is unknown at the same indent level as stdout. Instead, enabled should be indented as a child of stdout.

To make this configuration file valid, you need to insert spaces to indent enabled under stdout.