NAME¶
Net::CLI::Interact - Toolkit for CLI Automation
VERSION¶
version 2.142720
PURPOSE¶
This module exists to support developers of applications and libraries which
must interact with a command line interface.
SYNOPSIS¶
use Net::CLI::Interact;
my $s = Net::CLI::Interact->new({
personality => 'cisco',
transport => 'Telnet',
connect_options => { host => '192.0.2.1' },
});
# respond to a usename/password prompt
$s->macro('to_user_exec', {
params => ['my_username', 'my_password'],
});
my $interfaces = $s->cmd('show ip interfaces brief');
$s->macro('to_priv_exec', {
params => ['my_password'],
});
# matched prompt is updated automatically
# paged output is slurped into one response
$s->macro('show_run');
my $config = $s->last_response;
DESCRIPTION¶
Automating command line interface (CLI) interactions is not a new idea, but can
be tricky to implement. This module aims to provide a simple and manageable
interface to CLI interactions, supporting:
- •
- SSH, Telnet and Serial-Line connections
- •
- Unix and Windows support
- •
- Reuseable device command phrasebooks
If you're a new user, please read the Tutorial. There's also a Cookbook and a
Phrasebook Listing. For a more complete worked example check out the
Net::Appliance::Session distribution, for which this module was written.
INTERFACE¶
new( \%options )¶
Prepares a new session for you, but will not connect to any device. On Windows
platforms, you
must download the "plink.exe" program, and
pass its location to the "app" parameter. Other options are:
- "personality => $name" (required)
- The family of device command phrasebooks to load. There is a built-in
library within this module, or you can provide a search path to other
libraries. See Net::CLI::Interact::Manual::Phrasebook for further
details.
- "transport => $backend" (required)
- The name of the transport backend used for the session, which may be one
of Telnet, SSH, or Serial.
- "connect_options => \%options"
- If the transport backend can take any options (for example the target
hostname), then pass those options in this value as a hash ref. See the
respective manual pages for each transport backend for further
details.
- "log_at => $log_level"
- To make using the "logger" somewhat easier, you can pass this
argument the name of a log level (such as "debug",
"info", etc) and all logging in the library will be enabled at
that level. Use "debug" to learn about how the library is
working internally. See Net::CLI::Interact::Logger for a list of the valid
level names.
- "timeout => $seconds"
- Configures a default timeout value, in seconds, for interaction with the
remote device. The default is 10 seconds. You can also set timeout on a
per-command or per-macro call (see below).
Note that this does not (currently) apply to the initial connection.
cmd( $command )¶
Execute a single command statement on the connected device, and consume output
until there is a match with the current
prompt. The statement is
executed verbatim on the device, with a newline appended.
In scalar context the "last_response" is returned (see below). In list
context the gathered response is returned as a list of lines. In both cases
your local platform's newline character will end all lines.
macro( $name, \%options? )¶
Execute the commands contained within the named Macro, which must be loaded from
a Phrasebook. Options to control the output, including variables for
substitution into the Macro, are passed in the %options hash reference.
In scalar context the "last_response" is returned (see below). In list
context the gathered response is returned as a list of lines. In both cases
your local platform's newline character will end all lines.
last_response¶
Returns the gathered output after the most recent "cmd" or
"macro". In scalar context all data is returned. In list context the
gathered response is returned as a list of lines. In both cases your local
platform's newline character will end all lines.
transport¶
Returns the Transport backend which was loaded based on the
"transport" option to "new". See the Telnet, SSH, or
Serial documentation for further details.
phrasebook¶
Returns the Phrasebook object which was loaded based on the
"personality" option given to "new". See
Net::CLI::Interact::Phrasebook for further details.
set_phrasebook( \%options )¶
Allows you to (re-)configure the loaded phrasebook, perhaps changing the
personality or library, or other properties. The %options Hash ref should be
any parameters from the Phrasebook module, but at a minimum must include a
"personality".
set_default_contination( $macro_name )¶
Briefly, a Continuation handles the slurping of paged output from commands. See
the Net::CLI::Interact::Phrasebook documentation for further details.
Pass in the name of a defined Contination (Macro) to enable paging handling as a
default for all sent commands. This is an alternative to describing the
Continuation format in each Macro.
To unset the default Continuation, call the
"clear_default_continuation" method.
logger¶
This is the application's Logger object. A powerful logging subsystem is
available to your application, built upon the Log::Dispatch distribution. You
can enable logging of this module's processes at various levels, or add your
own logging statements.
set_global_log_at( $level )¶
To make using the "logger" somewhat easier, you can pass this method
the name of a log
level (such as "debug", "info",
etc) and all logging in the library will be enabled at that level. Use
"debug" to learn about how the library is working internally. See
Net::CLI::Interact::Logger for a list of the valid level names.
FUTHER READING¶
Prompt Matching¶
Whenever a command statement is issued, output is slurped until a matching
prompt is seen in that output. Control of the Prompts is shared between the
definitions in Net::CLI::Interact::Phrasebook dictionaries, and methods of the
Net::CLI::Interact::Role::Prompt core component. See that module's
documentation for further details.
Actions and ActionSets¶
All commands and macros are composed from their phrasebook definitions into
Actions and ActionSets (iterable sequences of Actions). See those modules'
documentation for further details, in case you wish to introspect their
structures.
COMPOSITION¶
See the following for further interface details:
- •
- Net::CLI::Interact::Role::Engine
AUTHOR¶
Oliver Gorwits <oliver@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Oliver Gorwits.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.