IBM Performance Management

Subnode configuration example

How to configure a sample agent with one defined subnode.

Example:

This example shows how to configure a sample agent that has one subnode named Example Subnode of type exs and the following three configuration properties:
  • Agent Cfg (actual property name is K00_AGENT_CFG) is defined only at the agent level.
  • Subnode Cfg (actual property name is K00_SUBNODE_CFG) is defined only in the example subnode.
  • Overridable Cfg (actual property name is K00_OVERRIDABLE_CFG) is defined at the agent level and was copied to the example subnode.
(Figure 1) shows these configuration properties on the Runtime Configuration Information page of the Agent Editor.
Figure 1. Configuration property definitions in the Agent Builder
Agent Editor pane with Runtime Configuration Information page open and runtime configuration information displayed
When this example agent is configured, the first page that is displayed is the Top section, which contains the Agent Cfg property as shown in (Figure 2). Because this property is an agent-level property, it is shown one time during agent configuration. Any instance of the Example Subnode can see this property value, but all instances see the same value.
Figure 2. Top section with agent-level configuration for the Agent Cfg property
Agent Configuration window with Top selected, and a value entered in the Agent Cfg field
If you are configuring from the Tivoli® Enterprise Monitoring Server command line, the Agent Cfg property can be set by using the following command: 
tacmd configureSystem -m HOSTNAME:00 -p "TOP.K00_AGENT_CFG=a value"
The next section that is displayed is the Main section as shown in Figure 3. It is also an agent-level section and contains the agent-level Overridable Cfg property. This property differs from the Agent Cfg property because this property was copied to the Example Subnode in the Agent Builder. This means that a default value for the property can be entered on the Main page. However, any Example Subnode instance can override the value that is entered here with a different value.
Figure 3. Main section with the agent-wide default value for the Overridable Cfg property
Agent Configuration window with Main selected and default value entered in the Overridable Cfg field
If you are configuring from the Tivoli Enterprise Monitoring Server command line, this property can be set by using the following command: 
tacmd configureSystem -m HOSTNAME:00 -p "MAIN.K00_OVERRIDABLE_CFG=default value"

You can place both of these properties in the same agent-level section. You can decide how many custom agent-level sections to create and how to distribute custom properties among them.

The next section that is displayed is the Example Subnode section as shown in Figure 4. Because this agent is being configured for the first time, there are no defined subnode instances and no subnode instance subsections are shown. The initial property values subsection is shown, although it is optional and some subnode types might not show it. Because the initial property values subsection is shown, default values can be entered for any of the configuration properties. The Overridable Cfg property already has a default value that was obtained from the agent-level property of the same name.
Figure 4. Example Subnode section page with no subnode
Agent Configuration window with Example Subnode selected and Subnode Cfg and Overridable Cfg fields displayed
Subnode instances are defined by doing the following actions on the empty Example Subnode section page (Figure 5):
  1. In the initial Example Subnode section, in the Subnode Cfg field, type the following default string for the property: sub-default value.
  2. Click New. An Example Subnode subsection is displayed after the initial properties subsection.
  3. In the Example Subnode field, type the following subnode instance ID: do.
  4. Click New. A second Example Subnode subsection is shown after the first.
  5. In the second Example Subnode field, type the following subnode instance ID: re.
  6. In the Subnode Cfg field, type the following value for the Subnode Cfg property: sc override.
  7. In the Overridable Cfg field, type the following value for the Overridable Cfg property: oc override.
Figure 5. Example Subnode section page with two subnode instances defined
Agent Configuration window with two defined subnode instances beneath the example subnode

The two new subsections cause the agent to create two subnode instances when it is started. Because the properties of the do subnode subsection were not changed, the default property values are used by that subnode instance. Since different values were entered for the properties in the re subsection, the re subnode instance uses those values that were typed.

You can set a default value from the Tivoli Enterprise Monitoring Server command line with the following command: 
tacmd configureSystem -m HOSTNAME:00 -p "exs.K00_SUBNODE_CFG=sub-default value"
The format for setting subnode default values is exactly like the format for setting agent-level properties, except that the section name identifies a subnode section.
You can create the subnode instances from the Tivoli Enterprise Monitoring Server command line with the following command: 
tacmd configureSystem -m HOSTNAME:00 -p "exs:do.K00_OVERRIDABLE_CFG=default value" \
 "exs:re.K00_SUBNODE_CFG=sc override" "exs:re.K00_OVERRIDABLE_CFG=oc override"

The subnode instance ID is inserted between the section name and property name. When you use the command line to create a subnode instance, at least one property must be specified, even if all the properties use default values. Otherwise, default values are not required to be specified on the command line when you define subnode instances.

All of the agent configuration properties can be set in a single command. The following command is equivalent to all of the preceding individual commands: 
tacmd configureSystem -m HOSTNAME:00 -p "TOP.K00_AGENT_CFG=a value" \
 "MAIN.K00_OVERRIDABLE_CFG=default value" \
 "exs.K00_SUBNODE_CFG=sub-default value" \
 "exs:do.K00_OVERRIDABLE_CFG=default value" \
 "exs:re.K00_SUBNODE_CFG=sc override" "exs:re.K00_OVERRIDABLE_CFG=oc override"