1Net::CLI::Interact::ManUusaelr::CCoonotkrbioboukt(e3dNpemPt)e:r:lCLDIo:c:uImnetnetraatcito:n:Manual::Cookbook(3pm)
2
6 Net::CLI::Interact::Manual::Cookbook - Miscellaneous recipes
7
9 The library works just fine under native windows (i.e use something
10 like Strawberry Perl - no need for cygwin), for Telnet, Serial and SSH
11 connections. However one additional step is required for you to have
12 success:
13 You must download the "plink.exe" application, and pass its filesystem
15 location in the "app" parameter to new(). Do not try to use any other
16 Telnet or SSH programs (for instance the Windows bundled "telnet") -
17 they will not work. Here's an example, if "plink.exe" is on your
18 Desktop:
19 my $s = Net::CLI::Interact->new(
21 personality => "cisco",
22 transport => "Telnet",
23 (Net::CLI::Interact::Transport::is_win32() ?
24 (app => "$ENV{HOMEPATH}\\Desktop\\plink.exe") : () ),
25 );
26
28 The library works fine on most Unix platforms. It will try to use the
29 native "telnet", "ssh" (openssh) and "cu" programs for Telnet, SSH and
30 Serial connections, respectively. If you want to use another
31 application, pass it in the "app" parameter to "new".
32 In some Unix environments there can be zombie child processes left
34 around after running your script. If this happens, set the "reap"
35 option, like so:
36 my $s = Net::CLI::Interact->new(
38 personality => "cisco",
39 transport => "Telnet",
40 connect_options => {
41 reap => 1,
42 },
43 );
44
46 Simple Commands
47 Simply send the command you wish to execute to the session. If not
48 already done, a connection to the device will be established
49 automatically:
50 $s->cmd('show ip int br');
52 Normally this matches against a default prompt, which has been
54 discovered automatically, or set by you:
55 $s->set_prompt('user_prompt');
57 It's also possible to pass in a custom prompt for this command only:
59 $s->cmd('show ip int br', { match => qr/special prompt>$/ });
61 However be aware that a side effect of this is that the custom prompt
63 becomes the new default prompt for subsequent commands or macros.
64 Macro Commands
66 Call a predefined Macro from the phrasebook using this method:
67 $s->macro('write_mem');
69 Sometimes the Macro needs parameters:
71 $s->macro('to_priv_exec', { params => ['my_password'] });
73 You can't really create a Macro on the fly very easily, but with
75 suitable use of cmd(), set_prompt(), and the "match" option to cmd()
76 it's possible to achieve some simple flexibility.
77
79 Phrasebook
80 It's possible to load a new phrasebook by the following method, which
81 must be passed at least the name of the personality:
82 $s->set_phrasebook({ personality => 'ios' });
84 You can pass any options which the Phrasebook module itself would take.
86 Prompt
88 The current prompt can be changed by passing the name of the new Prompt
89 as it is known by the phrasebook:
90 $s->set_prompt('name');
92 If you want to test whether the current prompt matches a different
94 named Prompt from the phrasebook, this method can be used:
95 $s->prompt_looks_like('name');
97
99 A generic logging service is available through the "$session->logger"
100 object, which is based on Log::Dispatch. You can configure the logger
101 at startup quite easily. See the Net::CLI::Interact::Logger manual page
102 for details of the interface (config for any option can simply be
103 passed to "Net::CLI::Interact->new()").
104 Destinations
106 The default configuration sends logging messages to standard output.
107 Let's say you also want to append them to a log file:
108 my $s = Net::CLI::Interact->new({
110 log_config => {
111 dispatchers => ['screen','file'],
112 screen => {
113 class => 'Log::Dispatch::Screen',
114 min_level => 'warning',
115 },
116 file => {
117 class => 'Log::Dispatch::File',
118 min_level => 'debug',
119 filename => '/var/log/myapp.log',
120 mode => 'append',
121 format => '[%d] %m',
122 },
123 },
124 # etc...
125 });
126 Note that some keys are required, such as the "class" and "min_level"
128 but others depend on the particular class being used. See
129 Log::Dispatch::Config for more details.
130 Log Levels and Categories
132 Each log message has a standard log level ("debug", "warning", etc) but
133 also a category which is a concept local to this module. Categories
134 allow more filtering of what is logged. Each time a message is logged
135 through "$s->logger->log(...)" it has a level and category.
136 Messages are only emitted if they pass the specific level set for that
138 category. In this way we can suppress messages about the transport but,
139 for example, show messages about prompt-matching at a debug level.
140 You can very easily set the log level for all categories using either
142 the "set_global_log_at" option to new(), or the "NCI_LOG_AT"
143 environment variable.
144 To configure these filters, use the "log_flags" option together with
146 the list of default log categories used by "Net::CLI::Interact". For
147 example:
148 my $s = Net::CLI::Interact->new({
150 log_flags => {
151 (map {$_ => 'notice'} Net::CLI::Interact->default_log_categories()),
152 dialogue => 'info',
153 },
154 # etc...
155 });
156 This example would set all categories to "notice" level except for the
158 "dialogue" category, which is set to "info" level to get more output
159 (on what is sent and received by each command).
160
162 You can override or add to the device command phrasebooks which ship
163 with this distribution. To start with, check the shipped dictionary for
164 your device's current level of support, at
165 Net::CLI::Interact::Manual::Phasebook.
166 If you want to add either some prompts or macros, first read the
168 documentation for these systems at Net::CLI::Interact::Phrasebook.
169 All phrasebooks can inherit from others, and this is based on their
171 location in a filesystem tree. See the phrasebooks bundled with the
172 Net::CLI::Interact distribution for an example of this in action.
173 If you wish to override a phrasebook entry, simply set "add_library" in
175 your code, and then create a file at the same relative point beneath
176 that library directory as the original version shipped with the
177 "Net::CLI::Interact" module, for example
178 ""<add_library>/cisco/pixos/pixos7/my_phrases"".
179 The file itself ("my_phrases") does not have to be the same name as the
181 original, and you can have more than one file if it helps. Only the
182 directory is matched against your chosen "personality" and then all
183 files in there, and higher in the "add_library" tree, and distribution
184 "library" tree, are loaded.
185 To check what phrasebooks and prompts/macros are loaded, run your
187 script with debug level set to "notice". The easiest way to do this is
188 by setting the environment variable "NCI_LOG_AT=notice".
189
191 Prompts
192 These are nothing more than named regular expressions:
193 prompt configure
195 match /\(config[^)]*\)# ?$/
196 Macros
198 This example waits for the device to ask "[startup-config]?" and then
199 responds with the text "startup-config". Remember, there is an implicit
200 "match" statement added at the end, which is the current prompt.
201 macro copy_run_start
203 send copy running-config startup-config
204 match /Destination filename \[startup-config\]\?$/
205 send startup-config
206 To send instead a "press" of the Return key (output record separator),
208 use:
209 macro write_mem
211 send copy running-config startup-config
212 match /Destination filename \[startup-config\]\?$/
213 send ''
214 To instead allow the user to pass in the file name, use a "sprintf"
216 format.
217 macro save_to_file
219 send copy running-config startup-config
220 match /Destination filename \[startup-config\]\?$/
221 send %s
222 The user must then pass a parameter to the "macro" call, even if it's
224 an empty string:
225 $s->macro('save_to_file', { params => ['file_name'] });
227 # or
228 $s->macro('save_to_file', { params => [''] });
229 Continuations
231 These are Macros which start with a match instead of a send:
232 macro more_pages
234 match / --More-- /
235 send ' '
236 Note that the parameter of the "send" is not sent with a Return
238 character (output record separator) appended.
239 When included in a macro, the continuation can be in-line, like this:
241 macro show_ip_route
243 send show ip route
244 follow / --More-- / with ' '
245perl v5.38.0 2023N-e0t7:-:2C1LI::Interact::Manual::Cookbook(3pm)