Configuration load list XML specification

Use the XML syntax from the configuration load list XML specification to create a load list for Centralized Configuration.

Default configuration load list path and file name

The following configuration load list file names are the defaults, where pc is the two-character product code:

Install_dir\localconfig\pc\pc_cnfglist.xml
Install_dir/localconfig/pc/pc_cnfglist.xml
IRA_SERVICE_INTERFACE_CONFIG_LOADLIST=PCCFGLST.RKANDATV
/QIBM/UserData/IBM/ITM/localconfig/a4/a4_cnfglist.xml

Use the IRA_SERVICE_INTERFACE_CONFIG_LOADLIST agent environment variable to change the default path and file name. See Environment variables for Centralized Configuration.

Elements

The elements and their attributes are case-insensitive. For example, you can enter <CONFIGSERVER>, <ConfigServer>, or <configserver>.

<ConfigurationArtifact> </ConfigurationArtifact>

ConfigurationArtifact is the root element identifying this as a load list configuration document. Enter <ConfigurationArtifact> at the beginning of the file and </ConfigurationArtifact> at the end. Example of a load list file:

<ConfigurationArtifact>
	<ConfigServer 
    Name="AGOURALAB" 
    URL="http://9.55.100.99/" 
    User="smith" 
    Password="{AES256:keyfile:a}hjZM0YaLzpd5JQC5DeboJg==" />
	<ConfigFile   
    Server="AGOURALAB" 
    Name="Private_Situations.xml"	 
    Path="ITM/Config/@HOSTNAME@" 
    Disp="PVTSIT" 
    Activate="YES" /> 
	<ConfigFile
    Server="AGOURALAB"	
    Name="TRAPCNFG.xml"
 	  Path="ITM/Config/common"
    Disp="trapcnfg"
    Activate="RESTART" />
  <ConfigFile
    Server="AGOURALAB"	
		Name="THRESHOLDS.XML"
    Path="ITM/Config/@PRODUCT@"
    Disp="threshold"
    Activate="YES" /> 
</ConfigurationArtifact>

<ConfigServer>

Define a central configuration server with the following attributes:

Name=

Defines a symbolic name of a SERVER statement. The name can be up to 32 characters and must be unique in the load list. Duplicate names are not permitted.

URL=

Defines the URL used to connect to the central configuration server, which can be either of the following types:

An Agent Service Interface acting as a central configuration server and specified as:
```
HTTP-method://Hostname:port
///agent-ServicePoint/agent-ServicePoint
```
A web server acting as a central configuration server and specified as:
```
HTTP-method://Hostname:[port]
/[path]
```

where:

HTTP-method: is http or https
Hostname: is the central configuration server host name. Use the IP address if the Hostname is not guaranteed to be resolved by local DNS.
port: is the target central configuration server listening port of the Tivoli Monitoring Service Index (KDH component code) or of the web server if the port is different than the default 80. The Tivoli Monitoring Service Index default port is 1920 for HTTP or 3661 for HTTPS, either of which can be customized with the KDC_FAMILIES environment variable in the target agent.
agent-ServicePoint: is the TMS/Engine-registered Agent Service Interface name, such as system.myhost_nt for the Windows OS agent and myhost_lz for the Linux OS agent. You can customize the service name of the target agent to a more functionally recognized name using the IRA_SERVICE_INTERFACE_NAME agent environment variable. For example, https://9.48.123.13:3661///Paris-CSF-A/Paris -CSF-A. Omit the agent-instance-name definition if you are using a generic web server configuration repository.
Path: is an additional target central configuration server path definition. For example, http://9.48.132.40:80/ITM/config.

User=

Optional. Specifies the target central configuration server server host system account user ID.

Password=

Optional. Specify user password in plain text or use the itmpwdsnmp utility program to encrypt user password and specify the output AES data string here. See SNMP PassKey encryption: itmpwdsnmp.

AltServer=

Optional. Specifies an alternate server name. The agent constructs the file request URL using the alternate server definition when it cannot contact or log on to this server. The alternate server definition cannot include an additional alternate server specification.

The following HTTP status codes cause the agent to retry the request using the AltServer specification:

401: Unauthorized
403: Forbidden
404: Object not found
500: Internal server error
503: Service unavailable

If you are using the AltServer attribute to specify an alternate central configuration server, be sure to define the alternate <ConfigServer> before the <ConfigServer> definition that references it. Example:

<ConfigServer
 Name="CENTRAL-CONFIG-ALTERNATE"
 URL="http://lnxhostB:1920///lnxhostB_lz/lnxhostB_lz"
 User="itmconfig"
 Password="{AES256:keyfile:a}vHBiEqmmvylNPs90DhQ==" />
<ConfigServer
 Name="CENTRAL-CONFIG-REPOSITORY"
 URL="http://lnxhostA:1920///lnxhostA_lz/lnxhostA_lz"
 User="itmconfig"
 Password="{AES256:keyfile:a}hjZM0YaLzpd5JQC5DJg=="
 AltServer=”CENTRAL-CONFIG-ALTERNATE” />

See also the example in "Environment variables in the configuration load list."

<ConfigFile>

Identifies a previously defined <ConfigServer> by name. The agent sends the request to this Server for downloading this particular file.

You can reference environment variables when defining <ConfigFile> element attributes. Where the variables are resolved depends the type of central configuration server:

When connection is to a monitoring agent acting as the central configuration server, environment variables used to define ConfigFile, Name, and Path attributes are resolved at the server.
When connection is to a web server acting as the central configuration server, all environment variables are resolved at the client.

Server=

Identifies a previously defined <ConfigServer> by name. The agent sends the request to this Server for downloading this particular file.

Name=

Specifies the file name at the server location. The name can include environment variables if they can be recognized and resolved by the agent.

Path=

Specifies the file location path on the target <ConfigServer>. The path can include environment variables that are resolved at the server when connecting to a central configuration server. The variables are resolved at the central configuration client when the connection is to a web server.

Path is relative from the HTTP root of the configuration server. When using a monitoring agent as the configuration server, the Install_dir/localconfig directory is the HTTP root. The configuration file anchor can be overridden by the IRA_SERVICE_INTERFACE_CONFIG_HOME environment variable.

Disp=

Optional. Specifies the local disposition of known agent configuration files. When the DISP attribute is specified, the agent places the downloaded ConfigFile (or ConfigFiles) in the correct location on the central configuration client system based on the environment settings of the client agent. The DISP attribute also enables activation options that are appropriate for each ConfigFile. The agent knows the local location and name of these agent configuration files and, upon downloading them, saves them according to the agent specification.

If the Disp attribute is omitted, CUSTOM is used by default. The placement of a file when using Disp=CUSTOM is restricted to locations within the Tivoli Monitoring Install_dir. This restriction is in place to enhance security. Other Disp file types are placed wherever the monitoring agent expects the file to be, even if the specified location is outside the Install_dir directory structure. If you specify Disp=CUSTOM, it is helpful to use the @ITMHOME@ keyword to specify the LocalPath.

The following disposition values are currently defined:

CNFGLIST: Configuration load list file.
PVTSIT: Private Situation configuration XML file
TRAPCNFG: Agent SNMP trap configuration XML file
THRESHOLD: Situation threshold override configuration XML file.
EIFCNFG: EIF configuration file
EIFMAP: EIF event mapping file.
UAMETA: Universal Agent application Meta files.
PASCAP: Proxy Agent Service (Agent Management Services) common agent package (CAP) file. The PASCAP Disp can be used only on a Tivoli Monitoring OS Agent that supports Agent Management Services. It downloads and activates the CAP file if the product is installed. Options=NOPRODUCTCHECK can be used to force the placement of the CAP file even if the product that the CAP file manages is not installed. (See Tivoli Agent Management Services installation and configuration.)
AAGP: Access Authorization Group Profile, which contains access authorization group definitions and user ID access authorization group assignments that were defined by the security administrator. (See Access Authorization Group Profile.)
CUSTOM: CUSTOM is the default value used if DISP is omitted. The LocalName and LocalPath attributes should be specified for DISP=CUSTOM. CUSTOM files can be downloaded only to a location within the agent's installation directory structure.

Options=

Specifies the configuration file handling option:

NOPRODUCTCHECK: Valid only with DISP=PASCAP. Bypass product installation requirement before the CAP file download operation. Currently this is the only option value defined.

LocalName=

Specifies the local system file name. LocalName is used only if DISP is omitted or is set to CUSTOM. If LocalName is omitted when Disp=CUSTOM, the NAME attribute is used. LocalName is ignored for all other Disp values because the agent identifies the location of the file using default values or override parameters.

LocalPath=

Specifies the local system file path. LocalPath is used only if DISP is omitted or is set to CUSTOM. If LocalPATH is omitted when Disp=CUSTOM, the PATH attribute is used. LocalPath is ignored for all other Disp values because the agent identifies the location of the file using default values or override parameters.

Activate=

NO

Replace current file with downloaded copy, but do not activate. The downloaded file must be newer than the existing configuration file. This is the default value.

RESTART

Restart the agent after a successful file download.

The following Disp types require the agent to restart in order to read the updated configuration files:

TRAPCNFG
EIFCNFG
EIFMAP

RESTART can be used with PVTSIT to force a replacement of the private situation definition rather than merging the definition with currently active situations.

RESTART is also available for Disp="CUSTOM".

RESTART is not supported on z/OS or i5. The agent process must be restarted in another manner to activate the new configuration.

Agent Management Services
The RESTART code uses Agent Management Services to recycle the agent:

The agent must be under the management of the Agent Management Services. This is accomplished by specifying <managerType>ProxyAgentServices</managerType> in the agent's common agent package (CAP) file or by using the AMS Start Management take action command
The OS agent must be running on the system so that the agent watchdog is available to recycle the agent.

Expect the following results if the agent is not under the management of the Agent Management Services or the OS agent is not running when the ConfigFile is retrieved from the central configuration server:

The agent writes a message to the log file that the restart is bypassed.
If SNMP or EIF eventing from the monitoring agent is enabled, an autonomous lifecycle status event is generated.
The file is activated the next time the agent is restarted.

By default, Agent Management Services is enabled for all OS agents except the zLinux OS agent, which is disabled. The Agent Management Services watchdog for the zLinux OS agent must be enabled manually to take advantage of RESTART capability. Otherwise, the zLinux OS agent must be restarted in another manner to activate the new configuration.

See Agent Management Services for details on using Agent Management Services to monitor the availability of agents.

YES

Instructs the agent to merge the downloaded file into the current file. New changes take affect dynamically without agent restart. This option is valid only for the following DISP values: CNFGLIST, PVTSIT, threshold, and THRESH.

Table 1. Configuration load list <ConfigFile> element and the Activate options available for the Disp type.
Disp=	Activate="Yes"	Activate="Restart"	Activate="NO"
CNFGLIST	Default	N/A	N/A
PVTSIT	Available	Available	Default
TRAPCNFG	N/A	Available	Default
EIFCNFG	N/A	Available	Default
EIFMAP	N/A	Available	Default
THRESHOLD	Available	Available	Default
UAMETA	N/A	Available	Default
PASCAP	CAP files are activated on download, therefore the Activate attribute does not apply.
AAGP	Default	N/A	N/A
CUSTOM	N/A	Available	Default

<ConfigParm>

Optional. Specifies an agent environment variable override value that updates the environment settings immediately and takes effect at the next operation interval or instance.

Interval=: Override or set IRA_SERVICE_INTERFACE_CONFIG_INTERVAL.
Backup=: Override or set IRA_SERVICE_INTERFACE_CONFIG_BACKUP.
NumbTasks=: Override or set IRA_SERVICE_INTERFACE_CONFIG_POOL_SIZE.
MaxWait=: Override or set IRA_SERVICE_INTERFACE_CONFIG_MAX_WAIT.