forked from ollyg/Net-CLI-Interact
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
181 lines (140 loc) · 7.03 KB
/
README
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
NAME
Net::CLI::Interact - Toolkit for CLI Automation
VERSION
version 2.142720
PURPOSE
This module exists to support developers of applications and libraries
which must interact with a command line interface.
SYNOPSIS
use Net::CLI::Interact;
my $s = Net::CLI::Interact->new({
personality => 'cisco',
transport => 'Telnet',
connect_options => { host => '192.0.2.1' },
});
# respond to a usename/password prompt
$s->macro('to_user_exec', {
params => ['my_username', 'my_password'],
});
my $interfaces = $s->cmd('show ip interfaces brief');
$s->macro('to_priv_exec', {
params => ['my_password'],
});
# matched prompt is updated automatically
# paged output is slurped into one response
$s->macro('show_run');
my $config = $s->last_response;
DESCRIPTION
Automating command line interface (CLI) interactions is not a new idea,
but can be tricky to implement. This module aims to provide a simple and
manageable interface to CLI interactions, supporting:
* SSH, Telnet and Serial-Line connections
* Unix and Windows support
* Reuseable device command phrasebooks
If you're a new user, please read the Tutorial. There's also a Cookbook
and a Phrasebook Listing. For a more complete worked example check out
the Net::Appliance::Session distribution, for which this module was
written.
INTERFACE
new( \%options )
Prepares a new session for you, but will not connect to any device. On
Windows platforms, you must download the "plink.exe" program, and pass
its location to the "app" parameter. Other options are:
"personality => $name" (required)
The family of device command phrasebooks to load. There is a
built-in library within this module, or you can provide a search
path to other libraries. See Net::CLI::Interact::Manual::Phrasebook
for further details.
"transport => $backend" (required)
The name of the transport backend used for the session, which may be
one of Telnet, SSH, or Serial.
"connect_options => \%options"
If the transport backend can take any options (for example the
target hostname), then pass those options in this value as a hash
ref. See the respective manual pages for each transport backend for
further details.
"log_at => $log_level"
To make using the "logger" somewhat easier, you can pass this
argument the name of a log *level* (such as "debug", "info", etc)
and all logging in the library will be enabled at that level. Use
"debug" to learn about how the library is working internally. See
Net::CLI::Interact::Logger for a list of the valid level names.
"timeout => $seconds"
Configures a 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).
Note that this does not (currently) apply to the initial connection.
cmd( $command )
Execute a single command statement on the connected device, and consume
output until there is a match with the current *prompt*. The statement
is executed verbatim on the device, with a newline appended.
In scalar context the "last_response" is returned (see below). 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.
macro( $name, \%options? )
Execute the commands contained within the named Macro, which must be
loaded from a Phrasebook. Options to control the output, including
variables for substitution into the Macro, are passed in the %options
hash reference.
In scalar context the "last_response" is returned (see below). 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.
last_response
Returns the gathered output after the most recent "cmd" or "macro". In
scalar context all data is returned. 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.
transport
Returns the Transport backend which was loaded based on the "transport"
option to "new". See the Telnet, SSH, or Serial documentation for
further details.
phrasebook
Returns the Phrasebook object which was loaded based on the
"personality" option given to "new". See Net::CLI::Interact::Phrasebook
for further details.
set_phrasebook( \%options )
Allows you to (re-)configure the loaded phrasebook, perhaps changing the
personality or library, or other properties. The %options Hash ref
should be any parameters from the Phrasebook module, but at a minimum
must include a "personality".
set_default_contination( $macro_name )
Briefly, a Continuation handles the slurping of paged output from
commands. See the Net::CLI::Interact::Phrasebook documentation for
further details.
Pass in the name of a defined Contination (Macro) to enable paging
handling as a default for all sent commands. This is an alternative to
describing the Continuation format in each Macro.
To unset the default Continuation, call the "clear_default_continuation"
method.
logger
This is the application's Logger object. A powerful logging subsystem is
available to your application, built upon the Log::Dispatch
distribution. You can enable logging of this module's processes at
various levels, or add your own logging statements.
set_global_log_at( $level )
To make using the "logger" somewhat easier, you can pass this method the
name of a log *level* (such as "debug", "info", etc) and all logging in
the library will be enabled at that level. Use "debug" to learn about
how the library is working internally. See Net::CLI::Interact::Logger
for a list of the valid level names.
FUTHER READING
Prompt Matching
Whenever a command statement is issued, output is slurped until a
matching prompt is seen in that output. Control of the Prompts is shared
between the definitions in Net::CLI::Interact::Phrasebook dictionaries,
and methods of the Net::CLI::Interact::Role::Prompt core component. See
that module's documentation for further details.
Actions and ActionSets
All commands and macros are composed from their phrasebook definitions
into Actions and ActionSets (iterable sequences of Actions). See those
modules' documentation for further details, in case you wish to
introspect their structures.
COMPOSITION
See the following for further interface details:
* Net::CLI::Interact::Role::Engine
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.