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
  • Storing overrides in multiple files
  • External override file location and privileges
  • External override file names
  • Defining which override files to use
  • Using macro variables in override files
  • External override file poll cycle
  • External override file format
  • Deleting the external override file
  • Additional functions

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.

1. 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.

2. 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.

1. Define the /AgentSetup/ExternalOverride variable as follows: 
   
   /AgentSetup/ExternalOverride = <mydir>, where mydir is the relative path to the <PATROL_HOME>/lib/admin directory.
2. Define the /AgentSetup/ExternalOverridePolltime variable as follows: 
   
   /AgentSetup/ExternalOverridePolltime = <n>, where n specifies how often the PATROL Agent checks the external file for changes.

3. 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.

4. 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.

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.

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");

External override file poll cycle

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

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.

 External file example

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.