IBM Tivoli Monitoring > Version 6.3 Fix Pack 2 > Administrator's Guide > Agent-based services > Centralized Configuration

IBM Tivoli Monitoring, Version 6.3 Fix Pack 2

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:

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

XML element tags and their attributes are not case-sensitive, but values are case-sensitive. For example, you can enter <CONFIGSERVER>, <ConfigServer>, or <configserver>.

<ConfigurationArtifact>

ConfigurationArtifact is the root element that identifies this XML file 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="@PRODUCT@_eventdest.xml"
      Path="DataStore/@PRODUCT@"
      Disp="EIFCNFG"
      Activate="YES" />
    <ConfigFile
      Server="AGOURALAB"
      Name="@PRODUCT@_eventmap.xml"
      Path="DataStore/@PRODUCT@"
      Disp="EIFMAP"
      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.

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 Disp=TRAPCNFG type requires the agent to restart in order to read the updated configuration files. RESTART is also available for Disp=CUSTOM.

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 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 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 events at the monitoring agent are 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

Specify "YES" instructs the agent to download and replace the existing configuration file. New changes are implemented dynamically without agent restart. This option is valid only for the following DISP values: CNFGLIST, PVTSIT, EIFCNFG and EIFMAP.

Specify YES does not automatically cause the EIF emitter to start or recycle. The EIF configuration file must be physically downloaded from the Centralized Configuration server to the agent in order to trigger file activation.

If you are using private situations and use Activate="YES", then specifying REFRESH="N" in your private situation configuration file instructs the agent to merge the downloaded file into the current file and then activate the file. If you specify REFRESH="Y" in your private situation configuration file, the agent replaces the local file with the downloaded file and then activate the file.


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 Available Available Default
EIFMAP Available 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.


Parent topic:

Centralized Configuration

+

Search Tips   |   Advanced Search