1Net::Telnet(3) User Contributed Perl Documentation Net::Telnet(3)
2
6 Net::Telnet - interact with TELNET port or other TCP ports
7
9 "use Net::Telnet ();"
10 see METHODS section below
12
14 Net::Telnet allows you to make client connections to a TCP port and do
15 network I/O, especially to a port using the TELNET protocol. Simple
16 I/O methods such as print, get, and getline are provided. More
17 sophisticated interactive features are provided because connecting to a
18 TELNET port ultimately means communicating with a program designed for
19 human interaction. These interactive features include the ability to
20 specify a time-out and to wait for patterns to appear in the input
21 stream, such as the prompt from a shell.
22 Other reasons to use this module than strictly with a TELNET port are:
24 · You're not familiar with sockets and you want a simple way to make
26 client connections to TCP services.
27 · You want to be able to specify your own time-out while connecting,
29 reading, or writing.
30 · You're communicating with an interactive program at the other end of
32 some socket or pipe and you want to wait for certain patterns to
33 appear.
34 Here's an example that prints who's logged-on to the remote host
36 sparky. In addition to a username and password, you must also know the
37 user's shell prompt, which for this example is "bash$"
38 use Net::Telnet ();
40 $t = new Net::Telnet (Timeout => 10,
41 Prompt => '/bash\$ $/');
42 $t->open("sparky");
43 $t->login($username, $passwd);
44 @lines = $t->cmd("who");
45 print @lines;
46 More examples are in the EXAMPLES section below.
48 Usage questions should be directed to the Usenet newsgroup
50 comp.lang.perl.modules.
51 Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have
53 suggestions for improvement.
54 What To Know Before Using
56 · All output is flushed while all input is buffered. Each object
57 contains its own input buffer.
58 · The output record separator for "print()" and "cmd()" is set to "\n"
60 by default, so that you don't have to append all your commands with a
61 newline. To avoid printing a trailing "\n" use "put()" or set the
62 output_record_separator to "".
63 · The methods "login()" and "cmd()" use the prompt setting in the
65 object to determine when a login or remote command is complete.
66 Those methods will fail with a time-out if you don't set the prompt
67 correctly.
68 · Use a combination of "print()" and "waitfor()" as an alternative to
70 "login()" or "cmd()" when they don't do what you want.
71 · Errors such as timing-out are handled according to the error mode
73 action. The default action is to print an error message to standard
74 error and have the program die. See the "errmode()" method for more
75 information.
76 · When constructing the match operator argument for "prompt()" or
78 "waitfor()", always use single quotes instead of double quotes to
79 avoid unexpected backslash interpretation (e.g. '/bash\$ $/'). If
80 you're constructing a DOS like file path, you'll need to use four
81 backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').
82 Of course don't forget about regexp metacharacters like ".", "[", or
84 "$". You'll only need a single backslash to quote them. The anchor
85 metacharacters "^" and "$" refer to positions in the input buffer.
86 To avoid matching characters read that look like a prompt, it's a
87 good idea to end your prompt pattern with the "$" anchor. That way
88 the prompt will only match if it's the last thing read.
89 · In the input stream, each sequence of carriage return and line feed
91 (i.e. "\015\012" or CR LF) is converted to "\n". In the output
92 stream, each occurrence of "\n" is converted to a sequence of CR LF.
93 See "binmode()" to change the behavior. TCP protocols typically use
94 the ASCII sequence, carriage return and line feed to designate a
95 newline.
96 · Timing-out while making a connection is disabled for machines that
98 don't support the "alarm()" function. Most notably these include MS-
99 Windows machines.
100 · You'll need to be running at least Perl version 5.002 to use this
102 module. This module does not require any libraries that don't
103 already come with a standard Perl distribution.
104 If you have the IO:: libraries installed (they come standard with
106 perl5.004 and later) then IO::Socket::INET is used as a base class,
107 otherwise FileHandle is used.
108 · Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have
110 suggestions for improvement.
111 Debugging
113 The typical usage bug causes a time-out error because you've made
114 incorrect assumptions about what the remote side actually sends. The
115 easiest way to reconcile what the remote side sends with your
116 expectations is to use "input_log()" or "dump_log()".
117 "dump_log()" allows you to see the data being sent from the remote side
119 before any translation is done, while "input_log()" shows you the
120 results after translation. The translation includes converting end of
121 line characters, removing and responding to TELNET protocol commands in
122 the data stream.
123 Style of Named Parameters
125 Two different styles of named parameters are supported. This document
126 only shows the IO:: style:
127 Net::Telnet->new(Timeout => 20);
129 however the dash-option style is also allowed:
131 Net::Telnet->new(-timeout => 20);
133 Connecting to a Remote MS-Windows Machine
135 By default MS-Windows doesn't come with a TELNET server. However third
136 party TELNET servers are available. Unfortunately many of these
137 servers falsely claim to be a TELNET server. This is especially true
138 of the so-called "Microsoft Telnet Server" that comes installed with
139 some newer versions MS-Windows.
140 When a TELNET server first accepts a connection, it must use the ASCII
142 control characters carriage-return and line-feed to start a new line
143 (see RFC854). A server like the "Microsoft Telnet Server" that doesn't
144 do this, isn't a TELNET server. These servers send ANSI terminal
145 escape sequences to position to a column on a subsequent line and to
146 even position while writing characters that are adjacent to each other.
147 Worse, when sending output these servers resend previously sent command
148 output in a misguided attempt to display an entire terminal screen.
149 Connecting Net::Telnet to one of these false TELNET servers makes your
151 job of parsing command output very difficult. It's better to replace a
152 false TELNET server with a real TELNET server. The better TELNET
153 servers for MS-Windows allow you to avoid the ANSI escapes by turning
154 off something some of them call console mode.
155
157 In the calling sequences below, square brackets [] represent optional
158 parameters.
159 new - create a new Net::Telnet object
161 $obj = new Net::Telnet ([$host]);
162 $obj = new Net::Telnet ([Binmode => $mode,]
164 [Cmd_remove_mode => $mode,]
165 [Dump_Log => $filename,]
166 [Errmode => $errmode,]
167 [Fhopen => $filehandle,]
168 [Host => $host,]
169 [Input_log => $file,]
170 [Input_record_separator => $chars,]
171 [Option_log => $file,]
172 [Ors => $chars,]
173 [Output_log => $file,]
174 [Output_record_separator => $chars,]
175 [Port => $port,]
176 [Prompt => $matchop,]
177 [Rs => $chars,]
178 [Telnetmode => $mode,]
179 [Timeout => $secs,]);
180 This is the constructor for Net::Telnet objects. A new object is
182 returned on success, the error mode action is performed on failure
183 - see "errmode()". The optional arguments are short-cuts to
184 methods of the same name.
185 If the $host argument is given then the object is opened by
187 connecting to TCP $port on $host. Also see "open()". The new
188 object returned is given the following defaults in the absence of
189 corresponding named parameters:
190 · The default Host is "localhost"
192 · The default Port is 23
194 · The default Prompt is '/[\$%#>] $/'
196 · The default Timeout is 10
198 · The default Errmode is "die"
200 · The default Output_record_separator is "\n". Note that Ors is
202 synonymous with Output_record_separator.
203 · The default Input_record_separator is "\n". Note that Rs is
205 synonymous with Input_record_separator.
206 · The default Binmode is 0, which means do newline translation.
208 · The default Telnetmode is 1, which means respond to TELNET
210 commands in the data stream.
211 · The default Cmd_remove_mode is "auto"
213 · The defaults for Dump_log, Input_log, Option_log, and
215 Output_log are "", which means that logging is turned-off.
216 binmode - toggle newline translation
218 $mode = $obj->binmode;
219 $prev = $obj->binmode($mode);
221 This method controls whether or not sequences of carriage returns
223 and line feeds (CR LF or more specifically "\015\012") are
224 translated. By default they are translated (i.e. binmode is 0).
225 If no argument is given, the current mode is returned.
227 If $mode is 1 then binmode is on and newline translation is not
229 done.
230 If $mode is 0 then binmode is off and newline translation is done.
232 In the input stream, each sequence of CR LF is converted to "\n"
233 and in the output stream, each occurrence of "\n" is converted to a
234 sequence of CR LF.
235 Note that input is always buffered. Changing binmode doesn't
237 effect what's already been read into the buffer. Output is not
238 buffered and changing binmode will have an immediate effect.
239 break - send TELNET break character
241 $ok = $obj->break;
242 This method sends the TELNET break character. This character is
244 provided because it's a signal outside the ASCII character set
245 which is currently given local meaning within many systems. It's
246 intended to indicate that the Break Key or the Attention Key was
247 hit.
248 This method returns 1 on success, or performs the error mode action
250 on failure.
251 buffer - scalar reference to object's input buffer
253 $ref = $obj->buffer;
254 This method returns a scalar reference to the input buffer for
256 $obj. Data in the input buffer is data that has been read from the
257 remote side but has yet to be read by the user. Modifications to
258 the input buffer are returned by a subsequent read.
259 buffer_empty - discard all data in object's input buffer
261 $obj->buffer_empty;
262 This method removes all data in the input buffer for $obj.
264 close - close object
266 $ok = $obj->close;
267 This method closes the socket, file, or pipe associated with the
269 object. It always returns a value of 1.
270 cmd - issue command and retrieve output
272 $ok = $obj->cmd($string);
273 $ok = $obj->cmd(String => $string,
274 [Output => $ref,]
275 [Cmd_remove_mode => $mode,]
276 [Errmode => $mode,]
277 [Input_record_separator => $chars,]
278 [Ors => $chars,]
279 [Output_record_separator => $chars,]
280 [Prompt => $match,]
281 [Rs => $chars,]
282 [Timeout => $secs,]);
283 @output = $obj->cmd($string);
285 @output = $obj->cmd(String => $string,
286 [Output => $ref,]
287 [Cmd_remove_mode => $mode,]
288 [Errmode => $mode,]
289 [Input_record_separator => $chars,]
290 [Ors => $chars,]
291 [Output_record_separator => $chars,]
292 [Prompt => $match,]
293 [Rs => $chars,]
294 [Timeout => $secs,]);
295 This method sends the command $string, and reads the characters
297 sent back by the command up until and including the matching
298 prompt. It's assumed that the program to which you're sending is
299 some kind of command prompting interpreter such as a shell.
300 The command $string is automatically appended with the
302 output_record_separator, By default that's "\n". This is similar
303 to someone typing a command and hitting the return key. Set the
304 output_record_separator to change this behavior.
305 In a scalar context, the characters read from the remote side are
307 discarded and 1 is returned on success. On time-out, eof, or other
308 failures, the error mode action is performed. See "errmode()".
309 In a list context, just the output generated by the command is
311 returned, one line per element. In other words, all the characters
312 in between the echoed back command string and the prompt are
313 returned. If the command happens to return no output, a list
314 containing one element, the empty string is returned. This is so
315 the list will indicate true in a boolean context. On time-out,
316 eof, or other failures, the error mode action is performed. See
317 "errmode()".
318 The characters that matched the prompt may be retrieved using
320 "last_prompt()".
321 Many command interpreters echo back the command sent. In most
323 situations, this method removes the first line returned from the
324 remote side (i.e. the echoed back command). See
325 "cmd_remove_mode()" for more control over this feature.
326 Use "dump_log()" to debug when this method keeps timing-out and you
328 don't think it should.
329 Consider using a combination of "print()" and "waitfor()" as an
331 alternative to this method when it doesn't do what you want, e.g.
332 the command you send prompts for input.
333 The Output named parameter provides an alternative method of
335 receiving command output. If you pass a scalar reference, all the
336 output (even if it contains multiple lines) is returned in the
337 referenced scalar. If you pass an array or hash reference, the
338 lines of output are returned in the referenced array or hash. You
339 can use "input_record_separator()" to change the notion of what
340 separates a line.
341 Optional named parameters are provided to override the current
343 settings of cmd_remove_mode, errmode, input_record_separator, ors,
344 output_record_separator, prompt, rs, and timeout. Rs is synonymous
345 with input_record_separator and ors is synonymous with
346 output_record_separator.
347 cmd_remove_mode - toggle removal of echoed commands
349 $mode = $obj->cmd_remove_mode;
350 $prev = $obj->cmd_remove_mode($mode);
352 This method controls how to deal with echoed back commands in the
354 output returned by cmd(). Typically, when you send a command to
355 the remote side, the first line of output returned is the command
356 echoed back. Use this mode to remove the first line of output
357 normally returned by cmd().
358 If no argument is given, the current mode is returned.
360 If $mode is 0 then the command output returned from cmd() has no
362 lines removed. If $mode is a positive integer, then the first
363 $mode lines of command output are stripped.
364 By default, $mode is set to "auto". Auto means that whether or not
366 the first line of command output is stripped, depends on whether or
367 not the remote side offered to echo. By default, Net::Telnet
368 always accepts an offer to echo by the remote side. You can change
369 the default to reject such an offer using "option_accept()".
370 A warning is printed to STDERR when attempting to set this
372 attribute to something that's not "auto" or a non-negative integer.
373 dump_log - log all I/O in dump format
375 $fh = $obj->dump_log;
376 $fh = $obj->dump_log($fh);
378 $fh = $obj->dump_log($filename);
380 This method starts or stops dump format logging of all the object's
382 input and output. The dump format shows the blocks read and
383 written in a hexadecimal and printable character format. This
384 method is useful when debugging, however you might want to first
385 try "input_log()" as it's more readable.
386 If no argument is given, the current log filehandle is returned.
388 An empty string indicates logging is off.
389 To stop logging, use an empty string as an argument.
391 If an open filehandle is given, it is used for logging and
393 returned. Otherwise, the argument is assumed to be the name of a
394 file, the file is opened and a filehandle to it is returned. If
395 the file can't be opened for writing, the error mode action is
396 performed.
397 eof - end of file indicator
399 $eof = $obj->eof;
400 This method returns 1 if end of file has been read, otherwise it
402 returns an empty string. Because the input is buffered this isn't
403 the same thing as $obj has closed. In other words $obj can be
404 closed but there still can be stuff in the buffer to be read.
405 Under this condition you can still read but you won't be able to
406 write.
407 errmode - define action to be performed on error
409 $mode = $obj->errmode;
410 $prev = $obj->errmode($mode);
412 This method gets or sets the action used when errors are
414 encountered using the object. The first calling sequence returns
415 the current error mode. The second calling sequence sets it to
416 $mode and returns the previous mode. Valid values for $mode are
417 "die" (the default), "return", a coderef, or an arrayref.
418 When mode is "die" and an error is encountered using the object,
420 then an error message is printed to standard error and the program
421 dies.
422 When mode is "return" then the method generating the error places
424 an error message in the object and returns an undefined value in a
425 scalar context and an empty list in list context. The error
426 message may be obtained using "errmsg()".
427 When mode is a coderef, then when an error is encountered coderef
429 is called with the error message as its first argument. Using this
430 mode you may have your own subroutine handle errors. If coderef
431 itself returns then the method generating the error returns
432 undefined or an empty list depending on context.
433 When mode is an arrayref, the first element of the array must be a
435 coderef. Any elements that follow are the arguments to coderef.
436 When an error is encountered, the coderef is called with its
437 arguments. Using this mode you may have your own subroutine handle
438 errors. If the coderef itself returns then the method generating
439 the error returns undefined or an empty list depending on context.
440 A warning is printed to STDERR when attempting to set this
442 attribute to something that's not "die", "return", a coderef, or an
443 arrayref whose first element isn't a coderef.
444 errmsg - most recent error message
446 $msg = $obj->errmsg;
447 $prev = $obj->errmsg(@msgs);
449 The first calling sequence returns the error message associated
451 with the object. The empty string is returned if no error has been
452 encountered yet. The second calling sequence sets the error
453 message for the object to the concatenation of @msgs and returns
454 the previous error message. Normally, error messages are set
455 internally by a method when an error is encountered.
456 error - perform the error mode action
458 $obj->error(@msgs);
459 This method concatenates @msgs into a string and places it in the
461 object as the error message. Also see "errmsg()". It then
462 performs the error mode action. Also see "errmode()".
463 If the error mode doesn't cause the program to die, then an
465 undefined value or an empty list is returned depending on the
466 context.
467 This method is primarily used by this class or a sub-class to
469 perform the user requested action when an error is encountered.
470 fhopen - use already open filehandle for I/O
472 $ok = $obj->fhopen($fh);
473 This method associates the open filehandle $fh with $obj for
475 further I/O. Filehandle $fh must already be opened.
476 Suppose you want to use the features of this module to do I/O to
478 something other than a TCP port, for example STDIN or a filehandle
479 opened to read from a process. Instead of opening the object for
480 I/O to a TCP port by using "open()" or "new()", call this method
481 instead.
482 The value 1 is returned success, the error mode action is performed
484 on failure.
485 get - read block of data
487 $data = $obj->get([Binmode => $mode,]
488 [Errmode => $errmode,]
489 [Telnetmode => $mode,]
490 [Timeout => $secs,]);
491 This method reads a block of data from the object and returns it
493 along with any buffered data. If no buffered data is available to
494 return, it will wait for data to read using the timeout specified
495 in the object. You can override that timeout using $secs. Also
496 see "timeout()". If buffered data is available to return, it also
497 checks for a block of data that can be immediately read.
498 On eof an undefined value is returned. On time-out or other
500 failures, the error mode action is performed. To distinguish
501 between eof or an error occurring when the error mode is not set to
502 "die", use "eof()".
503 Optional named parameters are provided to override the current
505 settings of binmode, errmode, telnetmode, and timeout.
506 getline - read next line
508 $line = $obj->getline([Binmode => $mode,]
509 [Errmode => $errmode,]
510 [Input_record_separator => $chars,]
511 [Rs => $chars,]
512 [Telnetmode => $mode,]
513 [Timeout => $secs,]);
514 This method reads and returns the next line of data from the
516 object. You can use "input_record_separator()" to change the
517 notion of what separates a line. The default is "\n". If a line
518 isn't immediately available, this method blocks waiting for a line
519 or a time-out.
520 On eof an undefined value is returned. On time-out or other
522 failures, the error mode action is performed. To distinguish
523 between eof or an error occurring when the error mode is not set to
524 "die", use "eof()".
525 Optional named parameters are provided to override the current
527 settings of binmode, errmode, input_record_separator, rs,
528 telnetmode, and timeout. Rs is synonymous with
529 input_record_separator.
530 getlines - read next lines
532 @lines = $obj->getlines([Binmode => $mode,]
533 [Errmode => $errmode,]
534 [Input_record_separator => $chars,]
535 [Rs => $chars,]
536 [Telnetmode => $mode,]
537 [Timeout => $secs,]
538 [All => $boolean,]);
539 This method reads and returns all the lines of data from the object
541 until end of file is read. You can use "input_record_separator()"
542 to change the notion of what separates a line. The default is
543 "\n". A time-out error occurs if all the lines can't be read
544 within the time-out interval. See "timeout()".
545 The behavior of this method was changed in version 3.03. Prior to
547 version 3.03 this method returned just the lines available from the
548 next read. To get that old behavior, use the optional named
549 parameter All and set $boolean to "" or 0.
550 If only eof is read then an empty list is returned. On time-out or
552 other failures, the error mode action is performed. Use "eof()" to
553 distinguish between reading only eof or an error occurring when the
554 error mode is not set to "die".
555 Optional named parameters are provided to override the current
557 settings of binmode, errmode, input_record_separator, rs,
558 telnetmode, and timeout. Rs is synonymous with
559 input_record_separator.
560 host - name of remote host
562 $host = $obj->host;
563 $prev = $obj->host($host);
565 This method designates the remote host for "open()". With no
567 argument it returns the current host name set in the object. With
568 an argument it sets the current host name to $host and returns the
569 previous host name. You may indicate the remote host using either
570 a hostname or an IP address.
571 The default value is "localhost". It may also be set by "open()"
573 or "new()".
574 input_log - log all input
576 $fh = $obj->input_log;
577 $fh = $obj->input_log($fh);
579 $fh = $obj->input_log($filename);
581 This method starts or stops logging of input. This is useful when
583 debugging. Also see "dump_log()". Because most command
584 interpreters echo back commands received, it's likely all your
585 output will also be in this log. Note that input logging occurs
586 after newline translation. See "binmode()" for details on newline
587 translation.
588 If no argument is given, the log filehandle is returned. An empty
590 string indicates logging is off.
591 To stop logging, use an empty string as an argument.
593 If an open filehandle is given, it is used for logging and
595 returned. Otherwise, the argument is assumed to be the name of a
596 file, the file is opened for logging and a filehandle to it is
597 returned. If the file can't be opened for writing, the error mode
598 action is performed.
599 input_record_separator - input line delimiter
601 $chars = $obj->input_record_separator;
602 $prev = $obj->input_record_separator($chars);
604 This method designates the line delimiter for input. It's used
606 with "getline()", "getlines()", and "cmd()" to determine lines in
607 the input.
608 With no argument this method returns the current input record
610 separator set in the object. With an argument it sets the input
611 record separator to $chars and returns the previous value. Note
612 that $chars must have length.
613 A warning is printed to STDERR when attempting to set this
615 attribute to a string with no length.
616 last_prompt - last prompt read
618 $string = $obj->last_prompt;
619 $prev = $obj->last_prompt($string);
621 With no argument this method returns the last prompt read by cmd()
623 or login(). See "prompt()". With an argument it sets the last
624 prompt read to $string and returns the previous value. Normally,
625 only internal methods set the last prompt.
626 lastline - last line read
628 $line = $obj->lastline;
629 $prev = $obj->lastline($line);
631 This method retrieves the last line read from the object. This may
633 be a useful error message when the remote side abnormally closes
634 the connection. Typically the remote side will print an error
635 message before closing.
636 With no argument this method returns the last line read from the
638 object. With an argument it sets the last line read to $line and
639 returns the previous value. Normally, only internal methods set
640 the last line.
641 login - perform standard login
643 $ok = $obj->login($username, $password);
644 $ok = $obj->login(Name => $username,
646 Password => $password,
647 [Errmode => $mode,]
648 [Prompt => $match,]
649 [Timeout => $secs,]);
650 This method performs a standard login by waiting for a login prompt
652 and responding with $username, then waiting for the password prompt
653 and responding with $password, and then waiting for the command
654 interpreter prompt. If any of those prompts sent by the remote
655 side don't match what's expected, this method will time-out, unless
656 timeout is turned off.
657 Login prompt must match either of these case insensitive patterns:
659 /login[: ]*$/i
661 /username[: ]*$/i
662 Password prompt must match this case insensitive pattern:
664 /password[: ]*$/i
666 The command interpreter prompt must match the current setting of
668 prompt. See "prompt()".
669 Use "dump_log()" to debug when this method keeps timing-out and you
671 don't think it should.
672 Consider using a combination of "print()" and "waitfor()" as an
674 alternative to this method when it doesn't do what you want, e.g.
675 the remote host doesn't prompt for a username.
676 On success, 1 is returned. On time out, eof, or other failures,
678 the error mode action is performed. See "errmode()".
679 Optional named parameters are provided to override the current
681 settings of errmode, prompt, and timeout.
682 max_buffer_length - maximum size of input buffer
684 $len = $obj->max_buffer_length;
685 $prev = $obj->max_buffer_length($len);
687 This method designates the maximum size of the input buffer. An
689 error is generated when a read causes the buffer to exceed this
690 limit. The default value is 1,048,576 bytes (1MB). The input
691 buffer can grow much larger than the block size when you
692 continuously read using "getline()" or "waitfor()" and the data
693 stream contains no newlines or matching waitfor patterns.
694 With no argument, this method returns the current maximum buffer
696 length set in the object. With an argument it sets the maximum
697 buffer length to $len and returns the previous value. Values of
698 $len smaller than 512 will be adjusted to 512.
699 A warning is printed to STDERR when attempting to set this
701 attribute to something that isn't a positive integer.
702 ofs - field separator for print
704 $chars = $obj->ofs
705 $prev = $obj->ofs($chars);
707 This method is synonymous with "output_field_separator()".
709 open - connect to port on remote host
711 $ok = $obj->open($host);
712 $ok = $obj->open([Host => $host,]
714 [Port => $port,]
715 [Errmode => $mode,]
716 [Timeout => $secs,]);
717 This method opens a TCP connection to $port on $host. If either
719 argument is missing then the current value of "host()" or "port()"
720 is used. Optional named parameters are provided to override the
721 current setting of errmode and timeout.
722 On success 1 is returned. On time-out or other connection
724 failures, the error mode action is performed. See "errmode()".
725 Time-outs don't work for this method on machines that don't
727 implement SIGALRM - most notably MS-Windows machines. For those
728 machines, an error is returned when the system reaches its own
729 time-out while trying to connect.
730 A side effect of this method is to reset the alarm interval
732 associated with SIGALRM.
733 option_accept - indicate willingness to accept a TELNET option
735 $fh = $obj->option_accept([Do => $telopt,]
736 [Dont => $telopt,]
737 [Will => $telopt,]
738 [Wont => $telopt,]);
739 This method is used to indicate whether to accept or reject an
741 offer to enable a TELNET option made by the remote side. If you're
742 using Do or Will to indicate a willingness to enable, then a
743 notification callback must have already been defined by a prior
744 call to "option_callback()". See "option_callback()" for details
745 on receiving enable/disable notification of a TELNET option.
746 You can give multiple Do, Dont, Will, or Wont arguments for
748 different TELNET options in the same call to this method.
749 The following example describes the meaning of the named
751 parameters. A TELNET option, such as "TELOPT_ECHO" used below, is
752 an integer constant that you can import from Net::Telnet. See the
753 source in file Telnet.pm for the complete list.
754 · Do => "TELOPT_ECHO"
756 · we'll accept an offer to enable the echo option on the
758 local side
759 · Dont => "TELOPT_ECHO"
761 · we'll reject an offer to enable the echo option on the
763 local side
764 · Will => "TELOPT_ECHO"
766 · we'll accept an offer to enable the echo option on the
768 remote side
769 · Wont => "TELOPT_ECHO"
771 · we'll reject an offer to enable the echo option on the
773 remote side
774 Use "option_send()" to send a request to the remote side to enable
776 or disable a particular TELNET option.
777 option_callback - define the option negotiation callback
779 $coderef = $obj->option_callback;
780 $prev = $obj->option_callback($coderef);
782 This method defines the callback subroutine that's called when a
784 TELNET option is enabled or disabled. Once defined, the
785 option_callback may not be undefined. However, calling this method
786 with a different $coderef changes it.
787 A warning is printed to STDERR when attempting to set this
789 attribute to something that isn't a coderef.
790 Here are the circumstances that invoke $coderef:
792 · An option becomes enabled because the remote side requested an
794 enable and "option_accept()" had been used to arrange that it
795 be accepted.
796 · The remote side arbitrarily decides to disable an option that
798 is currently enabled. Note that Net::Telnet always accepts a
799 request to disable from the remote side.
800 · "option_send()" was used to send a request to enable or disable
802 an option and the response from the remote side has just been
803 received. Note, that if a request to enable is rejected then
804 $coderef is still invoked even though the option didn't change.
805 Here are the arguments passed to &$coderef:
807 &$coderef($obj, $option, $is_remote,
809 $is_enabled, $was_enabled, $buf_position);
810 · 1. $obj is the Net::Telnet object
812 · 2. $option is the TELNET option. Net::Telnet exports
814 constants for the various TELNET options which just equate to
815 an integer.
816 · 3. $is_remote is a boolean indicating for which side the
818 option applies.
819 · 4. $is_enabled is a boolean indicating the option is enabled
821 or disabled
822 · 5. $was_enabled is a boolean indicating the option was
824 previously enabled or disabled
825 · 6. $buf_position is an integer indicating the position in the
827 object's input buffer where the option takes effect. See
828 "buffer()" to access the object's input buffer.
829 option_log - log all TELNET options sent or received
831 $fh = $obj->option_log;
832 $fh = $obj->option_log($fh);
834 $fh = $obj->option_log($filename);
836 This method starts or stops logging of all TELNET options being
838 sent or received. This is useful for debugging when you send
839 options via "option_send()" or you arrange to accept option
840 requests from the remote side via "option_accept()". Also see
841 "dump_log()".
842 If no argument is given, the log filehandle is returned. An empty
844 string indicates logging is off.
845 To stop logging, use an empty string as an argument.
847 If an open filehandle is given, it is used for logging and
849 returned. Otherwise, the argument is assumed to be the name of a
850 file, the file is opened for logging and a filehandle to it is
851 returned. If the file can't be opened for writing, the error mode
852 action is performed.
853 option_send - send TELNET option negotiation request
855 $ok = $obj->option_send([Do => $telopt,]
856 [Dont => $telopt,]
857 [Will => $telopt,]
858 [Wont => $telopt,]
859 [Async => $boolean,]);
860 This method is not yet implemented. Look for it in a future
862 version.
863 option_state - get current state of a TELNET option
865 $hashref = $obj->option_state($telopt);
866 This method returns a hashref containing a copy of the current
868 state of TELNET option $telopt.
869 Here are the values returned in the hash:
871 · $hashref->{remote_enabled}
873 · boolean that indicates if the option is enabled on the
875 remote side.
876 · $hashref->{remote_enable_ok}
878 · boolean that indicates if it's ok to accept an offer to
880 enable this option on the remote side.
881 · $hashref->{remote_state}
883 · string used to hold the internal state of option
885 negotiation for this option on the remote side.
886 · $hashref->{local_enabled}
888 · boolean that indicates if the option is enabled on the
890 local side.
891 · $hashref->{local_enable_ok}
893 · boolean that indicates if it's ok to accept an offer to
895 enable this option on the local side.
896 · $hashref->{local_state}
898 · string used to hold the internal state of option
900 negotiation for this option on the local side.
901 ors - output line delimiter
903 $chars = $obj->ors;
904 $prev = $obj->ors($chars);
906 This method is synonymous with "output_record_separator()".
908 output_field_separator - field separator for print
910 $chars = $obj->output_field_separator;
911 $prev = $obj->output_field_separator($chars);
913 This method designates the output field separator for "print()".
915 Ordinarily the print method simply prints out the comma separated
916 fields you specify. Set this to specify what's printed between
917 fields.
918 With no argument this method returns the current output field
920 separator set in the object. With an argument it sets the output
921 field separator to $chars and returns the previous value.
922 By default it's set to an empty string.
924 output_log - log all output
926 $fh = $obj->output_log;
927 $fh = $obj->output_log($fh);
929 $fh = $obj->output_log($filename);
931 This method starts or stops logging of output. This is useful when
933 debugging. Also see "dump_log()". Because most command
934 interpreters echo back commands received, it's likely all your
935 output would also be in an input log. See "input_log()". Note
936 that output logging occurs before newline translation. See
937 "binmode()" for details on newline translation.
938 If no argument is given, the log filehandle is returned. An empty
940 string indicates logging is off.
941 To stop logging, use an empty string as an argument.
943 If an open filehandle is given, it is used for logging and
945 returned. Otherwise, the argument is assumed to be the name of a
946 file, the file is opened for logging and a filehandle to it is
947 returned. If the file can't be opened for writing, the error mode
948 action is performed.
949 output_record_separator - output line delimiter
951 $chars = $obj->output_record_separator;
952 $prev = $obj->output_record_separator($chars);
954 This method designates the output line delimiter for "print()" and
956 "cmd()". Set this to specify what's printed at the end of
957 "print()" and "cmd()".
958 The output record separator is set to "\n" by default, so there's
960 no need to append all your commands with a newline. To avoid
961 printing the output_record_separator use "put()" or set the
962 output_record_separator to an empty string.
963 With no argument this method returns the current output record
965 separator set in the object. With an argument it sets the output
966 record separator to $chars and returns the previous value.
967 port - remote port
969 $port = $obj->port;
970 $prev = $obj->port($port);
972 This method designates the remote TCP port. With no argument this
974 method returns the current port number. With an argument it sets
975 the current port number to $port and returns the previous port. If
976 $port is a TCP service name, then it's first converted to a port
977 number using the perl function "getservbyname()".
978 The default value is 23. It may also be set by "open()" or
980 "new()".
981 A warning is printed to STDERR when attempting to set this
983 attribute to something that's not a positive integer or a valid TCP
984 service name.
985 print - write to object
987 $ok = $obj->print(@list);
988 This method writes @list followed by the output_record_separator to
990 the open object and returns 1 if all data was successfully written.
991 On time-out or other failures, the error mode action is performed.
992 See "errmode()".
993 By default, the "output_record_separator()" is set to "\n" so all
995 your commands automatically end with a newline. In most cases your
996 output is being read by a command interpreter which won't accept a
997 command until newline is read. This is similar to someone typing a
998 command and hitting the return key. To avoid printing a trailing
999 "\n" use "put()" instead or set the output_record_separator to an
1000 empty string.
1001 On failure, it's possible that some data was written. If you
1003 choose to try and recover from a print timing-out, use
1004 "print_length()" to determine how much was written before the error
1005 occurred.
1006 You may also use the output field separator to print a string
1008 between the list elements. See "output_field_separator()".
1009 print_length - number of bytes written by print
1011 $num = $obj->print_length;
1012 This returns the number of bytes successfully written by the most
1014 recent "print()" or "put()".
1015 prompt - pattern to match a prompt
1017 $matchop = $obj->prompt;
1018 $prev = $obj->prompt($matchop);
1020 This method sets the pattern used to find a prompt in the input
1022 stream. It must be a string representing a valid perl pattern
1023 match operator. The methods "login()" and "cmd()" try to read
1024 until matching the prompt. They will fail with a time-out error if
1025 the pattern you've chosen doesn't match what the remote side sends.
1026 With no argument this method returns the prompt set in the object.
1028 With an argument it sets the prompt to $matchop and returns the
1029 previous value.
1030 The default prompt is '/[\$%#>] $/'
1032 Always use single quotes, instead of double quotes, to construct
1034 $matchop (e.g. '/bash\$ $/'). If you're constructing a DOS like
1035 file path, you'll need to use four backslashes to represent one
1036 (e.g. '/c:\\\\users\\\\bill>$/i').
1037 Of course don't forget about regexp metacharacters like ".", "[",
1039 or "$". You'll only need a single backslash to quote them. The
1040 anchor metacharacters "^" and "$" refer to positions in the input
1041 buffer.
1042 A warning is printed to STDERR when attempting to set this
1044 attribute with a match operator missing its opening delimiter.
1045 put - write to object
1047 $ok = $obj->put($string);
1048 $ok = $obj->put(String => $string,
1050 [Binmode => $mode,]
1051 [Errmode => $errmode,]
1052 [Telnetmode => $mode,]
1053 [Timeout => $secs,]);
1054 This method writes $string to the opened object and returns 1 if
1056 all data was successfully written. This method is like "print()"
1057 except that it doesn't write the trailing output_record_separator
1058 ("\n" by default). On time-out or other failures, the error mode
1059 action is performed. See "errmode()".
1060 On failure, it's possible that some data was written. If you
1062 choose to try and recover from a put timing-out, use
1063 "print_length()" to determine how much was written before the error
1064 occurred.
1065 Optional named parameters are provided to override the current
1067 settings of binmode, errmode, telnetmode, and timeout.
1068 rs - input line delimiter
1070 $chars = $obj->rs;
1071 $prev = $obj->rs($chars);
1073 This method is synonymous with "input_record_separator()".
1075 telnetmode - turn off/on telnet command interpretation
1077 $mode = $obj->telnetmode;
1078 $prev = $obj->telnetmode($mode);
1080 This method controls whether or not TELNET commands in the data
1082 stream are recognized and handled. The TELNET protocol uses
1083 certain character sequences sent in the data stream to control the
1084 session. If the port you're connecting to isn't using the TELNET
1085 protocol, then you should turn this mode off. The default is on.
1086 If no argument is given, the current mode is returned.
1088 If $mode is 0 then telnet mode is off. If $mode is 1 then telnet
1090 mode is on.
1091 timed_out - time-out indicator
1093 $boolean = $obj->timed_out;
1094 $prev = $obj->timed_out($boolean);
1096 This method indicates if a previous read, write, or open method
1098 timed-out. Remember that timing-out is itself an error. To be
1099 able to invoke "timed_out()" after a time-out error, you'd have to
1100 change the default error mode to something other than "die". See
1101 "errmode()".
1102 With no argument this method returns 1 if the previous method
1104 timed-out. With an argument it sets the indicator. Normally, only
1105 internal methods set this indicator.
1106 timeout - I/O time-out interval
1108 $secs = $obj->timeout;
1109 $prev = $obj->timeout($secs);
1111 This method sets the timeout interval that's used when performing
1113 I/O or connecting to a port. When a method doesn't complete within
1114 the timeout interval then it's an error and the error mode action
1115 is performed.
1116 A timeout may be expressed as a relative or absolute value. If
1118 $secs is greater than or equal to the time the program started, as
1119 determined by $^T, then it's an absolute time value for when time-
1120 out occurs. The perl function "time()" may be used to obtain an
1121 absolute time value. For a relative time-out value less than $^T,
1122 time-out happens $secs from when the method begins.
1123 If $secs is 0 then time-out occurs if the data cannot be
1125 immediately read or written. Use the undefined value to turn off
1126 timing-out completely.
1127 With no argument this method returns the timeout set in the object.
1129 With an argument it sets the timeout to $secs and returns the
1130 previous value. The default timeout value is 10 seconds.
1131 A warning is printed to STDERR when attempting to set this
1133 attribute to something that's not an "undef" or a non-negative
1134 integer.
1135 waitfor - wait for pattern in the input
1137 $ok = $obj->waitfor($matchop);
1138 $ok = $obj->waitfor([Match => $matchop,]
1139 [String => $string,]
1140 [Binmode => $mode,]
1141 [Errmode => $errmode,]
1142 [Telnetmode => $mode,]
1143 [Timeout => $secs,]);
1144 ($prematch, $match) = $obj->waitfor($matchop);
1146 ($prematch, $match) = $obj->waitfor([Match => $matchop,]
1147 [String => $string,]
1148 [Binmode => $mode,]
1149 [Errmode => $errmode,]
1150 [Telnetmode => $mode,]
1151 [Timeout => $secs,]);
1152 This method reads until a pattern match or string is found in the
1154 input stream. All the characters before and including the match
1155 are removed from the input stream.
1156 In a list context the characters before the match and the matched
1158 characters are returned in $prematch and $match. In a scalar
1159 context, the matched characters and all characters before it are
1160 discarded and 1 is returned on success. On time-out, eof, or other
1161 failures, for both list and scalar context, the error mode action
1162 is performed. See "errmode()".
1163 You can specify more than one pattern or string by simply providing
1165 multiple Match and/or String named parameters. A $matchop must be
1166 a string representing a valid Perl pattern match operator. The
1167 $string is just a substring to find in the input stream.
1168 Use "dump_log()" to debug when this method keeps timing-out and you
1170 don't think it should.
1171 An optional named parameter is provided to override the current
1173 setting of timeout.
1174 To avoid unexpected backslash interpretation, always use single
1176 quotes instead of double quotes to construct a match operator
1177 argument for "prompt()" and "waitfor()" (e.g. '/bash\$ $/'). If
1178 you're constructing a DOS like file path, you'll need to use four
1179 backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').
1180 Of course don't forget about regexp metacharacters like ".", "[",
1182 or "$". You'll only need a single backslash to quote them. The
1183 anchor metacharacters "^" and "$" refer to positions in the input
1184 buffer.
1185 Optional named parameters are provided to override the current
1187 settings of binmode, errmode, telnetmode, and timeout.
1188
1190 RFC 854
1191 TELNET Protocol Specification
1192 ftp://ftp.isi.edu/in-notes/rfc854.txt
1194 RFC 1143
1196 Q Method of Implementing TELNET Option Negotiation
1197 ftp://ftp.isi.edu/in-notes/rfc1143.txt
1199 TELNET Option Assignments
1201 http://www.iana.org/assignments/telnet-options
1202
1204 This example gets the current weather forecast for Brainerd, Minnesota.
1205 my ($forecast, $t);
1207 use Net::Telnet ();
1209 $t = new Net::Telnet;
1210 $t->open("rainmaker.wunderground.com");
1211 ## Wait for first prompt and "hit return".
1213 $t->waitfor('/continue:.*$/');
1214 $t->print("");
1215 ## Wait for second prompt and respond with city code.
1217 $t->waitfor('/city code.*$/');
1218 $t->print("BRD");
1219 ## Read and print the first page of forecast.
1221 ($forecast) = $t->waitfor('/[ \t]+press return to continue/i');
1222 print $forecast;
1223 exit;
1225 This example checks a POP server to see if you have mail.
1227 my ($hostname, $line, $passwd, $pop, $username);
1229 $hostname = "your_destination_host_here";
1231 $username = "your_username_here";
1232 $passwd = "your_password_here";
1233 use Net::Telnet ();
1235 $pop = new Net::Telnet (Telnetmode => 0);
1236 $pop->open(Host => $hostname,
1237 Port => 110);
1238 ## Read connection message.
1241 $line = $pop->getline;
1242 die $line unless $line =~ /^\+OK/;
1243 ## Send user name.
1245 $pop->print("user $username");
1246 $line = $pop->getline;
1247 die $line unless $line =~ /^\+OK/;
1248 ## Send password.
1250 $pop->print("pass $passwd");
1251 $line = $pop->getline;
1252 die $line unless $line =~ /^\+OK/;
1253 ## Request status of messages.
1255 $pop->print("list");
1256 $line = $pop->getline;
1257 print $line;
1258 exit;
1260 Here's an example that uses the ssh program to connect to a remote
1262 host. Because the ssh program reads and writes to its controlling
1263 terminal, the IO::Pty module is used to create a new pseudo terminal
1264 for use by ssh. A new Net::Telnet object is then created to read and
1265 write to that pseudo terminal. To use the code below, substitute
1266 "changeme" with the actual host, user, password, and command prompt.
1267 ## Main program.
1269 {
1270 my ($pty, $ssh, @lines);
1271 my $host = "changeme";
1272 my $user = "changeme";
1273 my $password = "changeme";
1274 my $prompt = '/changeme:~> $/';
1275 ## Start ssh program.
1277 $pty = &spawn("ssh", "-l", $user, $host); # spawn() defined below
1278 ## Create a Net::Telnet object to perform I/O on ssh's tty.
1280 use Net::Telnet;
1281 $ssh = new Net::Telnet (-fhopen => $pty,
1282 -prompt => $prompt,
1283 -telnetmode => 0,
1284 -cmd_remove_mode => 1,
1285 -output_record_separator => "\r");
1286 ## Login to remote host.
1288 $ssh->waitfor(-match => '/password: ?$/i',
1289 -errmode => "return")
1290 or die "problem connecting to host: ", $ssh->lastline;
1291 $ssh->print($password);
1292 $ssh->waitfor(-match => $ssh->prompt,
1293 -errmode => "return")
1294 or die "login failed: ", $ssh->lastline;
1295 ## Send command, get and print its output.
1297 @lines = $ssh->cmd("who");
1298 print @lines;
1299 exit;
1301 } # end main program
1302 sub spawn {
1304 my(@cmd) = @_;
1305 my($pid, $pty, $tty, $tty_fd);
1306 ## Create a new pseudo terminal.
1308 use IO::Pty ();
1309 $pty = new IO::Pty
1310 or die $!;
1311 ## Execute the program in another process.
1313 unless ($pid = fork) { # child process
1314 die "problem spawning program: $!\n" unless defined $pid;
1315 ## Disassociate process from existing controlling terminal.
1317 use POSIX ();
1318 POSIX::setsid
1319 or die "setsid failed: $!";
1320 ## Associate process with a new controlling terminal.
1322 $tty = $pty->slave;
1323 $tty_fd = $tty->fileno;
1324 close $pty;
1325 ## Make stdio use the new controlling terminal.
1327 open STDIN, "<&$tty_fd" or die $!;
1328 open STDOUT, ">&$tty_fd" or die $!;
1329 open STDERR, ">&STDOUT" or die $!;
1330 close $tty;
1331 ## Execute requested program.
1333 exec @cmd
1334 or die "problem executing $cmd[0]\n";
1335 } # end child process
1336 $pty;
1338 } # end sub spawn
1339 Here's an example that changes a user's login password. Because the
1341 passwd program always prompts for passwords on its controlling
1342 terminal, the IO::Pty module is used to create a new pseudo terminal
1343 for use by passwd. A new Net::Telnet object is then created to read
1344 and write to that pseudo terminal. To use the code below, substitute
1345 "changeme" with the actual old and new passwords.
1346 my ($pty, $passwd);
1348 my $oldpw = "changeme";
1349 my $newpw = "changeme";
1350 ## Start passwd program.
1352 $pty = &spawn("passwd"); # spawn() defined above
1353 ## Create a Net::Telnet object to perform I/O on passwd's tty.
1355 use Net::Telnet;
1356 $passwd = new Net::Telnet (-fhopen => $pty,
1357 -timeout => 2,
1358 -output_record_separator => "\r",
1359 -telnetmode => 0,
1360 -cmd_remove_mode => 1);
1361 $passwd->errmode("return");
1362 ## Send existing password.
1364 $passwd->waitfor('/password: ?$/i')
1365 or die "no old password prompt: ", $passwd->lastline;
1366 $passwd->print($oldpw);
1367 ## Send new password.
1369 $passwd->waitfor('/new password: ?$/i')
1370 or die "bad old password: ", $passwd->lastline;
1371 $passwd->print($newpw);
1372 ## Send new password verification.
1374 $passwd->waitfor('/new password: ?$/i')
1375 or die "bad new password: ", $passwd->lastline;
1376 $passwd->print($newpw);
1377 ## Display success or failure.
1379 $passwd->waitfor('/changed/')
1380 or die "bad new password: ", $passwd->lastline;
1381 print $passwd->lastline;
1382 $passwd->close;
1384 exit;
1385 Here's an example you can use to down load a file of any type. The
1387 file is read from the remote host's standard output using cat. To
1388 prevent any output processing, the remote host's standard output is put
1389 in raw mode using the Bourne shell. The Bourne shell is used because
1390 some shells, notably tcsh, prevent changing tty modes. Upon
1391 completion, FTP style statistics are printed to stderr.
1392 my ($block, $filename, $host, $hostname, $k_per_sec, $line,
1394 $num_read, $passwd, $prevblock, $prompt, $size, $size_bsd,
1395 $size_sysv, $start_time, $total_time, $username);
1396 $hostname = "your_destination_host_here";
1398 $username = "your_username_here";
1399 $passwd = "your_password_here";
1400 $filename = "your_download_file_here";
1401 ## Connect and login.
1403 use Net::Telnet ();
1404 $host = new Net::Telnet (Timeout => 30,
1405 Prompt => '/[%#>] $/');
1406 $host->open($hostname);
1407 $host->login($username, $passwd);
1408 ## Make sure prompt won't match anything in send data.
1410 $prompt = "_funkyPrompt_";
1411 $host->prompt("/$prompt\$/");
1412 $host->cmd("set prompt = '$prompt'");
1413 ## Get size of file.
1415 ($line) = $host->cmd("/bin/ls -l $filename");
1416 ($size_bsd, $size_sysv) = (split ' ', $line)[3,4];
1417 if ($size_sysv =~ /^\d+$/) {
1418 $size = $size_sysv;
1419 }
1420 elsif ($size_bsd =~ /^\d+$/) {
1421 $size = $size_bsd;
1422 }
1423 else {
1424 die "$filename: no such file on $hostname";
1425 }
1426 ## Start sending the file.
1428 binmode STDOUT;
1429 $host->binmode(1);
1430 $host->print("/bin/sh -c 'stty raw; cat $filename'");
1431 $host->getline; # discard echoed back line
1432 ## Read file a block at a time.
1434 $num_read = 0;
1435 $prevblock = "";
1436 $start_time = time;
1437 while (($block = $host->get) and ($block !~ /$prompt$/o)) {
1438 if (length $block >= length $prompt) {
1439 print $prevblock;
1440 $num_read += length $prevblock;
1441 $prevblock = $block;
1442 }
1443 else {
1444 $prevblock .= $block;
1445 }
1446 }
1448 $host->close;
1449 ## Print last block without trailing prompt.
1451 $prevblock .= $block;
1452 $prevblock =~ s/$prompt$//;
1453 print $prevblock;
1454 $num_read += length $prevblock;
1455 die "error: expected size $size, received size $num_read\n"
1456 unless $num_read == $size;
1457 ## Print totals.
1459 $total_time = (time - $start_time) || 1;
1460 $k_per_sec = ($size / 1024) / $total_time;
1461 $k_per_sec = sprintf "%3.1f", $k_per_sec;
1462 warn("$num_read bytes received in $total_time seconds ",
1463 "($k_per_sec Kbytes/s)\n");
1464 exit;
1466
1468 Jay Rogers <jay@rgrs.com>
1469
1471 Copyright 1997, 2000, 2002 by Jay Rogers. All rights reserved. This
1472 program is free software; you can redistribute it and/or modify it
1473 under the same terms as Perl itself.
1474perl v5.12.0 2002-07-17 Net::Telnet(3)