NAME¶

Net::Appliance::Session::APIv2 - Back-compatibility with API version 2

VERSION¶

version 3.121640

INTRODUCTION¶

Version 3 of Net::Appliance::Session is a complete rewrite of the previous version and so all client code will need updating. This is not ideal, but is important for the module to survive, and have some much-requested features implemented. You can choose either to keep things just as they are on your system, with version 2 API client code and version 2 of the library. Or you can modify your code to be compatible with version 3 and install that newer version (recommended). Finally there is the option to have version 3 installed but use a simple compatibility layer to interface from version 2 client code.

APIv2 Back-Compat Module¶

If you have installed version 3 of the library but don't wish to update client code, this APIv2 Back-Compat Module might be sufficient for your application to keep working. In your code, wherever you have "use Net::Appliance::Session", replace it with:

 use Net::Appliance::Session::APIv2;

The effect is that a wrapper is placed around the version 3 API such that your version 2 client code should continue to work. Be aware that the author is not planning to add any features to this compatibility layer, and in fact some features are missing (those which cannot be mapped into the new API). The list of missing features is:

•

Custom phrasebooks cannot be loaded (i.e. the "Source" param to "new()" doesn't work)

•

The "error()" method is not implemented

•

Error strings in output from the device are not acted upon

•

All exceptions are of class "Net::Appliance::Session::Exception"

•

Exceptions probably don't contain the same amount of useful information

A note on error handling¶

A large part of the philosophy of earlier versions was that the module could identify certain error conditions at the CLI by the syntax used in output messages, and act accordingly. Together with that, client code was encouraged to capture exceptions and check for various conditions, exception types, and messages. When automating a CLI, this doesn't really make much sense. If a human makes a mistake, the CLI shows an error. A computer-driven script should never make a mistake - it will have been tested and developed. It's unnecessary overhead to check for errors all the time and attempt to recover. Of course, the remote device might still have a problem and report it, or die, but in that case version 3 of the module will still itself "die" with an error message. So any version 2 code you have which handles exceptions by class, and checks for Net::Appliance::Session::Exception will be okay, but other classes used in earlier versions are not supported in the compatibility layer.

Porting to API Version 3¶

The changes are not too severe - you should recognise all the method calls. Some features have been removed, and you will need to rewrite any custom phrasebooks. You should go through each of the following sections and make changes as required.

Method Parameter Passing¶

You must provide parameters to the "new", "connect", and "begin_privileged" methods as a hash reference with named parameters. There is no longer the option to have unnamed parameters as a bare list. Here is an example of how things must be, for each of these methods:

 my $s = Net::Appliance::Session->new({
     personality => 'ios',
     transport => 'SSH',
     host => 'hostname.example',
 });
 
 eval {
     $s->connect({ name => 'username', password => 'loginpass' });
 
     $s->begin_privileged({ password => 'privilegedpass' });
     
     # etc.....

Parameters to "new"¶

As shown above, you can no longer provide a bare device host name, and nothing else, to "new". You must provide the "hostname", "transport" and "personality". The "personality" parameter is the direct equivalent of "Platform" in the previous version 2 API. The Transports on offer are the same (except they now work on Windows natively - no cygwin required).

Parameters to "cmd"¶

As before, you can pass in a single string statement which will be issued to the connected CLI, followed by a carriage return. The method returns the complete response either in one Perl Scalar or an Array, depending on what you assign the result of the method call to:

 my $config     = $s->cmd('show running-config');
 my @interfaces = $s->cmd('show interfaces brief');

In addition, you can pass a Hash Reference as the second parameter, with some additional options. This includes a custom timeout for the command, custom Regular Expressions to match the completed response, and the option to suppress addition of a carriage return. See the Net::CLI::Interact::Role::Engine manual page for further details.

Custom Phrasebooks¶

Sadly it has not been possible to automatically import existing version 2 custom phrasebooks into the version 3 module. The built-in phrasebook is however still included, just as before. Please see the comprehensive documentation for Net::CLI::Interact::Phrasebook and the "add_library" method of this module, to see how to construct and install your custom phrasebook. There's also the Cookbook which gives examples of the new language.

Error and Exception Handling¶

As explained above, there are no longer any fancy exception objects, and instead just simple Perl "die" calls when things go wrong. Typically this will be a timeout in communications at the connected CLI, or a bug in the module code. Check out the example script included with this distribution for a demonstration of handling these errors.

Troubleshooting¶

Whereas before you used the "input_log" method, please use the "set_global_log_at" method instead, for similar dumping of communications (and more). There's actually much more powerful logging, if you check out the main Net::Appliance::Session manual pages.

 $s->set_global_log_at('debug');

Useful New Features¶

See the extensive documentation of Net::Appliance::Session or the underlying Net::CLI::Interact module for details. You have a lot more on offer with the version 3 API.

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.