itmcmd agent

Use the itmcmd agent command to start and stop a monitoring agent. You can start or stop one agent, all agents, or multiple agents. You cannot start or stop multiple instance agents on one command. You can also start the portal server and portal desktop client by using this command.

You must run the itmcmd agent command on the architecture for which the agent is installed.

To start or stop agents for distributed database agent, see itmcmd dbagent. However, the itmcmd agent command can start and stop agents for distributed databases, although it cannot select monitors for individual database servers or activate debugging options.

Note:

The monitoring agent can run using a non-root user ID on UNIX® and Linux® systems. This can be done by running the itmcmd agent start command while logged in as a non-root user. If the agent was running using a non-root user ID, and then the itmcmd agent start is run using the root user ID, then the monitoring agent subsequently runs as the root user. To confirm the user ID that the monitoring agent is using, run the following command:

itm_install/bin/cinfo -r

If the installation is not permissioned properly, then you might be unable to restart the agent as a non-root user ID after it has been run as the root user ID. To prevent this problem, ensure that the secureMain lock command with the -g option has been previously run. See the "Securing your IBM Tivoli Monitoring installation on Linux or UNIX" appendix in the IBM Tivoli Monitoring Installation and Setup Guide for further details.

If the agent is running as root, and that is not the desired user ID, then use the following steps to restart the agent:

Log in as root.
Run the itmcmd agent stop command.
Log in (or 'su') to the user ID that you want the agent to run as.
Run the itmcmd agent start command.

If the agent was running as root because of a system reboot, then complete the following steps so that the appropriate user ID is used the next time the system is rebooted. Editing the startup file is no longer supported. Instead you must modify the config/kcirunas.cfg file and then run bin/UpdateAutoRun.sh:

Edit install_dir/config/kcirunas.cfg.
Add a section, after the <agent> line, to specify the agent or agent instance that you want to start as a specific user ID. To specify the user ID to start a non-instance agent, or to start all instances of an agent, use the following syntax:
```
<productCode>product_code</productCode>
<default>
   <user>user_name</user>
</default>
```
To specify different user IDs to start different instances of an agent, use the following syntax:
```
<productCode>product_code</productCode>
<instance>
   <name>instance_name1</name>
   <user>user_name</user>
</instance> 
<instance>
   <name>instance_name2</name>
   <user>user_name</user>
</instance>
```
Where:

product_code

2-character product code for the agent, for example, ux for the Unix OS monitoring agent.

user_name

Name of the user to run the agent as.

instance_name1

Name of an instance.

instance_name2

Name of another instance.

Examples:
For the Unix OS monitoring agent, to run as itmuser:
```
<productCode>ux</productCode>
<default>
   <user>itmuser</user>
</default>
```
For the DB2 monitoring agent instances to run as the instance owner IDs:
```
<productCode>ud</productCode>
<instance>
   <name>db2inst1</name>
   <user>db2inst1</user>
</instance> 
<instance>
   <name>db2inst2</name>
   <user>db2inst2</user>
</instance>
```
For the Websphere MQ monitoring agent instances to all run as the mqm user ID, and for the default instance to not be started:
```
<productCode>mq</productCode>
<default>
   <user>mqm</user>
</default> 
<instance>
   <name>None</name>
   <autoStart>no</autoStart>
</instance>
```
Repeat step 2 for each agent or agent instance that you want to start as a specific user ID.
Save the file.
Run install_dir/bin/UpdateAutoRun.sh as root user.

itmcmd agent
              [-h install_dir ]
              [-f]
              [-l]
              [-o instance ]
              [-p option ]
              [-c]
              [-n]
              [-m]
              {start|stop} {pc ...|all}

where:

-h install_dir

(optional) Identifies the installation directory if it is not the one in which the script is located.

Also use this option to take action on an IBM Tivoli Monitoring installation directory other than the one in the current system.

-f

(optional) Starts or stops an agent without user confirmation.

Note:

When stopping an agent, this option must be entered before the stop option or you will receive an error. For example:

itmcmd agent -p INST1 -f stop um

-l

(optional) Deletes the log file associated with the monitoring agent that is being stopped. By default, the log file is saved when the monitoring agent is stopped.

-o instance

(optional) Identifies a database instance to start or stop. You must use this option if you are starting or stopping a DB2® agent.

-p option

(optional) Identifies a Universal Agent instance to start or stop. Use this option when you are starting or stopping a non-default instance of the Universal Agent.

-c

(optional) Indicates that the configuration file used on agent startup should not be updated or regenerated. By default, this file is updated each time the agent is started.

-n

(optional) When specified, indicates that the PID is not checked. If the PID of the initial agent is killed, then another process takes that PID.

-m

(optional) If specified, indicates the creation of multiple instances.

start|stop {pc ...|all}

Indicates to start or stop the monitoring agent. You can start or stop one or more agents by using the product codes (for example, specifying lz um starts the Linux monitoring agent and the Universal Agent). To start or stop all agents on the computer, use the all option.

See cinfo to identify the product code for an agent or component.

The following example starts the Universal Agent:

   itmcmd agent start um

The following example stops a non-default instance (inst1) of the Universal Agent:

   itmcmd agent -p INST1 stop um

The following example starts the portal server:

   itmcmd agent start cq

An exit status of 0 indicates that the command ran successfully. An exit status greater than 0 indicates that there was a failure in the process.

Note:

The log file for the agent session is always saved, regardless of whether the agent was stopped by using the itmcmd agent command or any other means, unless you use the -l option when you run the itmcmd agent command. Additionally, when the agent is stopped by using the itmcmd agent command, the log file for that session ends with the following message:

   "** Process terminated by user **"

itmcmd server

cinfo (to determine the product codes for agents and components)

Return to Table 7.

itmcmd agent

Description

CLI syntax

CLI example

Return values

Related commands