Configuring the BMC Impact Integration Web Services server

The installation routine sets the default values for port numbers.

 Modifying default port numbers

The following table lists the default port numbers that the BMC Impact Integration Web Services server uses. If these default ports are being used by another process, you must change the default port numbers so that the BMC Impact Integration Web Services server and client can communicate with each other and with connected BMC Impact Manager cells.

Default port numbers

Component

File

Default port number

HTTP transport server

This is the Tomcat server connector port in file:
$IIWS_HOME/Tomcat/conf/server.xml

  • 9080 for HTTP
  • 9443 for HTTPS

IIWSGatewayServer

$IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc/mcell.dir

1859

TOMCAT

$IIWS_HOME/Tomcat/conf/server.xml

  • 8007 for TOMCAT shutdown
  • 8011 for TOMCAT AJP

The HTTP transport server, defined in the server.xml file, specifies the Tomcat server Connector port number. This is the port through which the BMC Impact Integration Web Services client exchanges request-response messages with the BMC Impact Integration Web Services server.

The IIWSGatewayServer receives events from BMC Impact Manager cells. Each BMC Impact Integration Web Services server that Clients subscribe to for receiving events must have an associated IIWSGatewayServer entry in the mcell.dir file.

To change the HTTP transport server or Tomcat server Connector port number, or the TOMCAT shutdown or AJP ports

 To change the Tomcat server port or the HTTP transport server,

  1. Open the $IIWS_HOME/Tomcat/conf/server.xml file.
  2. Search for the port and change the port value.
  3. Save the file and restart Infrastructure Management.
Example

Connector port example:
<Connector port="9080" protocol="HTTP/1.1" 
connectionTimeout="20000" 
redirectPort=" 9443 " />

To change the port number of the IIWSGatewayServer

  1. In a text editor, open the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc/mcell.dir file.
  2. Change the port number for the IIWSGatewayServer entry.
  3. Save and close the file.
  4. Start or restart the server. If you have other configuration changes to make, you can start or restart the server when you are finished.

Guidelines for using DEBUG to diagnose issues

For diagnosing issues, see Configuring-the-BMC-Impact-Integration-Web-Services-logs.



Configuration file

The BMC Impact Integration Web Services configuration file, ImWebServices.conf, is stored in the $IIWS_HOME/Tomcat/webapps/imws/ WEB-INF/etcdirectory, which resides on the BMC Impact Integration Web Services server. It is loaded when the BMC Impact Integration Web Services server is started. After modifying a value, you need to restart the BMC Impact Integration Web Services server to apply the modified value.

 Configuration file parameters

The following table lists and describes the configuration file parameters. 

Configuration file parameters

Group

Parameters

Description

Message Buffer

MessageBufferKeepSent

The number of seconds to keep sent messages buffered while waiting for an answer.

Default: 300 seconds

MessageBufferKeepWait

The number of seconds that messages are retained in the buffer while waiting for the connection to be established.

Default: 3600 seconds (one hour)

MessageBufferBaseSize

The number of messages that can be stored in the message buffer.

Default: 5000 messages

MessageBufferSizeLimit

The maximum number of messages that can be stored in the message buffer.

Default: 0

MessageBufferReconnectInterval

(Optional) The number of seconds between attempts to connect to a BMC Impact Manager cell.

Default: 120

 

  • The value of this parameter cannot be less than 60 seconds.
  • When a connection is established, the BMC Impact Integration Web Services server sends buffered messages that are designated for the BMC Impact Manager cell with which a connection is established.

MessageBufferResendCount

The number of times to resend unanswered messages.

Default: 1

MessageBufferExpandPercentage

The percentage up to which the message buffer can expand.

Default: 10

Event Persistency

PersistencyEnabled

Enables persistency, which specifies additional buffering parameters when the buffer mode is No.

Valid values:

  • No (Default)
  • Yes

PersistencyLevel

(Optional) The buffer mode used when the Default buffering mode is specified. This parameter is enabled only when the PersistencyEnabled parameter value is Yes.

Valid values:

  • None (Default)
  • Low
  • High

These values are case-sensitive and must be entered as shown here.

PersistencyFileName

The name of the file where the buffered messages are stored.

Default: log/imgw-mposter.dat

PersistencyCleanupSize Threshold

The threshold size, in bytes, of the persistency file that activates garbage collection.

Default: 100000

PersistencyCleanupGarbage Threshold

The threshold percentage of the persistency file that activates garbage collection.

Default: 40 percent.

PersistencyDisconnectRemove Messages

Indicates whether messages written to the persistency file are deleted when the integration is intentionally disconnected from a BMC Impact Manager cell.

Valid values:

  • No
  • Yes (Default value)

The contents of the file are not deleted when the integration terminates unexpectedly.

PersistencyCleanupRefuseFile

Default: Yes

PersistencyStatisticsLevel

Default: None

GetEvents parameters

GateWayServername

The name of the gateway server for the BMC Impact Integration Web Services server that, like a listener server, receives messages from the cell(s). This gateway server needs to be defined in mcell.dir of the BMC Impact Integration Web Services of GWType imcomm. The cell(s) need to be configured to propagate the events to this gateway server.

Default: IIWSGatewayServer

MaxSubscriberNumber

The maximum number of subscriptions allowed for the gateway server.

Default: 100

RecvBufferSize

The maximum number of matching events stored in the gateway persistent receiver buffer. If the number of events received exceeds the RecvBufferSize value, old events are removed from the persistent receiver buffer.

Default: 2000

SelectorFileName

The file that defines the filter criteria used to identify and select the events that are propagated from Impact Managers.

Default: 2000

AutoSubscribe

When enabled, invoking GetEvents without prior subscription, will automatically register an unreliable subscription.

Default: AutoSubscribe=Yes

Cell Connection Timeout Parameters

ConnectionSetupTimeout

The maximum time, in seconds, that IIWS attempts to establish a TCP/IP connection to a cell. If the connection with the cell cannot be established within this time, the connection will not be established.

Default: 10 seconds

SynchronizeTimeout

The maximum time, in seconds, that IIWS attempts to synchronize or hand shake with the cell (after the TCP/IP connection has been established). If the synchronization with the cell cannot be completed within this time, the connection will not be established.

If the cell is busy with a database cleanup, it might be impossible to connect with the default values of ConnectionSetupTimeout and SynchronizeTimeout

Default: 5 seconds

Diagnostic Log Dump

 

 

SendDump

If true, events sent from the client to the cell are written to a log file in hex value.

Default: False

queryResultsDump

If true, query results received from the cell are written to a log file in hex value.

Default: False

RecvDump

If true, events propagated from the cell are written to a log file in hex value.

Default: False

Query Parameters

MaxReturnEventListSize

The maximum number of events or data returned each time in response to RetrieveQueryResults or GetEvents.

Default: 20

  Editing the configuration file

  1. Using a text editor, open the ImWebServices.conffile.

    Note

    The selector file is not required for web service clients that only send events or data or that only launch queries.

  2. (Optional). Modify the file to include any optional BMC Impact Integration Web Services server parameters that you want to use. The following table lists these parameters.
  3. Save the file by using the file name of your choice and the file extension .conf.
  4. Ensure that the configuration file can be read by the user under whose permissions the BMC Impact Integration Web Services server is running.
  5. Restart the BMC Impact Integration Web Services server.

Selector file

The BMC Impact Integration Web Services APIs use the selector file to define groups of criteria (called selectors ) that are used to identify and select events that propagate from BMC Impact Manager cells. Events that match all the criteria in a selector file become available to the publish-subscribe and polling mechanisms of the BMC Impact Integration Web Services clients. 

The selector file is required for the BMC Impact Integration Web Services clients that receive events from BMC Impact Manager cells. It is a case-insensitive text file. 

The selector file is crucial in determining which events the subscribing clients receive. The default selector file, iiws.selector, is stored under the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc sub directory.

Note

The selector file is not required for web service clients that only send events or data or that only launch queries.

The selector file will be looked up from the directory $IIWS_HOME/TOmcat/webapps/imws/WEB-INF/etc. The default filename is iiws.selector, and can be modified in the ImWebServices.conf file, as shown in the following example:

svci:IIAPISelectorFile="C:\Program Files\BMC Software\Impact
Integration Web Services/mcell/iiws.selector"

The default selector file provides the selector name Always matches for the $ClassName "Event". Using the default selector, your client receives all events propagating from the BMC Impact Manager cells. 

The BMC Impact Integration Web Services server loads this selector file at start.

  Selector File characteristics

Selector set files have the following characteristics:

  • Selector set file criteria are not case-sensitive.
  • The naming convention for selector set files is integrationName.selector.
  • Selector set file syntax is checked when the selector set file is loaded. If the selector set file contains problematic syntax, the BMC Impact Integration Web Services API bmcii_loadSelectorSet() function will fail.
  • The contents of a selector set file comprise a selector set. The selector set can contain one or more selectors. However, a selector set file can contain only one selector set.
  • Each selector in a selector set must have a unique name. However, different selector sets can have selectors with identical names.
  • When a selector set file is called by the BMC Impact Integration Web Services API bmcii_matchSelectorSet() function, it is scanned from beginning to end. The selection process for the selector stops the first time that a parameter in a selector is matched to a parameter value in a selector. After a match is made, the remaining selectors in a set are ignored. 

    If the bmcii_matchSelectorSetAll() function is called, the function continues to scan after a matching selector is identified.
  • Because the selector sets are scanned from beginning to end, the order of selectors in a set and in the lines within a selector are important to optimizing the matching process.
  • The $doselector function allows you to include selectors and subselectors within a selector set. Selectors and subselectors further refine the selector criteria.
  • The $doselector function invokes subselectors.
  • The relationship between the criteria described in successive lines of a single stanza in a message selector is AND, unless otherwise indicated.
  • The selector file supports the logical operators OR, AND, &&, and ||.
  • A selector set can contain multiple stanzas of selector criteria, nested one level deep. These multiple stanzas of selector criteria are referred to as selector groups. The logical relation between the groups can be expressed through an AND, OR, &&, or || connector.
  • Each line in a selector contains only one selector criterion.
  • The selector file supports the following comparison operators:
    • Greater-than (>)
    • Greater-than or equal to (>=)
    • Less-than (<)
    • Less-than or equal to (<=)
      The selector file supports these comparison operators for numerals only.
  • The selector file supports the metaslot feature, which enables you to include information about the message. For example, you can use the metaslot to indicate the source of a message. You must specify a metaslot by using the keyword metaslot, followed by a dot (.), to prefix the slot name: metaslot.classname="EVENT".
  • The selector file supports required slots. A required slot keyword determines the required slot or slots in the selector criteria. The message must have the specific required slot for it to match the selector criteria. 

    The required slot keyword consists of the term reqdslot, followed by a dot (.), both of which you can add as a prefix to the specific slot name: for example, reqdslot.msg="TEXT". To illustrate, if the selector criteria specified that the slot message is required ( reqdslot.msg="TEXT"), then a message that did not have the slot message would fail the matching test. 

    The reqdslot keyword overrides the FailOnMissingSlot parameter when the latter is set equal to FALSE. That is, a message that does not have the designated required slot fails to meet the selector criteria. 

    When the FailOnMissingSlot parameter is set to TRUE, the BMC II C APIs ignore the reqdslot keyword when they process the message to determine whether it meets the selector criteria.
  • You can use the full range of regular expressions as values for selector criteria. You can include any slots within the regular expression. The BMC II C APIs return the values of the slots at run time. Within a regular expression, you can specify a slot with the keyword slot, followed by a dot (.): slot.host. The BMC II C APIs will return the value of host before sending the regular expression to the library.

  Format

The following figure depicts the structure of the selector set file: 

Structure of selector set file

Selector set.PNG

Selector set files must contain header information that describes the selector set. The header information consists of following selectors:

 Selector set header

The selector set header provides the entire set of selectors in the file with identifying information and indicates whether the selector set is enabled for use. A single selector set header must precede all selectors and their selector groups in the selector set. 

The following table describes the required and optional selector set header parameters that precede the selectors in a set: 

Selector set header contents

Parameter

Description

Inclusion

SelectorSetName=

Name of the selector set

Required

FormatVersion=

Minimum version of the Product required to run the selector using this file

Optional

Version=

Version number of the selector set file, specified manually by the developer or integration end user.

Optional

ChangeDate=

Date when the file last changed, specified manually by the developer or integration end-user

Optional

Description=

Free-text description of the entire selector set

Optional

Enable=

Specifies whether the selector set (and all selectors in it) are enabled for use Valid values:

  • TRUE - Enabled
  • FALSE - Disabled

Required

 Sample selector set header

SelectorSetName=testselector
FormatVersion=2
Version=7.1
ChangeDate=November 14, 2007
Description=This file contains the event selector tests
Enable=TRUE

 Selector header

A selector header performs following actions:

  • Provides each set of selector criteria in the file with identifying information.
  • Indicates how some selector features will be implemented.
  • Indicates whether the specific selector criteria, including any selector groups included within it, are enabled for use.

A selector header must precede each collection of selector criteria in the selector set.

The following table describes the required and optional selector header parameters that precede each selector: 

Selector header contents

Parameter

Description

Inclusion

SelectorName=

Name of the selector, used by the Product to identify the selector that will be used in selection The name must be unique within the selector set.

Required

Description=

Free-text description of the selector

Optional

FailOnMissingSlot=

Indicates whether the match for the selector fails if a slot specified in the selector criteria is missing from the event Valid values:

  • TRUE - The match for the selector fails if a slot specified in the selector is missing from the event
  • FALSE - Missing slots cause the line to be ignored

If the message that is being examined does not include any of the slots that are being tested by the selector, the comparison will never result in a match. This is true even when the parameter statement is FailOnMissingSlot=false.
If you use the reqdslot keyword in the selector criteria, it is in effect only when FailOnMissingSlot is set to false.

Optional

IsSubSelector

Indicates whether the selector can be called only by the $doselector() function. Valid values are true or false.

Optional

Enable=

Specifies whether the selector is enabled for use Valid values:

  • TRUE - Enabled
  • FALSE - Disabled

Required

Sample selector set header

SelectorName=EVENT_SELECTOR
Description=Selectors for all events of class EVENT
FailOnMissingSlot=false
IsSubSelector=true
Enable=TRUE

 Selector criteria

Each selector in a message selector set is constructed of successive lines of comparison criteria. Each criterion is composed of a comparison expressed as an equation. Equation operators are listed in the following table. 

Each line contains one criterion with an AND relationship implied between lines (unless otherwise indicated). 

In addition, the selector can consist of multiple groups of comparison criteria, each group related to the other through an AND, OR, ||, or && connector.

Format issues

Selector functions, which are internal to the selector file, are described in the following table. Operators are described in the following table.

  • Each message selector in a set is enclosed in curly braces ({ } ).
  • Message selector groups within a message selector are nested one level deep and also enclosed in curly braces. Do not nest message selector groups more than one level deep.
  • To the right of the operator is a slot, static text, or a function. On the left is a slot, regular expression, static text, or a function.
  • Explicit text that is used as a matching criterion must be enclosed in double quotation marks (" " ).
  • If a criterion fails but has an OR relationship with the following criterion, and that criterion is a match, then that criterion pair is a match.
  • The selector function scans each successive selector group in a message selector until it finds a match. After it finds a match, it stops searching.

  • The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter selector functions and conceal developer comments. When a line in a selector is commented out, the selection function ignores it.
    Do not comment out whole selectors or selector sets. Instead, set the Enable parameter of the selector set header or the selector header to FALSE to disable the selector set or selector.

    Example

    The $functionName resolves a specified function and compares the results of that operation to a slot in the event. For example,
    $ClassName = "SECURITY_ALERT"

    The $ClassName function returns the class name of the event. The returned value is compared to the value to the right of the operator (in this case, the string, SECURITY_ALERT). If the event class name is SECURITY_ALERT, then the test is successful.

 Selector functions

Function

Description

$HostName

Specifies the host name of the computer on which on which BMC Impact Integration Web Services server is running:

Example

$HostName="MYCOMPUTER"
 Can also be inserted in the new message as a slot value: for example,
 MYCOMPUTER=$HostName.

$ClassName

Class name of the event. Can also be inserted in the new event as a slot value to set the class value of a destination event.

Example

slot.imclass=$ClassName
$ClassName="EVENT"

slot.slotname

Compares the value of slot. slotname in the event with the value specified to the right of the operator. When the slot and the value are both present in the event, the criterion is considered a match.

Example

slot.severity = "Critical"

$doselector

Calls additional selectors or subselectors, either or both of which can be linked to or included with an overarching selector.

$doselector is used as a single criterion in the selector or subselector.

Example
 $ClassName!="EVENTS"
$doselector(security_sel)
slot.status != "OPEN"

The selector examines the event class to determine whether it is "EVENTS." Then, the event is compared to the security_sel selector. If that comparison is completed successfully (all criteria matching), the comparison process continues processing using the original selector.

Example of $doselector calling a subselector

SelectorName=SELECTOR_ONE
Description=does some quick checks then calls the sub selector
FailOnMissingSlot=false
Enable=TRUE
{
slot.host="bob"
$doselector(SELECTOR_SUB)
}

SelectorName=SELECTOR_SUB
Description=makes sure it is not a test event
FailOnMissingSlot=false
Enable=TRUE
{
slot.msg!="This is a test"
$Class!="EVENT"
}

For an event to be considered a match to a selector, it must match all the criteria of the selector, including the criteria of selectors or subselectors called by the $doselector function.

$slotPresent

Specifies a slot name that must appear in the event that is being examined for the criterion to be a match.

Example

$SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.

$slotMissing

Specifies a slot name that must not appear in the event that is being examined for the criterion to be a match

Example

$SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.

$TimeT

Returns the number of seconds since January 1, 1970 in number format.

Example

slot.mc_date=$TimeT

$Format

Similar to printf, uses %s to insert values into a string, expands \t and \n.

%s is the only formatter available for $format

Examples

$format("%s:%s", slot.p_agent, slot.p_agent_port)=mc_origin.

$LocalTime

Enables you to specify the local time by using the same format parameters as strftime.

Examples

slot.time=LocalTime("%I:%M:S%p")

$GmtTime

Enables you to specify GMT by using the same format as strftime.

Examples

slot.time=$GmtTime("%I:%M:S%p")

$subString

Extracts specified components of a string.

Example

msg=$subString(slot.test, 0, 20) where the first parameter ( slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include.

$ToLower

Converts all the characters in a string to lowercase.

Example

mc_host=$ToLower(slot.hostname)

$ToUpper

Converts all the characters in a string to uppercase.

Example

mc_domain=$ToUpper(slot.domain)

$GetListValue

Retrieves the value at a specified location in a slot list.

Example

note=GetListValue(slot.notes, 3) where the first parameter (slot.notes in the example) is the slot to be examined from the event and the second parameter (3) is the index of the value to be retrieved.

$IpFromName

Performs a domain name server (DNS) lookup for the host name associated with the specified IP address.

Example

IP=$IpFromName("hostname.domain")

$HostFromIp

Performs a DNS lookup for the IP address associated with the specified host name.

Example

mc_host=$HostFromIp(slot.srcIP)

The following table describes the operators used for comparison in a selector set file: 

Selector operators

Operators

Description

=

For a match, the result to the left of the equals ( = ) operator must equal the result to the right of the operator.

Example

$Slot.Test = "EVENTS"

!=

For a match, the result to the left of the not equals ( * !=* ) operator must not equal the result to the right of the operator.

Example

$ClassName!="EVENT"

=~

Regular expression operator

If the event that is being evaluated by the selector contains the specified slot and slot value matching the regular expression at the right hand, a match is made.

Example

slot.severity= ~"MAJ*." The selector file supports multiple regular expression operators and keywords.

!=~

Regular expression operator If the regular expression fails to match, then the entire line succeeds. If the regular expression matches the value, then the line fails.

Example

slot.severity!="MAJ."

|| OR

Symbol and literal string, both of which specify an OR relationship between successive lines of selector criteria or between successive selector groups.

Example

OR relationship between successive lines of criteria $HostName = "data301" || $HostName = "data400" By default, AND relationships exist between successive lines of selector criteria.

&& AND

Symbol and literal string, both of which specify an AND relationship between successive lines of selector criteria or between successive selector groups.

Example

AND relationship between selector groups
{
slot.Test="EVENTS"
slot.mc_host="EVENTS"
}
AND
{
slot.Test="EVENTS2"
slot.mc_host="EVENTS2"
} By default, AND relationships exist between successive lines of selector criteria.

{ }

Indicates groups of alternative selector criteria within an individual selector. A group can be nested one level deep.

Example

{ }

> 

Specifies a greater-than comparison. Used exclusively with numerical relationships.

Example

slot.Test>10

>=

Specifies a greater-than or equal to comparison. Used exclusively with numerical relationships.

Example

slot.Test>=11

< 

Specifies a less-than comparison. Used exclusively with numerical relationships.

Example

slot.Test<12

<=

Specifies a less-than or equal to comparison. Used exclusively with numerical relationships.

Example

slot.Text<=11

The following table describes selector keywords that are prefixed to specific slots to indicate their function: metadata, required, or readable value. Remember to include the trailing dot (.) when prefixing the keyword to the slot name. 

Keyword descriptions

Keyword

Description

Metaslot.

Designates a slot as a metaslot, which means a slot that provides information about the event. The keyword, followed by a dot, is prefixed to the slot name that it designates.

Example

metaslot.class_name="EVENT"

reqdslot.

Designates a slot as a required slot. If the FailOnMissingSlot parameter is set to FALSE and if the event does not contain the specified required slot, it will not pass the selector criteria. If the FailOnMissingSlot parameter is set to TRUE, then this setting is ignored.

Example

reqdslot.msg="TEST"

slot.

Designates a readable slot value in regular expressions slot.msg=~"event from slot.host" The value of the host slot is used when evaluating the regular expression.

  Editing the selector file

  1. If necessary, copy the iiws.selector file from the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory to the working directory of your BMC Impact Integration Web Services server installation.
  2. In a text editor, open the iiws.selector file.
  3. Modify the different file components — selector set header, selector header, selector content, and operators — as needed.
  4. Save the file by using a file name of your choice and the file extension .selector. If you change the name of the selector file, modify the server instance parameter SelectorFileName in the ImWebServices.conf file accordingly.
  5. Ensure that the selector file can be read by the user under whose permissions the web services server is running.

If the BMC Impact Integration Web Services server is running, restart it to initialize the changes. 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*