1Net::CLI::Interact::ManUusaelr::CCoonotkrbioboukt(e3d)PNeertl::DCoLcIu:m:eInnttaetriaocnt::Manual::Cookbook(3)
2
3
4

NAME

6       Net::CLI::Interact::Manual::Cookbook - Miscellaneous recipes
7

Windows Support

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
14       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
20        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

Unix Support

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
33       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
37        my $s = Net::CLI::Interact->new(
38            personality => "cisco",
39            transport => "Telnet",
40            connect_options => {
41               reap => 1,
42           },
43        );
44

Running Commands

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
51        $s->cmd('show ip int br');
52
53       Normally this matches against a default prompt, which has been
54       discovered automatically, or set by you:
55
56        $s->set_prompt('user_prompt');
57
58       It's also possible to pass in a custom prompt for this command only:
59
60        $s->cmd('show ip int br', { match => qr/special prompt>$/ });
61
62       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
65   Macro Commands
66       Call a predefined Macro from the phrasebook using this method:
67
68        $s->macro('write_mem');
69
70       Sometimes the Macro needs parameters:
71
72        $s->macro('to_priv_exec', { params => ['my_password'] });
73
74       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
76       "cmd()" it's possible to achieve some simple flexibility.
77

Reconfiguring On-the-Fly

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
83        $s->set_phrasebook({ personality => 'ios' });
84
85       You can pass any options which the Phrasebook module itself would take.
86
87   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
91        $s->set_prompt('name');
92
93       If you want to test whether the current prompt matches a different
94       named Prompt from the phrasebook, this method can be used:
95
96        $s->prompt_looks_like('name');
97

Logging

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
105   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
109        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
127       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
131   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
137       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
141       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
145       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
149        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
157       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

Phrasebook Libraries

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
167       If you want to add either some prompts or macros, first read the
168       documentation for these systems at Net::CLI::Interact::Phrasebook.
169
170       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
174       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
180       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
186       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

Phrasebook Entries

191   Prompts
192       These are nothing more than named regular expressions:
193
194        prompt configure
195            match /\(config[^)]*\)# ?$/
196
197   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
202        macro copy_run_start
203            send copy running-config startup-config
204            match /Destination filename \[startup-config\]\?$/
205            send startup-config
206
207       To send instead a "press" of the Return key (output record separator),
208       use:
209
210        macro write_mem
211            send copy running-config startup-config
212            match /Destination filename \[startup-config\]\?$/
213            send ''
214
215       To instead allow the user to pass in the file name, use a "sprintf"
216       format.
217
218        macro save_to_file
219            send copy running-config startup-config
220            match /Destination filename \[startup-config\]\?$/
221            send %s
222
223       The user must then pass a parameter to the "macro" call, even if it's
224       an empty string:
225
226        $s->macro('save_to_file', { params => ['file_name'] });
227        # or
228        $s->macro('save_to_file', { params => [''] });
229
230   Continuations
231       These are Macros which start with a match instead of a send:
232
233        macro more_pages
234            match / --More-- /
235            send ' '
236
237       Note that the parameter of the "send" is not sent with a Return
238       character (output record separator) appended.
239
240       When included in a macro, the continuation can be in-line, like this:
241
242        macro show_ip_route
243            send show ip route
244            follow / --More-- / with ' '
245
246
247
248perl v5.36.0                      2022-0N7e-t2:2:CLI::Interact::Manual::Cookbook(3)
Impressum