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

Mnet::Expect::Cli can be used to spawn Expect processes, which can be used to programmatically control command line sessions to devices, with support for Mnet options, logging, caching, and testing.

Refer to the perl Expect module for more information. Also refer to the Mnet::Expct and Mnet::Expct::Cli::Ios modules.

METHODS

Mnet::Expect::Cli implements the methods listed below.

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 documented in the Mnet::Expect module new method:

    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 with host key checking disabled:

    my @spawn = qw(ssh);
    push @spawn, qw(-o StrictHostKeyChecking=no);
    push @spawn, qw(-o UserKnownHostsFile=/dev/null);
    push @spawn, qw(1.2.3.4);
    my $opts = { spawn => \@spawn, 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.

    # 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,

    ]);

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.

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 a response from the connected 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 in this module 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 the Expect module for more information.

TESTING

Mnet::Test --record and --replay command line options are supported by this module, and will record and replay command method outputs associated with calls to the command method, 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::Log

Mnet::Opts::Cli

Mnet::Test