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.

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 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 unecessary 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.

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.

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.....

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).

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.

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 (Net::CLI::Interact::Manual::Cookbook) which gives examples of the new language.

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.

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');

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.