4.2.1 General command plug-in

Function

This plug-in enables a specified command to be executed on the operation target device.

If you have pre-set authentication information in the Connection Destinations view, you can execute commands by specifying the following information in the general command plug-in:

The device on which to execute the command (destinationHost property)
Command to be executed (commandLine property)
Command arguments (commandLineParameter property)

For the command to be executed on the operation target device, specify characters that can be used in commands in the operating systems of the JP1/AO server and the operation target device. For example, if the JP1/AO server and the operation target device both run the Japanese version of Windows, characters in the MS932 character set can be specified.

If the operation target device is running Windows, the command is executed by the user account set in the authentication information. If the operation target device is running UNIX, the command is executed with root user privileges or the privileges of the connection user, depending on the value of the elevatePrivileges property. The following execution directory is used at command execution:

When the connection destination is running Windows: Admin$\Hitachi\CMALib\JP1AO\home

Admin$ is the directory specified in the windir environment variable.
When the connection destination is running UNIX and true is specified for the elevatePrivileges property: The home directory of the root user
When the connection destination is running UNIX and false is specified for the elevatePrivileges property: The home directory of the connection user

For details about how version 01.50.00 of the plug-in differs from previous versions, see A.1 Functional differences between basic plug-ins by version.

Prerequisites for execution

For details about the operation target devices that can be used as connection destinations, see A.1 (3) Operation target devices usable as connection destinations.
Certain commands must be installed on the operating system of the operation target device before you use the general command plug-in. For details, see the release notes.
To use the general command plug-in when the operation target device is running Windows, administrative sharing must be enabled. For details, see the Job Management Partner 1/Automatic Operation Overview and System Design Guide.

Cautionary notes

The locale and character set at the time of execution depend on the OS of the operation target device. For details, see Locale set for operation target devices during plug-in execution and Character set used for communication by JP1/AO during plug-in execution in the Job Management Partner 1/Automatic Operation Service Template Development Guide.
If the execution of a task is stopped while the plug-in is executing, the status of the task becomes Failed or Completed when the processing of the general command plug-in finishes. The status of steps and tasks after plug-in execution has finished depends on the return code of the step and the condition for executing subsequent steps. You can set a Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.
If you forcibly terminate a task while the plug-in is executing, the process tree being executed on the operation target device is immediately forcibly terminated and the status of the task becomes Failed or Completed. A return code of -1 appears for the step in the Task Details dialog box. The return code output to the task log depends on the timing with which the task was forcibly terminated.
When you forcibly terminate a task while the plug-in is executing, the execution results of the command or script specified in the commandLine property are outside the scope of product support.
The execution method differs depending on the OS of the operation target device. The command is executed by WMI in Windows, and SSH in UNIX. Therefore, the SSH server must be set up on UNIX-based operation target devices.
The port number used by SSH can be set in connection-destination property file (connection-destination-name.properties) or the property file (config_user.properties).
When the operation target device is running Windows, user profiles are not inherited. This means a plug-in can produce different execution results from a command or script executed on the desktop.

To avoid this issue, do not reference settings in user profiles, such as user environment variables, registry entries, and Internet Explorer settings, when executing a plug-in. If a command or script references an element of a user profile, the command or script might not behave as expected. For example, when you execute a command or script that references Internet Explorer proxy settings, the command or script might fail with a communication error. This might occur in scenarios such as implementing a Windows Update using a script.
If the operation target device is running UNIX, and you need to specify non-ASCII characters in the commandLine or commandLineParameter property, see A.5 Prerequisites for executing command lines containing non-ASCII characters in UNIX.

Version

01.50.00

Category

Hitachi/Basic

Return codes

Return code	Description
-1	The task was forcibly terminated while the plug-in was executing. -1 appears as the return code of the step in the Task Details dialog box.
0 to 63	The return code (0 to 63) of the command or script is returned as the return code of the plug-in. The meaning of the command or script depends on the command or script.
64	If the return code of the specified command or script is 64 or higher, 64 is returned as the return code of the plug-in.
65	The connection with the JP1/AO server failed. For example, the JP1/AO server might have stopped while the plug-in was being executed.
66	The following user is mapped to the JP1 user: A user who does not belong to the Administrators group. A user other than the built-in Administrator who belongs to the Administrators group, in an environment with UAC enabled.
68	There is no information about the target job execution ID.
69	An environment variable of the task-processing engine could not be acquired.
70	The connection with the operation target device failed.
71	Command execution failed.
72	The execution status of the command could not be acquired.
76	The connection timed out.
77	The host name of the operation target device could not be resolved.
78	Authentication with the operation target device failed for one of the following reasons: Password authentication failed. Public key authentication has not been set up on the operation target device. When the public key was being authenticated, the private key did not match the pass phrase. When the public key was being authenticated, the private key did not correspond to the public key registered in the operation target device. When the public key was being authenticated, an invalid private key was used.
80	Task execution has stopped.
81	The plug-in was called in an invalid status.
82	The request message from the task-processing engine could not be correctly parsed.
83	The environment of the JP1/AO server is corrupted.
84	Information about the specified plug-in could not be obtained.
86	The specified property value is invalid.
127	Another error has occurred.

Property list

The following table describes the properties.

Property key	Property name	Description	Default value	I/O type	Required
`destinationHost`	Destination Host	Specify the IPv4 address, IPv6 address, or host name of the operation target device. The host name should be within 1,024 characters. The JP1/AO server and the operation target device must be connected by a network. Note that multiple IP addresses or host names cannot be specified.	--	Input	R
`credentialType`	Credentials Type	As the authentication type to use during command or script execution, specify either of the following: `destination` Specify this option to use the authentication information set in the Connection Destinations view. Specifying `destination` applies the authentication information set for WMI or SSH in the connection destination definition according to the IP address of the JP1/AO login user. You can omit the specification of properties relating to authentication information (account, password, suPassword, and publicKeyAuthentication). `property` Specify this option to use the values specified in the following properties as authentication information: `account` `password` `suPassword` `publicKeyAuthentication`	--	Input	R
`account`	User ID	Specify the user ID to use to log in to the operation target device, using a maximum of 256 characters. You can also specify a domain user in either of the following formats: `domain-name` `\` `user-name` `user-name` `@` `domain-name`	--	Input	O
`password`	Password	Specify the password to use to log in to the operation target device, using a maximum of 256 characters. You can omit this property when the operation target device is running UNIX and true is specified for the publicKeyAuthentication property.	--	Input	O
`suPassword`	Root Password	If the OS of the operation target device is UNIX, specify the root password using a maximum of 256 characters. If the OS is Windows, this property does not need to be specified. You can also omit this property when the operation target device is running Windows, or when false is specified for the elevatePrivileges property.	--	Input	O
`publicKeyAuthentication`	SSH public key authentication setting	If the OS of the operation target device is UNIX, specify either of the following depending on whether you want to use public key authentication. The values are not case sensitive. If you do not specify a value, false is assumed. You can omit this property when the operation target device is running Windows. true Specify this option to use public key authentication. false Specify this option to use password authentication.	false	Input	O
`elevatePrivileges`	Elevate Privileges	If the OS of the operation target device is UNIX, specify either of the following depending on whether you want to elevate the user to root privileges. The values are not case sensitive. If you do not specify a value, true is assumed. You can omit this property when the operation target device is running Windows. true Specify this option to execute commands as a user with root privileges. false Specify this option to execute commands without elevating the user to root. Commands will be executed with the privileges of the connection user.	false	Input	O
`commandLine` ^#	Command Line	Specify the absolute path of the command or script to be executed on the operation target device, using a maximum of 256 characters. In the command line, specify characters that can be entered in command lines in the operating systems of the JP1/AO server and the operation target device. Special characters that represent environment variables in the command line are not escaped. To handle a special character as a character string, escape the character with a percent sign (`%`) in Windows, and a backslash (`\`) in UNIX. The command or script is executed subject to the privileges of the following user: When the operation target device is running Windows If destination is specified for the credentialType property, the command is executed with the privileges of the user set in the Connection Destinations view. If property is specified for the credentialType property, the command is executed with the privileges of the user specified in the account property. When the operation target device is running UNIX If destination is specified for the credentialType property, the command is executed with the privileges of the root user or the user set in the Connection Destinations view, depending on the value of the elevatePrivileges property. If property is specified for the credentialType property, the command is executed with the privileges of the root user or the user specified in the account property, depending on the value of the elevatePrivileges property.	--	Input	R
`commandLineParameter` ^#	Command-line Parameters	Specify the arguments of the command or script using a maximum of 1,024 characters. As the command line parameters, specify characters that can be entered in command lines in the OSs of the JP1/AO server and the operation target device. Special characters that represent environment variables in the command line are not escaped. To handle a special character as a character string, escape the character with a percent sign (`%`) in Windows, and a backslash (`\`) in UNIX. You can also specify an environment variable as the value of a command line parameter. The specification format depends on the OS of the operation target device. If the operation target device is running Windows: `%` `environment-variable` `%` If the operation target device is running UNIX: `$` `environment-variable`	--	Input	O
`stdoutProperty1`	Standard Output Property 1	The character string extracted by the `stdoutPattern1` property is output to this property.	--	Output	O
`stdoutPattern1`	Standard Output Pattern 1	Specify the regular expression pattern of the standard output to output to the `stdoutProperty1` property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If you specify the key of a service property in the `stdoutProperty1` property but do not specify the `stdoutPattern1` property, the entire standard output and standard error output of the command or script specified in the `commandLine` property is assigned to the service property.	--	Input	O
`stdoutProperty2`	Standard Output Property 2	The character string extracted by the `stdoutPattern2` property is output to this property.	--	Output	O
`stdoutPattern2`	Standard Output Pattern 2	Specify the regular expression pattern of the standard output to output to the `stdoutProperty2` property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If you specify the key of a service property in the `stdoutProperty2` property but do not specify the `stdoutPattern2` property, the entire standard output and standard error output of the command or script specified in the `commandLine` property is assigned to the service property.	--	Input	O
`stdoutProperty3`	Standard Output Property 3	The character string extracted by the `stdoutPattern3` property is output to this property.	--	Output	O
`stdoutPattern3`	Standard Output Pattern 3	Specify the regular expression pattern of the standard output to output to the `stdoutProperty3` property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If you specify the key of a service property in the `stdoutProperty3` property but do not specify the `stdoutPattern3` property, the entire standard output and standard error output of the command or script specified in the `commandLine` property is assigned to the service property.	--	Input	O

#

The standard output or standard error output of the commands or scripts specified in these properties are output as the standard output of the step in JP1/AO. However, processing for which the total standard output and standard error output of the command or script exceeds 100 KB is outside the scope of product support. Execute the command or script in advance to make sure that the total standard output and standard error output does not exceed 100 KB.
If the operation target device is running Windows, the content specified in the commandLine and commandLineParameter properties are made into a batch file and executed on the operation target device. Therefore, the result of this action might differ from the result if the same command and script were executed from the command prompt.

If the operation target device is running UNIX, linefeed codes in standard output and standard error output are changed as follows:
- CR(0x0d) is changed to LF(0x0a).
- CR+LF(0x0d0a) is changed to LF+LF(0x0a0a).
In addition, if the character string at the end of the standard output and standard error output is not a linefeed code (CR, LF, or CR+LF), LF(0x0a) is added to the end.

Usage example of stdoutPattern and stdoutProperty properties

By using the stdoutPattern property, you can extract the value output to standard output and store it in the stdoutProperty property. The following figure shows the data flow when specifying aaabbb(.*) in stdoutPattern1.

Figure 4‒1: Usage example of stdoutPattern and stdoutProperty properties

As defined in stdoutPattern1, for the standard output aaabbbccc, the value after aaabbb (in this case ccc) is extracted. The extracted value is stored in the stdoutProperty1 property.

Specifying the SSH port number

You can specify a port number when using SSH to connect to the operation target device. The following table describes how to specify the port number and the priority of each method.

Table 4‒1: Priority of SSH port numbers
Priority	Set in	Property key	Default value
1	Connection-destination property file (`connection-destination-name.properties`)	`ssh.port`	--
2	Property file (`config_user.properties`)	`ssh.port.number`	22

Legend:: --: No value is set.

Related topics

Prerequisites for connection destinations in the Job Management Partner 1/Automatic Operation Overview and System Design Guide
Properties file (config_user.properties) and Connection-destination property file (connection-destination-name.properties) in the Job Management Partner 1/Automatic Operation Configuration Guide
A.3 List of protocols used by each plug-in

To Page Top