.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Appliance::Session::APIv2 3pm"
.TH Net::Appliance::Session::APIv2 3pm "2012-06-12" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Appliance::Session::APIv2 \- Back\-compatibility with API version 2
.SH "VERSION"
.IX Header "VERSION"
version 3.121640
.SH "INTRODUCTION"
.IX Header "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.
.PP
You can choose either to keep things just as they are on your system, with
version 2 \s-1API\s0 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.
.SH "APIv2 Back-Compat Module"
.IX Header "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 \fImight\fR be sufficient for your
application to keep working. In your code, wherever you have \f(CW\*(C`use
Net::Appliance::Session\*(C'\fR, replace it with:
.PP
.Vb 1
\& use Net::Appliance::Session::APIv2;
.Ve
.PP
The effect is that a wrapper is placed around the version 3 \s-1API\s0 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 \s-1API\s0). The list
of missing features is:
.IP "\(bu" 4
Custom phrasebooks cannot be loaded (i.e. the \f(CW\*(C`Source\*(C'\fR param to \f(CW\*(C`new()\*(C'\fR
doesn't work)
.IP "\(bu" 4
The \f(CW\*(C`error()\*(C'\fR method is not implemented
.IP "\(bu" 4
Error strings in output from the device are not acted upon
.IP "\(bu" 4
All exceptions are of class \f(CW\*(C`Net::Appliance::Session::Exception\*(C'\fR
.IP "\(bu" 4
Exceptions probably don't contain the same amount of useful information
.SS "A note on error handling"
.IX Subsection "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 \s-1CLI\s0 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.
.PP
When automating a \s-1CLI\s0, this doesn't really make much sense. If a human makes a
mistake, the \s-1CLI\s0 shows an error. A computer-driven script should \fInever\fR 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 \f(CW\*(C`die\*(C'\fR with an error message.
.PP
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.
.SH "Porting to API Version 3"
.IX Header "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.
.SS "Method Parameter Passing"
.IX Subsection "Method Parameter Passing"
You must provide parameters to the \f(CW\*(C`new\*(C'\fR, \f(CW\*(C`connect\*(C'\fR, and \f(CW\*(C`begin_privileged\*(C'\fR
methods as a \fIhash reference with named parameters\fR. 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:
.PP
.Vb 5
\& my $s = Net::Appliance::Session\->new({
\&     personality => \*(Aqios\*(Aq,
\&     transport => \*(AqSSH\*(Aq,
\&     host => \*(Aqhostname.example\*(Aq,
\& });
\& 
\& eval {
\&     $s\->connect({ name => \*(Aqusername\*(Aq, password => \*(Aqloginpass\*(Aq });
\& 
\&     $s\->begin_privileged({ password => \*(Aqprivilegedpass\*(Aq });
\&     
\&     # etc.....
.Ve
.ie n .SS "Parameters to ""new"""
.el .SS "Parameters to \f(CWnew\fP"
.IX Subsection "Parameters to new"
As shown above, you can no longer provide a bare device host name, and nothing
else, to \f(CW\*(C`new\*(C'\fR. You \fImust\fR provide the \f(CW\*(C`hostname\*(C'\fR, \f(CW\*(C`transport\*(C'\fR and
\&\f(CW\*(C`personality\*(C'\fR.
.PP
The \f(CW\*(C`personality\*(C'\fR parameter is the direct equivalent of \f(CW\*(C`Platform\*(C'\fR in the
previous version 2 \s-1API\s0. The Transports on offer are the same (except they now
work on Windows natively \- no cygwin required).
.ie n .SS "Parameters to ""cmd"""
.el .SS "Parameters to \f(CWcmd\fP"
.IX Subsection "Parameters to cmd"
As before, you can pass in a single string statement which will be issued to
the connected \s-1CLI\s0, 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:
.PP
.Vb 2
\& my $config     = $s\->cmd(\*(Aqshow running\-config\*(Aq);
\& my @interfaces = $s\->cmd(\*(Aqshow interfaces brief\*(Aq);
.Ve
.PP
In addition, you can pass a Hash Reference as the \fIsecond\fR 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.
.SS "Custom Phrasebooks"
.IX Subsection "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.
.PP
Please see the comprehensive documentation for
Net::CLI::Interact::Phrasebook and the \f(CW\*(C`add_library\*(C'\fR 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.
.SS "Error and Exception Handling"
.IX Subsection "Error and Exception Handling"
As explained above, there are no longer any fancy exception objects, and
instead just simple Perl \f(CW\*(C`die\*(C'\fR calls when things go wrong. Typically this
will be a timeout in communications at the connected \s-1CLI\s0, or a bug in the
module code. Check out the example script included with this distribution for
a demonstration of handling these errors.
.SS "Troubleshooting"
.IX Subsection "Troubleshooting"
Whereas before you used the \f(CW\*(C`input_log\*(C'\fR method, please use the
\&\f(CW\*(C`set_global_log_at\*(C'\fR 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.
.PP
.Vb 1
\& $s\->set_global_log_at(\*(Aqdebug\*(Aq);
.Ve
.SS "Useful New Features"
.IX Subsection "Useful New Features"
See the extensive documentation of Net::Appliance::Session or the
underlying Net::CLI::Interact module for details. You have \fIa lot\fR more on
offer with the version 3 \s-1API\s0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Oliver Gorwits <oliver@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Oliver Gorwits.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.