NAME¶
Net::Appliance::Session - Run command-line sessions to network appliances
VERSION¶
version 3.121640
IMPORTANT NOTE ABOUT UPGRADING FROM VERSION 2.x¶
Between version 2.x and 3.x of this module the programmer's interface changed in
a number of ways. If you have existing code to migrate to this new version,
please see the Upgrading document which details all steps necessary.
SYNOPSIS¶
use Net::Appliance::Session;
my $s = Net::Appliance::Session->new({
personality => 'ios',
transport => 'SSH',
host => 'hostname.example',
privileged_paging => 1, # only if using ASA/PIX OS 7+
# and there are other behaviour options, see below
});
eval {
$s->connect({ username => 'username', password => 'loginpass' });
$s->begin_privileged({ password => 'privilegedpass' });
print $s->cmd('show access-list');
$s->end_privileged;
};
if ($@) {
warn "failed to execute command: $@";
}
$s->close;
DESCRIPTION¶
Use this module to establish an interactive command-line session with a network
appliance. There is special support for moving into "privileged"
mode and "configure" mode, along with the ability to send commands
to the connected device and retrieve returned output.
There are other CPAN modules that cover similar ground, but they are less robust
and do not handle native SSH, Telnet and Serial Line connections with a single
interface on both Unix and Windows platforms.
Built-in commands come from a phrasebook which supports many network device
vendors (Cisco, HP, etc) or you can install a new phrasebook. Most phases of
the connection are configurable for different device behaviours.
METHODS¶
As in the synopsis above, the first step is to create a new instance.
Recommended practice is to wrap all other method calls in a Perl
"eval" block to catch errors (typically time-outs waiting for CLI
response). For a demonstration of usage, see the example script shipped with
this distribution.
Net::Appliance::Session->new( \%options )¶
my $s = Net::Appliance::Session->new({
personality => 'ios',
transport => 'SSH',
host => 'hostname.example',
});
Prepares a new session for you, but will not connect to any device. Some options
are required, others optional:
- "personality => $name" (required)
- Tells the module which "language" to use when
talking to the connected device, for example "ios" for Cisco IOS
devices. There's a list of all the supported platforms in the Phrasebook
documentation. It's also possible to write new phrasebooks.
- "transport => $backend" (required)
- The name of the transport backend used for the session,
which may be one of Telnet, SSH, or Serial.
- "app => $location" (required on Windows)
- On Windows platforms, you must download the
"plink.exe" program, and pass its location in this
parameter.
- "host => $hostname" (required for Telnet and
SSH transports)
- When using the Telnet and SSH transports, you must
provide the IP or host name of the target device in this parameter.
- "connect_options => \%options"
- Some of the transport backends can take their own options.
For example with a serial line connection you might specify the port
speed, etc. See the respective manual pages for each transport backend for
further details.
- "add_library => $directory"
- If you've added to the built-in phrasebook with your own
macros, then use this option to load your new phrasebook file(s). The path
here should be the root within which the personality is installed, such
as:
${directory}/cisco/ios/pb
connect( \%options )¶
$s->connect({ username => $myname, password => $mysecret });
To establish a connection to the device, and possibly also log in, call this
method. Following a successful connection, paging of device output will be
disabled using commands appropriate to the platform. This feature can be
suppressed (see "CONFIGURATION", below).
Options available to this method, sometimes required, are:
- "username => $name"
- The login username for the device. Whether this is required
depends both on how the device is configured, and how you have configured
this module to act. If it looks like the device presented a Username
prompt. and you don't pass the username a Perl exception will be thrown.
The username is cached within the module for possible use later on when
entering "privileged" mode.
- "password => $secret"
- The login password for the device. Whether this is required
depends both on how the device is configured, and how you have configured
this module to act. If it looks like the device presented a Username
prompt. and you don't pass the username a Perl exception will be thrown.
The password is cached within the module for possible use later on when
entering "privileged" mode.
- "privileged_password => $secret"
(optional)
- In the situation where you've activated "privileged
paging", yet your device uses a different password for privileged
mode than login, you'll need to set that other password here.
Otherwise, because the module tries to disable paging, it first goes into
privileged mode as you instructed, and fails with the wrong (login)
password.
begin_privileged and end_privileged¶
$s->begin_privileged;
# do some work
$s->end_privileged;
Once you have connected to the device, change to "privileged" mode by
calling the "begin_privileged" method. The appropriate command will
be issued for your device platform, from the phrasebook. Likewise to exit
"privileged" mode call the "end_privileged" method.
Sometimes authentication is required to enter "privileged" mode. In
that case, the module defaults to using the username and password first passed
in the "connect" method. However to either override those or set
them in case they were not passed to "connect", use either or both
of the following options to "begin_privileged":
$s->begin_privileged({ username => $myname, password => $mysecret });
$s->begin_configure;
# make some changes
$s->end_configure;
To enter "configuration" mode for your device platform, call the
"begin_configure" method. This checks you are already in
"privileged" mode, as the module assumes this is necessary. If it
isn't necessary then see "CONFIGURATION" below to modify this
behaviour. Likewise to exit "configure" mode, call the
"end_configure" method.
cmd( $command )¶
my $config = $s->cmd('show running-config');
my @interfaces = $s->cmd('show interfaces brief');
Execute a single command statement on the connected device. The statement is
executed verbatim on the device, with a newline appended.
In scalar context the response is returned as a single string. 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.
You can also call the "last_response" method which returns the same
data with the same contextual behaviour.
This method accepts a hashref of options following the $command, which can
include a "timeout" value to permit long running commands to have
all their output gathered.
To handle more complicated interactions, for example commands which prompt for
confirmation or optional parameters, you should use a Macro. These are set up
in the phrasebook and issued via the "$s->macro($name)" method
call. See the Phrasebook and Cookbook manual pages for further details.
If you receive response text with a "mangled" copy of the issued
command at the start, then it's likely you need to set the terminal width.
This prevents the connected device from line-wrapping long commands. Issue
something like:
$s->begin_privileged;
$s->cmd('terminal width 512');
close¶
$s->close;
Once you have finished work with the device, call this method. It attempts to
back out of any "privileged" or "configuration" mode
you've entered, re-enable paging (unless suppressed) and then disconnect.
If a macro named "disconnect" exists in the loaded phrasebook then
it's called just before disconnection. This allows you to issue a command such
as "exit" to cleanly log out.
CONFIGURATION¶
Each of the entries below may either be passed as a parameter in the options to
the "new" method, or called as a method in its own right and passed
the appropriate setting. If doing the latter, it should be before you call the
"connect" method.
- do_login
- Defaults to true. Pass a zero (false) to disable logging in
to the device with a username and password, should you get a command
prompt immediately upon connection.
- do_privileged_mode
- Defaults to true. If on connecting to the device your user
is immediately in "privieleged" mode, then set this to zero
(false), which permits immediate access to "configure"
mode.
- do_configure_mode
- Defaults to true. If you set this to zero (false), the
module assumes you're in "configure" mode immediately upon
entering "privileged" mode. I can't think why this would be
useful but you never know.
- do_paging
- Defaults to true. Pass a zero (false) to disable the
post-login reconfiguration of a device which avoids paged command output.
If you cleanly "close" the device connection then paging is
re-enabled. Use this option to suppress these steps.
- privileged_paging
- Defaults to false. On some series of devices, in particular
the Cisco ASA and PIXOS7+ you must be in privileged mode in order to alter
the pager. If that is the case for your device, call this method with a
true value to instruct the module to better manage the situation.
- pager_enable_lines
- Defaults to 24. The command issued to re-enable paging (on
disconnect) typically takes a parameter which is the number of lines per
page. If you want a different value, set it in this option.
- pager_disable_lines
- Defaults to zero. The command issued to disable paging
typically takes a parameter which is the number of lines per page (zero
begin to disable paging). If your device uses a different number here, set
it in this option.
- wake_up
- When first connecting to the device, the he most common
scenario is that a Username (or some other) prompt is shown. However if no
output is forthcoming and nothing matches, the "enter" key is
pressed, in the hope of triggering a new prompt. Set this configuration
option to zero (false) to suppress this behaviour.
ASYNCHRONOUS BEHAVIOUR¶
The standard, and recommended way to use this module is as above, whereby the
application is blocked waiting for command response. It's also possible to
send a command, and separately return to ask for output at a later time.
$s->say('show clock');
This will send the command "show clock" to the connected device,
followed by a newline character.
$s->gather();
This will gather and return output, with similar behaviour to "cmd()",
above. That is, it blocks waiting for output and a prompt, will timeout, and
accepts the same options.
You can still use "last_response" after calling "gather",
however be aware that the command (from "say") may be echoed at the
start of the output, depending on device and connection transport.
DIAGNOSTICS¶
To see a log of all the processes within this module, and a copy of all data
sent to and received from the device, call the following method:
$s->set_global_log_at('debug');
In place of "debug" you can have other log levels, and via the
embedded Logger at "$s->nci->logger" it's possible to finely
control the diagnostics.
INTERNALS¶
See Net::CLI::Interact.
THANKS¶
The following people have kindly reported bugs with patches or contributed to
the development in some other way:
- •
- Carlos Vicente
AUTHOR¶
Oliver Gorwits <oliver@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 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.