Using CFGARGAGT

Prior to using the Argent Agent for iSeries, it must be configured. To do this customers use the CFGARGAGT command. The CFGARGAGT command simply gathers and stores some of your preferences about how the Argent Agent should operate on the system.

While CFGARGAGT has many variables, simply entering CFGARGAGT by itself will configure the agent using the default settings. For most installations, this will be sufficient. Customers wishing to adjust the agent settings should refer to the following sections.

Using CFGARGAGT During Installation

While CFGARGAGT has many parameters, issuing the

CFGARGAGT

command by itself will configure the agent using the default settings. For most installations, this will be sufficient. Customers wishing to adjust the agent settings after getting started should refer to the following sections.

CFGARGAGT Command Syntax

The CFGARGAGT command has the following syntax:

CFGARGAGT PORT(nnnnn) LOGLVL(log level) LOGSIZ(log file size) JOBD(job description name library/name) MSGQ(message queue library/name) ALWIPADDR(list of allowed IP addresses) ALWHOSTS(list of allowed Argent monitoring engine host names) CACHEITV(cache expiration interval) CMDDFT (default command processing behavior)

CFGARGAGT Command Parameters

Each parameter in the command has a specific meaning as described in this section.

PORT (nnnnn)

The PORT parameter tells the agent which TCP/IP port number to use when listening for incoming connections. The default value is 3093. The allowed values for this parameter are in the range 1024 through 65535. Typically, port 3093 is available for use by the Argent Agent for iSeries. In the case that you have difficulties connecting the Argent monitoring engine to the Argent Agent for iSeries, it may be necessary to use a different port number.

LOGLVL(log level)

The LOGLVL parameter tells the agent how much detail to include in the messages written to the Argent Agent for iSeries log file. This log file is comparable to the iSeries system history logs. The Argent Agent for iSeries log file contains routine messages about normal operation of the agent as well as messages that can help identify potential problems. There are four values supported:

*NONE This value limits log messages to the very fewest possible.
*NORMAL This value directs the agent to store routine messages about normal operations as well as messages about potential error conditions.
*DETAILED This value directs the agent to write extensive messages, including information about the status of internal agent operations and important calculations and results.
*VERBOSE This value directs the agent to the most extensive messages possible. This value is typically used only on the advice of qualified Argent support personnel in problem-determination or troubleshooting scenarios.

The default value for the LOGLVL parameter is *NONE .

LOGSIZ(log file size)

The LOGSIZ parameter tells the agent how large each Argent Agent for iSeries log file member can grow before it will be closed and a new log file member will be opened for logging. The name of the Argent Agent for iSeries log file is LOG and it is stored in the production installation library ARGENT. Each log file member within the LOG file has a member name that follows the naming convention “ Myymmddnnn” where M is the letter M, yymmdd is the date the log file member was created, and nnn is a sequence number starting at 001 and ranging up to 999. The LOGSIZ parameter specifies the largest size of each member within log file LOG. Similar to many IBM-provided system values, the LOGSIZ parameter is expressed in bytes.

JOBD (job description library/name)

The JOBD parameter tells the agent which job description to use to submit agent work for iSeries processing. The default value for this parameter is *LIBL/ARGENT . The default value is appropriate in most situations and should only be changed if the distributed Argent work management objects are not suitable in your iSeries IT environment.

MSGQ (message queue library/name)

The MSGQ parameter tells the agent which message queue to use to send and store informational and other messages about the operations of the Argent Agent for iSeries. The default for this parameter is the special value *SYSOPR . *SYSOPR is interpreted by the agent to mean message queue QSYSOPR in library QSYS . It is common for iSeries system administrators to want to route messages about a system monitoring product like the Argent Agent for iSeries to a message queue other than *SYSOPR . In some environments, many applications send messages to *SYSOPR, which tends to make important messages like Argent’s harder to find. In that case, you can use the CRTMSGQ command to create a separate message queue and then specify the message queue name and the library name of that message queue in this parameter.

ALWIPADDR(list of allowed IP addresses)

The ALWIPADDR parameter allows you to restrict access to the Argent Agent for iSeries. This parameter provides the agent with a list of IP addresses which are allowed to connect to your Argent Agent for iSeries. The default for this parameter is the special value *ANY . The *ANY special value is interpreted by the agent to mean that any Argent monitoring engine is allowed to connect to your Argent Agent for iSeries. *ANY is usually a good choice to get started with your new software. After the agent has been installed and running smoothly, the system administrator for your iSeries machine should change this value to specify a list containing only the IP addresses that are authorized to connect. Up to 16 values can be specified for this parameter. If more than one value is specified, the *ANY special value is disallowed. If more than one value is specified, each value must be enclosed in single quotes separated by spaces. Additionally, you can specify generic values using the wildcard character (“*”). Generic values are a useful way to specify a group of IP addresses that are allowed. To specify that all the IP address in the range 192.1.16.100 through 192.1.16.199 are allowed to connect to your Argent Agent for iSeries, you can specify the generic value 192.1.16.1*. As with simple list element values, generic values must be enclosed in single quotes and separated by a space. Simple values and generic values can be used together as list elements for this parameter.

Note: Using the *ANY special value or generic values containing the wildcard character can potentially reduce the security of your Argent Agent for iSeries. Please consult with your network administrator to be sure you have the best balance between configuration simplicity and network security.

ALWHOSTS(list of allowed Argent monitoring engine hosts)

The ALWHOSTS parameter allows you to restrict access to Argent Agent for iSeries. This parameter provides the agent with a list of Argent monitoring engine platform names which are allowed to connect to your Argent Agent for iSeries. The default for this parameter is the special value *ANY. The *ANY special value is interpreted by the agent to mean that any XT Monitor Engine is allowed to connect to your Argent Agent for iSeries. *ANY is usually a good choice to get started with your new software. After the agent has been installed and running smoothly, the system administrator for your iSeries machine should change this value to specify a list containing only the XT Monitor Engine hosts that are allowed to connect. Up to 16 values can be specified for this parameter. If more than one value is specified, the *ANY special value is disallowed. If more than one value is specified, each value must be enclosed in single quotes separated by spaces.

CACHEITV(nnnnn)

The CACHEITV parameter tells the agent how long performance metrics will remain in the agent cache until the values are considered expired and must be refreshed. The value is expressed in seconds. The default value 15 . The allowed values for this parameter are in the range 10 through 120.

CMDDFT(*ALLOW/*DISALLOW)

The CMDDFT parameter tells the agent what policy to use as a default for command processing. An Argent monitoring engine can submit commands in response to routine situations that occur on your iSeries machine. A good example would be a situation where the XT Monitor Engine has a rule defined that issues the STRSBS QBATCH command in response to finding that subsystem QBATCH is inactive. As an adjunct to iSeries system security, the XT Agent for iSeries provides a configuration procedure to create a list of commands that have unique policy requirements on the system. The CMDDFT parameter controls whether the default behavior of the agent is to allow iSeries commands from the XT Monitor Engine to be processed or prevent them from being processed.

The default value for this parameter is *ALLOW , which means that the Argent Agent for iSeries will allow the XT Monitor Engine to issue iSeries commands as part of normal rule processing. The result is that you will configure exceptions to this rule using the steps described later in this document. When the overall behavior is *ALLOW, you can configure a list of disallowed commands.

The other value for this parameter is *DISALLOW , which means that the Argent Agent for iSeries will prevent the XT Monitor Engine from issuing iSeries commands as part of normal rule processing. The result is that you will configure exceptions to this rule using the steps described later in this document. When the overall behavior is *DISALLOW , you can configure a list of allowed commands.

Sample CFGARGAGT Command

A sample CFGARGAGT command is shown below:

CFGARGAGT PORT( 3093) LOGLVL(*NORMAL) LOGSIZ (1000000)

JOBD(*LIBL/ARGENT) MSGQ (SYSADMIN/CRITMSGS)

ALWIPADDR (‘192.1.16.10*‘ ‘172.16.16.223‘ ‘65.55.221.10‘) ALWHOSTS(‘*ANY‘)

CACHEITV(30) CMDDFT (*ALLOW)

This sample command is interpreted as follows:

  • The port number used will be 3093.
  • The level of detail for log messages will be *NORMAL
  • The maximum size of each log file member will be 1,000,000 bytes
  • The job description the agent will use to submit work for processing will be job description ARGENT on the Argent Agent for iSeries library list ( *LIBL)
  • Information and notification messages generated by the agent will be sent to message queue CRITMSGS in library SYSADMIN.
  • Argent monitoring engines will be allowed to connect to
    • Any system in the range 192.1.16.100 through 192.1.16.109
    • 172.16.16.223
    • 65.55.221.10
    • Connection attempts from any other IP address will be rejected
  • Any Argent monitoring engine name connecting from one of the valid IP addresses will be accepted.
  • The cache expiration interval will be 30 seconds. After 30 seconds, any request for performance metrics will force the cache to be refreshed and the expiration interval to be reset.
  • iSeries commands issued as part of rule processing by the Argent monitoring engine will be allowed.

Experienced iSeries system administrators and users will recognize that the CFGARGAGT is like any other command object in that the order of the keywords is unimportant.

Using The iSeries Command Prompter With CFGARGAGT

CFGARGAGT works directly from any iSeries command line. The iSeries command prompter is not required. Some customers are more familiar with using the iSeries command prompter to help issue commands. For those customers, CFGARGAGT implements the IBM-provided iSeries command interpreter support. You can type some, none, or all of the command keyword parameters and then press F4 to invoke the system command prompter. Values that you specify on the command line before pressing F4 are accepted by the command prompter. Values that you do not specify are supplied from the existing configuration.

As example of this is shown below:




Click For Full Size

In this example, the user supplied the LOGLVL (*VERBOSE) parameter value from the command line. When the user presses F4 to invoke the command prompter, the following display is shown:




Click For Full Size

Notice that values supplied from the command line before pressing F4

are highlighted by the command prompter using the “>” character. Other values supplied from the existing configuration are not highlighted.

When To Use CFGARGAGT

Although it is not strictly required, CFGARGAGT should be used at least one time prior to running the agent for the first time. When CFGARGAGT is used at any other time, the values are stored in the configuration immediately, but they are not read in by the Argent Agent for iSeries until the next time the agent is ended and re-started. To avoid confusion, Argent recommends changing this parameter only when system operational schedules allow for the agent to be ended and re-started.

The Argent Agent for iSeries is designed to run properly “out-of-the-box ” using default values for the configuration elements just described. This may be a convenient way to get started. You can always change the configuration at a later time, when needed.

Including CFGARGAGT In Your Programs

Because CFGARGAGT is a command object, it can be included in C/L programs that your IT system administrators and developers might need to automate or standardize the operation of the Argent Agent for iSeries. CFGARGT can be invoked from the command line, submitted as a batch job, included in a C/L program, or invoked from a High Level Language (HLL) program. Since the Argent Agent for iSeries configuration changes very rarely, this capability is generally not needed.

Getting Started With CFGARGAGT

To keep things as simple as possible, Argent recommends simply typing

CFGARGAGT

from a command line and pressing F4. Accept the defaults and press <Enter>. This will provide a valid Argent Agent for iSeries configuration that will be suitable for your initial implementation and verification of the agent functionality.