4.2.8 Terminal connect plug-in
Function
This plug-in allows you to connect to an operation target device by using Telnet or SSH and perform authentication.
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 need to set the following information in the plug-in properties or in the Agentless Connection Destinations area.
-
Authentication method (password authentication, public key authentication, or keyboard interactive authentication)
-
Information required for password authentication or keyboard interactive authentication (user ID and password)
-
Information required for public key authentication (user ID)
The commands specified in the terminal command plug-in are executed with the privileges of the user authenticated by the terminal connect plug-in. To execute a command with administrator privileges, you need to execute the command in the terminal command plug-in that elevates the user to administrator privileges.
Prerequisites for execution
-
The plug-in uses the protocol specified in the protocol property to communicate with the JP1/AO server.
-
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.
-
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, JP1/AO uses the values set in the connection-destination property file (connection-destination-name.properties).
-
telnet.prompt.account and telnet.prompt.password in the connection-destination property file (connection-destination-name.properties)
-
plugin.terminal.prompt.account and plugin.terminal.prompt.password in the user-specified 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 appropriate 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 terminates 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 user-specified 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 property file (connection-destination-name.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.
-
If you forcibly terminate a task while the plug-in is running, reading from standard output and prompt detection are canceled and the task enters the Failed status. The session and token are then discarded. 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.
-
If the status of the subsequent step of the terminal connect plug-in is Failed, the Telnet or SSH connection is terminated. For this reason, if you use the Retry the Task From the Failed Step or Retry the Task From the Step After the Failed Step command to retry the task, the processing of the terminal command plug-in fails. However, this does not apply when retrying a repeated execution plug-in to which the terminal connect plug-in is subordinate.
-
The terminal connect plug-in maintains the connection even if Telnet authentication fails. To terminate the connection, you need to execute a terminal disconnect plug-in. However, if the task enters Failed or Completed status, the connection is terminated automatically and you do not need to execute 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 JP1/AO step. The size of the standard output and standard error output is the total number of bytes received by JP1/AO. 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.
Version
02.00.00
Tag
Terminal
Return codes
Return code |
Description |
---|---|
0 to 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 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 |
When the protocol is SSH, authentication with the operation target device failed for one of the following reasons:
|
69 |
An environment variable of the task-processing engine could not 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 could not 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 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. |
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 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 using no more than 1,024 characters. Multiple IP addresses or host names cannot be specified. |
-- |
Input |
R |
protocol |
Protocol |
Specify the protocol to use when connecting to the operation target device. You can specify the following protocols:
|
Telnet |
Input |
O |
credentialType |
Credentials Type |
As the authentication type to use during command or script execution, specify either of the following:
|
-- |
Input |
R |
account |
User ID |
Specify the user ID to use to log in to the operation target device, using a maximum of 256 characters. This property is required if both of the following are true:
|
-- |
Input |
O |
password |
Password |
Specify the password to use to log in 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 UNIX 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 |
O |
suPassword |
Administrator Password |
Specify the password required to elevate the user to administrator 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 of a terminal command plug-in. |
-- |
Input |
O |
publicKeyAuthentication |
SSH public key authentication setting |
If the OS of the operation target device is UNIX and the protocol is SSH, 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 applies. You can omit this property when the operation target device is running Windows.
|
false |
Input |
O |
keyboardInteractiveAuthentication |
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 |
port |
Port Number |
Specify the port number to use when connecting to the operation target device. |
-- |
Input |
O |
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 |
O |
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. |
CR |
Input |
O |
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 execute 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 |
R |
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). |
60000 |
Input |
O |
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 |
O |
outputCondition#2 |
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 |
stdoutPattern1 |
Standard Output Pattern 1 |
Specify the regular expression pattern of the standard output and standard error output to output to the stdoutProperty1 property, using a maximum of 1,024 characters. Specify the pattern in a PCRE-compliant format.#3 If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded. |
-- |
Input |
O |
stdoutProperty1 |
Standard Output Property 1 |
The character string extracted by the stdoutPattern1 property is output to this property. |
-- |
Output |
O |
stdoutPattern2 |
Standard Output Pattern 2 |
Specify the regular expression pattern of the standard output and standard error output to output to the stdoutProperty2 property, using a maximum of 1,024 characters. Specify the pattern in a PCRE-compliant format.#3 If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded. |
-- |
Input |
O |
stdoutProperty2 |
Standard Output Property 2 |
The character string extracted by the stdoutPattern2 property is output to this property. |
-- |
Output |
O |
stdoutPattern3 |
Standard Output Pattern 3 |
Specify the regular expression pattern of the standard output and standard error output to output to the stdoutProperty3 property, using a maximum of 1,024 characters. Specify the pattern in a PCRE-compliant format.#3 If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded. |
-- |
Input |
O |
stdoutProperty3 |
Standard Output Property 3 |
The character string extracted by the stdoutPattern3 property is output to this property. |
-- |
Output |
O |
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. |
0 |
Input |
O |
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 |
O |
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 |
O |
- #1
-
If you set false for both the publicKeyAuthentication and keyboardInteractiveAuthentication properties, password authentication is used.
- #2
-
This property is not available for plug-ins of versions earlier than 02.00.00. For versions earlier than 02.00.00, the system behaves as if patternMatch is specified. When plug-ins are updated to their latest versions, the value of this property will be reset to the default value (always). Reconfigure this property if necessary.
- #3
-
-
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.
|
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.
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 user-specified properties file (config_user.properties). When a value is set for a given 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 |
-- |
|
User-specified 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 |
-- |
|
User-specified 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 |
-- |
- Legend:
-
--: Blank by default.
- #
-
If no value is set in the plug-in property or the connection destination properties file (connection-destination-name.properties), UTF-8 is set.
Related topics
-
User-specified properties file (config_user.properties) and Connection-destination property file (connection-destination-name.properties) in the JP1/Automatic Operation Configuration Guide
-
Procedure to set public key authentication for SSH connections in the JP1/Automatic Operation Configuration Guide
- Organization of this subsection
(1) Example of using the terminal connect plug-in
Example of judging Telnet authentication errors
The following describes an example of using plug-in properties to realize 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 terminates 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 operation of a plug-in with the above properties when it encounters the following standard output:
- Example when 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 from ServerA) is stored in the stdoutProperty1 property.
- Example when 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.
Checking whether an authentication error has occurred when using SSH
When using SSH as the protocol, you can check 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 Connection Destinations area or the authentication-related properties of the terminal connect plug-in (account, password, publicKeyAuthentication, and keyboardInteractiveAuthentication). This process does not use the superuser password set in the Agentless Connection Destinations area 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 Connection Destinations area 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 property 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