Job Execution Strategy Interactive SSH

XTAM Server includes the facility to run a screen-scraping script on the remote server using SSH protocol called Interactive SSH.

Instead of connecting to a remote server and running a remote command on this server, the Interactive SSH strategy waits for the server prompt and types something in return.

  • Scripts for the Interactive SSH strategy contain multiple lines of expected prompt and resulting output that the strategy executes on the remote server.
  • Interactive SSH strategy is useful to implement status check, password reset or other custom automation logic on the remote devices with limiting scripting capabilities such as network routers, old Unix operating systems or custom devices with limiting shell.
  • Interactive SSH scripts are created in the Script Library as described in the following guide.
  • A record type or a record task list can include an Interactive SSH script like any other script in the system. Check Task Configuration guide.
  • System administrators can assign any task execution policies to an Interactive SSH script such as scheduled periodic policies (once a month, etc), event-based policies (after session, etc) or manual on-demand policies. Check system policy guide.

Interactive SSH script specification

Interactive SSH script contains multiple lines executed one after another one.

Each line is a pair or a triple of prompts separated with -> character in the following format

EXPECTED-PROMPT->OUTPUT

or

EXPECTED-PROMPT->OUTPUT->ERROR-CONDITION

Below is the example of version check on the remote Cisco router

>->show version

>->exit

The script reads:

  • open connection to the remote device;
  • wait for > prompt from the device;
  • type show version command;
  • wait for > prompt from the device;
  • type exit command that terminates the session.

XTAM job execution engine will capture the output of the script and present it in the job execution report in the Details field of the selected job.

When the Interactive SSH job execution strategy does not receive the expected prompt, it will abandon script execution with an Error status if the prompt does not appear after the timeout.

EXPECTED-PROMPT

EXPECTED-PROMPT is the prompt that the Interactive SSH strategy expects from the server to produce.

The EXPECTED-PROMPT could be a fixed string like in a Cisco example above or a regular expression started with the \r characters like in the example below.

The example waits for the $ or # prompts from the server before executing su - a command with the switch user on the record.

\r[$#]->su - {{SYSUSR}}

EXPECTED-PROMPT can also include terminal escape character in the form of \e characters.

The script in the example waits for the yellow # prompt from the server before executing shell commands.

# \e[0m->ls -alp

# \e[0m->echo completed

# \e[0m->exit

OUTPUT

OUTPUT is the string that the Interactive SSH strategy prints in response to the expected server prompt.

OUTPUT could be any command.

It can also include the following placeholders to represent the values in the record fields:

{{LOGIN}} - User on the record

{{OLDPWD}} - current Password on the record

{{NEWPWD}} - new password (generated or specified when running on-demand password reset)

{{SYSUSR}} - Switch User on the record

{{SYSPWD}} - Switch User Password on the record

{{SHADOW_LOGIN}} - Shadow User

{{SHADOW_PASSWORD}} - Shadow User Password

{{RECORD:FieldName}} - Values of custom fields on the record

{{SHADOW:FieldName}} - Values of custom fields on shadow record

$${User-Defined-Value} - the value specified by the operator executing the script on demand from the application GUI

ERROR-CONDITION

ERROR-CONDITION is a comma separated list of prompts from the execution of the previous command that causes the Interactive SSH strategy to abandon script execution.

The error conditions are useful to capture failures of the password reset to communicate the error back to the Interactive SSH strategy.

Return Result

Interactive SSH strategy captures the output from the remote device during the script execution, whites out the sensitive information such as passwords and stores the output in the Details of the job execution.

Interactive SSH strategy processes the script output to validate the job success.

Specifically, the script can use the following key sentences to communicate success or failure results back to the strategy so it will update logs and record with a new password accordingly.

Password Change Successful - Success

Password Change Unsuccessful - Error

Failure to wait for the expected character - Error

Failure to execute sequence - Error

XTAM Success - Success

xtam passwd error code: 0 - Success

ERROR - Error

command failed - Error