File: README

package info (click to toggle)
libnet-appliance-session-perl 4.142720-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 224 kB
  • ctags: 29
  • sloc: perl: 1,034; makefile: 8
file content (337 lines) | stat: -rw-r--r-- 13,995 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
NAME
    Net::Appliance::Session - Run command-line sessions to network
    appliances

VERSION
    version 4.142720

SYNOPSIS
     use Net::Appliance::Session;
 
     my $s = Net::Appliance::Session->new({
         personality => 'ios',
         transport => 'SSH',
         host => 'hostname.example',
         privileged_paging => 1, # only if using ASA/PIX OS 7+
                                 # and there are other behaviour options, see below
     });
 
     try {
         $s->connect({ username => 'username', password => 'loginpass' });
 
         $s->begin_privileged({ password => 'privilegedpass' });
         print $s->cmd('show access-list');
         $s->end_privileged;
     }
     catch {
         warn "failed to execute command: $_";
     }
     finally {
         $s->close;
     };

    or, try the bundled "nas" helper script (beta feature!):

     nas --help

DESCRIPTION
    Use this module to establish an interactive command-line session with a
    network appliance. There is special support for moving into "privileged"
    mode and "configure" mode, along with the ability to send commands to
    the connected device and retrieve returned output.

    There are other CPAN modules that cover similar ground, but they are
    less robust and do not handle native SSH, Telnet and Serial Line
    connections with a single interface on both Unix and Windows platforms.

    Built-in commands come from a phrasebook which supports many network
    device vendors (Cisco, HP, etc) or you can install a new phrasebook.
    Most phases of the connection are configurable for different device
    behaviours.

METHODS
    As in the synopsis above, the first step is to create a new instance.

    Recommended practice is to wrap all other calls (except "close()") in a
    "try" block, to catch errors (typically time-outs waiting for CLI
    response). This module exports the "try/catch/finally" methods (from
    Try::Tiny) into your namespace as a simpler alternative to using
    "eval()".

    For a full demonstration of usage, see the example script shipped with
    this distribution.

  Net::Appliance::Session->new( \%options )
     my $s = Net::Appliance::Session->new({
         personality => 'ios',
         transport => 'SSH',
         host => 'hostname.example',
     });

    Prepares a new session for you, but will not connect to any device. Some
    options are required, others optional:

    "personality => $name" (required)
        Tells the module which "language" to use when talking to the
        connected device, for example "ios" for Cisco IOS devices. There's a
        list of all the supported platforms in the Phrasebook documentation.
        It's also possible to write new phrasebooks.

    "transport => $backend" (required)
        The name of the transport backend used for the session, which may be
        one of Telnet, SSH, or Serial.

    "app => $location" (required on Windows)
        On Windows platforms, you must download the "plink.exe" program, and
        pass its location in this parameter.

    "host => $hostname" (required for Telnet and SSH transports)
        When using the Telnet and SSH transports, you must provide the IP or
        host name of the target device in this parameter.

    "timeout => $seconds"
        Configures a global default timeout value, in seconds, for
        interaction with the remote device. The default is 10 seconds. You
        can also set timeout on a per-command or per-macro call (see below).

    "connect_options => \%options"
        Some of the transport backends can take their own options. For
        example with a serial line connection you might specify the port
        speed, etc. See the respective manual pages for each transport
        backend for further details (SSH, Telnet, Serial).

    "add_library => $directory"
        If you've added to the built-in phrasebook with your own macros,
        then use this option to load your new phrasebook file(s). The path
        here should be the directory within which all your personalities are
        located, such as:

         ${directory}/cisco/ios/pb
         ${directory}/other/device/pb

        Usually the phrasebook files are called ""pb"" and to the
        "personality" option you pass the containing directory name, for
        example "ios" or "device" in the examples shown. See
        Net::CLI::Interact::Manual::Tutorial for further details.

    "nci_options => \%options"
        Should you wish to reconfigure the Net::CLI::Interact instance used
        inside of "Net::Appliance::Session", perhaps for an option not
        supported above, this generic setting is available.

  connect( \%options )
     $s->connect({ username => $myname, password => $mysecret });

    To establish a connection to the device, and possibly also log in, call
    this method. Following a successful connection, paging of device output
    will be disabled using commands appropriate to the platform. This
    feature can be suppressed (see "CONFIGURATION", below).

    Options available to this method, sometimes required, are:

    "username => $name"
        The login username for the device. Whether this is required depends
        both on how the device is configured, and how you have configured
        this module to act. If it looks like the device presented a Username
        prompt. and you don't pass the username a Perl exception will be
        thrown.

        The username is cached within the module for possible use later on
        when entering "privileged" mode.

    "password => $secret"
        The login password for the device. Whether this is required depends
        both on how the device is configured, and how you have configured
        this module to act. If it looks like the device presented a Username
        prompt. and you don't pass the username a Perl exception will be
        thrown.

        The password is cached within the module for possible use later on
        when entering "privileged" mode.

    "privileged_password => $secret" (optional)
        In the situation where you've activated "privileged paging", yet
        your device uses a different password for privileged mode than
        login, you'll need to set that other password here.

        Otherwise, because the module tries to disable paging, it first goes
        into privileged mode as you instructed, and fails with the wrong
        (login) password.

  begin_privileged and end_privileged
     $s->begin_privileged;
     # do some work
     $s->end_privileged;

    Once you have connected to the device, change to "privileged" mode by
    calling the "begin_privileged" method. The appropriate command will be
    issued for your device platform, from the phrasebook. Likewise to exit
    "privileged" mode call the "end_privileged" method.

    Sometimes authentication is required to enter "privileged" mode. In that
    case, the module defaults to using the username and password first
    passed in the "connect" method. However to either override those or set
    them in case they were not passed to "connect", use either or both of
    the following options to "begin_privileged":

     $s->begin_privileged({ username => $myname, password => $mysecret });

  begin_configure and end_configure
     $s->begin_configure;
     # make some changes
     $s->end_configure;

    To enter "configuration" mode for your device platform, call the
    "begin_configure" method. This checks you are already in "privileged"
    mode, as the module assumes this is necessary. If it isn't necessary
    then see "CONFIGURATION" below to modify this behaviour. Likewise to
    exit "configure" mode, call the "end_configure" method.

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

    Execute a single command statement on the connected device. The
    statement is executed verbatim on the device, with a newline appended.

    In scalar context the response is returned as a single string. In list
    context the gathered response is returned as a list of lines. In both
    cases your local platform's newline character will end all lines.

    You can also call the "last_response" method which returns the same data
    with the same contextual behaviour.

    This method accepts a hashref of options following the $command, which
    can include a "timeout" value to permit long running commands to have
    all their output gathered.

    To handle more complicated interactions, for example commands which
    prompt for confirmation or optional parameters, you should use a Macro.
    These are set up in the phrasebook and issued via the "$s->macro($name)"
    method call. See the Phrasebook and Cookbook manual pages for further
    details.

    If you receive response text with a "mangled" copy of the issued command
    at the start, then it's likely you need to set the terminal width. This
    prevents the connected device from line-wrapping long commands. Issue
    something like:

     $s->begin_privileged;
     $s->cmd('terminal width 510');

  close
     $s->close;

    Once you have finished work with the device, call this method. It
    attempts to back out of any "privileged" or "configuration" mode you've
    entered, re-enable paging (unless suppressed) and then disconnect.

    If a macro named "disconnect" exists in the loaded phrasebook then it's
    called just before disconnection. This allows you to issue a command
    such as "exit" to cleanly log out.

CONFIGURATION
    Each of the entries below may either be passed as a parameter in the
    options to the "new" method, or called as a method in its own right and
    passed the appropriate setting. If doing the latter, it should be before
    you call the "connect" method.

    do_login
        Defaults to true. Pass a zero (false) to disable logging in to the
        device with a username and password, should you get a command prompt
        immediately upon connection.

    do_privileged_mode
        Defaults to true. If on connecting to the device your user is
        immediately in "privieleged" mode, then set this to zero (false),
        which permits immediate access to "configure" mode.

    do_configure_mode
        Defaults to true. If you set this to zero (false), the module
        assumes you're in "configure" mode immediately upon entering
        "privileged" mode. I can't think why this would be useful but you
        never know.

    do_paging
        Defaults to true. Pass a zero (false) to disable the post-login
        reconfiguration of a device which avoids paged command output. If
        you cleanly "close" the device connection then paging is re-enabled.
        Use this option to suppress these steps.

    privileged_paging
        Defaults to false. On some series of devices, in particular the
        Cisco ASA and PIXOS7+ you must be in privileged mode in order to
        alter the pager. If that is the case for your device, call this
        method with a true value to instruct the module to better manage the
        situation.

    pager_enable_lines
        Defaults to 24. The command issued to re-enable paging (on
        disconnect) typically takes a parameter which is the number of lines
        per page. If you want a different value, set it in this option.

    pager_disable_lines
        Defaults to zero. The command issued to disable paging typically
        takes a parameter which is the number of lines per page (zero begin
        to disable paging). If your device uses a different number here, set
        it in this option.

    wake_up
        When first connecting to the device, the most common scenario is
        that a Username (or some other) prompt is shown. However if no
        output is forthcoming and nothing matches, the "enter" key is
        pressed, in the hope of triggering the display of a new prompt. This
        is typically most useful on Serial connected devices.

        Set this configuration option to zero to suppress this behaviour, or
        to the number of times "enter" should be pressed and output waited
        for. The default is to press "enter" once.

ASYNCHRONOUS BEHAVIOUR
    The standard, and recommended way to use this module is as above,
    whereby the application is blocked waiting for command response. It's
    also possible to send a command, and separately return to ask for output
    at a later time.

     $s->say('show clock');

    This will send the command "show clock" to the connected device,
    followed by a newline character.

     $s->gather();

    This will gather and return output, with similar behaviour to "cmd()",
    above. That is, it blocks waiting for output and a prompt, will timeout,
    and accepts the same options.

    You can still use "last_response" after calling "gather", however be
    aware that the command (from "say") may be echoed at the start of the
    output, depending on device and connection transport.

DIAGNOSTICS
    To see a log of all the processes within this module, and a copy of all
    data sent to and received from the device, call the following method:

     $s->set_global_log_at('notice');

    In place of "notice" you can have other log levels (e.g. "debug" for
    more, or "info" for less), and via the embedded Logger at
    "$s->nci->logger" it's possible to finely control the diagnostics.

INTERNALS
    See Net::CLI::Interact.

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

AUTHOR
    Oliver Gorwits <oliver@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 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.