1Cisco(3) User Contributed Perl Documentation Cisco(3)
2
6 Net::Telnet::Cisco - interact with a Cisco router
7
9 use Net::Telnet::Cisco;
10 my $session = Net::Telnet::Cisco->new(Host => '123.123.123.123');
12 $session->login('login', 'password');
13 # Execute a command
15 my @output = $session->cmd('show version');
16 print @output;
17 # 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 $session->close;
27
29 Net::Telnet::Cisco provides additional functionality to Net::Telnet for
30 dealing with Cisco routers.
31 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
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 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
48 new - create new Net::Telnet::Cisco object
49 $session = Net::Telnet::Cisco->new(
50 [Autopage => $boolean,] # 1
51 [More_prompt => $matchop,] # '/(?m:^\s*--More--)/',
52 [Always_waitfor_prompt => $boolean,] # 1
53 [Waitfor_pause => $milliseconds,] # 0.1
54 [Normalize_cmd => $boolean,] # 1
55 [Send_wakeup => $when,] # 0
56 [Ignore_warnings => $boolean,] # 0
57 [Warnings => $matchop,] # see docs
58 # Net::Telnet arguments
60 [Binmode => $mode,]
61 [Cmd_remove_mode => $mode,]
62 [Dump_Log => $filename,]
63 [Errmode => $errmode,]
64 [Fhopen => $filehandle,]
65 [Host => $host,]
66 [Input_log => $file,]
67 [Input_record_separator => $char,]
68 [Option_log => $file,]
69 [Output_log => $file,]
70 [Output_record_separator => $char,]
71 [Port => $port,]
72 [Prompt => $matchop,] # see docs
73 [Telnetmode => $mode,]
74 [Timeout => $secs,]
75 );
76 Creates a new object. Read `perldoc perlboot` if you don't
78 understand that.
79 login - login to a router
81 $ok = $obj->login($username, $password);
82 $ok = $obj->login([Name => $username,]
84 [Password => $password,]
85 [Passcode => $passcode,] # for Secur-ID/XTACACS
86 [Prompt => $match,]
87 [Timeout => $secs,]);
88 All arguments are optional as of v1.05. Some routers don't ask for
90 a username, they start the login conversation with a password
91 request.
92 cmd - send a command
94 $ok = $obj->cmd($string);
95 $ok = $obj->cmd(String => $string,
96 [Output => $ref,]
97 [Prompt => $match,]
98 [Timeout => $secs,]
99 [Cmd_remove_mode => $mode,]);
100 @output = $obj->cmd($string);
102 @output = $obj->cmd(String => $string,
103 [Output => $ref,]
104 [Prompt => $match,]
105 [Timeout => $secs,]
106 [Cmd_remove_mode => $mode,]
107 [Normalize_cmd => $boolean,]);
108 Normalize_cmd has been added to the default Net::Telnet args. It
110 lets you temporarily change whether backspace, delete, and kill
111 characters are parsed in the command output. (This is performed by
112 default)
113 prompt - return control to the program whenever this string occurs in
115 router output
116 $matchop = $obj->prompt;
117 $prev = $obj->prompt($matchop);
119 The default cmd_prompt changed in v1.05. It's suitable for matching
121 prompts like "router$ ", "router# ", "router> (enable) ", and
122 "router(config-if)# "
123 Let's take a closer look, shall we?
125 (?m: # Net::Telnet doesn't accept quoted regexen (i.e. qr//)
127 # so we need to use an embedded pattern-match modifier
128 # to treat the input as a multiline buffer.
129 ^ # beginning of line
131 [\w.-]+ # router hostname
133 \s? # optional space
135 (?: # Strings like "(config)" and "(config-if)", "(config-line)",
137 # and "(config-router)" indicate that we're in privileged
138 \(config[^\)]*\) # EXEC mode (i.e. we're enabled).
139 )? # The middle backslash is only there to appear my syntax
140 # highlighter.
141 \s? # more optional space
143 [\$#>] # Prompts typically end with "$", "#", or ">". Backslash
145 # for syntax-highlighter.
146 \s? # more space padding
148 (?: # Catalyst switches print "(enable)" when in privileged
150 \(enable\) # EXEC mode.
151 )?
152 \s* # spaces before the end-of-line aren't important to us.
154 $ # end of line
156 ) # end of (?m:
158 The default prompt published in 1.03 was
160 "/^\s*[\w().-]*[\$#>]\s?(?:\(enable\))?\s*$/". As you can see, the
161 prompt was drastically overhauled in 1.05. If your code suddenly
162 starts timing out after upgrading Net::Telnet::Cisco, this is the
163 first thing to investigate.
164 enable - enter enabled mode
166 $ok = $obj->enable;
167 $ok = $obj->enable($password);
169 $ok = $obj->enable([Name => $name,] [Password => $password,]
171 [Passcode => $passcode,] [Level => $level,]);
172 This method changes privilege level to enabled mode, (i.e. root)
174 If a single argument is provided by the caller, it will be used as
176 a password. For more control, including the ability to set the
177 privilege-level, you must use the named-argument scheme.
178 enable() returns 1 on success and undef on failure.
180 is_enabled - Am I root?
182 $bool = $obj->is_enabled;
183 A trivial check to see whether we have a root-style prompt, with
185 either the word "(enable)" in it, or a trailing "#".
186 Warning: this method will return false positives if your prompt has
188 "#"s in it. You may be better off calling "$obj->cmd("show
189 privilege")" instead.
190 disable - leave enabled mode
192 $ok = $obj->disable;
193 This method exits the router's privileged mode.
195 ios_break - send a break (control-^)
197 $ok = $obj->ios_break;
198 You may have to use errmode(), fork, or threads to break at the an
200 appropriate time.
201 last_prompt - displays the last prompt matched by prompt()
203 $match = $obj->last_prompt;
204 last_prompt() will return '' if the program has not yet matched a
206 prompt.
207 always_waitfor_prompt - waitfor and cmd prompt behaviour
209 $boolean = $obj->always_waitfor_prompt;
210 $boolean = $obj->always_waitfor_prompt($boolean);
212 Default value: 1
214 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 This method has no effect on login(). login() will always wait for
221 a prompt.
222 waitfor_pause - insert a small delay before waitfor()
224 $boolean = $obj->waitfor_pause;
225 $boolean = $obj->waitfor_pause($milliseconds);
227 Default value: 0.1
229 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 autopage - Turn autopaging on and off
236 $boolean = $obj->autopage;
237 $boolean = $obj->autopage($boolean);
239 Default value: 1
241 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 normalize_cmd - Turn normalization on and off
248 $boolean = $obj->normalize_cmd;
249 $boolean = $obj->normalize_cmd($boolean);
251 Default value: 1
253 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 Logging is unaffected by this setting.
260 more_prompt - Matchop used by autopage()
262 $matchop = $obj->prompt;
263 $prev = $obj->prompt($matchop);
265 Default value: '/(?m:\s*--More--)/'.
267 Please email me if you find others.
269 send_wakeup - send a newline to the router at login time
271 $when = $obj->send_wakeup;
272 $when = $obj->send_wakeup( 'connect' );
274 $when = $obj->send_wakeup( 'timeout' );
275 $when = $obj->send_wakeup( 0 );
276 Default value: 0
278 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 'connect' sends a newline immediately upon connection. 'timeout'
284 sends a newline if the connection timeouts. 0 turns this feature
285 off.
286 I understand this works with Livingston Portmasters.
288 ignore_warnings - Don't call error() for warnings
290 $boolean = $obj->ignore_warnings;
291 $boolean = $obj->ignore_warnings($boolean);
293 Default value: 0
295 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 warnings - Matchop used by ignore_warnings().
301 $boolean = $obj->warnings;
302 $boolean = $obj->warnings($matchop);
304 Default value:
306 /(?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 Not all strings that begin with a '%' are really errors. Some are
315 just warnings. Cisco calls these the CIPMIOSWarningExpressions.
316
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 # To a router
325 $session->cmd('terminal length 0');
326 # To a switch
328 $session->cmd('set length 0');
329 Logging
331 Want to see the session transcript? Just call input_log().
332 e.g.
334 my $session = Net::Telnet::Cisco->new(Host => $router,
335 Input_log => "input.log",
336 );
337 See input_log() in Net::Telnet for info.
339 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 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 my $MB = 1024 * 1024;
351 $session->max_buffer_length(5 * $MB);
352 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 For:
359 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 Try this:
370 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 $session->cmd(
380 "ping
381 $protocol
382 $ip
383 $repeat
384 $datagram
385 $timeout
386 $extended
387 $sweep
388 ");
389 If you prefer, you can put the cmd on a single line and replace every
391 static newline with the "\n" character.
392 e.g.
394 $session->cmd("ping\n$protocol\n$ip\n$repeat\n$datagram\n"
396 . "$timeout\n$extended\n$sweep\n");
397 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 my $backup_host = "tftpserver.somewhere.net";
404 my $device = "cisco.somewhere.net";
405 my $type = "router"; # or "switch";
406 my $ios_version = 12;
407 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
425 http://NetTelnetCisco.sourceforge.net/
426 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 nettelnetcisco-users is for usage discussion, help, tips, tricks, etc.
433 http://lists.sourceforge.net/lists/listinfo/nettelnetcisco-users
434 nettelnetcisco-devel is for uber-hackers; you know who you are.
436 http://lists.sourceforge.net/lists/listinfo/nettelnetcisco-devel
437 Help/discussion forums
439 http://sourceforge.net/forum/?group_id=48856
440 Bug tracker
442 http://sourceforge.net/tracker/?group_id=48856
443
445 Net::Telnet
446 Net::SNMP
448 UCD NetSNMP - http://www.netsnmp.org/
450 RAT/NCAT - http://ncat.sourceforge.net/
452
454 Joshua_Keroes@eli.net $Date: 2002/06/18 17:17:03 $
455 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 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
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 Institutions: infobot.org #perl, perlmonks.org, sourceforge.net, the
470 geeks at geekhouse.org, and eli.net.
471 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.
478perl v5.12.1 2002-06-18 Cisco(3)