Net::SSH2::Cisco - interact with a Cisco router via SSH
use Net::SSH2::Cisco; my $session = Net::SSH2::Cisco->new(host => '123.123.123.123'); $session->login('login', 'password'); # Execute a command my @output = $session->cmd('show version'); print @output; # Enable mode if ($session->enable("enable_password") ) { @output = $session->cmd('show privilege'); print "My privileges: @output\n"; } else { warn "Can't enable: " . $session->errmsg; } $session->close;
Net::SSH2::Cisco provides additional functionality to Net::SSH2 for dealing with Cisco routers in much the same way Net::Telnet::Cisco enhances Net::Telnet. In fact, this module borrows heavily from both of those excellent modules.
This module is basically a cut/paste of:
70% Net::Telnet
20% Net::Telnet::Cisco
5% Net::SSH2(::Channel)
5% original hack to make it all work together
I tried many ways first:
Create a child class of Net::SSH2 to no avail due to the C-type inside-out object it returns and my lack of experience.
Pass a Net::SSH2(::Channel) connection to Net::Telnet(::Cisco) fhopen() method, but it returned:
Not a GLOB reference at [...]/perl/vendor/lib/Net/Telnet.pm line 679.
Use Net::Telnet in @ISA with AUTOLOAD to leverage the accessors and code already written, but I'm not creating a Net::Telnet object and I couldn't get it to work.
@ISA
AUTOLOAD
That left me the (?only?) option - to write this Franken-module "liberally borrowing" from much smarter, more talented programmers than I.
Why Net::SSH2? Because it's the only SSH module on CPAN that works for me.
Net::SSH::Perl - too many dependencies making it too difficult to install; especially on Windows.
Net::OpenSSH - does not work on Windows (partial success).
Control::CLI - does a great job of being a parent to Net::SSH2 and Net::Telnet. Unfortunately, not Net::Telnet::Cisco, so no Cisco-specific enhancements.
Net::Appliance::Session - seemed promising, but has more dependencies than Net::SSH::Perl; no go.
Net::SSH2 comes bundled in vendor\lib with Strawberry Perl distributions and I've heard no complaints on Perl boards about use on *nix; so we're ready to go!
Before you use Net::SSH2::Cisco, you should have a good understanding of Net::SSH2, Net::Telnet and Net::Telnet::Cisco, so read their documentation first, and then come back here.
$obj = Net::SSH2::Cisco->new( [Always_waitfor_prompt => $mode,] # 1 [Autopage => $mode,] # 1 [Binmode => $mode,] # 0 [Blocking => $mode,] # 0 [Cmd_remove_mode => $mode,] # "auto" [Dump_Log => $file,] # '' [Family => $family,] # "ipv4" [Fhopen => $filehandle,] [Host => $host,] # "localhost" [Ignore_warnings => $mode,] # 0 [Input_log => $file,] # '' [Input_record_separator => $char,] # "\n" [Max_buffer_length => $len,] # 1,048,576 bytes (i.e., 1MB) [More_prompt => $matchop,] # '/(?m:^\s*--More--)/', [Normalize_cmd => $boolean,] # 1 [Output_field_separator => $chars,] # "" [Output_log => $file,] # '' [Output_record_separator => $char,] # "\n" [Port => $port,] # 22 [Prompt => $matchop,] # '/(?m:^(?:[\w.\/]+\:)?[\w.-]+\s?(?:\(config[^\)]*\))?\s?[\$#>]\s?(?:\(enable\))?\s*$)/' [Send_wakeup => $when,] # 0 [Timeout => $secs,] # 10 [Waitfor_clear => $mode,] # 0 [Waitfor_pause => $millisecs,] # 0.2 [Warnings] => $matchop,] # /(?mx:^% Unknown VPN |^%IP routing table VRF.* does not exist. Create first$ |^%No CEF interface information |^%No matching route to delete$ |^%Not all config may be removed and may reappear after reactivating )/ );
This is the constructor for Net::SSH2::Cisco objects. A new object is returned on success, failure returns undefined. The optional arguments are short-cuts to methods of the same name.
If the $host argument is given then the object is opened by connecting to TCP $port on $host. Also see connect(). The new object returned is given the defaults listed above.
connect()
$mode = $obj->always_waitfor_prompt; $mode = $obj->always_waitfor_prompt($mode);
If you pass a Prompt argument to cmd() or waitfor() a String or Match, they will return control on a successful match of your argument(s) or the default prompt. Set always_waitfor_prompt to 0 to return control only for your arguments.
This method has no effect on login(). login() will always wait for a prompt.
$mode = $obj->autopage; $mode = $obj->autopage($mode);
IOS pages output by default. It expects human eyes to be reading the output, not programs. Humans hit the spacebar to scroll page by page so autopage() mimics that behavior. This is the slow way to handle paging. Consider sending "terminal length 0" as the first cmd().
cmd()
$mode = $obj->binmode; $mode = $obj->binmode($mode);
This method controls whether or not sequences of carriage returns and line feeds (CR LF or more specifically "\015\012") are translated. By default they are translated (i.e. binmode is 0).
"\015\012"
0
If no argument is given, the current mode is returned.
If $mode is 1 then binmode is on and newline translation is not done.
1
If $mode is 0 then binmode is off and newline translation is done. In the input stream, each sequence of CR LF is converted to "\n".
"\n"
$mode = $obj->blocking; $mode = $obj->blocking($mode);
This method controls whether or not to enable blocking on the underlying Net::SSH2::Channel object created in connect().
blocking
$ok = $obj->close;
This method closes the object.
$ok = $obj->cmd($string); $ok = $obj->cmd( String => $string, [Output => $ref,] [Cmd_remove_mode => $mode,] [Errmode => $mode,] [Input_record_separator => $chars,] [Output_record_separator => $chars,] [Prompt => $match,] [Timeout => $secs,] [Waitfor_clear => $mode,] [Waitfor_pause => $millisecs,] ); @output = $obj->cmd($string); @output = $obj->cmd( String => $string, [Output => $ref,] [Cmd_remove_mode => $mode,] [Errmode => $mode,] [Input_record_separator => $chars,] [Output_record_separator => $chars,] [Prompt => $match,] [Timeout => $secs,] [Waitfor_clear => $mode,] [Waitfor_pause => $millisecs,] );
This method sends the command $string, and reads the characters sent back by the command up until and including the matching prompt. It's assumed that the program to which you're sending is some kind of command prompting interpreter such as a shell.
The command $string is automatically appended with the output_record_separator, by default it is "\n". This is similar to someone typing a command and hitting the return key. Set the output_record_separator to change this behavior.
In a scalar context, the characters read from the remote side are discarded and 1 is returned on success. On time-out, eof, or other failures, the error mode action is performed. See errmode().
errmode()
In a list context, just the output generated by the command is returned, one line per element. In other words, all the characters in between the echoed back command string and the prompt are returned. If the command happens to return no output, a list containing one element, the empty string is returned. This is so the list will indicate true in a boolean context. On time-out, eof, or other failures, the error mode action is performed. See errmode().
The characters that matched the prompt may be retrieved using last_prompt().
last_prompt()
Many command interpreters echo back the command sent. In most situations, this method removes the first line returned from the remote side (i.e. the echoed back command). See cmd_remove_mode() for more control over this feature.
cmd_remove_mode()
The Output named parameter provides an alternative method of receiving command output. If you pass a scalar reference, all the output (even if it contains multiple lines) is returned in the referenced scalar. If you pass an array or hash reference, the lines of output are returned in the referenced array or hash. You can use input_record_separator() to change the notion of what separates a line.
input_record_separator()
$mode = $obj->cmd_remove_mode; $mode = $obj->cmd_remove_mode($mode);
This method controls how to deal with echoed back commands in the output returned by cmd(). Typically, when you send a command to the remote side, the first line of output returned is the command echoed back. Use this mode to remove the first line of output normally returned by cmd().
If $mode is 0 then the command output returned from cmd() has no lines removed. If $mode is a positive integer, then the first $mode lines of command output are stripped.
By default, $mode is set to "auto". Auto means that whether or not the first line of command output is stripped, depends on whether or not it is matched in the first line of command output.
"auto"
$ok = $obj->connect($host); $ok = $obj->connect( [Fhopen => $filehandle,] [Host => $host,] [Port => $port,] [Family => $family,] [Timeout => $secs,] );
This method opens a TCP connection to $port on $host for the IP address $family. If $filehandle is provided, other options are ignored. If any of the arguments are missing then the current attribute value for the object is used. Specifying any optional named parameters overrides the current setting for this call to connect().
$filehandle
This essentially performs a Net::SSH2 connect() call.
$ok = $obj->disable;
This method exits the router's privileged mode.
$fh = $obj->dump_log; $fh = $obj->dump_log($fh); $fh = $obj->dump_log($filename);
This method starts or stops dump format logging of all the object's input and output. The dump format shows the blocks read and written in a hexadecimal and printable character format. This method is useful when debugging, however you might want to first try input_log() as it's more readable.
input_log()
If no argument is given, the log filehandle is returned. A returned empty string indicates logging is off.
To stop logging, use an empty string as an argument. The stopped filehandle is not closed.
If an open filehandle is given, it is used for logging and returned. Otherwise, the argument is assumed to be the name of a file, the filename is opened for logging and a filehandle to it is returned. If the filehandle is not already opened or the filename can't be opened for writing, the error mode action is performed.
NOTE: Logging starts after login so the initial login sequence (i.e., banner, username and password exchange) is not captured. This is due to Net::SSH2 not having a logging function.
$ok = $obj->enable; $ok = $obj->enable($password); $ok = $obj->enable( [Name => $name,] [Password => $password,] [Level => $level,] );
This method changes privilege level to enabled mode.
If a single argument is provided by the caller, it will be used as a password. Returns 1 on success and undef on failure.
$eof = $obj->eof;
This method returns 1 if end of file has been read, otherwise it returns an empty string.
$mode = $obj->errmode; $mode = $obj->errmode($mode);
This method gets or sets the action used when errors are encountered using the object. The first calling sequence returns the current error mode. The second calling sequence sets it to $mode. Valid values for $mode are "die" (the default), "return", a coderef or an arrayref.
"die"
"return"
When mode is "die" and an error is encountered using the object, then an error message is printed to standard error and the program dies.
When mode is "return" then the method generating the error places an error message in the object and returns an undefined value in a scalar context and an empty list in list context. The error message may be obtained using errmsg().
errmsg()
When mode is a coderef, then when an error is encountered coderef is called with the error message as its first argument. Using this mode you may have your own subroutine handle errors. If coderef itself returns then the method generating the error returns undefined or an empty list depending on context.
When mode is an arrayref, the first element of the array must be a coderef. Any elements that follow are the arguments to coderef. When an error is encountered, the coderef is called with its arguments. Using this mode you may have your own subroutine handle errors. If the coderef itself returns then the method generating the error returns undefined or an empty list depending on context.
A warning is printed to STDERR when attempting to set this attribute to something that is not "die", "return", a coderef, or an arrayref whose first element isn't a coderef.
$msg = $obj->errmsg; $msg = $obj->errmsg(@msgs);
The first calling sequence returns the error message associated with the object. The empty string is returned if no error has been encountered yet. The second calling sequence sets the error message for the object to the concatenation of @msgs. Normally, error messages are set internally by a method when an error is encountered.
$obj->error(@msgs);
This method concatenates @msgs into a string and places it in the object as the error message. Also see errmsg(). It then performs the error mode action. Also see errmode().
If the error mode doesn't cause the program to die, then an undefined value or an empty list is returned depending on the context.
This method is primarily used by this class or a sub-class to perform the user requested action when an error is encountered.
$family = $obj->family; $family = $obj->family($family);
This method designates which IP address family host() refers to, i.e. IPv4 or IPv6. IPv6 support is available when using perl 5.14 or later. With no argument it returns the current value set in the object. With an argument it sets the current address family to $family returns. Valid values are "ipv4" or "ipv6".
host()
"ipv4"
"ipv6"
This returns when attempting to set an invalid family or attempting to set "ipv6" when the Socket module is less than version 1.94 or IPv6 is not supported.
Note, Net::SSH2 does not support IPv6 natively, so setting "ipv6" requires IO::Socket::IP be installed.
$ok = $obj->fhopen($fh);
This method associates the open filehandle $fh with $obj for further I/O. Filehandle $fh must already be opened.
To support IPv6 in older versions of Net::SSH2, you may need to open an IO::Socket::IP object and pass that to connect(). In this module, Net::SSH2::Cisco takes care of IPv6 for you with the family() method by essentially doing the same thing in the background. If for some reason you're dropping this into existing code, you may already create your own IO object, so this allows for those existing instances.
family()
$host = $obj->host; $host = $obj->host($host);
This method designates the remote host for open(). It is either a hostname or an IP address. With no argument it returns the current value set in the object. With an argument it sets the current host name to $host. Use family() to control which IP address family, IPv4 or IPv6, hostnames should resolve to.
open()
It may also be set by new() or connect().
new()
$mode = $obj->ignore_warnings; $mode = $obj->ignore_warnings($mode);
Not all strings that begin with a '%' are really errors. Some are just warnings. By setting this, you are ignoring them.
$fh = $obj->input_log; $fh = $obj->input_log($fh); $fh = $obj->input_log($filename);
This method starts or stops logging of input. This is useful when debugging. Also see dump_log(). Because most command interpreters echo back commands received, it's likely all your output will also be in this log. Note that input logging occurs after newline translation. See binmode() for details on newline translation.
dump_log()
binmode()
$char = $obj->input_record_separator; $char = $obj->input_record_separator($char);
This method designates the line delimiter for input. It's used with cmd() to determine lines in the input.
With no argument this method returns the current input record separator set in the object. With an argument it sets the input record separator to $char. Note that $char must have length.
Alias:
$ok = $obj->ios_break; $ok = $obj->ios_break($char);
Send an IOS break. This is sent without a newline. Optional $char appends. For example, no argument sends "Control-^". Argument "X" effectively sends "Control-Shift-6-X".
$ok = $obj->is_enabled;
A trivial check to see whether we have a root-style prompt, with either the word "(enable)" in it, or a trailing "#".
Warning: this method will return false positives if the prompt has "#"s in it. You may be better off calling $obj->cmd("show privilege") instead.
$obj->cmd("show privilege")
$cmd = $obj->last_cmd;
This method returns the last command executed by cmd().
$prompt = $obj->last_prompt;
This method returns the last prompt read by cmd(). See prompt().
prompt()
$ok = $obj->login($username, $password); $ok = $obj->login( [Name => $username,] [Password => $password,] [Timeout => $secs,] );
This method performs a login with Net::SSH2 authentication methods. Currently, only auth_password is supported.
auth_password
Upon successful connection, a Net::SSH2::Channel object is created and:
blocking() is called on the channel
blocking()
shell() from Net::SSH2::Channel is opened
shell()
binmode() is called on the channel
The first prompt (see prompt())is read off.
Must be connected by calling new or connect first.
new
connect
$len = $obj->max_buffer_length; $prev = $obj->max_buffer_length($len);
This method designates the maximum size of the input buffer.
With no argument, this method returns the current maximum buffer length set in the object. With an argument it sets the maximum buffer length to $len. Values of $len smaller than 512 will be adjusted to 512.
A warning is printed to STDERR when attempting to set this attribute to something that isn't a positive integer.
$matchop = $obj->prompt; $matchop = $obj->prompt($matchop);
Match prompt for paging used by autopage().
autopage()
$mode = $obj->normalize_cmd; $mode = $obj->normalize_cmd($mode);
IOS clears '--More--' prompts with backspaces (e.g., ^H). If you're excited by the thought of having raw control characters like ^H (backspace), ^? (delete), and ^U (kill) in your command output, turn this feature off.
Logging is unaffected by this setting.
See waitfor_clear()
waitfor_clear()
See connect().
$chars = $obj->output_field_separator; $prev = $obj->output_field_separator($chars);
This method designates the output field separator for print(). Ordinarily the print method simply prints out the comma separated fields you specify. Set this to specify what's printed between fields.
print()
With no argument this method returns the current output field separator set in the object. With an argument it sets the output field separator to $chars.
$fh = $obj->output_log; $fh = $obj->output_log($fh); $fh = $obj->output_log($filename);
This method starts or stops logging of output. This is useful when debugging. Also see dump_log(). Because most command interpreters echo back commands received, it's likely all your output would also be in an input log. See input_log(). Note that output logging occurs before newline translation. See binmode() for details on newline translation.
$char = $obj->output_record_separator; $char = $obj->output_record_separator($char);
This method designates the output line delimiter for cmd().
The output record separator is set to "\n" by default, so there's no need to append all your commands with a newline.
With no argument this method returns the current output record separator set in the object. With an argument it sets the output record separator to $char.
$port = $obj->port; $port = $obj->port($port);
This method designates the remote TCP port for open(). With no argument this method returns the current port number. With an argument it sets the current port number to $port.
$ok = $obj->print(@list);
This method writes @list followed by the output_record_separator to the open object and returns 1 if all data was successfully written. On time-out or other failures, the error mode action is performed. See errmode().
By default, the output_record_separator() is set to "\n" so all your commands automatically end with a newline. In most cases your output is being read by a command interpreter which won't accept a command until newline is read. This is similar to someone typing a command and hitting the return key. To avoid printing a trailing "\n" use put() instead or set the output_record_separator to an empty string.
output_record_separator()
put()
You may also use the output field separator to print a string between the list elements. See output_field_separator().
output_field_separator()
This method sets the pattern used to find a prompt in the input stream. It must be a string representing a valid perl pattern match operator. The methods login() and cmd() try to read until matching the prompt. They will fail if the pattern you've chosen doesn't match what the remote side sends.
login()
With no argument this method returns the prompt set in the object. With an argument it sets the prompt to $matchop.
For an explanation of the default prompt, see Net::Telnet::Cisco.
For an explanation of valid prompts and creating match operators, see Net::Telnet.
$ok = $obj->put($string); $ok = $obj->put( String => $string, [Binmode => $mode,] [Errmode => $errmode,] [Timeout => $secs,] );
This method writes $string to the opened object and returns 1 if all data was successfully written. This method is like print() except that it doesn't write the trailing output_record_separator ("\n" by default). On time-out or other failures, the error mode action is performed. See errmode().
$when = $obj->send_wakeup; $when = $obj->send_wakeup('connect'); $when = $obj->send_wakeup('timeout'); $when = $obj->send_wakeup('noflush'); $when = $obj->send_wakeup(0);
Note: This is provided only for compatibility with drop-in replacement in Net::Telnet::Cisco scripts. This has limited functionality in this module.
Some routers quietly allow you to connect but don't display the expected login prompts. This would send a newline in the hopes it spurs the routers to print something.
The issue is a Net::SSH2::Channel to send the newline over isn't opened until after login.
However, sometimes there is contention on who talks first. With non-blocking mode by default, if the router sends a prompt, it must be "flushed" from the channel before subsequent commands can be issues to the router. Using the 'noflush' argument skips this step during login.
$sock = $obj->sock;
Returns the underlying IO::Socket (::INET or ::IP) object for the Net::SSH2 connection or undefined if not yet connected. This allows for socket accessors to be called.
For example:
printf "Connected to %s:%s\n", $obj->sock->peerhost, $obj->sock-peerport;
$ssh2 = $obj->ssh2;
Returns the Net::SSH2 object created by connect().
$chan = $obj->ssh2_chan;
Returns the Net::SSH2::Channel object created by login().
$to = $obj->timed_out;
This method indicates if a previous read, write, or open method timed-out.
$secs = $obj->timeout; $secs = $obj->timeout($secs);
This method sets the timeout interval used when performing I/O or connecting to a port.
If $secs is 0 then time-out occurs if the data cannot be immediately read or written.
With no argument this method returns the timeout set in the object. With an argument it sets the timeout to $secs.
$ok = $obj->waitfor($matchop); $ok = $obj->waitfor( [Match => $matchop,] [String => $string,] [Binmode => $mode,] [Errmode => $errmode,] [Timeout => $secs,] [Waitfor_clear => $mode,] ); ($prematch, $match) = $obj->waitfor($matchop); ($prematch, $match) = $obj->waitfor( [Match => $matchop,] [String => $string,] [Binmode => $mode,] [Errmode => $errmode,] [Timeout => $secs,] [Waitfor_clear => $mode,] );
This method reads until a pattern match or string is found in the input stream. All the characters before and including the match are removed from the input stream.
In a list context the characters before the match and the matched characters are returned in $prematch and $match. In a scalar context, the matched characters and all characters before it are discarded and 1 is returned on success. On time-out, eof, or other failures, for both list and scalar context, the error mode action is performed. See errmode().
You can specify more than one pattern or string by simply providing multiple Match and/or String named parameters. A $matchop must be a string representing a valid Perl pattern match operator. The $string is just a substring to find in the input stream.
$mode = $obj->waitfor_clear; $mode = $obj->waitfor_pause($mode);
This issues an ios_break with "Z" (i.e., CTRL-Z) after a waitfor() timeout and performs a flush() on the Net::SSH::Channel before the read(). This tries to compensate for a call to waitfor that times out and potentially leaves stuff in the channel. For best effect, this should be set at an object property in new(), but can be set on a local basis in cmd() and waitfor().
ios_break
waitfor()
flush()
read()
waitfor
The default is '1' - meaning on. This complements the behavior of normalize_cmd().
normalize_cmd()
Why do this? For example, "show running-config" takes time while "Building configuration..." and that may time out if a timeout is set too small. But in non-blocking mode, the output may start and fill the channel after the return from waitfor and if terminal length is a finite value - like the default 24 - a 'MORE' prompt is waiting - regardless of whether autopage is enabled.
autopage
To address the possible above scenario, we can send an ios_break with "Z" (i.e., CTRL-Z) to cancel the 'MORE' prompt. Otherwise, the first character of the subsequent command (usually from cmd()) will "satisfy" the MORE prompt, "disappear" from the output and potentially cause a router error (% Invalid input detected at ...). See the following example:
R1#sh run "Building configuration..."
TIMEOUT OCCUR! However, non-blocking mode allows output to fill buffer in the background up to a 'MORE' prompt:
Current configuration : 9721 bytes ! upgrade fpd auto version 12.4 no service pad [... output truncated ...] clock summer-time EDT recurring no ip source-route --More--
The buffer now has the above in it. The next command "show version" is issued and the following happens:
R1#how version ^ % Invalid input detected at '^' marker.
Where did the "s" in "show version" go? It "satisfied" the 'MORE' prompt and returned the regular router prompt where the rest of the command "how version" was entered, run and generated an error. You can see this for yourself at a router console by trying:
terminal length 24 show run [DO NOT PRESS SPACE OR ENTER AT THE --MORE-- PROMPT] show version
Alternatively, try this, which is what waitfor_clear effectively does:
waitfor_clear
terminal length 24 show run [DO NOT PRESS SPACE OR ENTER AT THE --MORE-- PROMPT] [PRESS CTRL-Z KEY COMBINATION] show version
$millisecs = $obj->waitfor_pause; $millisecs = $obj->waitfor_pause($millisecs);
There is a timing issue between SSH write() and read() manifested in cmd() and enable. This adds a slight delay after sending the command and before reading the result to compensate. You should not have to change the default.
enable
$boolean = $obj->warnings; $boolean = $obj->warnings($matchop);
Not all strings that begin with a '%' are really errors. Some are just warnings. Cisco calls these the CIPMIOSWarningExpressions.
See the EXAMPLES sections of both Net::Telnet and Net::Telnet::Cisco.
Net::SSH2, Net::Telnet, Net::Telnet::Cisco
Jay Rogers - author of Net::Telnet
Joshua Keroes - author of Net::Telnet::Cisco
David B. Robins - author of Net::SSH2
Without all of their excellent work, this would not be possible.
This software is released under the same terms as Perl itself. If you don't know what that means visit http://perl.com/.
Copyright (c) 2015 Michael Vincent
http://www.VinsWorld.com
All rights reserved
To install Net::SSH2::Cisco, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::SSH2::Cisco
CPAN shell
perl -MCPAN -e shell install Net::SSH2::Cisco
For more information on module installation, please visit the detailed CPAN module installation guide.