Configuring the probe and gateway services

The Agile Service Manager probe and gateway containers are installed together with the other core components. Once you have configured these, Agile Service Manager can display resource information generated from Netcool/OMNIbus events.

About this task

The probe service receives status from Agile Service Manager, and generates corresponding events in the Netcool/OMNIbus Event Viewer. These events are then fed back to Agile Service Manager via the gateway service, which updates the Agile Service Manager status via the status service with the eventId.

The following diagram depicts how the probe and gateway services work together with the Agile Service Manager status service to keep the event status between Agile Service Manager and Netcool/OMNIbus synchronized.

Specifically, this diagram shows how the data flow from Agile Service Manager status generates Netcool/OMNIbus events. When Netcool/OMNIbus is the source of events, however, the data flow from the Event Observer to the topology service not only updates the status eventId with ServerName/ServerSerial, but generates the status itself.

Restriction: Agile Service Manager is not compatible with the model of multiple ObjectServer pairs in OCP.

The following nco tools are deployed with the gateway container, and are exposed as container scripts in the $ASM_HOME/bin directory. These tools accept the -h or -help options.

nco_aes_crypt.sh

You use this tool to encrypt the ObjectServer username and password.

Important: You have to configure the username and password for the probe and gateway only if the ObjectServer is running in secure mode. See the related link to the Netcool/OMNIbus documentation for more information.

Encryption requires a key file, as named by NOI_KEY_FILE in the $ASM_HOME/integrations/omnibus/secure.env file.

nco_keygen.sh

You use this tool to generate a key file for encrypted usernames and passwords.

The key file is named by NOI_KEY_FILE in the $ASM_HOME/integrations/omnibus/secure.env file and is generated in the $ASM_HOME/security directory.

nco_ping.sh and nco_sql.sh

You use these tools to check access to a given ObjectServer; that is, to check connection status and verify TLS configuration.

The nco_sql.sh tool can also be used to perform SQL queries or apply schemas and trigger changes.

Both tools require the $ASM_HOME/integrations/omnibus/omni.dat file, and, if TLS is configured, the $ASM_HOME/integrations/omnibus/secure.env file.

Examples:

$ nco_ping.sh NCOMS
Thu Sep 17 10:02:57 UTC 2020 No Object Server CA certificate configured for connection to the Object Server
Pinging NCOMS
NCO_PING: Server available.

$ nco_sql.sh -server NCOMS -u asm
Thu Sep 17 10:06:44 UTC 2020 No Object Server CA certificate configured for connection to the Object Server
Accessing NCOMS as user asm
Password:
1> select count(*) from alerts.status;
2> go
 COUNT( * )
 -----------
        3449

(1 row affected)
1> exit

The following configuration files define the connection with Netcool/OMNIbus:

omni.dat

Netcool/OMNIbus connections data file (contains configuration examples)

$ASM_HOME/integrations/omnibus/omni.dat

G_ASM.props

Gateway properties file

$ASM_HOME/integrations/omnibus/kafka/gateway/G_ASM.props

probe.props

Probe properties file

$ASM_HOME/integrations/omnibus/kafka/probe/probe.props

secure.env

Additional secure configuration file (optional)

$ASM_HOME/integrations/omnibus/secure.env

Important: After changing any of the configuration files in the $ASM_HOME/integrations/omnibus directory, you must restart the probe and gateway services before your changes take effect.

Tip: You can use the included test scripts to generate a test event.

Configure target ObjectServer schema and triggers

1. Perform the following updates to the target Netcool/OMNIbus ObjectServers.
   Remember: Work with the Netcool/OMNIbus administrator to apply these changes.
   1. Set the sub-second clearance mechanism.

      Sub-second clearance mechanism

      This mechanism allows the correct clearance of event updates that occur in the same second.

      A new field is added to the alerts.status schema, which works in conjunction with the core Netcool/OMNIbus field @LastOccurrence; @LastOccurrenceUSec.

      This mechanism is set via the Agile Service Manager probe rules file and referred to in an updated generic clear trigger.

   2. Define the Agile Service Manager status events clearance.

      Agile Service Manager specific clearance

      A new Netcool/OMNIbus SQL trigger handles the specific clearance of Agile Service Manager status events.

   Note:

   Examples of these updates are provided with Agile Service Manager and are located in the $ASM_HOME/integrations/omnibus directory.

   asm-alert-fields.sql

   Defines two new fields:

   LastOccurrenceUSec

   Allows sub-second clearing

   AsmStatusId

   Stores the topology service status ID

   Without these fields, the probe and gateway services cannot connect.

   asm-trigger.sql

   Clears up events generated by Agile Service Manager when resources are deleted.

   These events will not be cleared if this trigger has not been applied.

   updated-generic-clear.sql

   Updates generic_clear automation to allow sub-second clearing.

   Warning: The sample updates supplied with Agile Service Manager should not be applied to an existing Netcool/OMNIbus deployment without a review by the Netcool/OMNIbus administrator, as they overwrite core Netcool/OMNIbus functions, which may have been customized in an existing Netcool/OMNIbus system. In this case the Netcool/OMNIbus administrator may need to develop custom updates for this integration.

   Hybrid scenario tip: If Agile Service Manager is deployed on OCP and connecting to an existing Netcool/OMNIbus or NOI system, you can obtain the sample SQL files via the following steps:

   1. Log into the OCP system.
   2. Extract the asm-trigger.sql file:

      oc get configmap asm-noi-gateway-config -o jsonpath="{.data.asm-trigger\.sql}" > asm-trigger.sql

   3. Extract the 'updated-generic-clear.sql file:

      oc get configmap asm-noi-gateway-config -o jsonpath="{.data.updated-generic-clear\.sql }" > updated-generic-clear.sql

   4. Recreate asm-alert-fields.sql:

      echo -e "alter table alerts.status add column AsmStatusId varchar(64);\nalter table alerts.status add column LastOccurrenceUSec int;\ngo\n" > asm-alert-fields.sql

   High availability scenario guidelines: When integrating Agile Service Manager with an existing multi-tiered ObjectServer HA (High Availability) deployment, apply the asm-alert-fields.sql, asm-trigger.sql, and updated-generic-clear.sql scripts to all servers. These scripts are available in $ASM_HOME/integrations/omnibus folder.
   The following example assumes a scenario with two HA aggregation servers and two HA collection servers (the gateway communicating with the aggregation layer and the probe communicating with the collection layer).

   asm-alert-fields.sql

   Apply this script to all ObjectServers.

   This script defines the new LastOccurrenceUSec and AsmStatusId fields, and all gateways synching between ObjectServers must copy these new fields.

   asm-trigger.sql

   Apply this script to both the collection and aggregation layers.

   Both layers require the asm_extra_deduplication trigger deployed by this script to pass data through from observer to probe to collection to aggregation).

   updated-generic-clear.sql

   Apply this script to both the collection and aggregation layers.

   This script updates generic_clear automation and is needed at both collection and aggregation layer to allow sub-second raising and clearing of events from Agile Service Manager observers.

Configure connectivity to the target ObjectServer(s)

2. Define the ObjectServer to which the probe and gateway services connect.
   Important: The default file paths in the probe and gateway properties files should not be altered. These fixed paths identify the files within the containers mounted in the $ASM_HOME/etc configuration files, and do not correspond to the paths on the Agile Service Manager host.
   1. Identify the ObjectServer to which the probe and gateway services connect.
      The ObjectServers must be identified in the $ASM_HOME/integrations/omnibus/omni.dat file. This location is fixed and will be mounted into the nasm-noi-probe and nasm-noi-gateway containers. In the following omni.dat sample a single ObjectServer is identified called 'AGG_P'.

      [AGG_P]
      {
         Primary:    1.2.3.4    4100
      }

      Further ObjectServers may be configured in this file, for example to support failover or multi-tier systems. See the related link to the Netcool/OMNIbus documentation for more information on editing omni.dat files.
   2. Configure the probe service to connect to the identified ObjectServer.
      The probe service is configured in the $ASM_HOME/integrations/omnibus/kafka/probe/probe.props file. This location is fixed and will be mounted into the nasm-noi-probe container. In the following probe.props sample the ObjectServer is specified by the 'Server' property, and must match the ObjectServer identified in the omni.dat file in the previous step, which in this example is 'AGG_P'.

      Server                          : 'AGG_P'

   3. Configure the gateway service to connect to the identified ObjectServer.
      The gateway service is configured in the $ASM_HOME/integrations/omnibus/kafka/gateway/G_ASM.props file. This location is fixed and will be mounted into the nasm-noi-gateway container. In the following G_ASM.props sample the ObjectServer is specified by the 'Gate.Reader.Server' property, and must match the ObjectServer identified in the omni.dat file.

      Gate.Reader.Server              : 'AGG_P'

Encrypt username and password

3. Use the nco_keygen.sh tool to generate a key file.
   For example:

   $ASM_HOME/bin/nco_keygen.sh 
   Generating key file $ASM_HOME/security/noi_keyfile
   

4. Encrypt the username and password using the generated key.
   In this example, the username and password are both asm:

   $ASM_HOME/bin/nco_aes_crypt.sh asm
   

   Example encrypted output:

   @44:9nx51SfAdcPhyQlmqcqL0OqHanR/wQUnZy943YI+TrQ=@
   

5. Add the encrypted username and password to the gateway property file:
   
   $ASM_HOME/integrations/omnibus/kafka/gateway/G_ASM.props

   Gate.Reader.Server              : ‘AGG_P'
   ConfigCryptoAlg                 : 'AES_FIPS'
   ConfigKeyFile                   : '$NCHOME/omnibus/asm/$NOI_KEY_FILE'
   Gate.Reader.Username            : '@44:9nx51SfAdcPhyQlmqcqL0OqHanR/wQUnZy943YI+TrQ=@'
   Gate.Reader.Password            : '@44:9nx51SfAdcPhyQlmqcqL0OqHanR/wQUnZy943YI+TrQ=@'
   

6. Add the encrypted username and password to the probe property file:
   
   $ASM_HOME/integrations/omnibus/kafka/probe/probe.props

   Server                          : ‘AGG_P'
   ConfigCryptoAlg                 : 'AES_FIPS'
   ConfigKeyFile                   : '$NCHOME/omnibus/asm/$NOI_KEY_FILE'
   AuthUserName                    : '@44:9nx51SfAdcPhyQlmqcqL0OqHanR/wQUnZy943YI+TrQ=@'
   AuthPassword                    : '@44:9nx51SfAdcPhyQlmqcqL0OqHanR/wQUnZy943YI+TrQ=@'
   

Define ObjectServer TLS

7. Define the Object Server CA certificate by ensuring the following:
   1. The CA certificate file must exist (or copied to) in the $ASM_HOME/security directory.
      Example:

      cp <previous_location>/aCaCert.crt $ASM_HOME/security/aCaCert.crt

   2. The file is named by NOI_CA_CERTIFICATE in the $ASM_HOME/integrations/omnibus/secure.env file.

      NOI_CA_CERTIFICATE=aCaCert.crt

8. Add TLS settings to the configuration files.

   omni.dat

   Required

   [AGG_P]
   {
       Primary:    noi-omnibus  ssl  4100
   }
   

   G_ASM.props

   Some configurations may require the gateway Gate.Reader.CommonNames property,

   Gate.Reader.Server              : ‘AGG_P'
   #Gate.Reader.CommonNames        : May be required
   

   probe.props

   Some configurations may require the probe SSLServerCommonName property.

   Server                          : ‘AGG_P'
   #SSLServerCommonName            : May be required

9. Required: After changing any of the configuration files in the $ASM_HOME/integrations/omnibus directory, you have to restart the probe and gateway services before your changes take effect.

# Example omni.dat file. Copy your own omni.dat file in here, and configure the 
# probe and gateway to connect to the appropriate object servers in their props files:
#
# - $ASM_HOME/integrations/omnibus/kafka/probe/probe.props 
# - $ASM_HOME/integrations/omnibus/kafka/gateway/G_ASM.props 
#
[AGG_P]
{
    Primary:    noi-omnibus    4100
}

#
# Example failover pair config. The gateway and probe properties would require:
#
# - Probe
# Server: 'AGG_V'
#
# - Gateway
# Gate.Reader.Server: 'AGG_V'
#
[AGG_V]
{
    Primary:    primary-host.example.com    4100
    Backup:     backup-host.example.com     4100
}


#
# Example of connecting the probe and gateway to different layers of a multi-tiered architecture. 
# The gateway and probe properties would require:
#
# - Probe
# Server: 'COL_P'
#
# - Gateway
# Gate.Reader.Server: 'AGG_P'
#
[AGG_P]
{
    Primary:    aggregation-layer-host.example.com    4100
}

[COL_P]
{
    Primary:    collection-layer-host.example.com    4100
}

#
# Example TLS config. The gateway and probe properties could use:
#
# - Probe
# Server: 'TLS_AGG_P'
#
# - Gateway
# Gate.Reader.Server: 'TLS_AGG_P'
#
# or can make use of the gateway Gate.Reader.CommonNames and probe SSLServerCommonName 
# properties
#
# The Object Server CA certificate or key database file + password must be configured 
# in $ASM_HOME/integrations/omnibus/secure.env
#
[TLS_AGG_P]
{
    Primary:    tls-host.example.com  ssl  4100
}

nco_test_create.sh
nco_test_verify.sh
nco_test_delete.sh