/ 
Mnet-5.06
River stage zero No dependents
/ Mnet::Expect::Cli

NAME

Mnet::Expect::Cli - Expect sessions to command line interfaces

SYNOPSIS

use Mnet::Expect::Cli;
my $opts = { spawn => "ssh 1.2.3.4", prompt => 1 };
my $expect = Mnet::Expect::Cli->new($opts);
my $output = $expect->command("ls");
$expect->close;

DESCRIPTION

This module can be used to create new Mnet::Expect::Cli objects, which inherit Mnet::Expect methods and have additional methods to handle logins, command execution, caching, and testing.

new

$expect = Mnet::Expect::Cli->new(\%opts)

This method can be used to create new Mnet::Expect::Cli objects.

The following input opts may be specified, in addition to options from the Mnet::Expect module:

delay           millseconds delay for command prompt detection
eol_unix        default true for output with unix /n eol chars only
failed_re       set to recognize failed logins, disabled by default
paging_key      default space key to send for pagination prompt
paging_re       default handles common prompts, refer to paging_re
password        set to password for spawned command, if needed
password_in     stderr prompt for stdin entry of password if not set
password_re     undef to skip password/passcode prompt detection
prompt_re       undef to skip cli prompt detect, refer to prompt_re
timeout         seconds for Expect restart_timeout_upon_receive
username        set to username for spawned command, if needed
username_re     undef to skip login/user/username promt detection

An error is issued if there are login problems.

For example, the following call will start an ssh expect session to a device:

my $opts = { spawn => "ssh 1.2.3.4", prompt => 1 };
my $expect = Mnet::Expect::Cli->new($opts);

Set failed_re to detect failed logins faster, as long as there's no conflict with text that appears in login banners. For example:

(?i)(closed|error|denied|fail|incorrect|invalid|refused|sorry)

Refer to the Mnet::Expect module for more information.

command

$output = $expect->command($command, $timeout, \@prompts)

This method returns output from the specified command from the current expect cli session, or undefined if there was a timeout.

The timeout input argument can be used to override the timeout for the current object. The prompts reference argument can be used to handle prompts that occur after entering a command, such as confirmation prompts. It should contain pairs of regex strings and responses. The regex string values should be what goes in between the forward slash characters of a regular expression. The response can be a string that is sent to the expect session without a carraige return, or may be a code reference that gets the current object and output as input args and returns a response string. An null prompt regex string is activated for timeouts. An undef prompt response causes an immediate return of output.

# sends $command, uses default timeout, defines some prompts
my $output = $expect->command($command, undef, [

    # send 1.2.3.4 if matched by expect -re /ip/
    'ip' => '1.2.3.4\r',

    # code ref
    'confirm? ' => sub { my $output = shift; return "y" },

    # returns prior output on timeout, might be undef
    undef => undef,

]);

Refer also to the command_cache_clear method for more info.

command_cache_clear

$expect->command_cache_clear

This method can be used to clear the cache used by the command method.

Normally the the command method caches the outputs for all executed commands, returning cached output when the same command is executed subsequently. When the cache is cleared the command method will execute the next instance of any specific command instead of returning cached output.

delay

$delay = $expect->delay($delay)

Get and/or set a new delay time in milliseconds for the current object. This delay is used when detecting extra command, prompt, or pagination output.

A good rule of thumb may be to set this delay to at least the round trip response time for the spawned process.

paging_re

$paging_re = $expect->paging_re($paging_re)

Get and/or set new paging_re for the current object.

Following are known pagination prompts covered by the default paging_re:

junos           =~ /^---\(more( \d\d?%)?\)---$/
cisco ASA       =~ /<--- More --->/
cisco ios       =~ /--more--/
cisco ios 15    =~ /--More--/

Following are other observed pagination prompts, not covered by default:

linux more cmd  =~ /--More--\(\d\d?%\)/

Note that matched pagination text is not appended to command output. Refer also to the command method for more information.

prompt_re

$prompt_re = $expect->prompt_re($prompt_re)

Get and/or set new prompt_re for the current object.

By default prompts that end with $ % # : > are recognized, and the first prompt detected after login is used as prompt_re for the resto of the expect session.

Note that prompt_re should start with a regex caret symbol and end with a regex dollar sign, to ensure it is accurately detected. Also the /Q and /E escape sequences do not appear to work in an expect regex.

timeout

$timeout = $expect->timeout($timeout)

Get and/or set a new timeout for the current object, refer to perldoc Expect.

TESTING

The Mnet::Opts::Cli and Mnet::Test --record and --replay command line options work with this module to record and replay command method outputs associated with various issued commands, integrated with the command_cache_clear method.

Refer to the Mnet::Test module for more information.

SEE ALSO

Expect

Mnet

Mnet::Expect

Mnet::Expect::Cli::Ios

Mnet::Test