1Net::CLI::Interact(3pm)User Contributed Perl DocumentatioNnet::CLI::Interact(3pm)
2
6 Net::CLI::Interact - Toolkit for CLI Automation
7
9 This module exists to support developers of applications and libraries
10 which must interact with a command line interface.
11
13 use Net::CLI::Interact;
14 my $s = Net::CLI::Interact->new({
16 personality => 'cisco',
17 transport => 'Telnet',
18 connect_options => { host => '192.0.2.1' },
19 });
20 # respond to a usename/password prompt
22 $s->macro('to_user_exec', {
23 params => ['my_username', 'my_password'],
24 });
25 my $interfaces = $s->cmd('show ip interfaces brief');
27 $s->macro('to_priv_exec', {
29 params => ['my_password'],
30 });
31 # matched prompt is updated automatically
32 # paged output is slurped into one response
34 $s->macro('show_run');
35 my $config = $s->last_response;
36
38 Automating command line interface (CLI) interactions is not a new idea,
39 but can be tricky to implement. This module aims to provide a simple
40 and manageable interface to CLI interactions, supporting:
41 • SSH, Telnet and Serial-Line connections
43 • Unix and Windows support
45 • Reuseable device command phrasebooks
47 If you're a new user, please read the Tutorial. There's also a Cookbook
49 and a Phrasebook Listing. For a more complete worked example check out
50 the Net::Appliance::Session distribution, for which this module was
51 written.
52
54 new( \%options )
55 Prepares a new session for you, but will not connect to any device. On
56 Windows platforms, you must download the "plink.exe" program, and pass
57 its location to the "app" parameter. Other options are:
58 "personality => $name" (required)
60 The family of device command phrasebooks to load. There is a built-
61 in library within this module, or you can provide a search path to
62 other libraries. See Net::CLI::Interact::Manual::Phrasebook for
63 further details.
64 "transport => $backend" (required)
66 The name of the transport backend used for the session, which may
67 be one of Telnet, SSH, or Serial.
68 "connect_options => \%options"
70 If the transport backend can take any options (for example the
71 target hostname), then pass those options in this value as a hash
72 ref. See the respective manual pages for each transport backend for
73 further details.
74 "log_at => $log_level"
76 To make using the "logger" somewhat easier, you can pass this
77 argument the name of a log level (such as "debug", "info", etc) and
78 all logging in the library will be enabled at that level. Use
79 "debug" to learn about how the library is working internally. See
80 Net::CLI::Interact::Logger for a list of the valid level names.
81 "timeout => $seconds"
83 Configures a default timeout value, in seconds, for interaction
84 with the remote device. The default is 10 seconds. You can also set
85 timeout on a per-command or per-macro call (see below).
86 Note that this does not (currently) apply to the initial
88 connection.
89 cmd( $command )
91 Execute a single command statement on the connected device, and consume
92 output until there is a match with the current prompt. The statement is
93 executed verbatim on the device, with a newline appended.
94 In scalar context the "last_response" is returned (see below). In list
96 context the gathered response is returned as a list of lines. In both
97 cases your local platform's newline character will end all lines.
98 macro( $name, \%options? )
100 Execute the commands contained within the named Macro, which must be
101 loaded from a Phrasebook. Options to control the output, including
102 variables for substitution into the Macro, are passed in the %options
103 hash reference.
104 In scalar context the "last_response" is returned (see below). In list
106 context the gathered response is returned as a list of lines. In both
107 cases your local platform's newline character will end all lines.
108 last_response
110 Returns the gathered output after the most recent "cmd" or "macro". In
111 scalar context all data is returned. In list context the gathered
112 response is returned as a list of lines. In both cases your local
113 platform's newline character will end all lines.
114 transport
116 Returns the Transport backend which was loaded based on the "transport"
117 option to "new". See the Telnet, SSH, or Serial documentation for
118 further details.
119 phrasebook
121 Returns the Phrasebook object which was loaded based on the
122 "personality" option given to "new". See Net::CLI::Interact::Phrasebook
123 for further details.
124 set_phrasebook( \%options )
126 Allows you to (re-)configure the loaded phrasebook, perhaps changing
127 the personality or library, or other properties. The %options Hash ref
128 should be any parameters from the Phrasebook module, but at a minimum
129 must include a "personality".
130 set_default_contination( $macro_name )
132 Briefly, a Continuation handles the slurping of paged output from
133 commands. See the Net::CLI::Interact::Phrasebook documentation for
134 further details.
135 Pass in the name of a defined Contination (Macro) to enable paging
137 handling as a default for all sent commands. This is an alternative to
138 describing the Continuation format in each Macro.
139 To unset the default Continuation, call the
141 "clear_default_continuation" method.
142 logger
144 This is the application's Logger object. A powerful logging subsystem
145 is available to your application, built upon the Log::Dispatch
146 distribution. You can enable logging of this module's processes at
147 various levels, or add your own logging statements.
148 set_global_log_at( $level )
150 To make using the "logger" somewhat easier, you can pass this method
151 the name of a log level (such as "debug", "info", etc) and all logging
152 in the library will be enabled at that level. Use "debug" to learn
153 about how the library is working internally. See
154 Net::CLI::Interact::Logger for a list of the valid level names.
155
157 Prompt Matching
158 Whenever a command statement is issued, output is slurped until a
159 matching prompt is seen in that output. Control of the Prompts is
160 shared between the definitions in Net::CLI::Interact::Phrasebook
161 dictionaries, and methods of the Net::CLI::Interact::Role::Prompt core
162 component. See that module's documentation for further details.
163 Actions and ActionSets
165 All commands and macros are composed from their phrasebook definitions
166 into Actions and ActionSets (iterable sequences of Actions). See those
167 modules' documentation for further details, in case you wish to
168 introspect their structures.
169
171 See the following for further interface details:
172 • Net::CLI::Interact::Role::Engine
174
176 Oliver Gorwits <oliver@cpan.org>
177
179 This software is copyright (c) 2017 by Oliver Gorwits.
180 This is free software; you can redistribute it and/or modify it under
182 the same terms as the Perl 5 programming language system itself.
183perl v5.38.0 2023-07-21 Net::CLI::Interact(3pm)