1Net::Appliance::SessionU(s3e)r Contributed Perl DocumentaNteito:n:Appliance::Session(3)
2
6 Net::Appliance::Session - Run command-line sessions to network
7 appliances
8
10 use Net::Appliance::Session;
11 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 try {
21 $s->connect({ username => 'username', password => 'loginpass' });
22 $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 or, try the bundled "nas" helper script (beta feature!):
35 nas --help
37
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 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 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
54 As in the synopsis above, the first step is to create a new instance.
55 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 For a full demonstration of usage, see the example script shipped with
63 this distribution.
64 Net::Appliance::Session->new( \%options )
66 my $s = Net::Appliance::Session->new({
67 personality => 'ios',
68 transport => 'SSH',
69 host => 'hostname.example',
70 });
71 Prepares a new session for you, but will not connect to any device.
73 Some options are required, others optional:
74 "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 "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 "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 "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 "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 "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 "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 ${directory}/cisco/ios/pb
112 ${directory}/other/device/pb
113 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 "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 connect( \%options )
125 $s->connect({ username => $myname, password => $mysecret });
126 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 Options available to this method, sometimes required, are:
133 "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 The username is cached within the module for possible use later on
142 when entering "privileged" mode.
143 "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 The password is cached within the module for possible use later on
152 when entering "privileged" mode.
153 "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 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 begin_privileged and end_privileged
164 $s->begin_privileged;
165 # do some work
166 $s->end_privileged;
167 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 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 $s->begin_privileged({ username => $myname, password => $mysecret });
180 begin_configure and end_configure
182 $s->begin_configure;
183 # make some changes
184 $s->end_configure;
185 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 cmd( $command )
193 my $config = $s->cmd('show running-config');
194 my @interfaces = $s->cmd('show interfaces brief');
195 Execute a single command statement on the connected device. The
197 statement is executed verbatim on the device, with a newline appended.
198 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 You can also call the "last_response" method which returns the same
204 data with the same contextual behaviour.
205 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 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 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 $s->begin_privileged;
222 $s->cmd('terminal width 510');
223 close
225 $s->close;
226 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 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
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 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 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 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 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 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 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 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 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 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
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 $s->say('show clock');
300 This will send the command "show clock" to the connected device,
302 followed by a newline character.
303 $s->gather();
305 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 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
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 $s->set_global_log_at('notice');
319 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
325 See Net::CLI::Interact.
326
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
333 Oliver Gorwits <oliver@cpan.org>
334
336 This software is copyright (c) 2019 by Oliver Gorwits.
337 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.
340perl v5.36.0 2023-01-20 Net::Appliance::Session(3)