ecsmgr

- HP OpenView Event Correlation Services engine manager

SYNOPSIS

DESCRIPTION

ecsmgr is the HP OpenView Event Correlation Services (ECS) correlation engine manager. ecsmgr can be used to alter the correlation engine's configuration when it is running.

Only the superuser can use the ecsmgr command.

Sections labelled "pmd" are only applicable when running the event correlation engine in a DM or NNM environment.

Options

The following option is used to identify the target correlation engine:

-instanceinstance

Identifies a particular engine instance when there are multiple instances on a host system.

The default for this option is -instance 1

pmd: The pmd-linked correlation engine is always instance 1.

The following option can be used to specify an event stream:

-stream sname

This option can be used with the -policy, -enable, and -disableoptions to affect the snamestream. For backward compatibility, if the -stream option is omitted, the default stream is affected.

Except for the default stream (which is automatically created at engine startup), the stream must have been previously created with the create_stream option.

The following options specify the action to perform on the target correlation engine. Only one of these options may be specified on the command line:

-auto_save_config [on|off]

When this option is turned on, the engine automatically saves all configuration changes (using ecsmgr) to the default startup configuration file (Unix: $OV_CONF/ecs/instance/config, Windows NT: %OV_CONF%\ecs\instance\config). This effectively makes the engine's configuration persistent across invocations.

This command implicitly saves the engine's configuration (to the default startup file), as the setting of this option is always made persistent.

The engine is automatically restored to the default startup configuration on startup (regardless of the setting of this option). See also -save_config and -restore_config.

-circuit_load cname file [dsname] [fsname]

Loads an ECS circuit file into the correlation engine and optionally associates a data store and fact store with it. A loaded circuit is not associated with a stream until it is enabled in a stream. The same circuit can be enabled in more than one stream.

cname must uniquely identify the ECS circuit in the target engine.

file must specify the name of a compiled ECS circuit file. See the ecsdes reference page for information about creating circuit files.

dsnamemust specify the name of a data store previously loaded with -data_load.

fsnamemust specify the name of a fact store previously loaded with -fact_load. If no data store was named, a zero (0) must be used in its place so that fsname will be interpreted as the name of the fact store.

-circuit_reload cname

Reloads ECS circuit cname with the circuit file that it was originally loaded from. Any data or fact stores associated with the circuit are not modified.

A circuit cannot be reloaded if its input or output is enabled in any stream.

-circuit_unload cname

Unloads ECS circuit cname from the correlation engine.

A circuit cannot be unloaded if its input or output is enabled in any stream.

-create_stream sname [output|discard]

Creates a new stream named sname in the correlation engine with the specified policy. If a policy is not specified, the policy defaults to output.

See policyfor more information about stream policy.

-data_dump dsname file

Saves the contents of the data store identified by dsname to file.

-data_load dsname file

Loads the data store file specified by file into the data store dsname. This command will fail if a data store named dsname already exists.

-data_unload dsname

Unloads the data store identified by dsnameunless the data store is currently being used by a circuit.

-data_update dsname file

Updates the data store identified by dsnameusing the contents of file.

-disable cname [input | output]

Disables event correlation in a stream by the loaded correlation circuit cname. This option affects the default stream unless the -stream option is also specified.

The input or output of the circuit can be disabled separately using the optional keywords input or output. If neither are specified, then both the input and output are disabled together. See enable for more information.

When the output of a circuit into a stream is disabled, the events within the circuit are flushed into that stream (subject to stream policy), but the circuit itself and the other streams are unaffected.

This option takes effect immediately

-enable cname [input | output]

Enables event correlation in a stream by the loaded correlation circuit cname. This option affects the default stream unless the -stream option is also specified (see -policy for more information about how circuits affect events in a stream). The same loaded circuit can be enabled in more than one stream.

Events will never enter the circuit more than once, regardless of how many streams in which the circuit is enabled for event input. In other words, a circuit will still receive events until its input has been disabled in every stream.

This option takes effect immediately.

-fact_dump fsname file

Saves the contents of the fact store identified by fsname to file.

-fact_load fsname file

Loads the fact store file specified by file into the fact store fsname. This command will fail if a fact store named fsnamealready exists.

-fact_unload fsname

Unloads the fact store identified by fsname unless the fact store is currently being used by a circuit.

-fact_updatefsname file

Updates the fact store identified by fsname using the contents of file.

-h

Displays the ecsmgr usage message.

-info

Returns version and status information about the correlation engine, event streams, and any loaded ECS circuits, fact stores, or data stores. This information includes:

Engine Status:

• engine environment
• engine instance
• engine version/build information time when the engine was last started engine trace mask
• engine log mask
• maximum engine log size
• maximum event log size
• input event logging

Stream Status:

• stream name
• stream policy
• stream event logging
• stream policy event logging circuits enabled in stream

Circuit Status:

• circuit identification (ECS circuit identifier name, date, version and unique id) time when the ECS circuit was last loaded circuit event logging
• circuit state (idle, input enabled, output enabled or running)
• fact store identification (name, date and version of the fact store)
• time when the fact store was last loaded data store identification (name, date and version of the data store)
• time when the data store was last loaded

-licinfo

Returns licensing and feature information about the correlation engine.

-logbitmap

Controls the level of log information generated by the correlation engine. The level is specified as a 32-bit mask.

A standalone correlation engine writes log information to ecs.log* provided the engine log mask is set.

pmd: A correlation engine linked to the HP OpenView pmd writes log information to the postmaster log file provided both the engine log mask and the pmd logging and tracing mask for the correlation engine sub-stack are set.

The bits in the correlation engine log mask have the following meanings:

DISASTERS(0x1)

Log disasters. Disasters shouldn't happen. If they do, then contact your HP representative and supply him or her with trace and log files. This will help us to improve the quality of this product. The correlation engine normally disables event correlation when a disaster occurs.

ERRORS(0x2)

Log errors. These are errors local to the operation of the correlation engine which may indicate malfunctioning of the engine or the ECS circuit.

WARNINGS(0x4)

Log warnings. These are unusual conditions that should be brought to the attention of the system administrator. These are not necessarily error conditions.

INFORM(0x8)

Log informative messages, and audit log messages.

The default setting of the correlation engine log mask is 0x7. To create a mask that is a combination of the bits that are listed above, you add the bits together which effectively ORs the bits. The result is then used as the argument to the -log option.

pmd: The default setting of the HP OpenView pmd logging and tracing mask for the correlation engine sub-stack is 0x00400007. See the pmdmgr(1M) reference page for information about postmaster tracing and logging and on setting the postmaster logging and tracing mask for sub-stacks.

See theecslogmsg(5) reference page for an explanation of the meaning of correlation engine log messages.

-log_events input [on|off]

Controls logging of events input by the correlation engine which are logged in ecsin.evt0. Annotation responses are also logged in this file.

-log_events stream [sname] [on|off]

Controls logging of events output and discarded by the specified stream. If the optional stream name is omitted, the default stream is assumed.

The output events are logged to sname_sout.evt0, and the discarded events are logged to sname_sdis.evt0 (where sname is the stream name).

-log_events policy [sname] [on|off]

Controls logging of events that no circuit in the specified stream accepted. Such events are handled by the stream's policy (see -policy). If the optional stream name is omitted, the default stream is assumed.

The output events are logged to sname_pout.evt0, and the discarded events are logged to sname_pdis.evt0 (where sname is the stream name).

-log_events circuit cname [on|off]

Controls logging of events output and discarded by the specified circuit. Annotation requests made by annotation nodes within the circuit are also logged in the circuit output log.

The output events are logged to cname_cout.evt0, and the discarded events are logged to cname_cdis.evt0 (where cname is the circuit name).

-max_log_size [engine|event] size

Sets the maximum engine or event log size to size kilobytes. Once a log file reaches this size it is rolled over by renaming it with a .evt1 extension. Any old .evt1 file is overwritten. New log entries continue to be written to the .evt0 file. Where engine is specified the engine log and trace files are affected. Where event is specified all event log files are affected. Upon startup the engine sets the parameter to a default of 512 kilobytes for both event and engine logging.

-merge_config [configfile]

Merges the contents of the named configuration file with the current engine configuration. If configfile is not specified, the contents of that engine's default configuration file are used.

If -auto_save_config is on, the result of the merge is stored in the default configuration file.

-policy [output|discard]

Sets the policy of a stream for handling events which are not correlated by a circuit. This option affects the default stream unless -stream is specified. The default stream has an initial policy of output when the engine is started.

In particular, stream policy affects events which do not enter any circuit within the stream, or enter an output-disabled circuit within the stream, or are present within a circuit when it becomes disabled in the stream. With a discard policy these events are discarded by the stream, but with an output policy these events are output by the stream.

Furthermore, this affects events which are correlated by more than one circuit in the same stream. With an output policy, events are output from the stream unless they are discarded by any circuit. With a discard policy, events are discarded by the stream unless they are output by any circuit.

Caution: Most circuits must be designed with a particular policy in mind, and running them with the wrong policy may cause unexpected output behavior. See the HP OpenView ECS Designer's Guide for details.

-remove_stream sname

Removes the stream named sname from the correlation engine. The default stream cannot be removed, and a stream cannot be removed whilst circuits are enabled within the stream.

-reset

Resets the correlation engine returning it to an uninitialized state. This removes all non-default streams, disables and unloads all currently loaded circuits, and unloads any fact stores and data stores. This option takes effect immediately.

pmd: Caution: Owing to the way dynamically linked libraries are implemented in some operating systems, using the ecsmgr -reset command causes the pmd image in memory to grow. Avoid repeated use of this command in normal operations.

-restore_config [configfile]

Restores the engine configuration from a saved file. The configuration is read from configfile if specified or from the default startup configuration file (Unix: $OV_CONF/ecs/instance/config, Windows NT: %OV_CONF%\ecs\instance\config) otherwise. This command implicitly resets the engine (see reset) first.

-save_ config [configfile]

Saves the current engine configuration to a file for later restoration. The configuration is written to configfile if specified or to the default startup configuration file (Unix: $OV_CONF/ecs/instance/config, Windows NT: %OV_CONF%\ecs\instance\config) otherwise.

The engine is automatically restored to the default startup configuration on startup. See also -restore_config and -auto_save_config.

-shutdown

Shuts down a standalone ECS engine gracefully. This command will only work on a standalone ECS engine (ecsd), and only when no circuits are enabled. To ensure that the shutdown succeeds, reset the engine prior to shutting it down.

-snapshot file

Dumps a snapshot of the correlation engine to file. The snapshot contains detailed information regarding the structure of all loaded circuits and the contents of any fact or data stores that are loaded.

-stats [verbose]

Retrieves and displays statistical information about the correlation engine, the streams and loaded circuits.

If the verboseoption is specified, additional circuit node statistics are displayed which can be helpful to a circuit designer.

-stream sname

See description of -stream at the start of this page.

-trace bitmap

Controls the level of trace information generated by the correlation engine. The level is specified as a 32-bit mask.

A standalone correlation engine writes trace information to ecs.trc* provided the engine trace mask is set.

pmd: An engine linked to the HP OpenView pmd writes trace information to the postmaster trace file provided both the engine trace mask and the pmdlogging and tracing mask for the correlation engine sub-stack are set.

Correlation engine trace output provides very detailed information about the loading and operation of ECS circuits. The bits in the engine trace mask have the following meanings:

• EVENTTRANSFER(0x1)
• EVENTDISCARD(0x2)
• EVENTCREATE(0x4)
• DEBUGGER(0x8)
• CREATEDELETE(0x10)
• INITIALIZE(0x20)
• ENTRYEXIT(0x40)
• LOOKUP(0x80)
• MEMORY(0x100)
• PROCESSINGINFO(0x200)
• CIRCUITLOAD(0x400)
• INVARIANTFAIL(0x800)
• INTERP(0x1000)
• INTERP_DETAIL(0x2000)
• EVENTDELETE(0x4000)
• MANAGEMENT(0x8000)
• SYSTEMTRACE(0x10000)

The default setting of the correlation engine trace mask is 0x0. To create a mask that is a combination of the bits that are listed above, you add the bits together which effectively ORs the bits. The result is then used as the argument to the -trace option.

pmd: The default setting of the HP OpenView pmd logging and tracing mask for the correlation engine sub-stack is 0x00400007. See the pmdmgr(1M) reference page for information about postmaster tracing and logging and on setting the postmaster logging and tracing mask for sub-stacks.

-updatecname file

Updates any fact store or data store associated with the ECS circuitcnamewith the fact store or data store updates in file. The update file can contain updates for the fact store or the data store, or both.

RETURN VALUES

ecsmgr returns one of the following values:

0 Success

1 Invalid ecsmgr option

2 Requested operation failed

3 Parsing of the ecsmgr command failed

4 API failure

5 Cannot execute ecsmgr - must be superuser

130 Interrupt received

EXAMPLES

Examples of howecsmgrcan be used:

To enable event correlation in the circuit named circuitname:

ecsmgr -enable circuitname

To set the logging level to DISASTERS and ERRORS messages only:

ecsmgr -log 0x3

DIAGNOSTICS

ecsmgr outputs a diagnostic message if a command fails. Further diagnostic information can be found in the correlation engine log and trace files.

FILES

The environment variables below represent universal pathnames that are established according to your shell and platform requirements. See the ovenvvars(1) reference page for information on universal pathnames for your platform and shell. For Windows NT platforms, substitute the environment variables in Windows NT format. For example, substitute $OV_LOG with %OV_LOG%.

$OV_CONF/ecs/instance/config

The default startup configuration file for engine instance instancethat is restored by the engine on startup.

$OV_LOG/ecs/instance/ecsd.log*

Engine log output file for standalone engine instance instance.

pmd: Engine log output is written to the HP OpenView postmaster log file ($OV_LOG/pmd.log*)

$OV_LOG/ecs/instance/ecsd.trc*

Engine trace output file for standalone engine instance instance.

pmd: Engine trace output is written to the HP OpenView postmaster trace file ($OV_LOG/pmd.trc*)

$OV_LOG/ecs/instance/ecsd.stderr

Standard Error output for the correlation engine with the corresponding instance number. This is only applicable if the correlation engine is running as a daemon.

$OV_LOG/ecs/instance/ecsin.evt*

Input event log file for engine instance instance.

$OV_LOG/ecs/instance/sname_sout.evt*

Output event log file for the stream sname in engine instance instance.

$OV_LOG/ecs/instance/sname_sdis.evt*

Discard event log file for the stream sname in engine instance instance.

$OV_LOG/ecs/instance/cname_cout.evt*

Output event log file for the circuit cname in engine instance instance.

$OV_LOG/ecs/instance/cname_cdis.evt*

Discard event log file for the circuit cname in engine instance instance.

$OV_LOG/ecs/instance/sname_pout.evt*

Output event log file for events not accepted by any circuit in the stream sname in engine instance instance.

$OV_LOG/ecs/instance/sname_pdis.evt*

Discard event log file for events not accepted by any circuit in the stream sname in engine instance instance.

AUTHOR

ecsmgrwas developed by Hewlett-Packard.

SEE ALSO

ecsdes

ecsd

ecslogmsg(5), ovstart(1M),ovstop(1M),ovstatus(1M),pmdmgr(1M)