1Net::Appliance::SessionU(s3e)r Contributed Perl DocumentaNteito:n:Appliance::Session(3)
2
3
4

NAME

6       Net::Appliance::Session - Run command-line sessions to network
7       appliances
8

SYNOPSIS

10        use Net::Appliance::Session;
11
12        my $s = Net::Appliance::Session->new({
13            personality => 'ios',
14            transport => 'SSH',
15            host => 'hostname.example',
16            privileged_paging => 1, # only if using ASA/PIX OS 7+
17                                    # and there are other behaviour options, see below
18        });
19
20        try {
21            $s->connect({ username => 'username', password => 'loginpass' });
22
23            $s->begin_privileged({ password => 'privilegedpass' });
24            print $s->cmd('show access-list');
25            $s->end_privileged;
26        }
27        catch {
28            warn "failed to execute command: $_";
29        }
30        finally {
31            $s->close;
32        };
33
34       or, try the bundled "nas" helper script (beta feature!):
35
36        nas --help
37

DESCRIPTION

39       Use this module to establish an interactive command-line session with a
40       network appliance. There is special support for moving into
41       "privileged" mode and "configure" mode, along with the ability to send
42       commands to the connected device and retrieve returned output.
43
44       There are other CPAN modules that cover similar ground, but they are
45       less robust and do not handle native SSH, Telnet and Serial Line
46       connections with a single interface on both Unix and Windows platforms.
47
48       Built-in commands come from a phrasebook which supports many network
49       device vendors (Cisco, HP, etc) or you can install a new phrasebook.
50       Most phases of the connection are configurable for different device
51       behaviours.
52

METHODS

54       As in the synopsis above, the first step is to create a new instance.
55
56       Recommended practice is to wrap all other calls (except close()) in a
57       "try" block, to catch errors (typically time-outs waiting for CLI
58       response).  This module exports the "try/catch/finally" methods (from
59       Try::Tiny) into your namespace as a simpler alternative to using
60       eval().
61
62       For a full demonstration of usage, see the example script shipped with
63       this distribution.
64
65   Net::Appliance::Session->new( \%options )
66        my $s = Net::Appliance::Session->new({
67            personality => 'ios',
68            transport => 'SSH',
69            host => 'hostname.example',
70        });
71
72       Prepares a new session for you, but will not connect to any device.
73       Some options are required, others optional:
74
75       "personality => $name" (required)
76           Tells the module which "language" to use when talking to the
77           connected device, for example "ios" for Cisco IOS devices. There's
78           a list of all the supported platforms in the Phrasebook
79           documentation. It's also possible to write new phrasebooks.
80
81       "transport => $backend" (required)
82           The name of the transport backend used for the session, which may
83           be one of Telnet, SSH, or Serial.
84
85       "app => $location" (required on Windows)
86           On Windows platforms, you must download the "plink.exe" program,
87           and pass its location in this parameter.
88
89       "host => $hostname" (required for Telnet and SSH transports)
90           When using the Telnet and SSH transports, you must provide the IP
91           or host name of the target device in this parameter.
92
93       "timeout => $seconds"
94           Configures a global default timeout value, in seconds, for
95           interaction with the remote device. The default is 10 seconds. You
96           can also set timeout on a per-command or per-macro call (see
97           below).
98
99       "connect_options => \%options"
100           Some of the transport backends can take their own options. For
101           example with a serial line connection you might specify the port
102           speed, etc. See the respective manual pages for each transport
103           backend for further details (SSH, Telnet, Serial).
104
105       "add_library => $directory | \@directories"
106           If you've added to the built-in phrasebook with your own macros,
107           then use this option to load your new phrasebook file(s). The path
108           here should be the directory within which all your personalities
109           are located, such as:
110
111            ${directory}/cisco/ios/pb
112            ${directory}/other/device/pb
113
114           Usually the phrasebook files are called ""pb"" and to the
115           "personality" option you pass the containing directory name, for
116           example "ios" or "device" in the examples shown. See
117           Net::CLI::Interact::Manual::Tutorial for further details.
118
119       "nci_options => \%options"
120           Should you wish to reconfigure the Net::CLI::Interact instance used
121           inside of "Net::Appliance::Session", perhaps for an option not
122           supported above, this generic setting is available.
123
124   connect( \%options )
125        $s->connect({ username => $myname, password => $mysecret });
126
127       To establish a connection to the device, and possibly also log in, call
128       this method. Following a successful connection, paging of device output
129       will be disabled using commands appropriate to the platform. This
130       feature can be suppressed (see "CONFIGURATION", below).
131
132       Options available to this method, sometimes required, are:
133
134       "username => $name"
135           The login username for the device. Whether this is required depends
136           both on how the device is configured, and how you have configured
137           this module to act.  If it looks like the device presented a
138           Username prompt. and you don't pass the username a Perl exception
139           will be thrown.
140
141           The username is cached within the module for possible use later on
142           when entering "privileged" mode.
143
144       "password => $secret"
145           The login password for the device. Whether this is required depends
146           both on how the device is configured, and how you have configured
147           this module to act.  If it looks like the device presented a
148           Username prompt. and you don't pass the username a Perl exception
149           will be thrown.
150
151           The password is cached within the module for possible use later on
152           when entering "privileged" mode.
153
154       "privileged_password => $secret" (optional)
155           In the situation where you've activated "privileged paging", yet
156           your device uses a different password for privileged mode than
157           login, you'll need to set that other password here.
158
159           Otherwise, because the module tries to disable paging, it first
160           goes into privileged mode as you instructed, and fails with the
161           wrong (login) password.
162
163   begin_privileged and end_privileged
164        $s->begin_privileged;
165        # do some work
166        $s->end_privileged;
167
168       Once you have connected to the device, change to "privileged" mode by
169       calling the "begin_privileged" method. The appropriate command will be
170       issued for your device platform, from the phrasebook. Likewise to exit
171       "privileged" mode call the "end_privileged" method.
172
173       Sometimes authentication is required to enter "privileged" mode. In
174       that case, the module defaults to using the username and password first
175       passed in the "connect" method. However to either override those or set
176       them in case they were not passed to "connect", use either or both of
177       the following options to "begin_privileged":
178
179        $s->begin_privileged({ username => $myname, password => $mysecret });
180
181   begin_configure and end_configure
182        $s->begin_configure;
183        # make some changes
184        $s->end_configure;
185
186       To enter "configuration" mode for your device platform, call the
187       "begin_configure" method. This checks you are already in "privileged"
188       mode, as the module assumes this is necessary. If it isn't necessary
189       then see "CONFIGURATION" below to modify this behaviour. Likewise to
190       exit "configure" mode, call the "end_configure" method.
191
192   cmd( $command )
193        my $config     = $s->cmd('show running-config');
194        my @interfaces = $s->cmd('show interfaces brief');
195
196       Execute a single command statement on the connected device. The
197       statement is executed verbatim on the device, with a newline appended.
198
199       In scalar context the response is returned as a single string. In list
200       context the gathered response is returned as a list of lines. In both
201       cases your local platform's newline character will end all lines.
202
203       You can also call the "last_response" method which returns the same
204       data with the same contextual behaviour.
205
206       This method accepts a hashref of options following the $command, which
207       can include a "timeout" value to permit long running commands to have
208       all their output gathered.
209
210       To handle more complicated interactions, for example commands which
211       prompt for confirmation or optional parameters, you should use a Macro.
212       These are set up in the phrasebook and issued via the
213       "$s->macro($name)" method call. See the Phrasebook and Cookbook manual
214       pages for further details.
215
216       If you receive response text with a "mangled" copy of the issued
217       command at the start, then it's likely you need to set the terminal
218       width. This prevents the connected device from line-wrapping long
219       commands. Issue something like:
220
221        $s->begin_privileged;
222        $s->cmd('terminal width 510');
223
224   close
225        $s->close;
226
227       Once you have finished work with the device, call this method. It
228       attempts to back out of any "privileged" or "configuration" mode you've
229       entered, re-enable paging (unless suppressed) and then disconnect.
230
231       If a macro named "disconnect" exists in the loaded phrasebook then it's
232       called just before disconnection. This allows you to issue a command
233       such as "exit" to cleanly log out.
234

CONFIGURATION

236       Each of the entries below may either be passed as a parameter in the
237       options to the "new" method, or called as a method in its own right and
238       passed the appropriate setting. If doing the latter, it should be
239       before you call the "connect" method.
240
241       do_login
242           Defaults to true. Pass a zero (false) to disable logging in to the
243           device with a username and password, should you get a command
244           prompt immediately upon connection.
245
246       do_privileged_mode
247           Defaults to true. If on connecting to the device your user is
248           immediately in "privieleged" mode, then set this to zero (false),
249           which permits immediate access to "configure" mode.
250
251       do_configure_mode
252           Defaults to true. If you set this to zero (false), the module
253           assumes you're in "configure" mode immediately upon entering
254           "privileged" mode. I can't think why this would be useful but you
255           never know.
256
257       do_paging
258           Defaults to true. Pass a zero (false) to disable the post-login
259           reconfiguration of a device which avoids paged command output. If
260           you cleanly "close" the device connection then paging is re-
261           enabled. Use this option to suppress these steps.
262
263       privileged_paging
264           Defaults to false. On some series of devices, in particular the
265           Cisco ASA and PIXOS7+ you must be in privileged mode in order to
266           alter the pager. If that is the case for your device, call this
267           method with a true value to instruct the module to better manage
268           the situation.
269
270       pager_enable_lines
271           Defaults to 24. The command issued to re-enable paging (on
272           disconnect) typically takes a parameter which is the number of
273           lines per page. If you want a different value, set it in this
274           option.
275
276       pager_disable_lines
277           Defaults to zero. The command issued to disable paging typically
278           takes a parameter which is the number of lines per page (zero begin
279           to disable paging). If your device uses a different number here,
280           set it in this option.
281
282       wake_up
283           When first connecting to the device, the most common scenario is
284           that a Username (or some other) prompt is shown. However if no
285           output is forthcoming and nothing matches, the "enter" key is
286           pressed, in the hope of triggering the display of a new prompt.
287           This is typically most useful on Serial connected devices.
288
289           Set this configuration option to zero to suppress this behaviour,
290           or to the number of times "enter" should be pressed and output
291           waited for. The default is to press "enter" once.
292

ASYNCHRONOUS BEHAVIOUR

294       The standard, and recommended way to use this module is as above,
295       whereby the application is blocked waiting for command response. It's
296       also possible to send a command, and separately return to ask for
297       output at a later time.
298
299        $s->say('show clock');
300
301       This will send the command "show clock" to the connected device,
302       followed by a newline character.
303
304        $s->gather();
305
306       This will gather and return output, with similar behaviour to cmd(),
307       above.  That is, it blocks waiting for output and a prompt, will
308       timeout, and accepts the same options.
309
310       You can still use "last_response" after calling "gather", however be
311       aware that the command (from "say") may be echoed at the start of the
312       output, depending on device and connection transport.
313

DIAGNOSTICS

315       To see a log of all the processes within this module, and a copy of all
316       data sent to and received from the device, call the following method:
317
318        $s->set_global_log_at('notice');
319
320       In place of "notice" you can have other log levels (e.g. "debug" for
321       more, or "info" for less), and via the embedded Logger at
322       "$s->nci->logger" it's possible to finely control the diagnostics.
323

INTERNALS

325       See Net::CLI::Interact.
326

THANKS

328       Over several years I have received many patches and suggestions for
329       improvement from users of this module. My heartfelt thanks to all, for
330       their contributions.
331

AUTHOR

333       Oliver Gorwits <oliver@cpan.org>
334
336       This software is copyright (c) 2019 by Oliver Gorwits.
337
338       This is free software; you can redistribute it and/or modify it under
339       the same terms as the Perl 5 programming language system itself.
340
341
342
343perl v5.36.0                      2023-01-20        Net::Appliance::Session(3)
Impressum