Enables terminals to establish connections.
The Terminal Connect Plug-in allows you to connect to an operation target device by using Telnet or SSH and authenticate.
When connecting by Telnet, set the user ID and password as needed. For SSH connections, you can select password authentication, public key authentication, or keyboard interactive authentication as the authentication method. You must set the following information in the plug-in properties or from the Agentless Remote Connections view.
- Authentication method (password authentication, public key authentication or keyboard interactive authentication)
- Information required for password authentication (user ID and password)
- Information required for public key authentication (user ID)
- Information required for keyboard interactive authentication (user ID and password)
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, you must run the command in the terminal command plug-in that elevates the user to root privileges.
Prerequisites
- The plug-in uses the protocol specified in the protocol property to communicate with the Ops Center Automator server.
- When connecting by Telnet, the plug-in detects when the operation target device is prompting the operator for a user ID and password. Set one of the following files as needed. If you set both files, Ops Center Automator uses the values set in the connection-destination properties file (connection-destination-name.properties).
- telnet.prompt.account and telnet.prompt.password in the connection-destination properties file (connection-destination-name.properties)
-
plugin.terminal.prompt.account and plugin.terminal.prompt.password in the properties file (config_user.properties)
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.
- If the value output to standard output matches the regular expression pattern specified in the promptPattern property, the plug-in ends immediately.
- After using Telnet to establish a connection to an operation target device, the plug-in waits for standard output and standard error output for the length of time set in the telnet.connect.wait property in the properties file (config_user.properties). If the connection destination service is a Web server or other entity that does not produce standard output or standard error output, set the port number of the service in the telnet.noStdout.port.list property of the connection-destination properties file (connection-destinationname.properties). If you set the port number, the plug-in finishes executing without waiting for standard output or standard error output.
- 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 terminal connect plug-in finishes. 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 a Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.
- The terminal connect plug-in maintains the connection even if Telnet authentication fails. To ebd the connection, you must run a terminal disconnect plug-in. However, if the task enters Failed or Completed status, the connection ends automatically and you do not must run the terminal disconnect plug-in.
- The standard output and standard error output of a terminal connect 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.
- The terminal connect plug-in cannot detect authentication errors in Telnet connections. For this reason, specify a regular expression pattern that detects authentication errors in standard output and standard error output in any of stdoutPattern1 to stdoutPattern3.
- 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 Connect Plug-in generates the following return codes:
| Return Code | Description |
|---|---|
| 0 - 63 | If standard output or standard error output matches the regular expression pattern specified in the returnCodePattern property, the plug-in returns the return code specified in the returnCode property. If standard output and standard error output do not match the pattern specified in the returnCodePattern property, 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:
|
| 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. |
| 76 | The connection timed out. |
| 77 | The host name of the operation target device cannot be resolved. |
| 78 | When connecting by SSH, authentication on 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 maximum number of tokens (99 per task) has been reached. The total standard output and standard error output has exceeded 100 KB. |
| 127 | Another error has occurred. |
Property list
The following properties are available for the Terminal Connect Plug-in:
| Property key | Property name | Description | I/O type | Required |
|---|---|---|---|---|
| destinationHost | Destination Host | Specify the IPv4 address, IPv6 address, or host name of the operation target device using no more than 1,024 characters. Multiple IP addresses or host names cannot be specified. | Input | true |
| protocol | Protocol | Specify the protocol to use when connection to the operating target device. You can specify the following protocols:
The default is Telnet. |
Input | false |
| 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 Agentless Remote Connections view. Specifying destination applies the authentication information set for Telnet or SSH in the connection destination definition according to the IP address of the Ops Center Automator 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:
|
Input | true |
| account | User ID | Specify the user ID to use to log on to the operation target device, using a maximum of 256 characters. This property is required if both of the following are true:
|
Input | false |
| password | Password | Specify the password to use to log on to the operation target device, using a maximum of 256 characters. This property is required if all of the following conditions are met:
If the OS of the operation target device is Linux and true is specified for the publicKeyAuthentication property, any value you specify is ignored. You can, however, set a value for the reserved.terminal.password reserved property to reference. |
Input | false |
| suPassword | Administrator Password | Specify the password required to elevate the user to root privilege, using a maximum of 256 characters. The value of the suPassword property is assigned to the reserved.terminal.suPassword property when you specify the latter in the command line or a terminal command plug-in. | Input | false |
| publicKeyAuthentication | SSH public key authentication settings | If the OS of the operation target device is Linux, 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 or keyboard interactive authentication. The default is false. |
Input | false |
| 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 is false. |
Input | false |
| Port | Port Number | Specify the port number to use when connecting to the operating target device. | 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:
|
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:
To use 0x0D as the newline character, specify CR. To use 0x0A, specify LF, and to use 0x0D0A, specify CRLF. The default 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 is 60000 |
Input | false |
| token | Token String | The token string that identifies the session is output to this property. You can specify the character string output to this property in the token property of terminal command plug-ins and terminal disconnect plug-ins. | Output | false |
| outputCondition | Output Condition | Specifies a condition to be output to the standard output property 1-3. You can specify the following values:
If there is no output in output properties, mapped service properties are also not updated. The default is a;ways. |
Input | false |
| stdoutPattern1 | Standard Output Pattern 1 | Specify the regular expression pattern of the standard output and standard error output to output the stdoutProperty property, using a maximum of 1,024 characters. Specify the pattern in a PCRE-compliant format. If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded. |
Input | false |
| stdoutProperty1 | Standard Output Property 1 | The character string extracted by the stdoutPattern1 property is output to this property. | Output | false |
| stdoutPattern2 | Standard Output Pattern 2 | Specify the regular expression pattern of the standard output and standard error output to output the stdoutProperty property, using a maximum of 1,024 characters. Specify the pattern in a PCRE-compliant format. If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded. |
Input | false |
| stdoutProperty2 | Standard Output Property 2 | The character string extracted by the stdoutPattern2 property is output to this property. | Output | false |
| stdoutPattern3 | Standard Output Pattern 3 | Specify the regular expression pattern of the standard output and standard error output to output the stdoutProperty property, using a maximum of 1,024 characters. Specify the pattern in a PCRE-compliant format. If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded. |
Input | false |
| stdoutProperty3 | Standard Output Property 3 | The character string extracted by the stdoutPattern3 property is output to this property. | Output | 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 PCRE compliant 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 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.
Following is a 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.
Priority when plug-in properties are set in several locations
Information related to plug-in properties can also be set in a connection destination properties file (connection destination-name.properties) or the properties file (config_user.properties). When a value is set for a property in multiple locations, the following priority applies:
| Setting | Location | Property key | Priority | Default value |
|---|---|---|---|---|
| Telnet port number | Plug-in property | port | 1 | -- |
| Connection destination properties file (connection-destination-name.properties) | telnet.port | 2 | -- | |
| Properties file (config_user.properties) | telnet.port.number | 3 | 23 | |
| SSH port number | Plug-in property | port | 1 | -- |
| Connection destination properties file (connection-destination-name.properties) | ssh.port | 2 | -- | |
| Properties file (config_user.properties) | ssh.port.number | 3 | 22 | |
| Character set name | Plug-in property | charset | 1 | -- |
| Connection destination properties file (connection-destination-name.properties) | terminal.charset | 2 | -- |
If no value is set in the plug-in property or the connection destination properties file (connection-destination-name.properties), UTF-8 is set.
Usage examples of terminal connect plug-in
Example of judging Telnet authentication errors
The following describes an example of using plug-in properties to achieve the following processing:
- Return 0 when login is successful.
- Return 1 when login fails.
- When login is successful, store the date and time of the last login and information about the connection source in the stdoutProperty1 property.
The following table describes examples of the values you can specify in plug-in properties to achieve this processing.
| Property key | Example of specified value | Meaning of specified value |
|---|---|---|
| promptPattern | ^\[prompt\]|^Login incorrect | If the contents of standard output matches [prompt] or Login incorrect, the plug-in ends and determines the return code. |
| stdoutPattern1 | ^Last login:(.*) | The character string following Last login: in standard output is stored in the stdoutProperty1 property. |
| defaultReturnCode | 0 | If the contents of standard output do not match the value specified in the returnCodePattern property, 0 is returned. |
| returnCodePattern | ^ Login incorrect | If the contents of standard output match Login incorrect, 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 1. |
The following describes the function of a plug-in with the properties listed previously when it encounters the following standard output.
This is an example when the login is successful.
Because the contents of standard output match the value specified in the promptPattern property, the terminal connect plug-in determines the return code. In this case, because the standard output does not match the value specified in the returnCodePattern property, the plug-in returns code (0), the value specified in the defaultReturnCode property.
The character string extracted by the stdoutPattern1 property (Mon Mar 18 13:21:13 2013 fromServerA) is stored in the stdoutProperty1 property.
This is an example when the login fails.
Because the contents of standard output match the value specified in the promptPattern property, the return code of the terminal connect plug-in is determined. In this case, because the return code matches the value specified in the returnCodePattern property, the plug-in returns code (1), the value specified in the returnCode property.
Verifying whether an authentication error occurred when using SSH
When using SSH as the protocol, you can verify whether an authentication error has occurred by reviewing the return code of the terminal connect plug-in.
Authentication errors are detected using the authentication information set in the Agentless Remote Connections view or the authentication-related properties of the terminal connect plug-in (account, password, and publicKeyAuthentication). This process does not use the superuser password set in the Agentless Remote Connections view or the suPassword property of the terminal connect plug-in.
If an authentication error is detected, the plug-in returns code 78. Note that the return code of the plug-in will be 70 if destination is specified for the credentialType property and the authentication information in the Agentless Remote Connections view is set incorrectly.
Example of connecting to a service such as an HTTP server that does not produce standard output
The following describes an example of connecting to a service that does not produce standard output. This example assumes that 80 is specified in the telnet.noStdout.port.list property in the connection-destination properties file (connection-destination-name.properties).
In this case, the values specified in the following properties are ignored, and the plug-in returns code 0.
- credentialType
- account
- password
- suPassword
- publicKeyAuthentication
- keyboardInteractiveAuthentication
- charset
- lineEnd
- promptPattern
- readWaitTime
- stdoutPattern1 to stdoutPattern3
- defaultReturnCode
- returnCodePattern
- returnCode