/ 
Net-Telnet-Wrapper-0.1
River stage one • 1 direct dependent • 1 total dependent
/ Net::Telnet::Wrapper

NAME

Net::Telnet::Wrapper - wrapper or extension for Net::Telnet and Net::Telnet::Cisco

VERSION

version 0.1

SYNOPSIS

use Net::Telnet::Wrapper;

## connect to Cisco router and execute show version + show clock
my $w = Net::Telnet::Wrapper->new('device_class' => 'Cisco::IOS', -host => 'routerA');
eval {
	$w->login( 'name' => "mwallraf", 'passwd' => "<mypass>", 'Passcode' => "<mypass>");
	$w->enable( 'name' => "mwallraf", 'passwd' => "<mypass>", 'Passcode' => "<mypass>");
	$w->cmd('show version');
	$w->cmd('show clock');
};
die $@ if ($@);
print join("\n", @{$w->GetOutput()} );


## check if we're logged in to the router in enable mode
print "We are connected to the router in ", $w->get_mode(), " mode\n";


## check if www.google.com is working
my $w = Net::Telnet::Wrapper->new('device_class' => 'TCP::HTTP', -host => 'www.google.com');
eval {
#	print $w->cmd("GET /index.html HTTP/1.0\n\n");
#	or
	print $w->test_url("/index.html");
};
die $@ if ($@);

DESCRIPTION

A wrapper or extension for Net::Telnet and Net::Telnet::Cisco that adds some default procedures like multiple login attempts as well as output formatting, error checking etc.

The wrapper has templates or device classes defined for many devices like Cisco routers, switches, firewalls but also Nortel, Packeteer, Unix etc. It's possible to add templates for almost any application that listens on a TCP port. All templates can be found in the Device folder.

Net::Telnet::Wrapper is not a replacement for Net::Telnet(::Cisco) and has to be used exactly the same way with the same parameters etc. It does have a few additional parameters and procedures.

WHY USING Net::Telnet::Wrapper

I am already using Net::Telnet, why should I use Net::Telnet::Wrapper?

You can use the exact same code no matter to which kind of device you are connecting to.

No need to write any code anymore for trying to reconnect in case the first connection attempt fails.

It is possible to get all the output at once, even if you have executed many commands.

Create your own device templates and override the default L<Net::Telnet> procedures if needed.

If you are connecting to network devices you want to know if you are connected in login mode, enable mode
or config mode. This module keeps track of this and you can always ask for the current mode.

PROCEDURES

All Net::Telnet and Net::Telnet::Cisco procedures can be used as described in their own manpages. The following procedure are specific for this module.

new - create a new Net::Telnet::Wrapper object

This is the constructor. This inherits from Net::Telnet::new() and uses the same parameters in addition to the following parameters :

$obj = new Net::Telnet::Wrapper ( 'device_class' => '$Device::Type', '-device' => $device );

$obj = new Net::Telnet::Wrapper (
                                   '-device'       => '$host',
                                   ['device_class' => '$Device::Type',]
                                   ['retry_open'   => '3',]
                                   ['retry_login'  => '3',]
                                   ['retry_cmd'    => '3',]
                                   ['inherit_auto' => '1',]
                                   ['inherit_class' => 'Net::Telnet',]
                                );


device_class = specify the device type, default = Unix::General
               see SUPPORTED DEVICES for all default device class templates
               
-device = the device to connect to, THIS IS THE ONLY DIFFERENCE COMPARED TO NET::TELNET !

retry_open = how many times do you want to re-attempt to connect to a device if it fails

retry_login = how many times do you want to re-attempt to login to a device

retry_cmd = how many times to you want to re-attempt to execute a command

inherit_auto = By default all device class templates starting with 'Cisco' will inherit
               from Net::Telnet::Cisco.  All others will inherit from Net::Telnet.
               Disable this switch if you want to override this and specify your own
               inheritance.
               
inherit_class = In case you disable inherit_auto then specify your own inheritance class.
get_device_class

Displays which device class we are using.

ex. print "device class = '",$w->get_device_class(),"\n";

This can show "Cisco::IOS" or "Unix::General" for example.

get_id

Every telnet session has its own unique id. This will show you the id.

get_mode

Returns the mode we are currently in. If are logged in then this will return LOGIN. See CONNECTION MODES for more info.

GetLastError

In case a problem occurred then this will show you the last error message.

GetOutput

This returns a reference to an array.

The array contains the output of each executed command.

ex. $w->cmd('show version'); $w->cmd('show clock'); print join("\n", @{$w->GetOutput()} );

The above will fill the output array with two elements. One element for each command.

IsSuccess

Returns true if the last function did not generate an error. Returns false otherwise, the error can then be retrieved with GetLastError()

login

This logs in to the device. It calls the default Net::Telnet::login procedure but catches any errors and re-attempts the login process in case of failure.

After logging in the _post_login commands are executed an by default this means that terminal paging is disabled if the device supports it. The terminal paging command is defined in the device class template files. Override the _post_login procedure in the template to change its behaviour.

enable

This enters the enable mode if the device supports it. It calls the default Net::Telnet::Cisco::enable procedure but catches any errors and re-attempts the enable process in case of failure.

After going to enable mode the _post_enable commands are executed an by default there are no post-enable commands defined. Override the _post_enable procedure in the template to change its behaviour.

config

This enters the config mode if the device supports it. It calls the default Net::Telnet::cmd procedure and executes the command needed to go to config mode. This command is defined in each device template. If needed it re-attempts to execute the command in case of failure.

Quit

Same as Net::Telnet::close()

Closes the telnet connection gently, meaning that if possible a logoff command is sent rather then just cutting of the TCP session.

CONNECTION MODES

Net::Telnet::Wrapper keeps track of the current connection mode you are in. There are 4 modes pre-defined but not all device types will support all of them.

This is mainly useful when connecting to network devices because usually you want to know if you have privileged or configuration commands enabled.

CONNECT

This is the mode you are in when you open a TCP port. For example when you do "telnet device" without logging in then you are in CONNECT mode. Connecting to a HTTP port for example will be in CONNECT mode as well.

LOGIN

After logging in to a device you are in LOGIN mode. This is the case for Unix servers, network devices etc.

ENABLE

Some network devices differentiate between privileged and non-privileged command sets. When you have access to privileged commands you will be in ENABLE mode. For Cisco this means entering the command "enable", for PacketShapers the command "touch" etc.

CONFIG

This is the mode when you are able to make configuration changes. For Cisco devices this means entering "config terminal".

SUPPORTED DEVICES - DEVICE CLASS

Templates -or device classes- for the supported devices can be found in the Devices folder. ex. For Cisco routers there is a module called Net::Telnet::Wrapper::Device::Cisco::IOS.

A template contains the default prompts for a device and specific logon or logoff commands etc.

Use the template name (ex. Cisco::IOS) as parameter when creating a new Net::Telnet::Wrapper object.

The following templates or device classes are known at this moment :

Cisco::IOS

Cisco devices based on IOS software.

Cisco::CATOS

Cisco switches based on CATOS

Cisco::ACNS

Cisco Cache Engines or Cisco Content Modules. All devices based on ACNS software.

Cisco::ASA

Cisco ASA firewalls.

Nortel::Contivity

Nortel Contivity switches, VPN concentrators.

Packeteer::PacketShaper

PacketShapers from Packeteer

TCP::HTTP

Connect to the HTTP port 80. Some additional procedures are defined in this template.

TCP::POP

Connect to the POP3 port 110. Default procedures are defined for logging in etc.

Unix::General

Connect to any general unix device. When using this template it is exactly the same as using Net::Telnet with default parameters.

ADDING DEVICES

New templates can be added. Just use the existing ones as example or start from the device class Template::New.

Basically it all comes down to defining the login modes (connect, login, enable, config) and the corresponding prompts.

If needed the default Net::Telnet procedures can be overriden in the templates, for example to define your custom login or logout procedure.

If you have created your own templates just let me know and I will add them to the distribution.

EXAMPLES

Check the test directory in the distribution for more examples or check http://www.2nms.com

Cisco router example
#!/usr/bin/perl

use strict;
use warnings;

use Net::Telnet::Wrapper;
use Data::Dumper;

my $w = Net::Telnet::Wrapper->new('device_class' => 'Cisco::IOS', -host => '10.131.128.1' );

eval {
	print "mode = ",$w->get_mode(),"\n";

	$w->login( 'name' => "mwallraf", 'passwd' => "<mypass>", 'Passcode' => "<mypass>");
	$w->enable( 'name' => "mwallraf", 'passwd' => "<mypass>", 'Passcode' => "<mypass>");

	$w->cmd('show version');

	print "mode = ",$w->get_mode(),"\n";
};
if ($@)  {
	die $@;
}

print @{$w->GetOutput()};

print "device class = '",$w->get_device_class(),"\n";
print "id = ",$w->get_id(),"\n";
print "test = ",$w->test(),"\n";
UNIX example
#!/usr/bin/perl

use strict;
use warnings;

use Net::Telnet::Wrapper;
use Data::Dumper;

my $w = Net::Telnet::Wrapper->new('device_class' => 'Unix::General', -host => 'linux1');

eval {
	print "MODE = ",$w->get_mode(),"\n";

	$w->login( 'name' => "mwallraf", 'passwd' => "<mypass>");

	$w->cmd('uname -a');

	print "MODE = ",$w->get_mode(),"\n";
};
if ($@)  {
	die $@;
}

print @{$w->GetOutput()};

print "device class = '",$w->get_device_class(),"\n";
print "id = ",$w->get_id(),"\n";
print "test = ",$w->test(),"\n";
HTTP example
#!/usr/bin/perl

use strict;
use warnings;

use Net::Telnet::Wrapper;
use Data::Dumper;

my $w = Net::Telnet::Wrapper->new('device_class' => 'TCP::HTTP', -host => 'www.google.com' );

eval {
	print "MODE = ",$w->get_mode(),"\n";

#	$w->cmd("GET /index.html HTTP/1.0\n\n");
#	or
	$w->test_url("/index.html");

	print "MODE = ",$w->get_mode(),"\n";
};
if ($@)  {
	die $@;
}

print @{$w->GetOutput()};

print "device class = '",$w->get_device_class(),"\n";
print "id = ",$w->get_id(),"\n";
print "test = ",$w->test(),"\n";
POP3 example
#!/usr/bin/perl

use strict;
use warnings;

use Net::Telnet::Wrapper;
use Data::Dumper;

my $w = Net::Telnet::Wrapper->new('device_class' => 'TCP::POP', -host => '<my mail server>' );

eval {
	print "MODE = ",$w->get_mode(),"\n";

	$w->pop_login("mwallraf", "<mypass>");
	my @count = $w->get_count_messages();
	print "There are $count[0] messages on the server\n";

	print "MODE = ",$w->get_mode(),"\n";
};
if ($@)  {
	die $@;
}

print @{$w->GetOutput()};

print "device class = '",$w->get_device_class(),"\n";
print "id = ",$w->get_id(),"\n";
print "test = ",$w->test(),"\n";

TODO

- add additional device class templates
- improve debug logging

CAVEATS

This is an extension to the existing Net::Telnet modules, all procedures are inherited so in case of problems check the forums for these modules first. Also do not forget to check the debugging part in the Net::Telnet doc.

Net::Telnet::Wrapper can be used in exactly the same way as the existing Net::Telnet modules, the major difference is that the prompts for many devices are pre-configured in separate device modules.

AUTHOR

Maarten Wallraf <perl@2nms.com>