8.4.4 Managing command execution

The JP1/Base command execution function controls the following modes of command execution in JP1/IM:

Command execution from the Execute Command window of JP1/IM - View
Command execution by automated action

The following describes the JP1/Base command execution function.

Organization of this subsection

(1) Executing commands
(2) Users permitted to execute commands
(3) OS-based command execution
(4) Using host groups to execute commands on multiple hosts
(5) Issuing JP1 events based on the command execution status
(6) Commands for troubleshooting
(7) Conditions for command execution

(1) Executing commands

When you execute a command in JP1/IM, JP1/IM on the manager directs the JP1/Base command execution function to execute the command. The command execution function then executes the command by sending a request to the agent specified as the execution target.

Commands executed by the user from JP1/IM - View or by an automated action are both processed by the command execution function. However, they differ in how the execution request is controlled (whether the request is queued or not queued).

Figure 8‒14: Command execution

As shown in the above figure, when you execute a command from JP1/IM - View, the command is executed immediately without being queued. When you execute multiple commands, each command is executed without any controls being placed on the execution order or the number of commands that can be executed concurrently.

Commands executed by automated actions are queued up to the specified command-queue-count. Also, the system does not execute more commands at any one time than the specified command-concurrent-execution-count.

The flow of processing is described below, following the numbers in the figure:

A command is executed.
- By an operation from JP1/IM - View
  
  When you execute a command from JP1/IM - View, a request for command execution is sent to JP1/IM on the manager that you are logged in to. That instance of JP1/IM then passes the request to the command execution function of JP1/Base on the local host.
- By automated action
  
  The automated action function of JP1/IM automatically executes an action upon receiving a JP1 event specified as a condition in an action definition. When this occurs, the command defined as the action in the action definition is passed by JP1/IM as an execution request to the command execution function of JP1/Base on the local host.
The manager requests the agent to execute the command.

The JP1/Base on the manager sends a request to the JP1/Base on the agent specified as the execution target, directing it to execute the command. If there is no response from the agent within the time period specified by response-monitoring-time, an error is returned to JP1/IM indicating that the host is unreachable.
The command is executed by JP1/Base on the agent.

The command execution function of JP1/Base on the agent executes the command using the OS shell or cmd.exe. The command is handled differently depending on how the command execution was requested:
- By an operation from JP1/IM - View
  
  The command is executed immediately.
- By automated action
  
  Command execution requests are queued by the command execution control of JP1/Base on the agent, and executed in order. The maximum number of commands in the queue is determined by the specified command-queue-count, and the number of commands that are executed in parallel is determined by the specified command-concurrent-execution-count. Although the number of commands being executed at any one time differs according to the duration of commands and the execution environment, it will never exceed command-concurrent-execution-count (under the default setting, command-concurrent-execution-count is set to 1, and commands are executed one at a time.)
  
  Command execution might be delayed when a command executed by an automated action takes a long time to execute and commands are set to be executed serially (the default setting). In this case, you can reduce delays by setting the command execution function to execute commands in parallel.
  
  Delays can also be introduced when a large number of commands are executed by automated actions, leading to a backlog of commands in the queue. You can gain advance notice of execution delays by setting the command-queue-count-threshold parameter (supported in JP1/Base 07-11). Under the default settings, a warning event is issued when the number of commands in the queue reaches 10, and a recovery event is issued when the number returns to 0.
The command execution result is sent from the agent to the manager.

JP1/Base on the agent sends the command execution result (command output) to the JP1/Base on the manager. When the command finishes executing, JP1/Base on the agent reports the execution results to JP1/IM via JP1/Base on the manager.

At this time, log information for the command is recorded in a command execution log file on the manager. The maximum number of records that can be contained in the execution log is defined by the -record option of the jcocmddef command.

You can view these command execution logs in the Execute Command window if the command was executed from JP1/IM - View, or in the Action Log Details window if the command was executed by an automated action.

In the description above, response-monitoring-time, command-queue-count, command-concurrent-execution-count, and command-queue-count-threshold are parameters of the JP1/Base command execution function. You can set these parameters using the jcocmddef command.

The flow of this processing task is described in 4.19.3 Executing commands on managed hosts from JP1/IM - View and Chapter 6. Command Execution by Automated Action. See also these descriptions as required.

To Page Top

(2) Users permitted to execute commands

To execute commands in the OS environment of the agent, you must have the appropriate OS user permissions.

At command execution, user mapping associates the JP1 user with an OS user on the agent, and the command is executed under the OS user permission associated with that JP1 user account.

If the target host is a Windows host, the OS user subject to user mapping must have Windows-specific user permissions. For details about the user permissions required for an OS user subject to user mapping, see the chapter on granting user permissions to OS users in the JP1/Base User's Guide.

Figure 8‒15: Command execution and user mapping

The command execution function directs the agent to use the following JP1 user accounts when executing commands:

Command execution from JP1/IM - View

The JP1 user who is currently logged in to JP1/IM - View
Command execution by automated action

The JP1 user specified in a definition with the highest priority based on the following ranking:
1. The JP1 user specified in u= in the automated action definition file (actdef.conf) (for compatibility) or in usr in the automated action definition file (actdef.conf)
2. The JP1 user specified by the ACTIONEXECUSER parameter in the automated action environment definition (action.conf) The JP1 user specified by the ACTIONEXECUSER parameter of the common definition information in the automated action environment definition file (action.conf.update)
3. jp1admin

At command execution, the JP1 user is mapped to the OS user defined in the user mapping at the agent where the command is to be executed.

To Page Top

(3) OS-based command execution

The JP1/Base command execution function uses the following methods for command execution requested by JP1/IM - View or an automated action.

(a) Users permitted to execute commands

The command is executed by the OS user mapped to the JP1 user.

(b) Method of command execution

The command execution function uses the following methods to execute commands:

In Windows

The command execution function executes cmd.exe /c command.
In UNIX

The command execution function uses the login shell of the OS user to execute the command, for example /bin/sh -c command (where the login shell is /bin/sh).

When you execute a command that creates a child process, JP1/Base will be unable to process the next command until the child process has terminated. This is because command execution management recognizes the command as still running.

(c) Environment for command execution

The environment used for command execution is described below.

Environment variables

You can use an environment variable file in JP1/Base to specify the environment variables used at command execution. Specify the environment variable file in the Execute Command window of JP1/IM - View or in the automated action definition file (actdef.conf). For details about the environment variable file, see the description of the environment variable file in the JP1/Base User's Guide.

If you do not set up an environment variable file, the following environment variables are used.
- In Windows
  
  The Windows system environment variables are used at command execution.
- In UNIX
  
  The environment variables of the command execution process (the environment variables specified in the JP1/Base start command jbs_start, for example) are used at command execution. The OS user profile is not loaded in UNIX systems.
OS user profile (Windows only)

You can load the OS user profile when you execute a command on the target host. You can enable this function using the -loaduserprofile option of the jcocmddef command (it is disabled by default).
Important
The environment on the target host must allow the commands to execute normally. Note the following, for example:
- Each command requires a certain amount of resources, such as memory, to execute. When you execute a large number of commands concurrently, the system might have insufficient resources to execute the commands. When there are insufficient system resources in Windows, for example, a dialog box is displayed with the message cmd.exe - DLL initialization failed.
  
  If this occurs, adjust the number of commands that are executed concurrently to ensure that sufficient resources are available for each command.
- When you execute a command or shell script that processes 2-byte code, an appropriate language code must be set as an environment variable, and a shell that supports 2-byte code such as the C shell must be used.
- Commands that cannot be executed in the format cmd.exe /c command or shell -c command cannot be executed by the JP1/Base command execution function.
- If the login shell of the OS user is the C shell, use the C shell for executing an automated action.
- In Windows, UAC is not enabled during the execution of these commands because the permissions for OS users are acquired by using the user permission "Act as part of the operating system". Make sure you perform enough operational checks if you are using user applications that ran on older Windows environments (e.g., when you change environments).
- In Windows, the path of the current folder for executing commands is installation-folder\COMMAND and cannot be changed by using the command execution function. If you want to change the current folder, change the directory in a batch file, and then execute a command.

(d) Command execution results

The execution results for commands executed by the command execution control are handled as follows:

Outputting command execution results

Command execution results (such as messages) are recorded^# in a command execution log file managed by the command execution control on the manager. Log information for commands executed from JP1/IM - View appears in the Execute Command window, and log information for commands executed by automated actions appears in the Action Log Details window.

When multiple commands are executed, the results might be output in a different order from the execution order. The result output timing is affected by such things as the time required to execute each command, performance and workload differences among the hosts on which the commands are executed, and retry after a communication error.

#

By changing settings in JP1/Base, you can limit the amount of execution result data output to the command execution log file when commands are executed from JP1/IM - View or by automated actions. You can either restrict the amount of transferred data or prevent registration of detailed information. Both are performed by specifying options in the jcocmddef command. Choose whichever method best suits your system operation.

Restricting the amount of transferred data

You can restrict the amount of execution log data by setting an upper limit (as a number of lines) for the amount of data that can be transferred from the execution-target host to the manager. This helps control the size of the command execution log file and reduces congestion on the communication lines between the hosts.

You can set separate limits for the execution results of commands executed from JP1/IM - View and for those executed by automated actions.

If you performed a new installation of version 8 of JP1/Base, data transfer will be restricted to a maximum of 1,000 lines by default.
Preventing registration of detailed information (applies to commands executed by automated actions only)

For the execution results of commands executed by automated actions, you can choose to register only information indicating the success or failure of the command, and discard detailed information such as message information. By doing so, you can improve the processing speed of the underlying JP1/Base components (and hence the speed with which automated actions are processed). However, when you prevent registration of detailed information, the message KAVB2401-I appears in the Message area of the Action Log Details dialog box, and no detailed log information is displayed (the Log area is unaffected). Do not enable this setting if you need to view detailed information (the setting is disabled by default).

The execution results of automated actions are managed by the action information file and the command execution log file.

If an automated action in which commands for the action have been omitted is executed, the execution results are not written to the command execution log file because no command is executed.

If a large number of actions are issued, only the action information file is wrapped. As a result, the execution results in the command execution log file and action information file might become inconsistent. In such a case, the execution results for another automated action that was executed in the past might be displayed.

To avoid this, do not define automated actions in which commands are omitted. Also, define commands that do not have a negative impact on the system, such as the echo command, in the automated action. If a large number of actions in which commands are omitted are issued and the execution results of other automated actions executed in the past are displayed, the command execution log file is also wrapped, and then inconsistency between the action information file and the command execution log file is resolved.

Command execution results (return code)

The following return codes appear in the command execution results:

In Windows

The return code passed to the command execution function by cmd.exe.
In UNIX

The return code passed to the command execution function by the shell that executed the command.

The command will not execute if an error occurs leading up to command execution (for example user mapping fails or the target host cannot be contacted).

Important: After command execution has terminated, the termination code reported in the JP1 event might differ from the actual termination code depending on when the termination code is finalized. After you have received a JP1 event notification, check the details of the command's execution results in the Action Log Details window.

To Page Top

(4) Using host groups to execute commands on multiple hosts

You can define a number of hosts together as a single group.

You can specify a host group as the target host at command execution. By doing so, you can execute the command on all the hosts in that group in a single operation.

For details about defining host groups and the host group definition file, see the description of the host group definition file in the JP1/Base User's Guide.

To Page Top

(5) Issuing JP1 events based on the command execution status

You can issue JP1 events that indicate the execution status of commands, such as when command execution starts and stops. JP1 events can be issued in the following cases:

Command execution from JP1/IM - View

When a command starts executing, finishes executing, or terminates abnormally.
Action (command) execution by automated action

When a command starts executing, finishes executing, terminates abnormally, or fails to execute (due to a failed request).

By enabling this functionality, you can use JP1 events to manage information about when commands are executed, by which users, and on which hosts. You can then display and monitor this information in the Event Console window of JP1/IM - View.

Use the jcocmddef command to set up issuing of these JP1 events.

The JP1/Base command execution function also provides for other JP1 events, examples of which are given below. These JP1 events do not require setup as above.

JP1 events issued based on how long a command takes to execute

This function is supported from version 07-10 of JP1/Base. A JP1 event is issued when a command has not finished executing within a predetermined period of time. This JP1 event helps you to identify hangups or undue delays in commands executed from JP1/IM - View or by automated action.

By default, this JP1 event is issued at 10-minute intervals. You can change this setting using the jcocmddef command.
JP1 events issued when the queuing threshold is exceeded

This function is supported from version 07-11 of JP1/Base. A JP1 event is issued when the number of commands in the queue reaches or exceeds a predetermined number, and another event is issued when the number returns to an acceptable level. These JP1 events allow you to gain advance notice of execution delays when a large number of commands are executed by automated actions, and let you know when the situation has recovered.

Under the default settings, a warning event is issued when the number of commands in the queue reaches 10, and a recovery event is issued when the number returns to 0. Use the jcocmddef command to modify these settings.

To Page Top

(6) Commands for troubleshooting

You might encounter the following problems when using the JP1/Base command execution function from JP1/IM.

A command that cannot be executed from JP1/IM - View (see 4.19.3(1) Executable commands) is executed accidentally and remains stuck in executing status.
A greater number of automated actions occur than was anticipated at the design stage, leading to a massive backlog of redundant actions in the queue.
A command executed by an automated action hangs or takes longer than expected to execute, preventing succeeding commands (actions) from executing.

To allow you to recover quickly from these errors, JP1/Base provides a command for checking the status of queuing or executing commands (jcocmdshow), and a command for deleting queuing or executing commands (jcocmddel)^#.

#

JP1/IM can cancel automated actions when command execution results in an error. When an error occurs in a command executed by an automated action, use this function where possible (for details, see 6.7 Canceling automated actions).

Figure 8‒16: Overview of jcocmdshow and jcocmddel commands

The jcocmdshow command displays the following information. Based on this information, determine which commands need to be deleted, and then delete them using the jcocmddel command.

Table 8‒12: Information displayed by the jcocmdshow command
Display item	Description
`ID`	The unique ID assigned to commands that are executing or queuing in the command execution function. When you use the `jcocmddel` command to delete a command, use this ID as the key.
`STATUS`	The execution status of the command in the command execution function, shown as either Running or Queuing.
`TYPE`	Whether the command was executed by JP1/IM - View or an automated action.
`USER`	The name of the JP1 user who issued the command execution request.
`STIME`	The time at which the command execution function received the instruction from JP1/IM to execute the command.
`ETIME`	The length of time that has elapsed since the command started execution.
`COMMAND`	The name of the executing or queuing command.

The jcocmdshow and jcocmddel command functionality is provided by JP1/Base and might not be supported depending on the version of JP1/Base on the host where the problem occurred. For details, see the JP1/Base User's Guide.

The jcocmdshow and jcocmddel commands can be executed in any of three ways:

From JP1/IM - View

You must specify the -f option when you execute the jcocmddel command from JP1/IM - View.
From the manager to an agent target host

You must specify the -s option. Note that in order to execute these commands, the manager must also be running JP1/Base version 07-10 or later.

Take care when using this option, as communication will take place directly between the manager and agent (using the same communication path as the definition collection and distribution function).
Directly on the host where the problem occurred

For details about these commands, see the command descriptions in the JP1/Base User's Guide.

To Page Top

(7) Conditions for command execution

The following figure summarizes the conditions for executing commands from JP1/IM - View and by automated actions.

Figure 8‒17: Conditions for executing commands and automated actions

Conditions for executing commands from JP1/IM - View:

The logged-in JP1 user has permission to execute commands.

JP1 users with JP1_Console_Admin or JP1_Console_Operator permissions are permitted to execute commands.
User mapping is defined on the target host.

User mapping is defined as follows:

JP1-user:server-host:OS-user

JP1-user is the user who is operating JP1/IM - View, server-host is the name of the server host the JP1 user is logged in to, and OS-user is the user name of a user or domain user registered on the target host.
The system configuration definition is set up (when executing commands on another host).

If the system configuration is not defined, you will be unable to execute commands on another host from JP1/IM - View.

Conditions for executing commands by automated action from the manager:

User mapping is defined on the target host.

User mapping is defined as follows:

JP1-user:server-host:OS-user

JP1-user is the user who executes the automated action, server-host is the name of the server host that issues the instruction to execute the automated action, and OS-user is the user name of a user or domain user registered on the target host.
The system configuration definition is set up (when executing commands on another host).

If the system configuration is not defined, you will be unable to execute a command on another host by automated action.

To Page Top