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:
|
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:
|
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:
|
-- |
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:
|
-- |
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.
|
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.
|
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.
|
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.
|
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. 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:
|
-- |
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. 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.
|
-- |
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 |
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. 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 |
- #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.
-
-
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.
|
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.
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