Terminal Command Plug-in

Ops Center Automator Service Builder User Guide

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

The Terminal Command Plug-in runs commands on the destination host that was connected to by using the Terminal Connect Plug-in.

Function

This plug-in allows you to run a specified command on an operation target device that is connected by using the terminal connect plug-in. The commands specified in the terminal command plug-in are run with the privileges of the user authenticated by the terminal connect plug-in. To run a command with root privileges, the terminal command plug-in must run the command that elevates the user to root privileges.

Prerequisites

  • The protocol specified in the protocol property of the terminal connect plug-in is used to communicate with the Ops Center Automator server.
  • A connection must have been established with the operation target device by a terminal connect plug-in.

Cautionary notes

  • The plug-in waits for standard output for the length of time specified in the readWaitTime property. If the time specified in readWaitTime elapses after output to standard output has ceased, plug-in execution ends in an error. Make sure that the value of the readWaitTime property is valid before using the plug-in. Any information output after the plug-in has timed out is discarded.
  • If the value output to standard output matches the regular expression pattern specified in the promptPattern property, the plug-in ends immediately.
  • If the command outputs information one page at a time, the system assumes that standard output has ceased. If the time specified in the readWaitTime property then passes, the plug-in ends with an error. Make sure that the command run by the terminal command plug-in is not configured to output results one page at a time.
  • Echoed command lines are also output to standard output. When needed, configure the command to not echo back.
  • If execution of a task is stopped during plug-in execution, the status of the task becomes Failed or Completed when the processing of the terminal command plug-in has finished. The session and token are then discarded. 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 Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.
  • The standard output and standard error output of the terminal command plug-in is output as the standard output of the Ops Center Automator step. The size of the standard output and standard error output is the total number of bytes received by Ops Center Automator. If the Telnet server or SSH server is configured to replace the linefeed character LF with CR+LF, allow two bytes for each linefeed character. The results of processing whose total standard output and standard error output exceeds 100 KB is outside the scope of product support. Make sure that the total standard output and standard error output does not exceed 100 KB.
  • If you intend to specify non-ASCII characters in the commandLine property, see General Command Plug-in.
  • When the Terminal Connect Plug-in version is less than 02.00.00, "patternMatch" is set in "outputCondition". But, the default value of "outputCondition" is "always" in the case of version 02.00.00. When you upgrade Terminal Connect Plug-in, keep this in mind.

Return codes

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

Return Code Description
0-63 If standard output and standard error output match the regular expression pattern specified in the returnCodePattern property, the plug-in returns the return code specified in the returnCode property. However, if the output does not match the pattern, the plug-in returns the return code specified in the defaultReturnCode property. Therefore, the meaning of the return code depends on the service template that is using 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 being run.
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.
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 environment of the Ops Center Automator server is corrupted.
84 Information about the specified plug-in cannot be obtained.
86 The specified property value is not valid.
87 Standard output and standard error output have timed out.
88 The total standard output and standard error output has exceeded 100 KB.
127 Another error has occurred.

Property list

The properties available for the Terminal Command Plug-in.

Property key Property name Description I/O type Required
token Token Specify the value of the token property of the terminal connect plug-in. Input true
commandLine Command Line Specify the absolute path of the command or script to be run on the operation target device, using a maximum of 1024 characters. In the command line, specify characters that can be entered in command lines in the OS of the Ops Center Automator server and the OS of 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 Linux OS.

If you must enter the superuser password in the command line to give the user root privileges, specify the reserved.terminal.suPassword reserved property. The reserved.terminal.account, reserved.terminal.password, and reserved.terminal.suPassword reserved properties reference token related authentication information set for the terminal connect plug-in. The specific authentication information the properties reference depends on the setting of the credentialType property of the terminal connect plug-in.

  • If destination is specified for the credentialType property, the reserved properties reference the authentication information defined in the connection destination.
  • If property is specified for the credentialType property, the reserved properties reference the authentication information specified in the credentialType property of the terminal connect plug-in.
Input false
charset Character Set Specify the character set to use when writing to the standard input of the operation target device and reading from standard output and standard error output. Specify the same character set as that of the user who logs in to the operation target. The names of character sets are not case sensitive. You can specify the following character sets:
  • EUC-JP
  • eucjp
  • ibm-943C
  • ISO-8859-1
  • MS932
  • PCK
  • Shift_JIS
  • UTF-8
  • windows-31j
Input false
lineEnd Newline Character When Telnet is specified in the protocol property of the terminal connect plug-in, specify the newline character to append to the values specified in the account and password properties. You can specify the following:
  • CR
  • LF
  • CRLF

To use 0x0D as the newline character, specify CR. To use 0x0A, specify LF, and to use 0x0D0A, specify CRLF.

The default value is CR.

Input false
promptPattern Prompt Pattern Specify the regular expression pattern to use to detect prompts in standard output and standard error output, using no more than 1,024 characters. This property is used to detect when the operation target device is ready to run commands after the connection is established. Specify the pattern in a PCRE-compliant format. When the output matches the specified regular expression pattern, the plug-in ends immediately. If the output does not match the pattern, the plug-in ends in an error when the time set in the readWaitTime property has elapsed since the last output to standard output or standard error output. Input true
readWaitTime Standard Output Wait Time When logging in to an operation target device, specify how long to wait after output to standard output or standard error output until the next output. Specify the timeout time in a range from 1 to 86,400,000 (in milliseconds).

The default value is 60000

Input false
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 false
stdoutProperty1 Standard Output Property 1 The character string extracted by the stdoutPattern1 property is output to this property. Output false
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 false
stdoutProperty2 Standard Output Property 2 The character string extracted by the stdoutPattern2 property is output to this property. Output false
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 false
stdoutProperty3 Standard Output Property 3 The character string extracted by the stdoutPattern3 property is output to this property. Output false
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 false
defaultReturnCode Default Return Code Specify the value to return as the return code when standard output and standard error output do not match the regular expression pattern specified in the returnCodePattern property. Specify a value in the range from 0 to 63.

The default is 0.

Input false
returnCodePattern Return Code Pattern Specify the regular expression pattern for standard output and standard error output, using a maximum of 1,024 characters. Specify the pattern in a PCREcompliant format. If standard output and standard error output match the specified pattern, the plug-in returns the value specified in the returnCode property. Input false
returnCode Return Code Specify the return code to be returned by the plug-in when standard output and standard error output match the pattern set in the returnCodePattern property. You can specify a value in the range from 0 to 63. If you omit this property, the plug-in returns the value specified in the defaultReturnCode property. Input false

Usage examples of terminal command plug-in

Example of terminating a terminal command plug-in with an error when an error is output to standard output

The following table describes an example of a terminal command plug-in that ends with an error when it acquires error-related information from standard output. Set the plug-in property as follows:

Property key Example of specified value Meaning of specified value
commandLine configServer arg0

arg1 arg2

Runs the specified command or script.
promptPattern ^\[prompt\] If the contents of standard output matches [prompt], the plug-in ends and determines the return value.
stdoutPattern1 ^Message:(.*) The character string following Message: in standard output is stored in the stdoutProperty1 property.
stdoutPattern2 ^Error:(.*) The character string following Error: in standard output is stored in the stdoutProperty2 property.
stdoutPattern3 ^ReturnCode:(.*) The character string following Returncode: in standard output is stored in the stdoutProperty3 property.
defaultReturnCode 0 If the contents of standard output do not match the value specified in the returnCodePattern property, return code 0 is returned.
returnCodePattern ^Error: If the contents of standard output match Error:, the plug-in returns the return code specified in the returnCode property.
returnCode 1 If the contents of standard output matches the value specified in the returnCodePattern property, the plug-in returns code 1.

The following describes the function of a plug-in with the previously listed properties when it encounters the following standard output.


Description of plug-in with previously listed properties encountering this standard output.

The contents of standard output match the value specified in the promptPattern property, so the terminal command plug-in determines which return code to return. Because standard output matches the value specified in the returnCodePattern property, the plug-in returns code (1), the value specified in the returnCode property.

The character strings extracted by the properties stdoutPattern1 to stdoutPattern3 are stored as follows in the properties stdoutPrpoerty1 to stdoutProperty3:

  • stdoutProperty1: command failed
  • stdoutProperty2: Permission Denied
  • stdoutProperty3: 128

Example of sending a GET request to an HTTP server

The following describes how to configure a plug-in that issues a request such as the following one to an HTTP server and verifies the response.


Configuring plug-in issuing request to HTTP server and verifying the response.

To issue a GET request to an HTTP server, specify each line of the request method and request header in the commandLine property of a terminal command plug-in.

Because the last line of the request needs to be blank, you must run the terminal command plug-in five times. The following table describes examples of the values to set in the properties of each instance of the plug-in.

Order of execution Value specified in the commandLine Value specified in the lineEnd Value specified in promptPattern
First GET /index.html HTTP/1.1 CRLF .*
Second Host: ServerA CRLF .*
Third User-Agent: Ops Center Automator CRLF .*
Fourth Accept-Charset: UTF-8 CRLF .*
Fifth -- (adds a blank line. Do not specify a value) CRLF .*

Because HTTP server requests use [CR]+[LF] as delimit characters, specify CRLF for the value specified in the lineEnd.

In the promptPattern property of the first to fourth terminal command plug-ins, you can specify regular expression patterns that also match blank characters.

Because standard output continues after you run the terminal command plug-ins, specify a regular expression that detects the end of standard output by the terminal command plug-ins in the promptPattern property.

The following describes the function of a plug-in with the previously listed properties when it encounters the following standard output:


Function of plug-in with previously listed properties and this standard output.

Because the contents of standard output match the value specified in the promptPattern property, the terminal command plug-in determines the return code.

If standard output matches the value specified in the returnCodePattern property, the return code specified in the returnCode property is returned as the return code of the plug-in.

If standard output does not match the value specified in the returnCodePattern property, the plug-in returns the return code specified in the defaultReturnCode property.