Novell is now a part of OpenText

Collector Development Guide

COLLECTOR PARAMETERS

Sentinel Collector plug-ins can include configuration-time parameters that control the run-time operation of those Collectors. The parameter system is designed to be modular and re-usable, and you will find that there are quite a few template parameters that you can use as you wish, or you can create your own.

You might use or create parameters, for example, to:

  • Allow implementors to select which version of a product they are integrating with, if it cannot be auto-detected based on the event stream.
  • Allow implementors to tune the size of database queries for their particular environment and database/Sentinel loads.
  • Allow implementors to specify certain properties about how their particular source products are configured, if the source offers several common options.
  • Allow implementors to control error reporting behavior of the Collector itself.
  • Allow implementors to specify whether certain optional fields are filled in or not, such as the legacy taxonomy fields, IP to hostname conversions, etc.

Adding Parameters to a Collector

Parameters are included with a given Collector in a very simple way; by listing them in a file. There are two different types of parameters — those provided with the template, and those created custom for each Collector — and hence there are two relevant files under the individual Collector's parameters directory:

template.pml
This file allows the developer to list the parameters to be included from the template. Template parameters are stored in //current/sdk/2011.1/Collector/static/parameters as individual files; review those files to see what parameters you can use from the template.
release.pml
This file lists the parameters that are locally defined for this particular release of the Collector. These parameters are also implemented as individual files, each of which is included in the same parameters directory where release.pml is located.

The format of the PML files is very simple; each parameter to be included is listed on its own line. The parameter name is just the filename of the file that contains the parameter, with no extension. So for example to include the parameters defined in missing_year.xml and max_rows.xml, you would add two lines to template.pml:

missing_year
max_rows

Using Parameters In Your Code

Parameters are configured at deployment time of the Collector by the person implementing that particular integration. The values set at that time for each parameter are then automatically loaded into memory in JavaScript so that you can access them from your code. Parameters are loaded into a global area of the instance object, which represents the running Collector. The template will create a hash table called params under the global CONFIG area, with the name of each hash element the name of the parameter and the value whatever value was configured for that parameter. Note however that the parameter name here is the InternalName defined in the parameter XML file, not the filename as specified in the PML file. For example, if an implementor sets the max_rows parameter to 200000, then you will have:

instance.CONFIG.params.Max_Rows_To_Return == 200000

(review the contents of //current/sdk/2011.1/Collector/static/parameters and see the InternalName element to find the name of the parameter).

Most parameters are simply specified as strings, whether they are typed in by the implementor or they are part of an enumerated selectable list. Boolean parameters, however, will show up as true Booleans in JavaScript, so they can be tested directly for truth/falsehood. Here's an example directly from the Event.send() method:

if (instance.CONFIG.params.Resolve_IP_and_Hostname) {
    // perform resolution
}

Defining Custom Parameters

The process of defining custom parameters is as simple as creating a small XML file that describes the parameter and possible values. An example called sample.xml is provided for you in the default Collector template, which is safe to delete if you are not planning to use it. You can copy that file and edit it to suit your needs, then all you have to do is add your new filename (without extension) to the release.pml file to include your custom parameter with the Collector. An example of where this happens commonly is also included, the query_variant_sample.xml file; in several cases we've found it necessary to give the implementor a way to choose between several alternate query variants, depending on the version or configuration of their source database. But we can't make this parameter a true template parameter, because the enumerated list of options will vary depending on the source product.

You may be able to figure out how to create your parameter simply by examining the samples, but the format of the parameters file is fully documented on a separate page — the format is used for several different plug-in types, including Actions and Reports.

Internal Parameters

In Collectors, parameters are stored in the global instance.CONFIG.params area, which is pre-loaded with the user-settable parameters from the UI. But we also use this area to store several "internal" parameters, set by the developer or automatically set, which are then used to control various aspects of Collector operations (typically, these trigger some automatic processing by the Collector template).

These parameters roughly break down into the following categories:

  • Parameters that are automatically set by internal code and control how the Collector behaves. Examples include auto-detecting the platform to determine what fields should be present in the output event, and turning on/off "user privilege level" lookups if the associated map file is present.
  • Pre-defined parameters that should be set by the developer based on the behavior of the specific product being integrated with. Examples include a parameter that specifies whether the source uses UTC, or whether it uses case-sensitive usernames. These parameters are defaulted in the release.js file with the assumption that the developer will review them and modify as necessary.
  • Parameter that are defined by the developer as a convenient way to consistently control Collector behavior. Use of these would be entirely up to the developer.

Here are the pre-defined internal parameters in release.js, all of which are members of instance.CONFIG.params:

usernameIsCaseSensitive
This parameter specifies that the event source treats usernames (and the domains/containers in which those usernames live) as case-sensitive, i.e. the user Test1 is different than the user test1. Sentinel defaults to treating all names as case-sensitive, so if the source system is not we have to do special processing (the names are universally lowercased) to ensure that correlation can properly match across events.
datanameIsCaseSensitive
This parameter specifies that the event source treats data object names (files, paths, etc) as case-sensitive, i.e. the file FILE.TXT is different than the file file.txt. Sentinel defaults to treating all names as case-sensitive, so if the source system is not we have to do special processing (the names are universally lowercased) to ensure that correlation can properly match across events.
hostnameIsCaseSensitive
This parameter specifies that the event source treats hostnames (and the domains in which those hosts live) as case-sensitive, i.e. the host myHOST is different than the user MYhost. Sentinel assumes that all hostnames are NOT case-sensitive, since that's the DNS standard, but you can override that default behavior by setting this parameter to true.
reportsUTC
This parameter specifies that the event source reports a UTC timestamp in its events. Sentinel stores all timestamps as UTC, so this inhibits timezone conversion for this source. Whether or not the source reports UTC, if it actually resides in a timezone other than UTC the source must either include timezone information in the event, or the customer must manually specify a timezone for the Event Source node in Event Source Manager. In either case that information will be used to calculate the "local time" ObserverTZ fields.

And here are the internal parameters that are used by the template, which should be set automatically without the developer needing to do anything:

schemaVersion
The template will autodetect the platform version and hence the version of the Event schema that it expects to receive. This will change the behavior of the Event.send() method to ensure that the output Event meets the requirements of the platform.
lookupPriv
This parameter controls whether the privilege level of users is looked up when events are sent. It is automatically set based on the contents of the privlevel.map file.
privDomain
If true, this parameter sets the privilege lookup to ignore user domains/containers when looking up privilege level; if you wish, you can override this in your initialize()
lookupSens
This parameter controls whether the sensitivity level of a given data object is looked up when events are sent. It is automatically set based on the contents of the datasensitivity.map file.
sensContainer
If true, this parameter sets the data sensitivity lookup to ignore namespace/container when looking up sensitivity; if you wish, you can override this in your initialize()

Collector Development Guide

Development Topics

© Copyright Micro Focus or one of its affiliates