Net-Appliance-Session-4.131260000755001750001750 012142003073 15766 5ustar00oliveroliver000000000000README100644001750001750 3325312142003073 16755 0ustar00oliveroliver000000000000Net-Appliance-Session-4.131260NAME Net::Appliance::Session - Run command-line sessions to network appliances VERSION version 4.131260 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 }); try { $s->connect({ username => 'username', password => 'loginpass' }); $s->begin_privileged({ password => 'privilegedpass' }); print $s->cmd('show access-list'); $s->end_privileged; } catch { warn "failed to execute command: $_"; } finally { $s->close; }; or, try the bundled "nas" helper script (beta feature!): nas --help 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 calls (except "close()") in a "try" block, to catch errors (typically time-outs waiting for CLI response). This module exports the "try/catch/finally" methods (from Try::Tiny) into your namespace as a simpler alternative to using "eval()". For a full 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. "timeout => $seconds" Configures a global 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). "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 (SSH, Telnet, Serial). "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 directory within which all your personalities are located, such as: ${directory}/cisco/ios/pb ${directory}/other/device/pb Usually the phrasebook files are called ""pb"" and to the "personality" option you pass the containing directory name, for example "ios" or "device" in the examples shown. See Net::CLI::Interact::Manual::Tutorial for further details. "nci_options => \%options" Should you wish to reconfigure the Net::CLI::Interact instance used inside of "Net::Appliance::Session", perhaps for an option not supported above, this generic setting is available. 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 }); begin_configure and end_configure $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 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 the display of a new prompt. This is typically most useful on Serial connected devices. Set this configuration option to zero to suppress this behaviour, or to the number of times "enter" should be pressed and output waited for. The default is to press "enter" once. 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('notice'); In place of "notice" you can have other log levels (e.g. "debug" for more, or "info" for less), and via the embedded Logger at "$s->nci->logger" it's possible to finely control the diagnostics. INTERNALS See Net::CLI::Interact. THANKS Over several years I have received many patches and suggestions for improvement from users of this module. My heartfelt thanks to all, for their contributions. AUTHOR Oliver Gorwits COPYRIGHT AND LICENSE This software is copyright (c) 2013 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. Changes100644001750001750 2475612142003073 17400 0ustar00oliveroliver000000000000Net-Appliance-Session-4.1312604.131260 2013-05-06 20:36:23 Europe/London * Minor fix for incorrect data type on timeout 4.131210 2013-05-01 21:45:36 Europe/London * Expose global timeout setting * Add nci_options setting for passing not-natively-supported options to NCI 4.122741 2012-09-30 15:05:51 Europe/London * Bug fix for info messages in nas script 4.122740 2012-09-30 14:35:47 Europe/London * RANCID .cloginrc support for nas script 4.122730 2012-09-29 23:56:37 Europe/London * Add scripting system bin/nas * Export Try::Tiny methods as better alternative to eval() * Update for the prompts named "prompt" which are now called "generic" * Improve documentation on use of custom phrasebook libraries 4.122630 2012-09-19 17:23:45 Europe/London * Port from Moose to Moo * Remove APIv2 back-compat module 3.122530 2012-09-09 15:54:04 Europe/London * should be checking for "user" prompt not macro! * alter default suggested log level to 'notice' 3.122100 2012-07-29 00:44:52 Europe/London * Support serial console servers where the console might be asleep (C. Tucker) 3.122010 2012-07-19 20:50:58 Europe/London * Try enable_paging and disable_paging macros before generic 'paging' (C. Tucker) * Add links to transport man pages in documentation. 3.121640 2012-06-12 23:24:42 Europe/London * Library version number is logged at instatiation. 3.121570 2012-06-05 19:56:02 Europe/London * Change async interface put() to be say() because of the auto-newline * If connection fails, the transport (ssh, telnet, etc) error is emitted * Do not run disconnect macro when connect fails (J. Whitten) 3.120580_001 2012-02-27 21:47:51 Europe/London * Implement async interface - put() and gather() (rt.cpan #75201) 3.120560 2012-02-25 17:20:36 Europe/London * fix POD typo and add NAME to APIv2 (C. Vicente) * fix Win32 path for plink.exe 3.113610 2011-12-27 00:54:02 Europe/London * New implementation of output parser. Note the following: For the cmd() and macro() methods: 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. 3.113600 2011-12-26 16:36:25 Europe/London * Issue disconnect macro if the phrasebook has one, on close() * Fix bug in privileged_password implementation (reported by Paul Niemi) 3.112610 2011-09-18 10:42:28 Europe/London * Add more tests for found bugs * Add note to POD about terminal width (Mathias) 3.112600 2011-09-17 14:24:53 Europe/London * Add test for pipe in command (V. Foitzik) 3.112510 2011-09-08 22:06:06 Europe/London * Added privileged_password option (J. Roth rt.cpan#69139) 3.112290 2011-08-17 20:16:43 Europe/London * Added native last_prompt (on request of G.Peirce) 3.112190 2011-08-07 22:20:13 Europe/London * Make add_library work (for scalar only) 3.111690 2011-06-18 08:24:15 Europe/London * Fix incorrect username accessor method name (cvicente rt.cpan #68897) * Loosen type constraint on connect_options (cvicente rt.cpan #68899) 3.111600 2011-06-09 11:08:43 Europe/London * Add delegation methods for Net::Telnet to APIv2 * Tidy and fix a couple of things in the example script 3.111590 2011-06-08 23:28:03 Europe/London * Implement v2 API compat layer 3.111530 2011-06-02 23:45:26 Europe/London * Ported to Net::CLI::Interact backend 2.111080 2011-04-18 10:13:04 Europe/London * Spot login auth failures, Steve C. (rt.cpan #67487) 2.110470 2011-02-16 19:23:54 Europe/London * Prevent close() unless already opened, Steve C. (rt.cpan #65453) 2.110090 2011-01-09 11:14:48 Europe/London * Fix bug in use of close_called, Steve C. (rt.cpan #64450) 2.103641 2010-12-30 21:28:09 Europe/London * Observe output_record_separator, thanks Steve C. (rt.cpan #55187) * Protect against death spiral in timeout/close, also Steve C. (rt.cpan #53796) * Implement privileged_pagin method to manage ASA/PIX 7+ - Paul Graydon (rt.cpan #63359) 2.103640 2010-12-30 20:54:56 Europe/London * Port to Dist::Zilla libnet-appliance-session-perl (1.36) UNRELEASED; urgency=low * Add import of WNOHANG symbol from POSIX (reported by Dominik Gehl) -- Oliver Gorwits Fri, 23 Jan 2009 08:32:13 +0000 libnet-appliance-session-perl (1.35) UNRELEASED; urgency=low * Fix again for imported POSIX symbols on CENTOS 5 (reported by Dominik Gehl) -- Oliver Gorwits Wed, 31 Dec 2008 12:10:22 +0000 libnet-appliance-session-perl (1.34) UNRELEASED; urgency=low * Fix pod to mention new supported devices (JUNOS, HP, Nortel) -- Oliver Gorwits Tue, 30 Dec 2008 22:45:48 +0000 libnet-appliance-session-perl (1.33) UNRELEASED; urgency=low * Mention enable_paging and disable_paging methods (RT#40783) * Do not import symbols from POSIX (reported by Dominik Gehl) -- Oliver Gorwits Tue, 30 Dec 2008 22:08:13 +0000 libnet-appliance-session-perl (1.32) UNRELEASED; urgency=low * Fix bug in Telnet with no username (RT.cpan #40229) thanks to mstefanov -- Oliver Gorwits Sat, 8 Nov 2008 21:12:38 +0000 libnet-appliance-session-perl (1.31) UNRELEASED; urgency=low * Move to using Module::Install * Update License to be same terms as Perl -- Oliver Gorwits Sat, 8 Nov 2008 17:08:58 +0000 libnet-appliance-session-perl (1.26) UNRELEASED; urgency=low * Make all method params case insensitive (requested by raimundh) (this follows what Net::Telnet does) -- Oliver Gorwits Tue, 2 Sep 2008 13:16:34 +0100 libnet-appliance-session-perl (1.25) UNRELEASED; urgency=low * Fix the buggy SIGCHLD handler (reported by Andrew D. Clark) -- Oliver Gorwits Sun, 17 Aug 2008 18:33:23 +0100 libnet-appliance-session-perl (1.24) UNRELEASED; urgency=low * Add use of FileHandle in the Transport - seems to be a 5.10 issue? -- Oliver Gorwits Fri, 18 Jul 2008 14:08:27 +0100 libnet-appliance-session-perl (1.23) UNRELEASED; urgency=low * Added support for debugging shell on failure, see Devel::REPL::Plugin::NAS -- Oliver Gorwits Tue, 3 Jun 2008 17:41:01 +0100 libnet-appliance-session-perl (0.22) UNRELEASED; urgency=low * Add disconnect method to Transport, as a noop except for Serial (see RT.cpan#35937) -- Oliver Gorwits Sat, 17 May 2008 20:28:32 +0100 libnet-appliance-session-perl (0.21) unstable; urgency=low * Send SIGKILL to child if we're running in cygwin * Minor fix to typo in Cookbook -- Oliver Gorwits Sat, 2 Feb 2008 19:12:28 +0000 libnet-appliance-session-perl (0.19) unstable; urgency=low * Bug fix for not setting last prompt (thx miky) * Minor change to docs to mention setting in_foo_mode -- Oliver Gorwits Sat, 19 Jan 2008 21:51:29 +0000 libnet-appliance-session-perl (0.18) unstable; urgency=low * Now automatically reap child processes -- Oliver Gorwits Sun, 23 Dec 2007 14:35:03 +0000 libnet-appliance-session-perl (0.17) unstable; urgency=low * Minor fixes to Cookbook POD to improve CPAN rendering. -- Oliver Gorwits Tue, 4 Dec 2007 21:08:00 +0000 libnet-appliance-session-perl (0.16) unstable; urgency=low * Add Cookbook courtesy of Nigel Bowden. -- Oliver Gorwits Tue, 4 Dec 2007 19:06:00 +0000 libnet-appliance-session-perl (0.15) unstable; urgency=low * Users report that the child reaping isn't stable across all systems, so revert to old system of doing nothing -- Oliver Gorwits Tue, 3 Jul 2007 16:40:00 +0100 libnet-appliance-session-perl (0.14) unstable; urgency=low * Allow SSH Transport to handle username prompts, suggestion courtesy of Nigel Bowden * Set Unix systems to automatically reap child processes -- Oliver Gorwits Tue, 3 Jul 2007 13:23:00 +0100 libnet-appliance-session-perl (0.13) unstable; urgency=low * Bug in my use of Class::Data::Inheritable. A schoolboy-error :( -- Oliver Gorwits Mon, 29 Jan 2007 16:48:00 +0000 libnet-appliance-session-perl (0.12) unstable; urgency=low * Bug in SSH Transport which would catch someone out one day -- Oliver Gorwits Sun, 28 Jan 2007 23:46:00 +0000 libnet-appliance-session-perl (0.11) unstable; urgency=low * Add CheckPB option to allow (almost) complete disabling of phrasebook entry checks * Separate out phrasebook entry checking in case not all required (e.g. not going to use configure mode) * Add special named argument to cmd() allowing operation more like Net::Telnet's waitfor() * Add Opts option to SSH Engine to support arbitrary openssh args -- Oliver Gorwits Sun, 28 Jan 2007 20:54:00 +0000 libnet-appliance-session-perl (0.09) unstable; urgency=low * Remove all hard-coded command phrases and prompt regexps, they are now pulled from the loaded phrasebook so can be overridden * Check all phrases are actually in the loaded phrasebook at instantiation time and die if any are not available * As a result, now require Net::Appliance::Phrasebook >= 0.07 * Allow user to disable login (user/pass) negotiation e.g. for public route servers * Also allow user to disable paging management, or override the number of lines used to re-enable paging * Also allow user to disable privileged and configure modes (see docs) * New Transport for Serial Line access, called 'Serial' (not tested much) * New Transport for Telnet access, called 'Telnet' (not tested much) * Factor out the IO::Pty code into Transport base class. Also checked it out, and it's actually pretty sane, so can stay in. -- Oliver Gorwits Tue, 14 Nov 2006 11:59:00 +0000 libnet-appliance-session-perl (0.05) unstable; urgency=low * Major rewrite - move Phrasebook out into Net::Appliance::Phrasebook - remove all the require guff and have it properly inheriting namespaces - rewrite Exception class into a module -- Oliver Gorwits Tue, 19 Sep 2006 18:16:17 +0100 libnet-appliance-session-perl (0.01) unstable; urgency=low * Initial Release. -- Oliver Gorwits Tue, 11 Jul 2006 18:16:17 +0100 bin000755001750001750 012142003073 16457 5ustar00oliveroliver000000000000Net-Appliance-Session-4.131260nas100755001750001750 1051212142003073 17345 0ustar00oliveroliver000000000000Net-Appliance-Session-4.131260/bin#!/usr/bin/env perl use strict; use warnings FATAL => 'all'; use lib './lib'; use Net::Appliance::Session::Scripting; Net::Appliance::Session::Scripting::run(); # ABSTRACT: Create Reusable Session Scripts # PODNAME: nas __END__ =pod =head1 NAME nas - Create Reusable Session Scripts =head1 VERSION version 4.131260 =head1 SYNOPSIS $ nas --help nas [options] [hostname or IP] -p, --personality Device (default: "ios") -t, --transport method (Serial, Telnet, default: SSH) -u, --username to connect as on device (default: $USER) -R, --record Record session -P, --playback Play back session -s, --script When recording, save playback script to this -l, --cmdlog NAS to record commands to, or play them back from -e, --exit-last Num. of output lines from last command is program exit status -c, --cloginrc RANCID cloginrc with device credentials -z, --nopassword Do not ask for device password (if not using cloginrc) -o, --echo Echo commands sent, when playing back the recorded script/cmdlog -M, --paging Do not attempt to disable command output paging -B, --nobanner Suppress display of any login banner received from the device -q, --quiet Hide informational messages -v, --verbose NCI log ("debug", "notice", "info", etc) -V, --version Display this program's version number -h, --help Display this help text =head1 DESCRIPTION Use this program to help write reusable L scripts, play them back, and also to more easily connect to network devices. =over 4 =item * Start a connection to a network device using CLI switches, and prompts for credentials. This is easier than writing short Perl programs. =item * Record a set of commands issued to one network device into a command log, then replay that log against other devices (C<< -R -l >> and C<< -P -l >>). =item * Record a session and produce a Perl script which when run, replays the session to the same host, or overridable to other devices (C<< -R -s