Properties and command line options

You use properties to define the operational environment of the gateway. You can override the default values by changing the values of these properties that are defined in the properties file.

The following tables describe the properties available with the Gateway for Message Bus. For more information about generic and Inter-Process Communication (IPC) properties and command line options, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.

The following sections describe the standard properties used to configure the gateway:

Common Tivoli Netcool/OMNIbus properties
Common gateway properties
Java properties
Mapping properties
Reader properties
Gateway-specific properties

Note: You can configure the gateway to operate in one of two modes of operation: standard mode or IBM Operations Analytics - Log Analysis (LA) mode. Each of these modes uses its own properties file.

Common Tivoli Netcool/OMNIbus properties

Table 1 describes the Tivoli Netcool/OMNIbus common properties defined in the following properties files:

G_XML.props - For gateways operating in standard mode.
G_SCALA.props - For gateways operating in LA mode.

Table 1. Common Tivoli Netcool/OMNIbus properties
Property name	Command line option	Description
ConfigCryptoAlg `string`	N/A	Use this property to specify the encryption algorithm that the gateway uses. Use this property with the ConfigKeyFile property and the `nco_aes_crypt` utility that is supplied with Tivoli Netcool/OMNIbus. The default is `AES`. Note: You need to set this property to `AES_FIPS` if you are encrypting properties in one of the transport module properties files. Note: The use of the encryption functionality is optional. If you do not plan to use the encryption functionality, keep the default values associated with the ConfigCryptoAlg and ConfigKeyFile properties. If you do make use of the encryption functionality then you can encrypt the string valued properties in the gateway properties files and the transport module properties files.
ConfigKeyFile `string`	N/A	Use this property to specify the encryption key that is used to encrypt data. Use this property with the ConfigCryptoAlg property and the `nco_aes_crypt` utility that is supplied with Tivoli Netcool/OMNIbus. The default is `""`.
Connections `integer`	-connections `integer`	Use this property to specify the maximum number of client connections that can be made to the gateway server. The default is 30.
Help `boolean`	-help `boolean`	Use this property to instruct the gateway to display application help information on startup and exit. The default is FALSE.
MaxLogFileSize `integer`	-maxlogfilesize `integer`	Use this property to specify the size (in bytes) that the gateway allocates for the log file. When the log file reaches this size, the gateway renames the log file by appending the name with the characters `.old` and creates a new log file. The default is 1024.
MessageLevel `string`	-messagelevel `string`	Use this property to specify the level of the log file messages. The default is warn.
MessageLog `string`	-messagelog `string`	Use this property to specify the path to the message log file. If you are running the gateway in standard mode, the default for this property is $OMNIHOME/log/G_XML.log. If you are running the gateway in LA mode, the default for this property is $OMNIHOME/log/G_SCALA.log.
Name `string`	-name `string`	Use this property to specify the name of the current gateway instance. If you want to run multiple gateways on one machine, you must use a different name for each instance. If you are running the gateway in standard mode, set this property to G_XML. If you are running the gateway in LA mode, set this property to G_SCALA. You need to have created a server (using the Server Editor `nco_xigen`) in the Tivoli Netcool/OMNIbus interfaces file.
Props.CheckNames `boolean`	N/A	Use this property to instruct the gateway to shut down if any property in the properties file is set to an invalid value. The default is TRUE.
PropsFile `string`	-propsfile `string`	Use this property to specify the location and name of the gateway properties file. If you are running the gateway in standard mode, the default for this property is $OMNIHOME/etc/G_XML.props. If you are running the gateway in LA mode, the default for this property is $OMNIHOME/etc/G_SCALA.props.
UniqueLog `boolean`	-uniquelog `boolean`	Use this property to specify that log file names are made unique by adding the PID of the gateway to the file name. The default is FALSE.
Version `boolean`	-version `boolean`	Use this property to instruct the gateway to display information about the application version on startup and exit. The default is FALSE.

Common gateway properties

Table 2 describes the Tivoli Netcool/OMNIbus common gateway properties defined in the following properties files:

G_XML.props - For gateways operating in standard mode.
G_SCALA.props - For gateways operating in LA mode.

Table 2. Common gateway properties
Property name	Command line option	Description
Gate.CacheHashTblSize `integer`	-chashtblsize `integer`	Use this property to specify the number of elements the gateway allocates for the hash table cache. The default is 5023.
Map definition file for gateways operating in standard mode
Gate.MapFile `string`	-mapfile `string`	Use this property to specify the mapping file for the gateway to use. If you are running the gateway in standard mode, the default is $OMNIHOME/gates/xml/xml.map.
Map definition file for gateways operating in LA mode
Gate.MapFile `string`	-mapfile `string`	Use this property to specify the mapping file for the gateway to use. See Summary for the mapping file you should use based on which version of Network Manager Insight Pack and OMNIbus Insight Pack you are running the gateway with deployed against IBM Operations Analytics - Log Analysis.
Gate.NGtkDebug `boolean`	-ngtkdebug `boolean`	Use this property to enable the logging of NGTK library debug messages. The default is TRUE.
Gate.PAAware `integer`	-paaware `integer`	This property indicates whether the gateway is Process Agent (PA) aware. The default is 0 (not PA aware). Note: This property is maintained by the PA server and is included in the properties file for information only.
Gate.PAAwareName `string`	-paname `string`	This property indicates the name of the PA controlling the gateway. The default is "". Note: This property is maintained by the PA server and is included in the properties file for information only.
Gate.StartupCmdFile `string`	-startupcmdfile `string`	Use this property to specify the location of the startup command file. If you are running the gateway in standard mode, the default for this property is $OMNIHOME/gates/xml/xml.startup.cmd. If you are running the gateway in LA mode, the default is: $OMNIHOME/gates/xml/scala/xml.startup.cmd.
Gate.Transfer. FailoverSyncRate `integer`	-fsyncrate `integer`	Use this property to specify the rate (in seconds) of the failover synchronization. The default is 60.
Gate.UnixAdminGrp `string`	-unixadmingrp `string`	Use this property to specify the administration group to which the gateway must belong if standard UNIX authentication is used. The default is ncoadmin.
Gate.UsePamAuth `boolean`	-usepamauth `boolean`	Use this property to specify whether Pluggable Authentication Module (PAM) authentication is used. The default is FALSE. Note: To run the gateway in FIPS 140-2 mode, set this property to TRUE.

Java properties

Table 3 describes the Tivoli Netcool/OMNIbus available Java™ properties defined in the following properties files:

G_XML.props - For gateways operating in standard mode.
G_SCALA.props - For gateways operating in LA mode.

Table 3. Java properties
Property name	Command line option	Description
Gate.Java.Arguments `string`	-javaargs `string`	Use this property to specify the Java arguments. The default is " ". Note: You can specify more than one argument for the Gate.Java.Arguments property by specifying a space-separated list of arguments within single quote marks. For example: `'arg1 arg2 arg3'`.
Gate.Java.ClassPath `string`	-javacpath `string`	Use this property to specify the path to the third-party and user-defined Java classes that create the required Java virtual machine (JVM) environment. The default is $CLASSPATH.
Gate.Java.Debug `boolean`	-javadebug `boolean`	Use this property to specify whether the debugging option is enabled for the JVM environment. The default is TRUE.
Gate.Java.Library Path `string`	-javalibpath `string`	Use this property to specify the path to the library files for the required JVM environment. The default is " ".

Mapping properties

Table 4 describes the Tivoli Netcool/OMNIbus available mapping properties defined in the following properties files:

G_XML.props - For gateways operating in standard mode.
G_SCALA.props - For gateways operating in LA mode.

Table 4. Mapping properties
Property name	Command line option	Description
Gate.Mapper.Debug `boolean`	-mapperdebug `boolean`	Use this property to specify whether the gateway includes mapper debug messages in the debug log. The default is TRUE.
Gate.Mapper.Forward HistoricDetails `boolean`	-mapperforhistdtls `boolean`	Use this property to specify whether the gateway forwards all historic details on converted update. The default is FALSE. Note: The Gateway for Message Bus cannot forward events from the alerts.journal or alerts.details tables.
Gate.Mapper.Forward HistoricJournals `boolean`	-mapperforhistjrnl `boolean`	Use this property to specify whether the gateway forwards all historic journals on converted update. The default is FALSE. Note: The Gateway for Message Bus cannot forward events from the alerts.journal or alerts.details tables.

Reader properties

Table 5 describes the Tivoli Netcool/OMNIbus available gateway reader properties defined in the following properties files:

G_XML.props - For gateways operating in standard mode.
G_SCALA.props - For gateways operating in LA mode.

Table 5. Reader properties
Property name	Command line option	Description
Gate.Reader.Debug `boolean`	-readerdebug `boolean`	Use this property to specify whether the gateway includes gateway reader debug messages in the debug log. The default is TRUE.
Gate.Reader.Description `string`	-readerdescription `string`	Use this property to specify the application description for the reader connection. This description is used in triggers and allows you to determine which component of the gateway attempted to perform an action. The default is Gateway Reader.
Gate.Reader.Details TableName `string`	-readerdetailstblname `string`	Use this property to specify the name of the details table that the gateway reads. The default is alerts.details. Note: The Gateway for Message Bus cannot forward events from the alerts.journal or alerts.details tables.
Gate.Reader.Failback Enabled `boolean`	-readerfailbackenabled `boolean`	Use this property to specify whether failback is enabled for the ObjectServer. The default is TRUE.
Gate.Reader.Failback Timeout `integer`	-readerfailbacktimeout `integer`	Use this property to specify the time (in seconds) that the gateway reader awaits before entering failback mode. The default is 30.
Gate.Reader.IducFlushRate `integer`	-readeriducflushrate `integer`	Use this property to specify the rate (in seconds) of the granularity of the reader. If you set this property to 0, the reader gets its updates at the same granular rate as that of the ObjectServer to which it is connected. The default is 0. Attention: If you set this property to a value greater than 0, the reader issues automatic IDUC flush requests to the ObjectServer with this frequency. This enables the reader to run at a faster granularity than that of the ObjectServer, thus enabling the gateway to capture more detailed event changes in systems where the ObjectServer itself has high granularity settings.
Gate.Reader.Journal TableName `string`	-readerjournaltblname `string`	Use this property to specify the name of the journal table that the gateway reads. The default is alerts.journal. Note: The Gateway for Message Bus cannot forward events from the alerts.journal or alerts.details tables.
Gate.Reader.LogOSSql `boolean`	-readerlogossql `boolean`	Use this property to specify whether the gateway logs all SQL commands sent to the ObjectServer in debug mode. The default is FALSE.
Gate.Reader.Password `string`	-readerpassword `string`	Use this property to specify the password associated with the user specified by the Gate.Reader.Username property. The default is " ". If the ObjectServer from which the gateway reads alerts is running on Tivoli Netcool/OMNIbus V8.1 or above in FIPS 140-2 mode, this password must be either plain text or encrypted using the nco_aes_crypt utility. For details about the encryption utilities, see the IBM Tivoli Netcool/OMNIbus Administration Guide.
Gate.Reader. ReconnectTimeout `string`	-readerreconntimeout `string`	Use this property to specify the time (in seconds) between each reconnection poll attempt that the gateway makes if the connection to the ObjectServer is lost. The default is 30.
Gate.Reader.Server `string`	-readerserver `string`	Use this property to specify the name of the ObjectServer from which the gateway reads alerts. The default is NCOMS.
Gate.Reader. StatusTableName `string`	-readerstatustblname `string`	Use this property to specify the name of the status table that the gateway reads. The default is alerts.status.
Gate.Reader. TblReplicateDefFile `string`	-readertblrepdeffile `string`	Use this property to specify the path to the table replication definition file. If you are running the gateway in standard mode, the default is $OMNIHOME/gates/xml/xml.reader.tblrep.def. If you are running the gateway in LA mode, the default is: $OMNIHOME/xml/scala/ xml.reader.tblrep.def.
Gate.Reader.Username `string`	-readerusername `string`	Use this property to specify the user name that is used to authenticate the ObjectServer connection. The default is root.

Gateway-specific properties

Table 6 describes the Tivoli Netcool/OMNIbus available gateway-specific properties defined in the following properties files:

G_XML.props - For gateways operating in standard mode.
G_SCALA.props - For gateways operating in standard mode.

Table 6. Gateway-specific properties
Property name	Command line option	Description
Gate.XMLGateway.DateFormat `string`	-dateformat `string`	Use this property to specify the format of UTC (date) columns in the constructed XML. If you are running the gateway in standard mode, the default is yyyy-MM-dd\'T\'HH:mm:ss. If you are running the gateway in LA mode, the default is yyyy-MM-dd\'T\'HH:mm:ssZ. The default is different because it needs to provide timezone details about the date and time to IBM Operations Analytics - Log Analysis. You may never need to change the value of this property. If you do need to, see the following JDK Documentation for details on how to define the date format: http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html Note: For gateways running in LA mode: Ensure that the format of this property matches the format of the date/time field in the data source properties file. The data source properties file is called omnibus1100.properties.
Gate.XMLGateway.Debug `boolean`	-xmlgatewaydebug `boolean`	Use this property to specify whether the debug log includes gateway debug messages. The default is TRUE.
Gate.XMLGateway.FailbackEnabled `boolean`	xmlgatewayfailbackenabled `boolean`	Use this property to specify whether failback is enabled for the gateway. The default is TRUE.
Gate.XMLGateway.FailbackTimeout `string`	xmlgatewayfailbacktimeout `string`	Use this property to specify the time (in seconds) that the gateway waits before entering failback mode. The default is 30.
Gate.XMLGateway.ForwardKeyValuePairs `boolean`	-forwardkeyvaluepairs `boolean`	Use this property to enable the forwarding of Netcool `key-value` pairs to the Transport Module. For details about configuring the JMS Transport, see The jmsTransport.properties file.) For details about dynamic value assignment, see Dynamic value assignment for jmsHeaderMap and jmsPropertyMap This property works in conjunction with Gate.XMLGateway.ForwardMappedFields. The default is FALSE.
Gate.XMLGateway.ForwardMappedFields `boolean`	-forwardmappedfields `boolean`	Use this property to specify the mapped fields defined in the gateway’s map file to be added in the forwarded `key-value` pairs. This property takes effects only when Gate.XMLGateway.ForwardKeyValuePairs is set to TRUE. If forwarding `key-value` pairs is enabled, leaving the Gate.XMLGateway.ForwardMappedFields property blank causes all mapped field to be added to the `key-value` pairs. To reduce the memory footprint, specify only the mapped fields required by the relevant use case in the Transport Module. Default: "".
Gate.XMLGateway.MessageID `string`	-messageid `string`	Use this property to specify the message ID for the gateway. The message ID determines which transformation is required. The message ID will be either a specific transformation or `@col_name` (where `col_name` is a field within Tivoli Netcool/OMNIbus), which then uses the value of the column specified as the ID to decide which transformation is required. The default is netcoolEvents.
Gate.XMLGateway.MessageKey `string`	-messagekey `string`	Use this property to specify a static or a dynamic key to be used for every message that goes into Kafka transport (Kafka producer). A dynamic key is a real-time value sourced from one of the columns defined in the map file (G_XML.map). To use a dynamic key, the property value must start with `@`. For example, to enable a dynamic message key in a Kafka producer send operation, set Gate.XMLGateway.MessageKey to `@ServerSerial`. Note: This property only supports `@ServerSerial` and `@ServerName`. If you specify any other property value, the gateway displays an error message. The message key effects the Kafka producer's send operation in relation to topic partitioning. For consistency of partitioned delivery, the dynamic key must be present in every IDUC fetch, and so the choice of message key must adhere to that requirement. When you specify the name of the column providing the key value using the Gate.XMLGateway.MessageKey property, events received through the Kafka transport will be forwarded to partitions as determined by the following algorithm: `Partition number=hash(key) % number of partitions` This method returns different partition numbers evenly when a larger number of partitions is used, and the events will be distributed more evenly among the partitions. The default is ''.
Gate.XMLGateway.MessageType `string`	-messagetype `string`	Use this property to specify whether the value defined by the Gate.XMLGateway.MessageID property is a transformer module name or transformer module endpoint. This property takes the following values: NAME: The value defined by the Gate.XMLGateway.MessageID property is a transformer module name. ENDPOINT: The value defined by the Gate.XMLGateway.MessageID property is a transformer module endpoint. The default is NAME.
Gate.XMLGateway.PublishTraceOn `boolean`	-pubtraceon `boolean`	Use this property to specify whether the gateway prints the following event messages before and after transformation: `Log message: Transforming message - [<event_message>]. Log message: Transformed message - [<event_message>].` The default is FALSE.
Gate.XMLGateway.ReconnectAttempts `integer`	-reconnectattempts `integer`	Use this property to specify the number of times that the gateway should attempt to reconnect to the target system. The default is 12.
Gate.XMLGateway.ReconnectDelay `integer`	-reconnectdelay `integer`	Use this property to specify the time (in seconds) between each reconnection attempt. The total delay is the specified value plus the connection timeout value. The default is 20.
Gate.XMLGateway.ReconnectTimeout `integer`	xmlgatewayreconntimeout `integer`	Use this property to specify the time (in seconds) between each reconnection poll attempt if the gateway loses the connection to the ObjectServer. The default is 30.
Gate.XMLGateway.ReplaceXmlInvalidChars	-replacexmlinvalidchars	Use this property to enable the replacement of invalid characters found in Netcool data during the construction of XML event prior to the XSLT process. The invalid characters concerned refer to the control character sets in the XML standard, see https://www.w3.org/TR/xml/#charsets. Unconverted control characters in an XML document may trigger a Java exception in the XLST process. The replacement of each invalid character follows the format defined by the Gate.XMLGateway.XmlInvalidCharsFormatter property. The default is FALSE.
Gate.XMLGateway.ThreadPoolSize `integer`	-thrpoolsize `integer`	Use this property to specify the number of threads in the XML transformation thread pool. Increasing the size of the thread pool allows more XML messages to be concurrently processed using the transformation system. The default is 10.
Gate.XMLGateway.TransformerFile `string`	-transformerfile `string`	Use this property to specify the location of the transformer module file. If you are running the gateway in standard mode, the default is $OMNIHOME/java/conf/transformers.xml. If you are running the gateway in LA mode, the default is $OMNIHOME/java/conf/scalaTransformers.xml.
Gate.XMLGateway.TransformerInputType `string`	-transformeritype `string`	Use this property to specify whether the input format of the event into the transformer is `xml` or `json`. When json is used then the event will be passed into the transformer as JSON. This means that a transformer module that can handle JSON is used in place of the default XSLT transformer. The default is xml. Note: For details of using this property, see Configuring the gateway to produce JSON data.
Gate.XMLGateway.TransportFile `string`	-transportfile `string`	Use this property to specify the location of the transport module properties file. If you are running the gateway in standard mode, the default is $OMNIHOME/java/conf/jmsTransport.properties. If you are running the gateway in LA mode, the default is $OMNIHOME/java/conf/scalaTransport.properties.
Gate.XMLGateway.TransportType `string`	-transporttype `string`	Use this property to specify either the transport module method to be used or the name of the transport module class to use. If you are running the gateway in standard mode, the default is JMS. You can also specify one of the following values if your gateway is running in standard mode: JMS File HTTP MultiChannelHTTP KAFKA MQTT PULSAR Socket If you are running the gateway in LA mode, the default is SCALA.
Gate.XMLGateway.XmlInvalidCharsFormatter	-xmlinvalidcharsformatter	Specify the format for invalid character replacement. This property takes effects only when Gate.XMLGateway.ReplaceXmlInvalidChars is set to TRUE. The configured format must fulfill the following:criteria: Adhere to Java print format syntax, otherwise a runtime exception will occur. Typically, numeral format are recommended, such as `%d, %x, %X`. White spaces are valid print format. To suppress invalid characters, apply empty configuration. The resultant Netcool data, embedded with tokens produced from the formatter, must be compliant to the input document standard (which is always XML) and the output document standard (which can be XML, JSON, or others) for the XSLT process. This requires extra care from the user. Format violation may escape detection within the gateway, for example when a string valid to the input document standard is invalid to the output document standard. For example, the `xml-to-json` transformation process does not validate the document produced (for performance sake). The outcome of this scenario is the receiver’s rejection of the malformed event. The default is [U+%04X]