Using external override files to manage parameter overrides

Using external files is the recommended method for managing parameter overrides. In this method, parameter overrides are stored in one or more external files. The PATROL Agent periodically checks if an external override file has changed or if a different external override file must be used. If a file or its contents change, the PATROL Agent implements the new overrides.

You can store your override definitions in a single file or in multiple files in the same directory. The following sections explain the procedures and uses for each method.

Storing overrides in a single file

When you store override definitions in a single file, the PATROL Agent periodically checks the time stamp of the file to see if it has been updated. If the file has been updated, the agent implements the new parameter override definitions contained in the file. The following procedure outlines the steps you must perform to store your override definitions in a single file. More details about each step are documented in the rest of this section.

Define the /AgentSetup/ExternalOverride variable as follows:

/AgentSetup/ExternalOverride = <myfile>, where myfile is the name of the override file you want to use. This file is not required to have an extension.
Create myfile with the override definitions you want to use. The file name must be the same file name you define in /AgentSetup/ExternalOverride.

The following example file, myfile, defines overrides for the LDldDiskTimePercent parameter of the NT_LOGICAL_DISKS application class and the PAWorkRateExecsMin parameter of the PATROL_NT application class.
```
myfile
[/NT_LOGICAL_DISKS//LDldDiskTimePercent]
ACTIVE=1
BORDER_ACTIVE=0
ALARM1_ACTIVE=0
ALARM2_ACTIVE=0

[/PATROL_NT/PATROL_NT/PAWorkRateExecsMin]
ACTIVE=1
BORDER_ACTIVE=0
ALARM1_ACTIVE=0
ALARM2_ACTIVE=0
```
Anytime you create or update this file, the PATROL Agent applies the new overrides to the parameters.

For more information about creating the content of override files, see the External override file format section below.

Storing overrides in multiple files

When you store override definitions in multiple files, the PATROL Agent checks the directory containing the files for updated definitions. If the files contain new definitions, the agent implements them. The following procedure outlines the steps you must perform to store your override definitions in multiple files. More details about each step are documented in the rest of this section.

Define the /AgentSetup/ExternalOverride variable as follows:

/AgentSetup/ExternalOverride = <mydir>, where mydir is the relative path to the <PATROL_HOME>/lib/admin directory.
Define the /AgentSetup/ExternalOverridePolltime variable as follows:

/AgentSetup/ExternalOverridePolltime = <n>, where n specifies how often the PATROL Agent checks the external file for changes.
Create the files with the override definitions you want to use. When using multiple files, each file can only define overrides for a single application class. The file name of each file must exactly match the name of the application class for which it defines overrides.

The following example shows two separate override files, NT_LOGICAL_DISKS and PATROL_NT. Each file is named after the application class for which it defines parameter overrides. When the /AgentSetup/ExternalOverridevariable is defined as the relative path to the override file directory, the PATROL Agent reads all files in the directory and applies the overrides as defined in each file.
```
NT_LOGICAL_DISKS
[/NT_LOGICAL_DISKS//LDldDiskTimePercent]
ACTIVE=1
BORDER_ACTIVE=0
ALARM1_ACTIVE=0
ALARM2_ACTIVE=0

PATROL_NT
[/PATROL_NT/PATROL_NT/PAWorkRateExecsMin]
ACTIVE=1
BORDER_ACTIVE=0
ALARM1_ACTIVE=0
ALARM2_ACTIVE=0
```
For details about creating the content of override files, see External override file format.
Create the @timestamp file.

The PATROL Agent checks for a file called @timestamp (without a file extension) every n seconds in the path defined by /AgentSetup/ExternalOverride. The n seconds is based on the value specified for /AgentSetup/ExternalOverridePolltime.

The agent does not read the file, it only checks its time stamp. You must create the @timestamp file manually.

If the @timestamp file has a different time stamp as before or does not exist, the PATROL Agent reads all files in the directory which have changed.

External override file location and privileges

All external override files must be located in the PATROL_HOME/lib/admin directory (UNIX) or PATROL_HOME\lib\admin folder (Windows). This directory can be read-only.

The PATROL Agent does not write to external override files and it reads them with the PATROL_ADMIN user. Therefore, the external override files can be read-only and owned by the PATROL_ADMIN user.

Note

You must manually create external override files.

External override file names

The file naming conventions for override files vary depending on whether you use a single file or multiple files. File names must not have extensions.

Single file method

If you are storing your override definitions in a single file, you can use any file name you want; however, you must make sure it matches the file name you define in the The /AgentSetup/ExternalOverride configuration variable.

Multiple file method

If you store your override definitions in multiple files, each file can specify overrides only for a single application class. Each override file file name must exactly match the name of the application class that it defines overrides for.

If a file contains a definition for an application class that is different from the file name, the PATROL Agent ignores the definition. For example, a file named CPU can only contain definitions for the CPU application class. If it contains definitions for other application classes, the definitions are ignored. Additionally, if a file is removed, then the definition for the application class is removed.

Defining which override files to use

The /AgentSetup/ExternalOverride configuration variable determines which file(s) to use.

Format and type of data	Text string indicating a file name. The string can contain macro variables.
Default value	(empty string = no file)
Minimum and maximum	Not applicable
Dependencies	/AgentSetup/ExternalOverridePolltime specifies how often the file is checked for changes.
Recommendations	Use macro variables to specify different names for different situations and name the external override files accordingly.

Using macro variables in override files

You can specify different files for different situations by using macro variables. However, if the macro variable does not exist by default, you must give it a value using the PSL set() command.

In the following example, the value for %{hostname} exists by default since it is a built-in value populated by the PATROL Agent. However, %{timeofday} does not exist by default, so you must set the variable using either of the following commands:

set("/timeofday", "day"); or set("/timeofday", "night");

Example

To use different files during the day and night, you must use a macro variable and use it in the configuration variable.

/AgentSetup/ExternalOverride = "%{hostname}_%{timeofday}

If /timeofday is set to "day", the PATROL Agent uses the file PATROL_HOME/lib/admin/myhost_day

If /timeofday is set to "night", the PATROL Agent uses the file PATROL_HOME/lib/admin/myhost_night

External override file poll cycle

The /AgentSetup/ExternalOverridePolltime configuration variable determines how often the PATROL Agent checks the external file for changes.

Format and type of data	Integer, seconds 0 — external file polling is disabled 60+ — the polling cycle in seconds
Default value	0
Minimum and maximum	0 or 60+, no maximum
Dependencies	/AgentSetup/ExternalOverride specifies which file is checked for changes.
Recommendations	None

To manually check whether the file has changed, use the %OVERRIDE CHECK command.

External override file format

The file format is the standard ini file format. The name of a section identifies the parameter to be overridden. The attributes for a section indicate the properties and values to be used. All lines starting with a # are treated as comments and ignored.

Sections

The name of each section identifies the parameter to be overridden. To override a parameter for a specific application instance, use the following format for the section name:

[/APPLICATION/INSTANCE_SID/PARAMETER]

To override a parameter for all instances of an application class, leave the INSTANCE_SID blank:

[/APPLICATION/ /PARAMETER]

Attributes

The attribute and value pairs for each section identify the new values to be used. The following table lists the available attribute and value pairs.

Attribute and value pairs

Attribute	Description
ACTIVE	Boolean. This attribute defines whether the parameter is active or not.
INTERVAL	Integer. This integer attribute defines the number of seconds for the polling interval. This attribute does not apply to consumer parameters.
BORDER_ACTIVE ALARM1_ACTIVE ALARM2_ACTIVE	Boolean. These attributes define whether the alarm ranges are active or not for the border, alarm1, and alarm2 ranges.
BORDER_MINIMUM ALARM1_MINIMUM ALARM2_MINIMUM	Integer. These attributes define the minimum values for the border, alarm1, and alarm2 ranges.
BORDER_MAXIMUM ALARM1_MAXIMUM ALARM2_MAXIMUM	Integer. These attributes define the maximum values for the border, alarm1, and alarm2 ranges.
BORDER_STATE ALARM1_STATE ALARM2_STATE	Constant. These attributes define the state for the border, alarm1, and alarm2 ranges. Possible values are OK, WARN, WARNING, and ALARM.
BORDER_ALARM_WHEN ALARM1_ALARM_WHEN ALARM2_ALARM_WHEN	Constant. These attributes define when the alarms occur for the border, alarm1, and alarm2 ranges. Possible values are ALARM_INSTANT, ALARM_AFTER_N, and ALARM_AFTER_RECOVERY.
BORDER_ALARM_WHEN_N ALARM1_ALARM_WHEN_N ALARM2_ALARM_WHEN_N	Integer. These attributes define the number of consecutive times the parameter must have a value within the range before the alarm occurs. This attribute is only ALARM_AFTER_N is used.
BORDER_DO_RECOVERY ALARM1_DO_RECOVERY ALARM2_DO_RECOVERY	Boolean. These attributes define whether the recovery action is run or not.

External file example

# The values are chosen for demo purposes only
# Do not use these in a production environment !

# Override all instances of LDldDiskTimePercent
[/NT_LOGICAL_DISKS//LDldDiskTimePercent]

ACTIVE=1
BORDER_ACTIVE=1
BORDER_MINIMUM=10
BORDER_MAXIMUM=90
BORDER_STATE=ALARM
BORDER_ALARM_WHEN=ALARM_INSTANT
ALARM1_ACTIVE=1
ALARM1_MINIMUM=50
ALARM1_MAXIMUM=70
ALARM1_STATE=WARN
ALARM1_ALARM_WHEN=ALARM_AFTER_N
ALARM1_ALARM_WHEN_N=2
ALARM2_ACTIVE=1
ALARM2_MINIMUM=70
ALARM2_MAXIMUM=90
ALARM2_STATE=ALARM
ALARM2_ALARM_WHEN=ALARM_INSTANT
ALARM2_DO_RECOVERY=NO


# Override PAWorkRateExecsMin for only the
# PATROL_NT application instances

[/PATROL_NT/PATROL_NT/PAWorkRateExecsMin]
ACTIVE=1
BORDER_ACTIVE=1
BORDER_MINIMUM=0
BORDER_MAXIMUM=100
BORDER_STATE=ALARM
BORDER_ALARM_WHEN=ALARM_INSTANT
ALARM1_ACTIVE=1
ALARM1_MINIMUM=30
ALARM1_MAXIMUM=60
ALARM1_STATE=WARN
ALARM1_ALARM_WHEN=ALARM_AFTER_N
ALARM1_ALARM_WHEN_N=2
ALARM2_ACTIVE=1
ALARM2_MINIMUM=60
ALARM2_MAXIMUM=100
ALARM2_STATE=ALARM
ALARM2_ALARM_WHEN=ALARM_INSTANT

Deleting the external override file

If the PATROL Agent cannot locate the external override file because it is moved or deleted, the PATROL Agent considers the file unchanged. This makes it easy for you to implement a software distribution mechanism that moves the existing external override file to a backup location before copying over the new external override file.

To clear all overrides from an external override file, you must delete the contents of the file and leave the blank file in place until the next polling cycle.

Additional functions

The PATROL Agent also includes the following commands that you can use with external override files:

%OVERRIDE DUMP
%OVERRIDE REAPPLY
%OVERRIDE CHECK

%OVERRIDE DUMP

This command outputs the following information:

The information in the external file
The polling interval
The name of the current external override file

%OVERRIDE REAPPLY

This command reapplies all of the settings in the external override file. This command is only useful when PSL function overrides are also used. When this command is run, all overrides in the external override file are applied, replacing any corresponding overrides created by the PSL function.

%OVERRIDE CHECK

This command checks if the external file has changed.