1Net::Telnet::Cisco(3) User Contributed Perl DocumentationNet::Telnet::Cisco(3)
2
3
4

NAME

6       Net::Telnet::Cisco - interact with a Cisco router
7

SYNOPSIS

9         use Net::Telnet::Cisco;
10
11         my $session = Net::Telnet::Cisco->new(Host => '123.123.123.123');
12         $session->login('login', 'password');
13
14         # Execute a command
15         my @output = $session->cmd('show version');
16         print @output;
17
18         # Enable mode
19         if ($session->enable("enable_password") ) {
20             @output = $session->cmd('show privilege');
21             print "My privileges: @output\n";
22         } else {
23             warn "Can't enable: " . $session->errmsg;
24         }
25
26         $session->close;
27

DESCRIPTION

29       Net::Telnet::Cisco provides additional functionality to Net::Telnet for
30       dealing with Cisco routers.
31
32       cmd() parses router-generated error messages - the kind that begin with
33       a '%' - and stows them in $obj->errmsg(), so that errmode can be used
34       to perform automatic error-handling actions.
35

CAVEATS

37       Before you use Net::Telnet::Cisco, you should have a good understanding
38       of Net::Telnet, so read it's documentation first, and then come back
39       here to see the improvements.
40
41       Some things are easier to accomplish with UCD's C-based SNMP module, or
42       the all-perl Net::SNMP. SNMP has three advantages: it's faster, handles
43       errors better, and doesn't use any VTYs on the router. SNMP does have
44       some limitations, so for anything you can't accomplish with SNMP,
45       there's Net::Telnet::Cisco.
46

METHODS

48       new - create new Net::Telnet::Cisco object
49               $session = Net::Telnet::Cisco->new(
50                   [Always_waitfor_prompt => $boolean,]      # 1
51                   [Autopage              => $boolean,]      # 1
52                   [Ignore_warnings       => $boolean,]      # 0
53                   [More_prompt           => $matchop,]      # '/(?m:^\s*--More--)/',
54                   [Normalize_cmd         => $boolean,]      # 1
55                   [Send_wakeup           => $when,]         # 0
56                   [Waitfor_pause         => $milliseconds,] # 0.1
57                   [Warnings              => $matchop,]      # see docs
58
59                   # Net::Telnet arguments
60               );
61
62           Creates a new object. Read `perldoc perlboot` if you don't
63           understand that.
64
65       login - login to a router
66               $ok = $obj->login($username, $password);
67
68               $ok = $obj->login([Name     => $username,]
69                                 [Password => $password,]
70                                 [Passcode => $passcode,] # for Secur-ID/XTACACS
71                                 [Prompt   => $match,]
72                                 [Timeout  => $secs,]);
73
74           All arguments are optional as of v1.05. Some routers don't ask for
75           a username, they start the login conversation with a password
76           request.
77
78       cmd - send a command
79               $ok = $obj->cmd($string);
80               $ok = $obj->cmd(String   => $string,
81                               [Output  => $ref,]
82                               [Prompt  => $match,]
83                               [Timeout => $secs,]
84                               [Cmd_remove_mode => $mode,]);
85
86               @output = $obj->cmd($string);
87               @output = $obj->cmd(String   => $string,
88                                   [Output  => $ref,]
89                                   [Prompt  => $match,]
90                                   [Timeout => $secs,]
91                                   [Cmd_remove_mode => $mode,]
92                                   [Normalize_cmd => $boolean,]);
93
94           Normalize_cmd has been added to the default Net::Telnet args. It
95           lets you temporarily change whether backspace, delete, and kill
96           characters are parsed in the command output. (This is performed by
97           default)
98
99       prompt - return control to the program whenever this string occurs in
100       router output
101               $matchop = $obj->prompt;
102
103               $prev = $obj->prompt($matchop);
104
105           The default cmd_prompt changed in v1.05. It's suitable for matching
106           prompts like "router$ ", "router# ", "router> (enable) ", and
107           "router(config-if)# "
108
109           Let's take a closer look, shall we?
110
111             (?m:          # Net::Telnet doesn't accept quoted regexen (i.e. qr//)
112                       # so we need to use an embedded pattern-match modifier
113                       # to treat the input as a multiline buffer.
114
115               ^           # beginning of line
116
117                 [\w.-]+       # router hostname
118
119                 \s?       # optional space
120
121                 (?:       # Strings like "(config)" and "(config-if)", "(config-line)",
122                       # and "(config-router)" indicate that we're in privileged
123                   \(config[^\)]*\) # EXEC mode (i.e. we're enabled).
124                 )?        # The middle backslash is only there to appear my syntax
125                       # highlighter.
126
127                 \s?       # more optional space
128
129                 [\$#>]        # Prompts typically end with "$", "#", or ">". Backslash
130                       # for syntax-highlighter.
131
132                 \s?       # more space padding
133
134                 (?:       # Catalyst switches print "(enable)" when in privileged
135                   \(enable\)  # EXEC mode.
136                 )?
137
138                 \s*       # spaces before the end-of-line aren't important to us.
139
140               $           # end of line
141
142             )         # end of (?m:
143
144           The default prompt published in 1.03 was
145           "/^\s*[\w().-]*[\$#>]\s?(?:\(enable\))?\s*$/". As you can see, the
146           prompt was drastically overhauled in 1.05. If your code suddenly
147           starts timing out after upgrading Net::Telnet::Cisco, this is the
148           first thing to investigate.
149
150       enable - enter enabled mode
151               $ok = $obj->enable;
152
153               $ok = $obj->enable($password);
154
155               $ok = $obj->enable([Name => $name,] [Password => $password,]
156                              [Passcode => $passcode,] [Level => $level,]);
157
158           This method changes privilege level to enabled mode, (i.e. root)
159
160           If a single argument is provided by the caller, it will be used as
161           a password. For more control, including the ability to set the
162           privilege-level, you must use the named-argument scheme.
163
164           enable() returns 1 on success and undef on failure.
165
166       is_enabled - Am I root?
167               $bool = $obj->is_enabled;
168
169           A trivial check to see whether we have a root-style prompt, with
170           either the word "(enable)" in it, or a trailing "#".
171
172           Warning: this method will return false positives if your prompt has
173           "#"s in it. You may be better off calling "$obj->cmd("show
174           privilege")" instead.
175
176       disable - leave enabled mode
177               $ok = $obj->disable;
178
179           This method exits the router's privileged mode.
180
181       fhopen - use already open filehandle for I/O
182               $ok = $obj->fhopen($fh);
183
184           This method associates the open filehandle $fh with $obj for
185           further I/O.  Filehandle $fh must already be opened.
186
187           The value 1 is returned success, the error mode action is performed
188           on failure.
189
190       ios_break - send a break (control-^)
191               $ok = $obj->ios_break;
192
193           You may have to use errmode(), fork, or threads to break at the an
194           appropriate time.
195
196       last_cmd - displays the last command
197               $match = $obj->last_cmd;
198
199           last_cmd() will return '' if the program does not yet have a last
200           command.
201
202       last_prompt - displays the last prompt matched by prompt()
203               $match = $obj->last_prompt;
204
205           last_prompt() will return '' if the program has not yet matched a
206           prompt.
207
208       always_waitfor_prompt - waitfor and cmd prompt behaviour
209               $boolean = $obj->always_waitfor_prompt;
210
211               $boolean = $obj->always_waitfor_prompt($boolean);
212
213           Default value: 1
214
215           If you pass a Prompt argument to cmd() or waitfor() a String or
216           Match, they will return control on a successful match of your
217           argument(s) or the default prompt. Set always_waitfor_prompt to 0
218           to return control only for your arguments.
219
220           This method has no effect on login(). login() will always wait for
221           a prompt.
222
223       waitfor_pause - insert a small delay before waitfor()
224               $boolean = $obj->waitfor_pause;
225
226               $boolean = $obj->waitfor_pause($milliseconds);
227
228           Default value: 0.1
229
230           In rare circumstances, the last_prompt is set incorrectly. By
231           adding a very small delay before calling the parent class's
232           waitfor(), this bug is eliminated. If you ever find reason to
233           modify this from it's default setting, please let me know.
234
235       autopage - Turn autopaging on and off
236               $boolean = $obj->autopage;
237
238               $boolean = $obj->autopage($boolean);
239
240           Default value: 1
241
242           IOS pages output by default. It expects human eyes to be reading
243           the output, not programs. Humans hit the spacebar to scroll page by
244           page so autopage() mimicks that behaviour. This is the slow way to
245           handle paging. See the Paging EXAMPLE for a faster way.
246
247       normalize_cmd - Turn normalization on and off
248               $boolean = $obj->normalize_cmd;
249
250               $boolean = $obj->normalize_cmd($boolean);
251
252           Default value: 1
253
254           IOS clears '--More--' prompts with backspaces (e.g. ^H). If you're
255           excited by the thought of having raw control characters like ^H
256           (backspace), ^? (delete), and ^U (kill) in your command output,
257           turn this feature off.
258
259           Logging is unaffected by this setting.
260
261       more_prompt - Matchop used by autopage()
262               $matchop = $obj->prompt;
263
264               $prev = $obj->prompt($matchop);
265
266           Default value: '/(?m:\s*--More--)/'.
267
268           Please email me if you find others.
269
270       send_wakeup - send a newline to the router at login time
271               $when = $obj->send_wakeup;
272
273               $when = $obj->send_wakeup( 'connect' );
274               $when = $obj->send_wakeup( 'timeout' );
275               $when = $obj->send_wakeup( 0 );
276
277           Default value: 0
278
279           Some routers quietly allow you to connect but don't display the
280           expected login prompts. Sends a newline in the hopes that this
281           spurs the routers to print something.
282
283           'connect' sends a newline immediately upon connection.  'timeout'
284           sends a newline if the connection timeouts.  0 turns this feature
285           off.
286
287           I understand this works with Livingston Portmasters.
288
289       ignore_warnings - Don't call error() for warnings
290               $boolean = $obj->ignore_warnings;
291
292               $boolean = $obj->ignore_warnings($boolean);
293
294           Default value: 0
295
296           Not all strings that begin with a '%' are really errors. Some are
297           just warnings. By setting this, you are ignoring them. This will
298           show up in the logs, but that's it.
299
300       warnings - Matchop used by ignore_warnings().
301               $boolean = $obj->warnings;
302
303               $boolean = $obj->warnings($matchop);
304
305           Default value:
306
307               /(?mx:^% Unknown VPN
308                    |^%IP routing table VRF.* does not exist. Create first$
309                    |^%No CEF interface information
310                    |^%No matching route to delete$
311                    |^%Not all config may be removed and may reappear after reactivating
312                )/
313
314           Not all strings that begin with a '%' are really errors. Some are
315           just warnings. Cisco calls these the CIPMIOSWarningExpressions.
316

EXAMPLES

318   Paging
319       v1.08 added internal autopaging support to cmd(). Whenever a '--Page--'
320       prompt appears on the screen, we send a space right back. It works, but
321       it's slow. You'd be better off sending one of the following commands
322       just after login():
323
324         # To a router
325         $session->cmd('terminal length 0');
326
327         # To a switch
328         $session->cmd('set length 0');
329
330   Logging
331       Want to see the session transcript? Just call input_log().
332
333         e.g.
334         my $session = Net::Telnet::Cisco->new(Host => $router,
335                           Input_log => "input.log",
336                           );
337
338       See input_log() in Net::Telnet for info.
339
340       Input logs are easy-to-read translated transcripts with all of the
341       control characters and telnet escapes cleaned up. If you want to view
342       the raw session, see dump_log() in Net::Telnet. If you're getting
343       tricky and using print() in addition to cmd(), you may also want to use
344       output_log().
345
346   Big output
347       Trying to dump the entire BGP table? (e.g. "show ip bgp") The default
348       buffer size is 1MB, so you'll have to increase it.
349
350         my $MB = 1024 * 1024;
351         $session->max_buffer_length(5 * $MB);
352
353   Sending multiple lines at once
354       Some commands like "extended ping" and "copy" prompt for several lines
355       of data. It's not necessary to change the prompt for each line.
356       Instead, send everything at once, separated by newlines.
357
358       For:
359
360         router# ping
361         Protocol [ip]:
362         Target IP address: 10.0.0.1
363         Repeat count [5]: 10
364         Datagram size [100]: 1500
365         Timeout in seconds [2]:
366         Extended commands [n]:
367         Sweep range of sizes [n]:
368
369       Try this:
370
371         my $protocol  = ''; # default value
372         my $ip       = '10.0.0.1';
373         my $repeat    = 10;
374         my $datagram  = 1500;
375         my $timeout   = ''; # default value
376         my $extended  = ''; # default value
377         my $sweep     = ''; # default value
378
379         $session->cmd(
380         "ping
381         $protocol
382         $ip
383         $repeat
384         $datagram
385         $timeout
386         $extended
387         $sweep
388         ");
389
390       If you prefer, you can put the cmd on a single line and replace every
391       static newline with the "\n" character.
392
393       e.g.
394
395         $session->cmd("ping\n$protocol\n$ip\n$repeat\n$datagram\n"
396                 . "$timeout\n$extended\n$sweep\n");
397
398   Backup via TFTP
399       Backs up the running-confg to a TFTP server. Backup file is in the form
400       "router-confg". Make sure that file exists on the TFTP server or the
401       transfer will fail!
402
403         my $backup_host  = "tftpserver.somewhere.net";
404         my $device       = "cisco.somewhere.net";
405         my $type         = "router"; # or "switch";
406         my $ios_version  = 12;
407
408         my @out;
409         if ($type eq "router") {
410             if ($ios_version >= 12) {
411                 @out = $session->cmd("copy system:/running-config "
412                       . "tftp://$backup_host/$device-confg\n\n\n");
413             } elsif ($ios_version >= 11) {
414                 @out = $session->cmd("copy running-config tftp\n$backup_host\n"
415                       . "$device-confg\n");
416             } elsif ($ios_version >= 10) {
417                 @out = $session->cmd("write net\n$backup_host\n$device-confg\n\n");
418             }
419         } elsif ($type eq "switch") {
420             @out = $session->cmd("copy system:/running-config "
421                       . "tftp://$backup_host/$device-confg\n\n\n");
422         }
423

SUPPORT

425       http://NetTelnetCisco.sourceforge.net/
426
427   Mailing lists
428       nettelnetcisco-announce is for important security bulletins and
429       upgrades. Very low traffic, no spam, HIGHLY RECOMMENDED!
430       http://lists.sourceforge.net/lists/listinfo/nettelnetcisco-announce
431
432       nettelnetcisco-users is for usage discussion, help, tips, tricks, etc.
433       http://lists.sourceforge.net/lists/listinfo/nettelnetcisco-users
434
435       nettelnetcisco-devel is for uber-hackers; you know who you are.
436       http://lists.sourceforge.net/lists/listinfo/nettelnetcisco-devel
437
438   Help/discussion forums
439       http://sourceforge.net/forum/?group_id=48856
440
441   Bug tracker
442       http://sourceforge.net/tracker/?group_id=48856
443

SEE ALSO

445       Net::Telnet
446
447       Net::SNMP
448
449       UCD NetSNMP - http://www.netsnmp.org/
450
451       RAT/NCAT - http://ncat.sourceforge.net/
452

AUTHOR

454       Joshua_Keroes@eli.net $Date: 2002/06/18 17:17:03 $
455
456       It would greatly amuse the author if you would send email to him and
457       tell him how you are using Net::Telnet::Cisco.
458
459       As of Mar 2002, 170 people have emailed me. N::T::C is used to help
460       manage over 14,000 machines! Keep the email rolling in!
461

THANKS

463       The following people understand what Open Source Software is all about.
464       Thanks Brian Landers, Aaron Racine, Niels van Dijke, Tony Mueller,
465       Frank Eickholt, Al Sorrell, Jebi Punnoose, Christian Alfsen, Niels van
466       Dijke, Kevin der Kinderen, Ian Batterbee, Leonardo Cont, Steve Meier,
467       and Andre Bonhote.
468
469       Institutions: infobot.org #perl, perlmonks.org, sourceforge.net, the
470       geeks at geekhouse.org, and eli.net.
471
472       Send in a patch and we can make the world a better place.
473
475       Copyright (c) 2000-2002 Joshua Keroes, Electric Lightwave Inc.  All
476       rights reserved. This program is free software; you can redistribute it
477       and/or modify it under the same terms as Perl itself.
478
479
480
481perl v5.32.1                      2021-01-27             Net::Telnet::Cisco(3)
Impressum