4.2.2 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 Agentless Connection Destinations area, 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, you can execute the command using the permissions of the System account by specifying true for the runAsSystem property. If the operation target device is running UNIX, the command is executed with root user permissions or the permissions of the connection user, depending on the value specified for the elevatePrivileges property.

If the OS of the local host on which the local execution function is enabled is Windows, the command is executed with the privileges of the System account. If the OS is Linux, the command is executed with root user privileges.

The execution directory to be used when a command is executed is as follows:

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 the functional differences from the versions earlier than 02.01.00, 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 JP1/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 JP1/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.
When you forcibly terminate a task while the plug-in is running, the process tree being executed on the operation target device is immediately forcibly terminated and the status of the task becomes Failed or Completed. In this case, a return code of 80 appears for the step in the Flow area of the Tasks window. 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. In Windows, SMB and RPC are used for execution. In UNIX, SSH is used for execution. Therefore, in UNIX, the SSH server must be set up on the operation target devices.
The port number used by SSH can be set in connection-destination property file (connection-destination-name.properties) or the user-specified properties file (config_user.properties).
If the OS of the JP1/AO server is Linux and the OS of an operation target device is Windows, you cannot specify an IPv6 address as a connection destination.
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.4 Prerequisites for executing command lines containing non-ASCII characters in UNIX.
Interactive commands and script that seek user input and commands that do not end automatically using a GUI display or the like cannot be executed.

Version

02.01.00

Tag

Execute Script

Return codes

Return code	Description
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. The total amount of data output to the standard output and standard error output exceeded 100 KB.
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. Keyboard interactive authentication failed.
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^#1`	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 area. Specifying `destination` applies the authentication information set for Windows 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`, `publicKeyAuthentication`, and `keyboardInteractiveAuthentication`). `property` Specify this option to use the values specified in the following properties as authentication information: `account` `password` `suPassword` `publicKeyAuthentication` `keyboardInteractiveAuthentication`	--	Input	R
`account^#1`	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^#1`	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^#1`	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
`runAsSystem`	Run as system account	If the OS of the operation target device is Windows, specify whether to execute commands using the permissions of the System account. If the OS of the operation target device is UNIX, the value specified in this property is ignored. true Specify this value to execute commands using the permissions of the System account. false Specify this value to not use the permissions of the System account to execute commands. When you specify this value, commands are executed using the permissions of the user set in the authentication information.	false	Input	O
`publicKeyAuthentication^#1`	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 not use public key authentication.^#2	false	Input	O
`keyboardInteractiveAuthentication`^#1	SSH keyboard interactive authentication setting	If the OS of the operation target device is UNIX, specify either of the values below, depending on whether you want to use keyboard interactive authentication for connection. 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. Note, however, that the value of the keyboardInteractiveAuthentication property takes effect only if the publicKeyAuthentication property is set to `false`. If you set the publicKeyAuthentication property to `true`, public key authentication is used even if you set the keyboardInteractiveAuthentication property to `true`. true Specify this value to use keyboard interactive authentication. false Specify this value to not use keyboard interactive authentication.^#2	false	Input	O
`elevatePrivileges^#1`	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` ^#3	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. For example, if an agentless remote connection executes the command line "`echo abc\def`" in a UNIX environment, "`abcdef`" is output instead of "`abc\def`". 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 area. 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 area, 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` ^#3	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. For example, if an agentless remote connection executes the command line "`echo`" and command line parameter "`abc%def`" in a Windows environment, "`abcdef`" is output instead of "`abc%def`". 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
`outputCondition`	Condition for outputting standard output properties	Specify the condition for outputting values to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. You can specify either of the following values: always Values are always output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. Null characters are output if the standard output and standard error output do not match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties. patternMatch Values are output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties only if the standard output and standard error output match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties. If the standard output and standard error output do not match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, no values are output. In this case, values are not updated even if the service properties are mapped to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties.	always	Input	R
`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.^#4 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.^#4 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.^#4 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

#1

If the operation target device is the local host on which the local execution function is enabled, the setting of this property is ignored.

#2

If you set false for both the publicKeyAuthentication and keyboardInteractiveAuthentication properties, password authentication is used.

#3

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.

#4

The parts grouped by parentheses are extracted by the regular expression.
If you specify multiple groups in the regular expression, only values that match the first group are stored in the output property of the plug-in.
If the regular expression applies to multiple value ranges, only the first range of values is stored in the output property of the plug-in. Multiple value ranges cannot be stored in an output property.
If you specify "(.*)", you can extract the character string from the beginning to the line feed of the character string including the line feed, such as the execution result of any command.

Example of using the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, and the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties

You can compare the standard output and the standard error output to the values of the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, and then store the results in the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. The following figure shows the data flow when specifying aaabbb(.*) in stdoutPattern1, stdoutPattern2, and stdoutPattern3.

Figure 4‒1: Example of using the 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.

You can use the outputCondition property to specify whether values are to be output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties in the following case: the standard output does not match the regular expressions specified for the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties and, as a result, the values cannot be extracted.

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	User-specified properties file (`config_user.properties`)	`ssh.port.number`	22

Legend:: --: No value is set.

Related topics

Prerequisites for connection destinations in the JP1/Automatic Operation Overview and System Design Guide
User-specified properties file (config_user.properties) and Connection-destination property file (connection-destination-name.properties) in the JP1/Automatic Operation Configuration Guide
A.2 List of protocols used by each plug-in

To Page Top