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: 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	When the protocol is SSH, authentication with the operation target device failed for one of the following reasons: Password authentication failed. Public key authentication has not been set up on the operation target device. When the public key was being authenticated, the private key did not match the pass phrase. When the public key was being authenticated, the private key did not correspond to the public key registered in the operation target device. When the public key was being authenticated, an invalid private key was used.
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. Keyboard interactive authentication 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 SSH	Telnet	Input	O
`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 (user ID, password, and administrator password) set in the Connection Destinations area. Specifying `destination` applies the authentication information set in the connection destination for Telnet or SSH according to the IP address of the logged-in JP1/AO user. You can omit the specification of properties relating to authentication information (`account`, `password`, `suPassword`, `publicKeyAuthentication`, or `keyboardInteractiveAuthentication`). `property` Specify this option to use the values specified in the following properties as authentication information: `account` `password` `suPassword` `publicKeyAuthentication` keyboardInteractiveAuthentication	--	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: `SSH` is specified in the `protocol` property. `property` is specified in the `credentialType` property.	--	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: `SSH` is specified in the `protocol` property. `property` is specified in the `credentialType` property. false is specified in the publicKeyAuthentication property. 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. true Specify this option to use public key authentication. false Specify this option to not use public key authentication.^#1	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`. true Specify this value to use keyboard interactive authentication. false Specify this value to not use keyboard interactive authentication.^#	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: `EUC-JP` `eucjp` `ibm-943C` `ISO-8859-1` `MS932` `PCK` `Shift_JIS` `UTF-8` `windows-31j`	--	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: `CR` `LF` `CRLF` 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 Values are always output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. Null characters are output if the standard output and standard error output do not match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties. patternMatch Values are output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties only if the standard output and standard error output match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties. If the standard output and standard error output do not match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, no values are output. In this case, values are not updated even if the service properties are mapped to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties.	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.

Figure 4‒3: Example of using the 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.

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:

Table 4‒8: Priority of information related to plug-in properties
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	--
Character set name^#	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
4.2.9 Terminal command plug-in
4.2.10 Terminal disconnect plug-in
A.2 List of protocols used by each plug-in
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

(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

[Figure]

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

[Figure]

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

To Page Top