General Command Plug-in

Ops Center Automator Service Builder User Guide

Version
11.0.x
Audience
anonymous
Part Number
MK-99AUT002-18

The General Command Plug-in runs a command line on the destination host.

If you have pre-set authentication information in the Agentless Remote Connections view, you can run commands by specifying the following information in the general command plug-in:

  • Device on which to run the command (destinationHost property)
  • Command to run (commandLine property)
  • Command arguments (commandLineParameter property)

If destination host is a Ops Center Automator Server (localhost), the user ID and the password are unnecessary.

For the command to run on the target device, specify characters that can be used in commands in the OSs of the Ops Center Automator server and the operation target device. For example, if the Ops Center Automator server and the target device both run the Windows OS with Japanese Locale, you can specify characters in the MS932 character set.

When local execution function is enabled and the OS of the local host is Windows, the command runs with System account privileges. If the OS is Linux, the command runs with root user privileges. The execution folder for the command is specified as follows:

  • When the connection destination is running Windows: Admin$\Hitachi\CMALib\HAD\home Admin$ is the folder specified in the windir environment variable.
  • When the connection destination is running Linux OS and true is specified for the elevatePrivileges property: The home folder of the root user
  • When the connection destination is running Linux OS and false is specified for the elevatePrivileges property: The home folder of the connection user

Prerequisites

Specific commands must be installed on the OS of the target device before you use the general command plug-in.

To use the general command plug-in when the target device is running Windows, you must enable administrative sharing.

Cautionary notes

  • IPv6 is not supported when Ops Center Automator is running on Linux OS and the destination host is Windows.
  • The locale and character set at the for running the plug-in depend on the OS of the operation target device.
  • If a task is stopped while the plug-in is running, the status of the task changes to Failed or Completed when the general command plug-in processing finishes. The status of steps and tasks after plug-in finishes running depends on the return code of the step and the condition for running subsequent steps. You can set a Subsequent-step Execution Condition in the Create Step or Edit Step dialog box.
  • The execution method differs depending on the OS of the target device. The command is run by SMB and RPC in Windows, and SSH in Linux OS. Therefore, the SSH server must be set up on Linux-based operation target devices.
  • The SSH port number is set in the connection-destination properties file (connection-destinationname.properties) or the properties file (config_user.properties).
  • When the target device is running Windows, user profiles are not inherited. This means a plug-in can produce different results from a command or script run on the desktop. To avoid this problem, do not reference settings in user profiles, such as user environment variables and registry entries, and proxy settings, when running 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 run a command or script that references 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 target device is running Linux OS, and you must specify non-ASCII characters in the commandLine or commandLineParameter property, the login script setting is required in the following plug-ins:
    • General Command Plug-in
    • File-Transfer Plug-in
    • Custom Plug-in
    • Terminal Command Plug-in
Note: Applies only to the File-Transfer Plug-in when a non-ASCII character is included in the value of the remoteFilePath property.

Login script setting

You can check the status of the istrip setting in standard output by running the stty -a command in the command line for each plug-in. If -istrip appears in standard output, theistrip setting is disabled. If istrip is not prefixed with "-" in standard output, the istrip setting is enabled.

The following example shows "istrip" with the correct setting:



If istrip appears without the dash (-) you must edit the login script file and add the line stty -istrip.

Note: If you use the setting that elevates user permissions to root, the istrip setting will be overwritten in the login script of the root user. Make sure that the istrip setting is disabled in the login script of the root user.

Return codes

The General Command Plug-in generates the following return codes:

Return Code Description
0-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 command or script is 64 or higher, 64 is returned as the return code of the plug-in.
65 The connection with the Ops Center Automator server failed. For example, the Ops Center Automator server might have stopped while the plug-in was running.
66 The following user is mapped to the Ops Center Automator 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 No information about the target job execution ID exists.
69 An environment variable of the task-processing engine cannot be acquired.
70 The connection with the operation target device failed.
71 Command execution failed.
72 The execution status of the command cannot be acquired.
76 The connection timed out.
77 The host name of the operation target device cannot be resolved.
78 Authentication with the operation target device failed for one of the following reasons:
  • Password authentication failed.
  • Public key authentication is not set up on the operation target device.
  • During authentication of the public key, the private key did not match the pass phrase.
  • During authentication of the public key, the private key did not correspond to the public key registered in the operation target device.
  • During authentication of the public key, a private key was used that is not valid.
80 Task execution has stopped.
81 The plug-in was called in a status that is not valid.
82 The request message from the task-processing engine cannot be correctly parsed.
83 The Ops Center Automator server environment is corrupted.
84 Information about the plug-in cannot be obtained.
86 The specified property value is not valid.
127 Another error occurred.

Property list

The following properties are available for the General Command plug-in:

Property key Property name Description I/O type
destinationHost R Destination Host Specify the IPv4 address, IPv6 address, or host name of the operation target device. The host name cannot exceed 1,024 characters. The Ops Center Automator server and the operation target device must be connected by a network. Note that multiple IP addresses or host names cannot be specified. Input
credentialType R 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 Agentless Remote Connections view. Specifying destination applies the authentication information set for Windows or SSH in the connection destination definition according to the IP address of the Ops Center Automator logon 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
account User ID Specify the user ID to use to log on 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
password Password Specify the password to use to log on to the operation target device, using a maximum of 256 characters. You can omit this property when the operation target device is running Linux OS and true is specified for the publicKeyAuthentication property. Input
suPassword Root Password If the OS of the operation target device is Linux OS, 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
runAsSystem Run As System Account When running on a Windows host, you can specify true to run the command using the system account or false to allow the command to run using another connected user. The connected user becomes the user specified for Agentless Remote Connections or plug-in properties, regardless of the specification of this property. The values are not case sensitive. If you do not specify a value, false is assumed. If the OS of the destination host is not Windows, this value is ignored.

The default value is false.

Input
publicKeyAuthentication SSH public key authentication settings If the OS of the operation target device is Linux OS, 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 or keyboard interactive authentication.

The default value is false.

Input
keyboardInteractiveAuthentication SSH keyboard interactive authentication settings Controls whether to use SSH keyboard interactive authentication for the Linux OS environment. If the OS of the destination is Linux OS, the system toggles between using and not using keyboard interactive authentication. If the property is set to true, keyboard interactive authentication is used. If the property is set to false, keyboard interactive authentication is not used. This property is not case-sensitive. This property is valid only when publicKeyAuthentication is set to false. If this property does not exist (which is true for a previous plug-in version) or if no value is specified, false is assumed for the property.

The default value is false.

Input
elevatePrivileges Elevate Privileges If the OS of the operation target device is Linux, 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 run commands as a user with root privileges.
false
Specify this option to run commands without elevating the user to root. Commands are run with the privileges of the connection user.

The default value is false.

Input
commandLine R Command Line Specify the absolute path of the command or script to be run on the operation target device, using a maximum of 256 characters. In Windows, the execution user is changed according to the specification of the plug-in property "runAsSystem". 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 Linux OS. The command or script is run 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 run with the privileges of the user set in the Agentless Remote Connections view.
  • If property is specified for the credentialType property, the command is run with the privileges of the user specified in the account property.

When the operation target device is running Linux OS

  • If destination is specified for the credentialType property, the command is run with the privileges of the root user or the user set in the Agentless Remote Connections view, depending on the value of the elevatePrivileges property.
  • If property is specified for the credentialType property, the command is run with the privileges of the root user or the user specified in the account property, depending on the value of the elevatePrivileges property.
Input
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 Ops Center Automator server and the operation target device. Special characters that represent environment variables in the command line are not scaped. To handle a special character as a character string, escape the character with a percent sign (%) in Windows, and a backslash (\) in Linux OS. 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 Linux OS:

$ environment-variable

Input
outputCondition Output Condition Specifies a condition to be output to the standard output property 1-3. You can specify the following values:
  • always -- Outputs a null character even if it does not match the specified pattern.
  • patternMatch -- Outputs only when matching the standard output pattern 1-3.

If there is no output in output properties, mapped service properties are also not updated.

The default value is Always.

Input
stdoutProperty1 Standard Output Property 1 The character string extracted by the stdoutPattern1 property is output to this property. Output
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
stdoutProperty2 Standard Output Property 2 The character string extracted by the stdoutPattern2 property is output to this property. Output
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
stdoutProperty3 Standard Output Property 3 The character string extracted by the stdoutPattern3 property is output to this property. Output
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
R: Required

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 Ops Center Automator. 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. Run 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 run on the operation target device. Therefore, the result of this action might differ from the result if the same command and script were run from the command prompt.

If the operation target device is running Linux OS, 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.


Data flow when specifying aaabbb(.*) in stdoutPattern1.

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 priority of each method.

Priority Set in Property key Default value
1 Connection-destination properties file (connection-destination-name.properties) ssh.port --
2 Properties file (config_user.properties) ssh.port.number 22