|
|
This chapter introduces Info Gateways, their key features, and how they are used. It helps you to understand what Info Gateways are before you use them.
This chapter contains the following sections:
The Cisco Info Center gateway is a mechanism for actively integrating the Cisco Info Center system with third party applications and replicating alerts between Cisco Info Servers.
When an Info Gateway is running, it runs multiple threads called Readers and Writers. Readers extract alerts from Cisco Info Servers. Writers forward alerts to Cisco Info Servers or to other applications. Only one type of Reader exists, however, various types of Writers exist for specific applications. Figure 5-1 shows an example Info Gateway configuration.
In this example, one source Cisco Info Server (NCOMS) is recording alerts in a Sybase database, generating trouble tickets for a Remedy ARS, and replicating alerts in another Cisco Info Server (DENCO). The DENCO Cisco Info Server is also replicating alerts in the Sybase database.
Between the Readers and the Writers are routes which specify where a Reader should forward alerts. A single Reader can have a number of routes to different Writers, and a single Writer can have multiple routes from different Readers.
See Section, "An Example Info Gateway Configuration", for more information about how this Info Gateway is created.
Every Info Gateway has a configuration file. The configuration file is used to define the environment and operation of the Info Gateway including its:
When an Info Gateway is run, it reads and processes the commands in the configuration file to define the connection between the source Cisco Info Server and the alert destination(s).
All Info Gateway configuration files are stored in the directory:
$OMNIHOME/etc/<gatename>.conf
where <gatename> is the name of the Info Gateway, for example:
$OMNIHOME/etc/NCO_GATE.conf
This example shows where the NCO_GATE configuration file is stored. Note, <gatename> must be the same as the gateway name used to run the Info Gateway through process control. See Section,"Running an Info Gateway", for more information.
Info Gateway configuration files use their own language. All of the commands you can use in the configuration files are described in Appendix H, "Info Gateway Command Reference".
This section describes the main Info Gateway components. All Info Gateways must include at least one Reader, Writer, route, and mapping with optional filters. Each of these components is created by a command from the Info Gateway command reference. See Appendix H, "Info Gateway Command Reference", for more information about these and other commands.
Readers extract alerts from Cisco Info Servers. There is one type of Reader, the Cisco Info Server Reader. Readers are created using the START READER command. This command defines the name of the Reader and the name of the Cisco Info Server to read from.
For example, to create a Reader for the Cisco Info Server NCOMS, as shown in Figure 5-1, add the following command to the configuration file:
START READER NCOMS_READ CONNECT TO NCOMS;
Once this command has been issued, the Reader is started and the Info Gateway attempts to open a connection to the source Cisco Info Server. When the Info Gateway succeeds in opening the connection, it immediately starts to read alerts from the Cisco Info Server. In order for the Reader to be able to forward these alerts to their destination, you must define an associated route and Writer.
The START READER command is described in more detail in Appendix H, "Reader Commands".
Writers write the alerts acquired by a Reader to the destination application or Cisco Info Server. Writers are created using the START WRITER command. This command defines the name of the Writer and the parameters that allow it to connect to its destination.
For example, to create a Writer for the Remedy Action Request System (ARS), as shown in Figure 5-1, you would add the following command to the configuration file:
START WRITER ARS_WRITER(TYPE = ARS,
REVISION = 1,
MAP = ARS_MAP,
SERVER = 'orac',
SCHEMA = 'Omnibus 3.3',
USER = 'Demo',
PASSWORD = '',
FEEDBACK = TRUE,
FEEDBACK_SERVER = NCOMS,
FEEDBACK_FIELD = 'Location',
JOURNAL = 536870919);
Once this command is issued, the Info Gateway tries to establish and check the connection to the alert destination; either an application or another Cisco Info Server. When the Writer is configured correctly, it writes every alert received from the source Cisco Info Server, until the STOP WRITER command is issued. Note, the connection between the Reader and Writer must pass through a route.
The START WRITER and STOP WRITER commands are described in more detail in Appendix H, "Writer Commands". All of the available third party application Writers are described in more detail in Chapter 6, "Using Info Gateways." The Cisco Info Server Writers are described in more detail in "Types of Info Gateways".
Routes create the link between Readers and Writers. Routes are created using the ADD ROUTE command. This command defines the name of the route, the source Reader, and the destination Writer.
For example, to create a route between the Cisco Info Server NCOMS and the Remedy ARS Writer, as shown in Figure 5-1, you would add the following command to the configuration file:
ADD ROUTE FROM NCOMS_READ TO ARS_WRITER;
Once this command is issued, the connection between a Reader and Writer is established. Provided all of the commands have been configured correctly, any alerts received by the source Cisco Info Server are read by the Reader, passed through the route to the Writer, and written into the destination Cisco Info Server or application.
The ADD ROUTE command is described in more detail in Appendix H, "Route Commands".
Mappings define how the format of the alerts received from the source Cisco Info Server should be changed so they can be written to the destination Cisco Info Server or application. Each Writer has a different mapping which is started using the CREATE MAPPING command.
For example, to create a mapping between the Cisco Info Server Reader and the Remedy ARS Writer, as shown in Figure 5-1, you would add the following command to the configuration file:
CREATE MAPPING ARS_MAP(536870914 = '@Identifier' ON INSERT ONLY,
536870913 = '@Serial' ON INSERT ONLY,
536870944 = '@Node' ON INSERT ONLY,
536870915 = '@NodeAlias' ON INSERT ONLY,
536870932 = '@Manager' ON INSERT ONLY,
536870939 = '@Agent' ON INSERT ONLY,
536870918 = '@AlertGroup' ON INSERT ONLY,
536870931 = '@AlertKey' ON INSERT ONLY,
7 = '@Severity',
536870916 = '@Summary' ON INSERT ONLY,
536870946 = '@StateChange',
536870912 = '@FirstOccurrence' ON INSERT ONLY,
536870917 = '@LastOccurrence',
536870935 = '@InternalLast',
536870938 = '@Poll' ON INSERT ONLY,
536870941 = '@Type' ON INSERT ONLY,
536870940 = '@Tally',
536870945 = '@Class' ON INSERT ONLY,
536870942 = '@Grade' ON INSERT ONLY,
536870934 = '@Location' ON INSERT ONLY,
536870933 = '@Acknowledged'
);
This example shows how the alert fields read from the source Cisco Info Server (represented by the @ symbol) are mapped into ARS fields. The ON INSERT ONLY flag controls the updating of the field. Mappings with the ON INSERT ONLY flag are only written once; when the alert is created for the first time in the Cisco Info Server. Mappings not having the ON INSERT ONLY flag, are updated each time the alert changes.
The mapping has a name, ARS_MAP. Between the parentheses, each line defines which fields in ARS receive which data from the Cisco Info Server's fields. Fields in an ARS database are referred to with long integer values, rather than field names. For example, the following line defines that field 536870913 in ARS, has the value of the Serial field from the Cisco Info Server:
536870913 = '@Serial' ON INSERT ONLY,
The CREATE MAPPING command is described in more detail in Appendix H, "Mapping Commands". The format of each Info Gateway specific mapping is described in Chapter 6.
You may not always want to send all of the alerts read by a Reader to the destination Cisco Info Server or application. For example, you may only want to send alerts that have a critical severity level. Filters are used to define which alerts read by the Cisco Info Server Reader, are forwarded to the destination.
Filters are created using the CREATE FILTER command and are then applied through the START READER command. For example, to create a filter that only allows critical alerts to be forwarded to the destination application or Cisco Info Server, you could add the following command to the configuration file:
CREATE FILTER CRITONLY AS 'Severity = 5';
This command creates a filter named CRITONLY, which only forwards alerts with a critical severity level (5). To apply the command to the Cisco Info Server Reader, as shown in Figure 5-1, you add the following command to the configuration file:
START READER NCOMS_READ CONNECT TO NCOMS USING FILTER CRITONLY;
The CREATE FILTER command is described in more detail in Section, "Filter Commands", in Appendix H.
When you need more than one filter on the same Cisco Info Server, you can create multiple Readers on a Cisco Info Server. For example, when you want one Reader to forward all of the critical alerts, and another to forward everything else, you could use the following commands:
CREATE FILTER CRITONLY AS 'Severity = 5';
CREATE FILTER THEREST AS 'Severity <5';
START READER CRIT_NCOMS CONNECT TO NCOMS USING FILTER CRITONLY;
START READER REST_NCOMS CONNECT TO NCOMS USING FILTER THEREST;
It is important to note, when you want to perform string comparisons with filters, you must escape the quotes within the CREATE FILTER command with backslashes. For example, when you want to create a filter that only forwards alerts from a node called fred, the CREATE FILTER command is:
CREATE FILTER FREDONLY AS 'NODE = \'fred\'';
Filters can also be loaded from Cisco Info Center Event List (.elf) files as created by the Filter Builder. For example:
LOAD FILTER FROM '/usr/filters/myfilt.elf';
This command loads the file /usr/filters/myfilt.elf as a filter. This filter takes the name entered in the Filter Builder Name field. Note, you should ensure the Name field is alphabetic with no spaces.
See the Cisco Info Center Administrator Reference guide for more information about the Filter Builder and Event List (.elf) files.
Two different types of Info Gateways exist:
Third party application Info Gateways are used to integrate the Cisco Info Center into other applications. For example, the Remedy ARS Info Gateway is used to convert Cisco Info Center alerts into Remedy ARS trouble tickets.
Cisco Info Server Info Gateways are used to replicate alerts between Cisco Info Servers. Typically, this could mean using one Cisco Info Server as a backup to another Cisco Info Server or using one Cisco Info Server as a mirror image of another Cisco Info Server.
Third party application Info Gateways are defined by their Writers. The following third party application Writers are currently available:
Each of these Writers is described in detail in Chapter 6, "Using Info Gateways", along with the Writer attributes you can use and the mappings they require.
Only one type of Cisco Info Server gateway exists. It is described in detail in Chapter 6, "Using Info Gateways." However, two distinct Cisco Info Server Writer configurations can be used:
Each of these configurations is described in the following sections.
A unidirectional Cisco Info Gateway is a gateway that only allows alerts to flow in one direction. Therefore, any changes made in the source Cisco Info Server are replicated in the destination Cisco Info Server. However, any changes made in the destination Cisco Info Server are not replicated in the source Cisco Info Server.
Figure 5-2 shows the configuration of a unidirectional Cisco Info Gateway as stored in the configuration file NCO_GATE.
A unidirectional Cisco Info Gateway is created in the same way as any other Info Gateway. They require at least a Reader, a route, a mapping, and a Cisco Info Server Writer. See Chapter 6, "Using Info Gateways", for more information.
In a bidirectional Cisco Info Gateway configuration, any changes made to the contents of either Cisco Info Server are replicated in the other Cisco Info Server. Both Cisco Info Servers work in unison, as if they were one. This allows you to maintain two Cisco Info Servers, on different machines, that can continue to run should one of them fail.
Bidirectional Cisco Info Gateways have a similar configuration to unidirectional Cisco Info Gateways. The difference is the addition of the COUNTERPART attribute to the Cisco Info Server Writers. The COUNTERPART attribute defines a link between a Cisco Info Server's Writer and Reader. The Info Gateway interprets a Reader and Writer connected by a counterpart as one half of a bidirectional Cisco Info Gateway. Figure 5-3 shows a typical bidirectional Cisco Info Gateway configuration.
The Readers and routes shown in this example are configured in the same way as for a unidirectional Info Gateway. However, the Writers are slightly different, as it is the Writer that defines the counterparts. The Writers in this example would be created in the configuration file as follows:
START WRITER DENCO_WRITER(TYPE = OBJECT_SERVER,
REVISION = 1,
SERVER = DENCO,
MAP = SERVER_MAP,
COUNTERPART = DENCO_READER);START WRITER NCOMS_WRITER(TYPE = OBJECT_SERVER,
REVISION = 1,
SERVER = DENCO,
MAP = SERVER_MAP,
COUNTERPART = NCOMS_READER);
It is important to use counterparts when linking two Cisco Info Servers together. When you do not, two unidirectional Info Gateways, that are not related to each other, are created. The effect of this is that any alerts received by either Cisco Info Server are automatically forwarded to the other Cisco Info Server. This Cisco Info Server then detects that it had received a new alert and forwards it back through the second Info Gateway to the first Cisco Info Server. This creates an endless loop of alerts between the two Cisco Info Servers.
The counterpart works by disabling IDUC, for that alert, on its associated Reader. This is so that when an alert is forwarded through the Writer (without IDUC) it is added to the Event List and not detected by the Reader as a new alert.
This section describes two of the key techniques of Info Gateway operation; store and forward and resynchronization. Both of these techniques are used to ensure the stability of your system in the event of a system or Cisco Info Server crash.
When either the Sybase Writer or the Cisco Info Server Writer are in store mode, they store everything they would normally forward in a file named:
$OMNIHOME/var/<writername>.<destserver>.store
Where <writername> is the name of the Writer and <destserver> is the name of the server to which the Info Mediator was attempting to send alerts.
When the Info Gateway detects the destination server is back on-line, it switches into forward mode and forwards the alert information held in the .store file to the destination server. Once all alerts in the .store file have been forwarded, the Writer returns to normal operation.
Store and forward only works when a connection to the destination (Cisco Info Server or Sybase database), has been established, used, and then lost. When the destination server is not running when the Info Gateway starts, store and forward mode is not triggered and the Info Gateway stops.
When the Info Gateway connects to the destination and a store and forward file already exists, the Info Gateway replays the contents of the store and forward file before it forwards new alerts.
Note, store and forward does not work with bidirectional Info Gateway configurations.
The Cisco Info Server can be run in secure mode. The -secure option controls the authentication of any Info Mediator or Info Gateway connection requests with a user name and an encrypted password. The default is unsecure mode. This is set with the -unsecure option.
When a connection request is sent, the Cisco Info Server issues an authentication message. The Info Gateway must respond with the correct user name and password. The user name and password are set in the Info Gateway configuration file. When the user name and password are incorrect, the Cisco Info Server issues an error message and rejects the connection.
When you are running an Cisco Info Server in secure mode, you must add two commands to each Info Gateway configuration file: AUTH_USER and AUTH_PASSWORD. The AUTH_USER command defines a valid user name, which is used to identify the Info Gateway. The AUTH_PASSWORD command defines a password.
The passwords used in secure mode must be encrypted. You can encrypt them using the nco_crypt utility.
To enable an Info Gateway to run in secure mode:
1. Add the AUTH_USER and AUTH_PASSWORD commands to the Writer in the configuration file. These commands are in the format:
command '<value>';
Where <value> is the user name or password. Note, these commands must appear in the configuration file before any Reader commands.
2. Add a unique name for the Info Gateway as the AUTH_USER command value.
3. Create an encrypted password by entering:
nco_crypt <password>
Where <password> is the unencrypted form of the password. The nco_crypt utility displays an encrypted version of the password.
4. Copy the encrypted password into the AUTH_PASSWORD command value.
5. Run the Info Gateway.
Using Cisco Info Center, you can create a unidirectional or bidirectional Info Gateway that connects two Cisco Info Servers together. Using one of these Info Gateways, you can synchronize the contents of one Cisco Info Server with the contents of another.
However, when one of these Cisco Info Servers becomes unavailable (for example, due to a system failure), the contents of the Cisco Info Servers could become desynchronized. When this happens, you can resynchronize the contents of the Cisco Info Servers using either the RESYNC (for bidirectional Info Gateways) or UNIRESYNC (for unidirectional Info Gateways) command.
In order to resynchronize a pair of Cisco Info Servers, Cisco Info Center defines one as the master and one as the slave. The slave server is the one that has been corrupted. During a resynchronization, data is always written from the master to the slave.
You can re-synchronize a unidirectional Info Gateway using the UNIRESYNC command. This command has the following syntax:
UNIRESYNC READER WRITER;
UNIRESYNC checks the contents of the two Cisco Info Servers connected through the Reader and Writer specified and, when necessary, re-synchronizes them.
In a unidrectional Info Gateway, data only flows in one direction. The source server is the master server and the destination is the slave server.
You can re-synchronize a bidirectional Info Gateway using the RESYNC command. This command has the following syntax:
RESYNC WRITERNAME, WRITERNAME [MASTER=WRITERNAME] [PREFER=WRITERNAME];
You must supply the names of the two Cisco Info Server Writers in your bidirectional Info Gateway, however, the MASTER and PREFER parameters are optional.
When you do not specify a MASTER or PREFER parameter, the RESYNC command checks the two Cisco Info Servers and works out which has been running the longest. That Cisco Info Server becomes the master, the other becomes the slave. The command then deletes the contents of the slave Cisco Info Server and populates it with the contents of the master Cisco Info Server.
When you know which Cisco Info Server has been running the longest, you can use the optional MASTER parameter to specify it as the master server. For example:
RESYNC DENCO_WRITER, NCOMS_WRITER MASTER=NCOMS_WRITER;
In this example, the NCOMS Cisco Info Server is specified as the master server. When this command is issued, regardless of which Cisco Info Server has been running the longest, the contents of the DENCO Cisco Info Server is deleted and populated with the contents of the NCOMS Cisco Info Server.
You can also specify a preferred master Cisco Info Server using the PREFER parameter. This parameter specifies which Cisco Info Server should be used as a master in the event both have been running for the same length of time.
You may want to filter the events transferred from one Cisco Info Server to another during a resynchronization. For example, you may want to ensure a Cisco Info Server never transfers events with a Severity>3 to its counterpart Cisco Info Server.
When both Readers in your bidirectional Info Gateway use the same filter, the alerts passed between the two Cisco Info Servers are filtered correctly. However, when your bidirectional Info Gateway uses two different filters, you must force the Info Gateway to use the same filter for both Readers using the RESYC_FILTER attribute in the Writer definition. You can also use the RESYC_FILTER attribute to force the Info Gateway to use a specific filter only during resynchronization.
The following example shows two bidirectional Cisco Info Server Writers. The DENCO_WRITER includes a RESYNC_FILTER attribute. This filter defines that when the DENCO and NCOMS Cisco Info Servers are re-synchronized, the NCOMS Cisco Info Server only transfers events with a Severity<3.
CREATE FILTER resync_filter AS 'Severity < 3';START WRITER DENCO_WRITER(TYPE = OBJECT_SERVER,
REVISION = 1,
SERVER = DENCO,
MAP = SERVER_MAP,
COUNTERPART = DENCO_READER,
RESYC_FILTER = resync_filter);START WRITER NCOMS_WRITER(TYPE = OBJECT_SERVER,
REVISION = 1,
SERVER = DENCO,
MAP = SERVER_MAP,
COUNTERPART = NCOMS_READER
);
This section describes how to use specific Info Gateways including how to load, run, and configure them.
Once you have created your Info Gateway configuration file, you must configure it through the servers editor (nco_xigen). Each Info Gateway must have a unique name and port number. See the Cisco Info Center Administrator Reference guide for more information about nco_xigen.
When necessary, once you have installed the Info Gateway, you can update the configuration file. See Section, "The Info Gateway Configuration File", for more information.
To run an Info Gateway, specify:
$OMNIHOME/bin/nco_gate -name <gatename>
Where <gatename> is the name of the Info Gateway you want to run.
Process control is described in detail in the Cisco Info Center Administrator Reference guide. This section describes how to run an Info Gateway under Process Control. It is assumed you have read the Process Control chapter of the Cisco Info Center Administrator Reference guide and understand the concept of a service, a process, and process dependencies.
To run an Info Gateway under Process Control:
1. Edit the configuration file as described in Section, "The Info Gateway Configuration File".
2. Select the service you want the Info Gateway process to run under, from the Process Control Manager window.
3. Select the Process menu's Create option. The Process Definition window is displayed.
4. Specify the definition of the Info Gateway process you want to run. Figure 5-4 shows an example definition for an Info Gateway named Gate1.
5. When you have completed the fields in the Process Definition window, click on the Apply button.
6. Click on the Close button to return to the Process Control Manager window, where the new Info Gateway process is displayed.
The Info Gateway is now run under Process Control whenever the service is started. For more information about starting and stopping processes and services, see the Cisco Info Center Administrator Reference guide.
You can change the configuration of an Info Gateway interactively while it is running, by using the nco_sql command.
You must be a member of the ncoadmin group to log into an Info Gateway. Create the ncoadmin group and add Cisco Info Center users to it. When you run NIS, NIS+, or another global information service, you must ask the administrator of that service to do this for you.
The nco_sql command requires one parameter (-server) followed by the name of the Info Gateway. For example, when you have a server running named NCOMS, to log into it, specify:
$OMNIHOME/bin/nco_sql -server NCOMS
When you press Return, you are prompted to specify a password. You should specify your UNIX password, not your Cisco Info Center password.
Once you are logged into the Info Gateway, you can specify commands to configure it dynamically. The following example shows a typical session in which a new route is added:
$ nco_sql -server NCO_GATE
Password:
User 'admin' logged in.
1> ADD ROUTE FROM DENCO_READ TO ARS_WRITER;
2> go
1>
Each command you specify must be terminated by a semi-colon and followed by a go command, which issues the previously entered command.
When you want to disable the interactive configuration facility, add the following command to the configuration file:
When interactively logged in to the gateway, it is possible to save the configuration of the gateway with the command:
SAVE CONFIG TO '<filename>';
Where <filename> is the name of a file on a local file system.
When you save a configuration in this way, you can use the file created as a configuration file for other Info Gateways.
It is also possible to load configurations interactively. We recommend you discard the current configuration before this is done, by using the DUMP CONFIG command. DUMP CONFIG does not clear the configuration when any Readers and Writers are running or when the configuration has been changed interactively. See Appendix H, "Info Gateway Command Reference", for more information.
Although you can force the DUMP CONFIG command to clear the configuration (DUMP CONFIG FORCE), we recommend you first halt all running Readers and Writers manually with the STOP command.
To determine when the configuration has been changed interactively, use the SHOW SYSTEM command.
Once you have dumped the configuration, you can load a new configuration with the command:
LOAD CONFIG FROM <filename> ;
Where <filename> is the name of a file on a local file system.
This section describes how you could create the example Info Gateway shown in Figure 5-5.
For the purpose of this example, the Info Gateway configuration has been split into a number of stages, as follows:
1. Initializing the Info Gateway.
2. Creating the Cisco Info Gateway.
3. Creating the Remedy ARS mapping.
4. Creating the Remedy ARS Writer.
5. Adding the Remedy ARS route.
6. Connecting to Sybase.
7. Preparing Sybase.
8. Mapping Sybase.
9. Creating the Sybase writer.
10. Adding the Sybase route.
11. Connecting to another Cisco Info Server.
12. Sharing a writer.
Each of these stages is described in the following sections.
For the purpose of this example, it is assumed the Cisco Info Servers (NCOMS and DENCO) and the third-party applications (Remedy ARS and Sybase) are already installed and working correctly.
Figure 5-6 shows the system configuration with no Info Gateway connections:
It is important to note that although the Info Gateway process can be run, it does nothing without being issued commands to configure its operation. Normally these commands are read at start up from the configuration file:
$OMNIHOME/etc/gatename.conf
With the Info Gateway named NCO_GATE, the configuration file is named:
$OMNIHOME/etc/NCO_GATE.conf
In this example, it is assumed that you have already configured the Info Gateways NCO_GATE, NCOMS, and DENCO through the servers editor (nco_xigen). See the Cisco Info Center Administrator Reference guide for more information about nco_xigen.
The first stage is to create a Reader to extract data from the NCOMS Cisco Info Server. The following command is the first line of the configuration file (NCO_GATE.conf):
START READER NCOMS_READ CONNECT TO NCOMS;
This command creates a Reader called NCOMSs_READ which connects to NCOMS as shown in Figure 5-7.
The Reader is now reading data from NCOMS. However, it is discarding the data because it has nowhere to send it. Therefore, both the Info Gateway and the Cisco Info Server are wasting processing power. You should avoid setting up Readers without corresponding Writers.
Mapping is a mechanism for controlling how a Writer uses new and updated information from a Reader. The following command creates a mapping for the Remedy ARS:
CREATE MAPPING ARS_MAP(536870914 = '@Identifier' ON INSERT ONLY,
536870913 = '@Serial' ON INSERT ONLY,
536870944 = '@Node' ON INSERT ONLY,
536870915 = '@NodeAlias' ON INSERT ONLY,
536870932 = '@Manager' ON INSERT ONLY,
536870939 = '@Agent' ON INSERT ONLY,
536870918 = '@AlertGroup' ON INSERT ONLY,
536870931 = '@AlertKey' ON INSERT ONLY,7 = '@Severity',536870916 = '@Summary' ON INSERT ONLY,
536870946 = '@StateChange',
536870912 = '@FirstOccurrence' ON INSERT ONLY,
536870917 = '@LastOccurrence',
536870935 = '@InternalLast',
536870938 = '@Poll' ON INSERT ONLY,
536870941 = '@Type' ON INSERT ONLY,
536870940 = '@Tally',
536870945 = '@Class' ON INSERT ONLY,
536870942 = '@Grade' ON INSERT ONLY,
536870934 = '@Location' ON INSERT ONLY,
536870933 = '@Acknowledged');
This mapping requires the Remedy ARS administrator to configure a schema in Remedy ARS to accept this information. When this is not done beforehand, the mapping cannot find the specified fields and the Info Gateway cannot write to Remedy ARS.
Creating a Writer provides the Info Gateway a way to send data to another application. There are different types of Writers for each specific application. The type of Writer is determined by the TYPE parameter used when creating the Writer. The following command creates a Remedy ARS Writer:
START WRITER ARS_WRITER
(TYPE = ARS,
REVISION = 1,
MAP = ARS_MAP,
SERVER = 'orac',
SCHEMA = 'Omnibus 3.3',
USER = 'Demo',
PASSWORD = '',
FEEDBACK = TRUE,
FEEDBACK_SERVER = NCOMS,
FEEDBACK_FIELD = 'Location',
JOURNAL = 536870919);
After the TYPE= parameter comes the REVISION= parameter; which is used for setting the version of the Writer to use when more than one Writer of a particular type exists. The other parameters are Writer-type specific. The following sections describe each line in the order they appear.
Following is the beginning of the command to start a Writer called ARS_WRITER:
The open parenthesis specifies the start of the parameters for the Writer, followed by the TYPE parameter. In this case, it sets the TYPE to ARS to identify the Writer is for Remedy ARS:
(
TYPE=ARS,
The REVISION parameter is for future compatibility and will be incremented as new Writers appear. For now, it should be set to 1:
REVISION = 1,
The MAP parameter selects which mapping should be used for this Writer:
MAP = ARS_MAP,
The SERVER parameter indicates on which machine the Remedy ARS server can be found. In this case, it is on a machine called orac:
SERVER = 'orac',
Remedy ARS supports multiple schemas, the SCHEMA parameter specifies which schema it should write into. The schema in Remedy ARS should be created by the ARS administrator with the schema supplied with the Info Gateway:
SCHEMA = 'Omnibus 3.3',
The Writer must be able to log on to Remedy ARS to submit and update trouble tickets. The USER parameter specifies the user name. The PASSWORD parameter specifies which password the user should specify:
USER = 'Demo',
PASSWORD = '',
When a trouble ticket is posted to Remedy ARS, it is given its own trouble ticket number. It is useful to know, when looking at an alert in Cisco Info Center, which trouble ticket is being used. The feedback mechanism allows for this. Setting the FEEDBACK parameter to true instructs the Writer that when a new trouble ticket is written to Remedy ARS, it should take the allocated ticket number and write it back to an Cisco Info Server in a particular field. The FEEDBACK_SERVER parameter names the Cisco Info Server where the ticket number should be written. The FEEDBACK_FIELD parameter specifies the field into which the trouble ticket number is written. For example:
FEEDBACK = TRUE,
FEEDBACK_SERVER = NCOMS,
FEEDBACK_FIELD = 'Location',
The JOURNAL parameter contains the ID number of the Journal field in the ARS schema. When this parameter is present, the Writer updates the journal entry for each alert in ARS:
JOURNAL = 563870919
To complete the Writer, the parentheses are closed, followed by a semicolon:
);When this command is executed, a Writer is started. The configuration now contains one Reader and one Writer as shown in Figure 5-8
Note, no data flows at this point. The next stage is to connect the Reader to the Writer using a route.
Routes allow information to flow from a Reader to a Writer. The following command adds a route into the ARS Info Gateway:
ADD ROUTE FROM NCOMS_READ TO ARS_WRITER;
When this command is issued, a route is established. The Remedy ARS Info Gateway is now complete, as shown in Figure 5-9.
Cisco Info Center alerts become trouble tickets in the Remedy ARS system and the trouble ticket numbers appear in the alert's Location field in the NCOMS Cisco Info Server. When the Severity, InternalLast, StateChange, or Tally fields change in alerts on the NCOMS Cisco Info Server, those changes update the relevant trouble tickets in Remedy ARS; this type of field updating is controlled by the mapping.
The next connection to be made in this example is a connection to Sybase. The Writer for Sybase is different than the Remedy ARS Writer because instead of creating and updating a record for each alert, the Sybase Writer keeps a full transaction log in a database table.
There is no need to configure another Reader for this connection as the Cisco Info Server Reader can forward alerts to multiple Writers.
Before using a connection to a Sybase Writer, a database table must be created in the Sybase system. The process involves creating a user for Sybase and running an SQL script to create a table in a new database. Once the setup is complete, Sybase has a new table called status in a database called alerts.
In order for the Info Gateway to communicate with Sybase, you must add the Sybase server to the configuration of the servers editor (nco_xigen). The server must have a unique name and port number. See the Cisco Info Center Administrator Reference guide for more information about nco_xigen.
The next stage is to create a map for Sybase. The most important thing to note is the order of the fields to be written to in the mapping must match the order of the fields in the Sybase table. When they do not match, fields are mapped incorrectly. The following example creates a Sybase mapping:
CREATE MAPPING SYBASE_MAP('ActionTime' = ACTION_TIME,'ActionCode' = ACTION_CODE,'Identifier' = '@Identifier','Serial' = '@Serial','Node' = '@Node','NodeAlias' = '@NodeAlias','Manager' = '@Manager','Agent' = '@Agent','AlertGroup' = '@AlertGroup','AlertKey' = '@AlertKey','Severity' = '@Severity','Summary' = '@Summary','StateChange' = '@StateChange','FirstOccurrence' = '@FirstOccurrence','LastOccurrence' = '@LastOccurrence','InternalLast' = '@InternalLast','Poll' = '@Poll','Type' = '@Type','Tally' = '@Tally','Class' = '@Class','Grade' = '@Grade','Location' = '@Location','OwnerUID' = '@OwnerUID','Acknowledged' = '@Acknowledged','ServerName' = '@ServerName');
In this example, note the first difference between the Sybase and Remedy ARS Writers is Sybase uses names of fields (in single quotes) rather than integer values.
In this mapping, the first two fields do not map to fields in the Cisco Info Server but to ACTION_TIME and ACTION_CODE. These are special Info Gateway values. ACTION_TIME assigns the mapped field the date and time when a change occurred. ACTION_CODE assigns the letters I, U, and D (for insert, update, and delete) to identify the type of change that occurred.
There is no use of ON INSERT ONLY unlike in the Remedy ARS Writer. This is because the entire record is written every time to the Sybase table.
The next stage is to create a Sybase Writer. The following command creates the Sybase Writer:
START WRITER SYBASE_WRITER
(TYPE = SYBASE,
REVISION = 1,
SERVER = DARKSTAR,
MAP = SYBASE_MAP,
USERNAME = 'sa',
PASSWORD = '',
FORWARD_DELETES = TRUE);
The Writer TYPE should be set to SYBASE, with the REVISION set to 1.
The rest of the attributes for the Writer define which Sybase server to communicate with (DARKSTAR), which map to use (SYBASE_MAP), the user name to log in with (sa), and the password (a null string as there is no password in this example). The last attribute, FORWARD_DELETES, controls the forwarding of alert deletions to the Sybase table. Normally, this is set to TRUE to ensure a complete audit trail.
With a Writer created, the last stage is to add a route with the command:
ADD ROUTE FROM NCOMS_READ TO SYBASE_WRITER;
The example configuration file now contains a Remedy ARS Info Gateway and a Sybase Info Gateway, as shown in Figure 5-10
One Reader is now forwarding alerts to two separate Writers. The next stage is to connect to the other Cisco Info Server.
By connecting two Cisco Info Servers, a system can be created where different groups of network administrators can be aware of faults under the control of the other groups. In our example, it may be the Cisco Info Server DENCO is used by a support group who have their own Info Mediators connected into DENCO. By connecting the Cisco Info Servers through the Info Gateway, Cisco Info Center alerts in NCOMS are forwarded to the DENCO Cisco Info Server. DENCO operators can manipulate the alerts from NCOMS, however, the changes are not passed back to the NCOMS server.
The mapping between Cisco Info Servers is sensitive to the ordering of the fields in the mapping. The order of fields in the mapping must match the order of fields in the alerts.status table. The first thing to note is the @Serial field mapping. Instead of duplicating the value from the source Cisco Info Server, it overrides the value to 0. This is to allow the destination Cisco Info Server to re-serialize the alert because Cisco Info Servers do not share serial numbers. The following command creates an Cisco Info Server mapping:
CREATE MAPPING SERVER_MAP
('Identifier' = '@Identifier' ON INSERT ONLY,
'Serial' = 0 ON INSERT ONLY,
'Node' = '@Node' ON INSERT ONLY,
'NodeAlias' = '@NodeAlias' ON INSERT ONLY,
'Manager' = '@Manager' ON INSERT ONLY,
'Agent' = '@Agent' ON INSERT ONLY,
'AlertGroup' = '@AlertGroup' ON INSERT ONLY,
'AlertKey' = '@AlertKey' ON INSERT ONLY,
'Severity' = '@Severity',
'Summary' = '@Summary' ON INSERT ONLY,
'StateChange' = '@StateChange',
'FirstOccurrence' = '@FirstOccurrence' ON INSERT ONLY,
'LastOccurrence' = '@LastOccurrence',
'InternalLast' = '@InternalLast',
'Poll' = '@Poll' ON INSERT ONLY,
'Type' = '@Type' ON INSERT ONLY,
'Tally' = '@Tally',
'Class' = '@Class' ON INSERT ONLY,
'Grade' = '@Grade' ON INSERT ONLY,
'Location' = '@Location' ON INSERT ONLY,
'OwnerUID' = '@OwnerUID',
'Acknowledged' = '@Acknowledged',
'ServerName' = '@ServerName' ON INSERT ONLY,
'ServerSerial' = '@ServerSerial' ON INSERT ONLY);
In this example, the Info Gateway dynamically updates the Severity, StateChange, LastOccurrence, InternalLast, OwnerUID, and Acknowledged fields.
The last part of the mapping uses the two fields which were added in the setup process: ServerName and ServerSerial. The ServerName field is the name of the Cisco Info Server where the Cisco Info Center alert originated. The ServerSerial field is for the serial number of the alert on the original Cisco Info Server. This is how the system maintains serial number information between Cisco Info Servers.
The following command creates an Cisco Info Server Writer:
START WRITER OS_WRITER
(TYPE = OBJECT_SERVER,
REVISION = 1,
SERVER = DENCO,
MAP = SERVER_MAP,);
The Cisco Info Server Writer requires four parameters to be set. The TYPE parameter is set to OBJECT_SERVER to indicate it is an Cisco Info Server Writer. The REVISION parameter is currently set to 1. The SERVER parameter specifies the Writer should connect to the DENCO Cisco Info Server. The MAP parameter selects the mapping to be used.
The following command creates the route between the Cisco Info Server Reader and Cisco Info Server Writer:
ADD ROUTE FROM NCOMS_READ TO OS_WRITER;
The example configuration file now contains a Remedy ARS Info Gateway, a Sybase Info Gateway, and a unidirectional Cisco Info Server Info Gateway, as shown in Figure 5-11.
In this example, one Reader is forwarding Cisco Info Center alerts to three separate Writers.
A Writer can be connected to multiple Readers. To connect a Reader and a Writer that already exist, you add a route between them as follows:
START READER DENCO_READ CONNECT TO DENCO;
ADD ROUTE FROM DENCO_READ TO SYBASE_WRITER;
The example configuration file is now complete, as shown in Figure 5-12.
Posted: Thu Mar 18 11:28:23 PST 1999
Copyright 1989-1999©Cisco Systems Inc.
