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.
preflighttool 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
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
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.
- When
-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.
- When
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, theproduct
key can refer to other data sources, not just OMEGAMON monitoring agents.
- The validator checks whether the value of the
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
.