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 or EXAMPLES sections 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. IPv6 support is available
22 when using perl 5.14 or later (see "family()".
23 Other reasons to use this module than strictly with a TELNET port are:
25 • You're not familiar with sockets and you want a simple way to make
27 client connections to TCP services.
28 • You want to be able to specify your own time-out while connecting,
30 reading, or writing.
31 • You're communicating with an interactive program at the other end of
33 some socket or pipe and you want to wait for certain patterns to
34 appear.
35 Here's an example that prints who's logged-on to a remote host. In
37 addition to a username and password, you must also know the user's
38 shell prompt, which for this example is "bash$ "
39 use Net::Telnet ();
41 $t = new Net::Telnet (Timeout => 10,
42 Prompt => '/bash\$ $/');
43 $t->open($host);
44 $t->login($username, $passwd);
45 @lines = $t->cmd("who");
46 print @lines;
47 See the EXAMPLES section below for more examples.
49 Usage questions should be directed to the perlmonks.org discussion
51 group. Bugs can be viewed or reported at cpan.org on the Net::Telnet
52 page.
53 What To Know Before Using
55 • All output is flushed while all input is buffered. Each object
56 contains its own input buffer.
57 • The output record separator for "print()" and "cmd()" is set to "\n"
59 by default, so that you don't have to append all your commands with a
60 newline. To avoid printing a trailing "\n" use "put()" or set the
61 output_record_separator to "".
62 • The methods "login()" and "cmd()" use the prompt setting in the
64 object to determine when a login or remote command is complete.
65 Those methods will fail with a time-out if you don't set the prompt
66 correctly.
67 • Use a combination of "print()" and "waitfor()" as an alternative to
69 "login()" or "cmd()" when they don't do what you want.
70 • Errors such as timing-out are handled according to the error mode
72 action. The default action is to print an error message to standard
73 error and have the program die. See the "errmode()" method for more
74 information.
75 • When constructing the match operator argument for "prompt()" or
77 "waitfor()", always use single quotes instead of double quotes to
78 avoid unexpected backslash interpretation (e.g. '/bash\$ $/'). If
79 you're constructing a DOS like file path, you'll need to use four
80 backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').
81 Of course don't forget about regexp metacharacters like ".", "[", or
83 "$". You'll only need a single backslash to quote them. The anchor
84 metacharacters "^" and "$" refer to positions in the input buffer.
85 To avoid matching characters read that look like a prompt, it's a
86 good idea to end your prompt pattern with the "$" anchor. That way
87 the prompt will only match if it's the last thing read.
88 • In the input stream, each sequence of carriage return and line feed
90 (i.e. "\015\012" or CR LF) is converted to "\n". In the output
91 stream, each occurrence of "\n" is converted to a sequence of CR LF.
92 See "binmode()" to change the behavior. TCP protocols typically use
93 the ASCII sequence, carriage return and line feed to designate a
94 newline.
95 • Timing-out while making a connection is disabled for machines that
97 don't support the "alarm()" function. Most notably these include MS-
98 Windows machines.
99 • You'll need to be running at least Perl version 5.002 to use this
101 module. This module does not require any libraries that don't
102 already come with a standard Perl distribution.
103 If you have the IO:: libraries installed (they come standard with
105 perl5.004 and later) then IO::Socket::INET is used as a base class,
106 otherwise FileHandle is used.
107 Debugging
109 The typical usage bug causes a time-out error because you've made
110 incorrect assumptions about what the remote side actually sends. The
111 easiest way to reconcile what the remote side sends with your
112 expectations is to use "input_log()" or "dump_log()".
113 "dump_log()" allows you to see the data being sent from the remote side
115 before any translation is done, while "input_log()" shows you the
116 results after translation. The translation includes converting end of
117 line characters, removing and responding to TELNET protocol commands in
118 the data stream.
119 Style of Named Parameters
121 Two different styles of named parameters are supported. This document
122 only shows the IO:: style:
123 Net::Telnet->new(Timeout => 20);
125 however the dash-option style is also allowed:
127 Net::Telnet->new(-timeout => 20);
129 Connecting to a Remote MS-Windows Machine
131 By default MS-Windows doesn't come with a TELNET server. However third
132 party TELNET servers are available. Unfortunately many of these
133 servers falsely claim to be a TELNET server. This is especially true
134 of the so-called "Microsoft Telnet Server" that comes installed with
135 some newer versions MS-Windows.
136 When a TELNET server first accepts a connection, it must use the ASCII
138 control characters carriage-return and line-feed to start a new line
139 (see RFC854). A server like the "Microsoft Telnet Server" that doesn't
140 do this, isn't a TELNET server. These servers send ANSI terminal
141 escape sequences to position to a column on a subsequent line and to
142 even position while writing characters that are adjacent to each other.
143 Worse, when sending output these servers resend previously sent command
144 output in a misguided attempt to display an entire terminal screen.
145 Connecting Net::Telnet to one of these false TELNET servers makes your
147 job of parsing command output very difficult. It's better to replace a
148 false TELNET server with a real TELNET server. The better TELNET
149 servers for MS-Windows allow you to avoid the ANSI escapes by turning
150 off something some of them call console mode.
151
153 In the calling sequences below, square brackets [] represent optional
154 parameters.
155 new - create a new Net::Telnet object
157 $obj = new Net::Telnet ([$host]);
158 $obj = new Net::Telnet ([Binmode => $mode,]
160 [Cmd_remove_mode => $mode,]
161 [Dump_Log => $filename,]
162 [Errmode => $errmode,]
163 [Family => $family,]
164 [Fhopen => $filehandle,]
165 [Host => $host,]
166 [Input_log => $file,]
167 [Input_record_separator => $chars,]
168 [Localfamily => $family,]
169 [Localhost => $host,]
170 [Max_buffer_length => $len,]
171 [Ofs => $chars,]
172 [Option_log => $file,]
173 [Ors => $chars,]
174 [Output_field_separator => $chars,]
175 [Output_log => $file,]
176 [Output_record_separator => $chars,]
177 [Port => $port,]
178 [Prompt => $matchop,]
179 [Rs => $chars,]
180 [Telnetmode => $mode,]
181 [Timeout => $secs,]);
182 This is the constructor for Net::Telnet objects. A new object is
184 returned on success, the error mode action is performed on failure
185 - see "errmode()". The optional arguments are short-cuts to
186 methods of the same name.
187 If the $host argument is given then the object is opened by
189 connecting to TCP $port on $host. Also see "open()". The new
190 object returned is given the following defaults in the absence of
191 corresponding named parameters:
192 • The default Host is "localhost"
194 • The default Port is 23
196 • The default Family is "ipv4"
198 • The default Prompt is '/[\$%#>] $/'
200 • The default Timeout is 10
202 • The default Errmode is "die"
204 • The default Output_record_separator is "\n". Note that Ors is
206 synonymous with Output_record_separator.
207 • The default Input_record_separator is "\n". Note that Rs is
209 synonymous with Input_record_separator.
210 • The default Binmode is 0, which means do newline translation.
212 • The default Telnetmode is 1, which means respond to TELNET
214 commands in the data stream.
215 • The default Cmd_remove_mode is "auto"
217 • The defaults for Dump_log, Input_log, Option_log, and
219 Output_log are "", which means that logging is turned-off.
220 • The default Max_buffer_length is 1048576 bytes, i.e. 1 MiB.
222 • The default Output_field_separator is "". Note that Ofs is
224 synonymous with Output_field_separator.
225 • The default Localhost is ""
227 • The default Localfamily is "ipv4"
229 binmode - toggle newline translation
231 $mode = $obj->binmode;
232 $prev = $obj->binmode($mode);
234 This method controls whether or not sequences of carriage returns
236 and line feeds (CR LF or more specifically "\015\012") are
237 translated. By default they are translated (i.e. binmode is 0).
238 If no argument is given, the current mode is returned.
240 If $mode is 1 then binmode is on and newline translation is not
242 done.
243 If $mode is 0 then binmode is off and newline translation is done.
245 In the input stream, each sequence of CR LF is converted to "\n"
246 and in the output stream, each occurrence of "\n" is converted to a
247 sequence of CR LF.
248 Note that input is always buffered. Changing binmode doesn't
250 effect what's already been read into the buffer. Output is not
251 buffered and changing binmode will have an immediate effect.
252 break - send TELNET break character
254 $ok = $obj->break;
255 This method sends the TELNET break character. This character is
257 provided because it's a signal outside the ASCII character set
258 which is currently given local meaning within many systems. It's
259 intended to indicate that the Break Key or the Attention Key was
260 hit.
261 This method returns 1 on success, or performs the error mode action
263 on failure.
264 buffer - scalar reference to object's input buffer
266 $ref = $obj->buffer;
267 This method returns a scalar reference to the input buffer for
269 $obj. Data in the input buffer is data that has been read from the
270 remote side but has yet to be read by the user. Modifications to
271 the input buffer are returned by a subsequent read.
272 buffer_empty - discard all data in object's input buffer
274 $obj->buffer_empty;
275 This method removes all data in the input buffer for $obj.
277 close - close object
279 $ok = $obj->close;
280 This method closes the socket, file, or pipe associated with the
282 object. It always returns a value of 1.
283 cmd - issue command and retrieve output
285 $ok = $obj->cmd($string);
286 $ok = $obj->cmd(String => $string,
287 [Output => $ref,]
288 [Cmd_remove_mode => $mode,]
289 [Errmode => $mode,]
290 [Input_record_separator => $chars,]
291 [Ors => $chars,]
292 [Output_record_separator => $chars,]
293 [Prompt => $match,]
294 [Rs => $chars,]
295 [Timeout => $secs,]);
296 @output = $obj->cmd($string);
298 @output = $obj->cmd(String => $string,
299 [Output => $ref,]
300 [Cmd_remove_mode => $mode,]
301 [Errmode => $mode,]
302 [Input_record_separator => $chars,]
303 [Ors => $chars,]
304 [Output_record_separator => $chars,]
305 [Prompt => $match,]
306 [Rs => $chars,]
307 [Timeout => $secs,]);
308 This method sends the command $string, and reads the characters
310 sent back by the command up until and including the matching
311 prompt. It's assumed that the program to which you're sending is
312 some kind of command prompting interpreter such as a shell.
313 The command $string is automatically appended with the
315 output_record_separator, by default it is "\n". This is similar to
316 someone typing a command and hitting the return key. Set the
317 output_record_separator to change this behavior.
318 In a scalar context, the characters read from the remote side are
320 discarded and 1 is returned on success. On time-out, eof, or other
321 failures, the error mode action is performed. See "errmode()".
322 In a list context, just the output generated by the command is
324 returned, one line per element. In other words, all the characters
325 in between the echoed back command string and the prompt are
326 returned. If the command happens to return no output, a list
327 containing one element, the empty string is returned. This is so
328 the list will indicate true in a boolean context. On time-out,
329 eof, or other failures, the error mode action is performed. See
330 "errmode()".
331 The characters that matched the prompt may be retrieved using
333 "last_prompt()".
334 Many command interpreters echo back the command sent. In most
336 situations, this method removes the first line returned from the
337 remote side (i.e. the echoed back command). See
338 "cmd_remove_mode()" for more control over this feature.
339 Use "dump_log()" to debug when this method keeps timing-out and you
341 don't think it should.
342 Consider using a combination of "print()" and "waitfor()" as an
344 alternative to this method when it doesn't do what you want, e.g.
345 the command you send prompts for input.
346 The Output named parameter provides an alternative method of
348 receiving command output. If you pass a scalar reference, all the
349 output (even if it contains multiple lines) is returned in the
350 referenced scalar. If you pass an array or hash reference, the
351 lines of output are returned in the referenced array or hash. You
352 can use "input_record_separator()" to change the notion of what
353 separates a line.
354 Optional named parameters are provided to override the current
356 settings of cmd_remove_mode, errmode, input_record_separator, ors,
357 output_record_separator, prompt, rs, and timeout. Rs is synonymous
358 with input_record_separator and ors is synonymous with
359 output_record_separator.
360 cmd_remove_mode - toggle removal of echoed commands
362 $mode = $obj->cmd_remove_mode;
363 $prev = $obj->cmd_remove_mode($mode);
365 This method controls how to deal with echoed back commands in the
367 output returned by cmd(). Typically, when you send a command to
368 the remote side, the first line of output returned is the command
369 echoed back. Use this mode to remove the first line of output
370 normally returned by cmd().
371 If no argument is given, the current mode is returned.
373 If $mode is 0 then the command output returned from cmd() has no
375 lines removed. If $mode is a positive integer, then the first
376 $mode lines of command output are stripped.
377 By default, $mode is set to "auto". Auto means that whether or not
379 the first line of command output is stripped, depends on whether or
380 not the remote side offered to echo. By default, Net::Telnet
381 always accepts an offer to echo by the remote side. You can change
382 the default to reject such an offer using "option_accept()".
383 A warning is printed to STDERR when attempting to set this
385 attribute to something that is not "auto" or a non-negative
386 integer.
387 dump_log - log all I/O in dump format
389 $fh = $obj->dump_log;
390 $fh = $obj->dump_log($fh);
392 $fh = $obj->dump_log($filename);
394 This method starts or stops dump format logging of all the object's
396 input and output. The dump format shows the blocks read and
397 written in a hexadecimal and printable character format. This
398 method is useful when debugging, however you might want to first
399 try "input_log()" as it's more readable.
400 If no argument is given, the log filehandle is returned. A
402 returned empty string indicates logging is off.
403 To stop logging, use an empty string as an argument. The stopped
405 filehandle is not closed.
406 If an open filehandle is given, it is used for logging and
408 returned. Otherwise, the argument is assumed to be the name of a
409 file, the filename is opened for logging and a filehandle to it is
410 returned. If the filehandle is not already opened or the filename
411 can't be opened for writing, the error mode action is performed.
412 eof - end of file indicator
414 $eof = $obj->eof;
415 This method returns 1 if end of file has been read, otherwise it
417 returns an empty string. Because the input is buffered this isn't
418 the same thing as $obj has closed. In other words $obj can be
419 closed but there still can be stuff in the buffer to be read.
420 Under this condition you can still read but you won't be able to
421 write.
422 errmode - define action to be performed on error
424 $mode = $obj->errmode;
425 $prev = $obj->errmode($mode);
427 This method gets or sets the action used when errors are
429 encountered using the object. The first calling sequence returns
430 the current error mode. The second calling sequence sets it to
431 $mode and returns the previous mode. Valid values for $mode are
432 "die" (the default), "return", a coderef, or an arrayref.
433 When mode is "die" and an error is encountered using the object,
435 then an error message is printed to standard error and the program
436 dies.
437 When mode is "return" then the method generating the error places
439 an error message in the object and returns an undefined value in a
440 scalar context and an empty list in list context. The error
441 message may be obtained using "errmsg()".
442 When mode is a coderef, then when an error is encountered coderef
444 is called with the error message as its first argument. Using this
445 mode you may have your own subroutine handle errors. If coderef
446 itself returns then the method generating the error returns
447 undefined or an empty list depending on context.
448 When mode is an arrayref, the first element of the array must be a
450 coderef. Any elements that follow are the arguments to coderef.
451 When an error is encountered, the coderef is called with its
452 arguments. Using this mode you may have your own subroutine handle
453 errors. If the coderef itself returns then the method generating
454 the error returns undefined or an empty list depending on context.
455 A warning is printed to STDERR when attempting to set this
457 attribute to something that is not "die", "return", a coderef, or
458 an arrayref whose first element isn't a coderef.
459 errmsg - most recent error message
461 $msg = $obj->errmsg;
462 $prev = $obj->errmsg(@msgs);
464 The first calling sequence returns the error message associated
466 with the object. The empty string is returned if no error has been
467 encountered yet. The second calling sequence sets the error
468 message for the object to the concatenation of @msgs and returns
469 the previous error message. Normally, error messages are set
470 internally by a method when an error is encountered.
471 error - perform the error mode action
473 $obj->error(@msgs);
474 This method concatenates @msgs into a string and places it in the
476 object as the error message. Also see "errmsg()". It then
477 performs the error mode action. Also see "errmode()".
478 If the error mode doesn't cause the program to die, then an
480 undefined value or an empty list is returned depending on the
481 context.
482 This method is primarily used by this class or a sub-class to
484 perform the user requested action when an error is encountered.
485 family - IP address family for remote host
487 $family = $obj->family;
488 $prev = $obj->family($family);
490 This method designates which IP address family "host()" refers to,
492 i.e. IPv4 or IPv6. IPv6 support is available when using perl 5.14
493 or later. With no argument it returns the current value set in the
494 object. With an argument it sets the current address family to
495 $family and returns the previous address family. Valid values are
496 "ipv4", "ipv6", or "any". When "any", the "host()" can be a
497 hostname or IP address for either IPv4 or IPv6. After connecting,
498 you can use "sockfamily()" to determine which IP address family was
499 used.
500 The default value is "ipv4".
502 The error mode action is performed when attempting to set this
504 attribute to something that isn't "ipv4", "ipv6", or "any". It is
505 also performed when attempting to set it to "ipv6" when the Socket
506 module is less than version 1.94 or IPv6 is not supported in the OS
507 as indicated by Socket::AF_INET6 not being defined.
508 fhopen - use already open filehandle for I/O
510 $ok = $obj->fhopen($fh);
511 This method associates the open filehandle $fh with $obj for
513 further I/O. Filehandle $fh must already be opened.
514 Suppose you want to use the features of this module to do I/O to
516 something other than a TCP port, for example STDIN or a filehandle
517 opened to read from a process. Instead of opening the object for
518 I/O to a TCP port by using "open()" or "new()", call this method
519 instead.
520 The value 1 is returned success, the error mode action is performed
522 on failure.
523 get - read block of data
525 $data = $obj->get([Binmode => $mode,]
526 [Errmode => $errmode,]
527 [Telnetmode => $mode,]
528 [Timeout => $secs,]);
529 This method reads a block of data from the object and returns it
531 along with any buffered data. If no buffered data is available to
532 return, it will wait for data to read using the timeout specified
533 in the object. You can override that timeout using $secs. Also
534 see "timeout()". If buffered data is available to return, it also
535 checks for a block of data that can be immediately read.
536 On eof an undefined value is returned. On time-out or other
538 failures, the error mode action is performed. To distinguish
539 between eof or an error occurring when the error mode is not set to
540 "die", use "eof()".
541 Optional named parameters are provided to override the current
543 settings of binmode, errmode, telnetmode, and timeout.
544 getline - read next line
546 $line = $obj->getline([Binmode => $mode,]
547 [Errmode => $errmode,]
548 [Input_record_separator => $chars,]
549 [Rs => $chars,]
550 [Telnetmode => $mode,]
551 [Timeout => $secs,]);
552 This method reads and returns the next line of data from the
554 object. You can use "input_record_separator()" to change the
555 notion of what separates a line. The default is "\n". If a line
556 isn't immediately available, this method blocks waiting for a line
557 or a time-out.
558 On eof an undefined value is returned. On time-out or other
560 failures, the error mode action is performed. To distinguish
561 between eof or an error occurring when the error mode is not set to
562 "die", use "eof()".
563 Optional named parameters are provided to override the current
565 settings of binmode, errmode, input_record_separator, rs,
566 telnetmode, and timeout. Rs is synonymous with
567 input_record_separator.
568 getlines - read next lines
570 @lines = $obj->getlines([Binmode => $mode,]
571 [Errmode => $errmode,]
572 [Input_record_separator => $chars,]
573 [Rs => $chars,]
574 [Telnetmode => $mode,]
575 [Timeout => $secs,]
576 [All => $boolean,]);
577 This method reads and returns all the lines of data from the object
579 until end of file is read. You can use "input_record_separator()"
580 to change the notion of what separates a line. The default is
581 "\n". A time-out error occurs if all the lines can't be read
582 within the time-out interval. See "timeout()".
583 The behavior of this method was changed in version 3.03. Prior to
585 version 3.03 this method returned just the lines available from the
586 next read. To get that old behavior, use the optional named
587 parameter All and set $boolean to "" or 0.
588 If only eof is read then an empty list is returned. On time-out or
590 other failures, the error mode action is performed. Use "eof()" to
591 distinguish between reading only eof or an error occurring when the
592 error mode is not set to "die".
593 Optional named parameters are provided to override the current
595 settings of binmode, errmode, input_record_separator, rs,
596 telnetmode, and timeout. Rs is synonymous with
597 input_record_separator.
598 host - name or IP address of remote host
600 $host = $obj->host;
601 $prev = $obj->host($host);
603 This method designates the remote host for "open()". It is either
605 a hostname or an IP address. With no argument it returns the
606 current value set in the object. With an argument it sets the
607 current host name to $host and returns the previous value. Use
608 "family()" to control which IP address family, IPv4 or IPv6, host
609 refers to.
610 The default value is "localhost". It may also be set by "open()"
612 or "new()".
613 input_log - log all input
615 $fh = $obj->input_log;
616 $fh = $obj->input_log($fh);
618 $fh = $obj->input_log($filename);
620 This method starts or stops logging of input. This is useful when
622 debugging. Also see "dump_log()". Because most command
623 interpreters echo back commands received, it's likely all your
624 output will also be in this log. Note that input logging occurs
625 after newline translation. See "binmode()" for details on newline
626 translation.
627 If no argument is given, the log filehandle is returned. A
629 returned empty string indicates logging is off.
630 To stop logging, use an empty string as an argument. The stopped
632 filehandle is not closed.
633 If an open filehandle is given, it is used for logging and
635 returned. Otherwise, the argument is assumed to be the name of a
636 file, the filename is opened for logging and a filehandle to it is
637 returned. If the filehandle is not already opened or the filename
638 can't be opened for writing, the error mode action is performed.
639 input_record_separator - input line delimiter
641 $chars = $obj->input_record_separator;
642 $prev = $obj->input_record_separator($chars);
644 This method designates the line delimiter for input. It's used
646 with "getline()", "getlines()", and "cmd()" to determine lines in
647 the input.
648 With no argument this method returns the current input record
650 separator set in the object. With an argument it sets the input
651 record separator to $chars and returns the previous value. Note
652 that $chars must have length.
653 A warning is printed to STDERR when attempting to set this
655 attribute to a string with no length.
656 last_prompt - last prompt read
658 $string = $obj->last_prompt;
659 $prev = $obj->last_prompt($string);
661 With no argument this method returns the last prompt read by cmd()
663 or login(). See "prompt()". With an argument it sets the last
664 prompt read to $string and returns the previous value. Normally,
665 only internal methods set the last prompt.
666 lastline - last line read
668 $line = $obj->lastline;
669 $prev = $obj->lastline($line);
671 This method retrieves the last line read from the object. This may
673 be a useful error message when the remote side abnormally closes
674 the connection. Typically the remote side will print an error
675 message before closing.
676 With no argument this method returns the last line read from the
678 object. With an argument it sets the last line read to $line and
679 returns the previous value. Normally, only internal methods set
680 the last line.
681 localfamily - IP address family for local host
683 $localfamily = $obj->localfamily;
684 $prev = $obj->localfamily($family);
686 This method designates which IP address family "localhost()" refers
688 to, i.e. IPv4 or IPv6. IPv6 support is available when using perl
689 5.14 or later. With no argument it returns the current value set
690 in the object. With an argument it sets the current local address
691 family to $family and returns the previous address family. Valid
692 values are "ipv4", "ipv6", or "any". When "any", the "localhost()"
693 can be a hostname or IP address for either IPv4 or IPv6.
694 The default value is "ipv4".
696 The error mode action is performed when attempting to set this
698 attribute to something that isn't "ipv4", "ipv6", or "any". It is
699 also performed when attempting to set it to "ipv6" when the Socket
700 module is less than version 1.94 or IPv6 is not supported in the OS
701 as indicated by Socket::AF_INET6 not being defined.
702 localhost - bind local socket to a specific network interface
704 $localhost = $obj->localhost;
705 $prev = $obj->localhost($host);
707 This method designates the local socket IP address for "open()".
709 It is either a hostname, an IP address, or a null string (i.e. "").
710 A null string disables this feature.
711 Normally the OS picks which local network interface to use. This
713 method is useful when the local machine has more than one network
714 interface and you want to bind to a specific one. With no argument
715 it returns the current value set in the object. With an argument
716 it sets the current local host name to $host and returns the
717 previous value. Use "localfamily()" to control which IP address
718 family, IPv4 or IPv6, local host refers to.
719 The default value is "".
721 login - perform standard login
723 $ok = $obj->login($username, $password);
724 $ok = $obj->login(Name => $username,
726 Password => $password,
727 [Errmode => $mode,]
728 [Prompt => $match,]
729 [Timeout => $secs,]);
730 This method performs a standard login by waiting for a login prompt
732 and responding with $username, then waiting for the password prompt
733 and responding with $password, and then waiting for the command
734 interpreter prompt. If any of those prompts sent by the remote
735 side don't match what's expected, this method will time-out, unless
736 timeout is turned off.
737 Login prompt must match either of these case insensitive patterns:
739 /login[: ]*$/i
741 /username[: ]*$/i
742 Password prompt must match this case insensitive pattern:
744 /password[: ]*$/i
746 The command interpreter prompt must match the current setting of
748 prompt. See "prompt()".
749 Use "dump_log()" to debug when this method keeps timing-out and you
751 don't think it should.
752 Consider using a combination of "print()" and "waitfor()" as an
754 alternative to this method when it doesn't do what you want, e.g.
755 the remote host doesn't prompt for a username.
756 On success, 1 is returned. On time out, eof, or other failures,
758 the error mode action is performed. See "errmode()".
759 Optional named parameters are provided to override the current
761 settings of errmode, prompt, and timeout.
762 max_buffer_length - maximum size of input buffer
764 $len = $obj->max_buffer_length;
765 $prev = $obj->max_buffer_length($len);
767 This method designates the maximum size of the input buffer. An
769 error is generated when a read causes the buffer to exceed this
770 limit. The default value is 1,048,576 bytes (1 MiB). The input
771 buffer can grow much larger than the block size when you
772 continuously read using "getline()" or "waitfor()" and the data
773 stream contains no newlines or matching waitfor patterns.
774 With no argument, this method returns the current maximum buffer
776 length set in the object. With an argument it sets the maximum
777 buffer length to $len and returns the previous value. Values of
778 $len smaller than 512 will be adjusted to 512.
779 A warning is printed to STDERR when attempting to set this
781 attribute to something that isn't a positive integer.
782 ofs - field separator for print
784 $chars = $obj->ofs
785 $prev = $obj->ofs($chars);
787 This method is synonymous with "output_field_separator()".
789 open - connect to port on remote host
791 $ok = $obj->open($host);
792 $ok = $obj->open([Host => $host,]
794 [Port => $port,]
795 [Family => $family,]
796 [Errmode => $mode,]
797 [Timeout => $secs,]
798 [Localhost => $host,]
799 [Localfamily => $family,]);
800 This method opens a TCP connection to $port on $host for the IP
802 address $family. If any of those arguments are missing then the
803 current attribute value for the object is used. Specifing Host
804 sets that attribute for the object. Specifing any of the other
805 optional named parameters overrides the current setting.
806 The default IP address family is "ipv4". $family may be set to
808 "ipv4", "ipv6", or "any". See "family()" for more details.
809 Localhost is used to bind to a specific local network interface.
811 If the object is already open, it is closed before attempting a
813 connection.
814 On success 1 is returned. On time-out or other connection
816 failures, the error mode action is performed. See "errmode()".
817 Time-outs don't work for this method on machines that don't
819 implement SIGALRM - most notably MS-Windows machines. For those
820 machines, an error is returned when the system reaches its own
821 time-out while trying to connect.
822 A side effect of this method is to reset the alarm interval
824 associated with SIGALRM.
825 option_accept - indicate willingness to accept a TELNET option
827 $fh = $obj->option_accept([Do => $telopt,]
828 [Dont => $telopt,]
829 [Will => $telopt,]
830 [Wont => $telopt,]);
831 This method is used to indicate whether to accept or reject an
833 offer to enable a TELNET option made by the remote side. If you're
834 using Do or Will to indicate a willingness to enable, then a
835 notification callback must have already been defined by a prior
836 call to "option_callback()". See "option_callback()" for details
837 on receiving enable/disable notification of a TELNET option.
838 You can give multiple Do, Dont, Will, or Wont arguments for
840 different TELNET options in the same call to this method.
841 The following example describes the meaning of the named
843 parameters. A TELNET option, such as "TELOPT_ECHO" used below, is
844 an integer constant that you can import from Net::Telnet. See the
845 source in file Telnet.pm for the complete list.
846 • Do => "TELOPT_ECHO"
848 • we'll accept an offer to enable the echo option on the
850 local side
851 • Dont => "TELOPT_ECHO"
853 • we'll reject an offer to enable the echo option on the
855 local side
856 • Will => "TELOPT_ECHO"
858 • we'll accept an offer to enable the echo option on the
860 remote side
861 • Wont => "TELOPT_ECHO"
863 • we'll reject an offer to enable the echo option on the
865 remote side
866 Use "option_send()" to send a request to the remote side to enable
868 or disable a particular TELNET option.
869 option_callback - define the option negotiation callback
871 $coderef = $obj->option_callback;
872 $prev = $obj->option_callback($coderef);
874 This method defines the callback subroutine that is called when a
876 TELNET option is enabled or disabled. Once defined, the
877 option_callback may not be undefined. However, calling this method
878 with a different $coderef changes it.
879 A warning is printed to STDERR when attempting to set this
881 attribute to something that isn't a coderef.
882 Here are the circumstances that invoke $coderef:
884 • An option becomes enabled because the remote side requested an
886 enable and "option_accept()" had been used to arrange that it
887 be accepted.
888 • The remote side arbitrarily decides to disable an option that
890 is currently enabled. Note that Net::Telnet always accepts a
891 request to disable from the remote side.
892 • "option_send()" was used to send a request to enable or disable
894 an option and the response from the remote side has just been
895 received. Note, that if a request to enable is rejected then
896 $coderef is still invoked even though the option didn't change.
897 Here are the arguments passed to &$coderef:
899 &$coderef($obj, $option, $is_remote,
901 $is_enabled, $was_enabled, $buf_position);
902 • 1. $obj is the Net::Telnet object
904 • 2. $option is the TELNET option. Net::Telnet exports
906 constants for the various TELNET options which just equate to
907 an integer.
908 • 3. $is_remote is a boolean indicating for which side the
910 option applies.
911 • 4. $is_enabled is a boolean indicating the option is enabled
913 or disabled
914 • 5. $was_enabled is a boolean indicating the option was
916 previously enabled or disabled
917 • 6. $buf_position is an integer indicating the position in the
919 object's input buffer where the option takes effect. See
920 "buffer()" to access the object's input buffer.
921 option_log - log all TELNET options sent or received
923 $fh = $obj->option_log;
924 $fh = $obj->option_log($fh);
926 $fh = $obj->option_log($filename);
928 This method starts or stops logging of all TELNET options being
930 sent or received. This is useful for debugging when you send
931 options via "option_send()" or you arrange to accept option
932 requests from the remote side via "option_accept()". Also see
933 "dump_log()".
934 If no argument is given, the log filehandle is returned. An empty
936 string indicates logging is off.
937 To stop logging, use an empty string as an argument. The stopped
939 filehandle is not closed.
940 If an open filehandle is given, it is used for logging and
942 returned. Otherwise, the argument is assumed to be the name of a
943 file, the filename is opened for logging and a filehandle to it is
944 returned. If the filehandle is not already opened or the filename
945 can't be opened for writing, the error mode action is performed.
946 option_send - send TELNET option negotiation request
948 $ok = $obj->option_send([Do => $telopt,]
949 [Dont => $telopt,]
950 [Will => $telopt,]
951 [Wont => $telopt,]
952 [Async => $boolean,]);
953 This method is not yet implemented. Look for it in a future
955 version.
956 option_state - get current state of a TELNET option
958 $hashref = $obj->option_state($telopt);
959 This method returns a hashref containing a copy of the current
961 state of TELNET option $telopt.
962 Here are the values returned in the hash:
964 • $hashref->{remote_enabled}
966 • boolean that indicates if the option is enabled on the
968 remote side.
969 • $hashref->{remote_enable_ok}
971 • boolean that indicates if it's ok to accept an offer to
973 enable this option on the remote side.
974 • $hashref->{remote_state}
976 • string used to hold the internal state of option
978 negotiation for this option on the remote side.
979 • $hashref->{local_enabled}
981 • boolean that indicates if the option is enabled on the
983 local side.
984 • $hashref->{local_enable_ok}
986 • boolean that indicates if it's ok to accept an offer to
988 enable this option on the local side.
989 • $hashref->{local_state}
991 • string used to hold the internal state of option
993 negotiation for this option on the local side.
994 ors - output line delimiter
996 $chars = $obj->ors;
997 $prev = $obj->ors($chars);
999 This method is synonymous with "output_record_separator()".
1001 output_field_separator - field separator for print
1003 $chars = $obj->output_field_separator;
1004 $prev = $obj->output_field_separator($chars);
1006 This method designates the output field separator for "print()".
1008 Ordinarily the print method simply prints out the comma separated
1009 fields you specify. Set this to specify what's printed between
1010 fields.
1011 With no argument this method returns the current output field
1013 separator set in the object. With an argument it sets the output
1014 field separator to $chars and returns the previous value.
1015 By default it's set to an empty string.
1017 output_log - log all output
1019 $fh = $obj->output_log;
1020 $fh = $obj->output_log($fh);
1022 $fh = $obj->output_log($filename);
1024 This method starts or stops logging of output. This is useful when
1026 debugging. Also see "dump_log()". Because most command
1027 interpreters echo back commands received, it's likely all your
1028 output would also be in an input log. See "input_log()". Note
1029 that output logging occurs before newline translation. See
1030 "binmode()" for details on newline translation.
1031 If no argument is given, the log filehandle is returned. A
1033 returned empty string indicates logging is off.
1034 To stop logging, use an empty string as an argument. The stopped
1036 filehandle is not closed.
1037 If an open filehandle is given, it is used for logging and
1039 returned. Otherwise, the argument is assumed to be the name of a
1040 file, the filename is opened for logging and a filehandle to it is
1041 returned. If the filehandle is not already opened or the filename
1042 can't be opened for writing, the error mode action is performed.
1043 output_record_separator - output line delimiter
1045 $chars = $obj->output_record_separator;
1046 $prev = $obj->output_record_separator($chars);
1048 This method designates the output line delimiter for "print()" and
1050 "cmd()". Set this to specify what's printed at the end of
1051 "print()" and "cmd()".
1052 The output record separator is set to "\n" by default, so there's
1054 no need to append all your commands with a newline. To avoid
1055 printing the output_record_separator use "put()" or set the
1056 output_record_separator to an empty string.
1057 With no argument this method returns the current output record
1059 separator set in the object. With an argument it sets the output
1060 record separator to $chars and returns the previous value.
1061 peerhost - IP address of the other end of the socket connection
1063 $ipaddr = $obj->peerhost;
1064 This method returns a string which is the IPv4 or IPv6 address the
1066 remote socket is bound to (i.e. it is the IP address of "host()").
1067 It returns "" when not connected.
1068 peerport - TCP port of the other end of the socket connection
1070 $port = $obj->peerport;
1071 This method returns the port number which the remote socket is
1073 bound to. It is the same as the "port()" number when connected.
1074 It returns "" when not connected.
1075 port - remote port
1077 $port = $obj->port;
1078 $prev = $obj->port($port);
1080 This method designates the remote TCP port for "open()". With no
1082 argument this method returns the current port number. With an
1083 argument it sets the current port number to $port and returns the
1084 previous port. If $port is a TCP service name, then it's first
1085 converted to a port number using the perl function
1086 "getservbyname()".
1087 The default value is 23.
1089 The error mode action is performed when attempting to set this
1091 attribute to something that is not a positive integer or a valid
1092 TCP service name.
1093 print - write to object
1095 $ok = $obj->print(@list);
1096 This method writes @list followed by the output_record_separator to
1098 the open object and returns 1 if all data was successfully written.
1099 On time-out or other failures, the error mode action is performed.
1100 See "errmode()".
1101 By default, the "output_record_separator()" is set to "\n" so all
1103 your commands automatically end with a newline. In most cases your
1104 output is being read by a command interpreter which won't accept a
1105 command until newline is read. This is similar to someone typing a
1106 command and hitting the return key. To avoid printing a trailing
1107 "\n" use "put()" instead or set the output_record_separator to an
1108 empty string.
1109 On failure, it's possible that some data was written. If you
1111 choose to try and recover from a print timing-out, use
1112 "print_length()" to determine how much was written before the error
1113 occurred.
1114 You may also use the output field separator to print a string
1116 between the list elements. See "output_field_separator()".
1117 print_length - number of bytes written by print
1119 $num = $obj->print_length;
1120 This returns the number of bytes successfully written by the most
1122 recent "print()" or "put()".
1123 prompt - pattern to match a prompt
1125 $matchop = $obj->prompt;
1126 $prev = $obj->prompt($matchop);
1128 This method sets the pattern used to find a prompt in the input
1130 stream. It must be a string representing a valid perl pattern
1131 match operator. The methods "login()" and "cmd()" try to read
1132 until matching the prompt. They will fail with a time-out error if
1133 the pattern you've chosen doesn't match what the remote side sends.
1134 With no argument this method returns the prompt set in the object.
1136 With an argument it sets the prompt to $matchop and returns the
1137 previous value.
1138 The default prompt is '/[\$%#>] $/'
1140 Always use single quotes, instead of double quotes, to construct
1142 $matchop (e.g. '/bash\$ $/'). If you're constructing a DOS like
1143 file path, you'll need to use four backslashes to represent one
1144 (e.g. '/c:\\\\users\\\\bill>$/i').
1145 Of course don't forget about regexp metacharacters like ".", "[",
1147 or "$". You'll only need a single backslash to quote them. The
1148 anchor metacharacters "^" and "$" refer to positions in the input
1149 buffer.
1150 The error mode action is performed when attempting to set this
1152 attribute with a match operator missing its opening delimiter.
1153 put - write to object
1155 $ok = $obj->put($string);
1156 $ok = $obj->put(String => $string,
1158 [Binmode => $mode,]
1159 [Errmode => $errmode,]
1160 [Telnetmode => $mode,]
1161 [Timeout => $secs,]);
1162 This method writes $string to the opened object and returns 1 if
1164 all data was successfully written. This method is like "print()"
1165 except that it doesn't write the trailing output_record_separator
1166 ("\n" by default). On time-out or other failures, the error mode
1167 action is performed. See "errmode()".
1168 On failure, it's possible that some data was written. If you
1170 choose to try and recover from a put timing-out, use
1171 "print_length()" to determine how much was written before the error
1172 occurred.
1173 Optional named parameters are provided to override the current
1175 settings of binmode, errmode, telnetmode, and timeout.
1176 rs - input line delimiter
1178 $chars = $obj->rs;
1179 $prev = $obj->rs($chars);
1181 This method is synonymous with "input_record_separator()".
1183 sockfamily - IP address family of connected local socket
1185 $sockfamily = $obj->sockfamily;
1186 This method returns which IP address family "open()" used to
1188 successfully connect. It is most useful when the requested address
1189 "family()" for "open()" was "any". Values returned may be "ipv4",
1190 "ipv6", or "" (when not connected).
1191 sockhost - IP address of this end of the socket connection
1193 $ipaddr = $obj->sockhost;
1194 This method returns a string which is the IPv4 or IPv6 address the
1196 local socket is bound to. It returns "" when not connected.
1197 sockport - TCP port of this end of the socket connection
1199 $port = $obj->sockport;
1200 This method returns the port number which the local socket is bound
1202 to. It returns "" when not connected.
1203 telnetmode - turn off/on telnet command interpretation
1205 $mode = $obj->telnetmode;
1206 $prev = $obj->telnetmode($mode);
1208 This method controls whether or not TELNET commands in the data
1210 stream are recognized and handled. The TELNET protocol uses
1211 certain character sequences sent in the data stream to control the
1212 session. If the port you're connecting to isn't using the TELNET
1213 protocol, then you should turn this mode off. The default is on.
1214 If no argument is given, the current mode is returned.
1216 If $mode is 0 then telnet mode is off. If $mode is 1 then telnet
1218 mode is on.
1219 timed_out - time-out indicator
1221 $boolean = $obj->timed_out;
1222 $prev = $obj->timed_out($boolean);
1224 This method indicates if a previous read, write, or open method
1226 timed-out. Remember that timing-out is itself an error. To be
1227 able to invoke "timed_out()" after a time-out error, you'd have to
1228 change the default error mode to something other than "die". See
1229 "errmode()".
1230 With no argument this method returns 1 if the previous method
1232 timed-out. With an argument it sets the indicator. Normally, only
1233 internal methods set this indicator.
1234 timeout - I/O time-out interval
1236 $secs = $obj->timeout;
1237 $prev = $obj->timeout($secs);
1239 This method sets the timeout interval used when performing I/O or
1241 connecting to a port. When a method doesn't complete within the
1242 timeout interval then it's an error and the error mode action is
1243 performed.
1244 A timeout may be expressed as a relative or absolute value. If
1246 $secs is greater than or equal to the time the program started, as
1247 determined by $^T, then it's an absolute time value for when time-
1248 out occurs. The perl function "time()" may be used to obtain an
1249 absolute time value. For a relative time-out value less than $^T,
1250 time-out happens $secs from when the method begins.
1251 If $secs is 0 then time-out occurs if the data cannot be
1253 immediately read or written. Use the undefined value to turn off
1254 timing-out completely.
1255 With no argument this method returns the timeout set in the object.
1257 With an argument it sets the timeout to $secs and returns the
1258 previous value. The default timeout value is 10 seconds.
1259 A warning is printed to STDERR when attempting to set this
1261 attribute to something that is not an "undef" or a non-negative
1262 integer.
1263 waitfor - wait for pattern in the input
1265 $ok = $obj->waitfor($matchop);
1266 $ok = $obj->waitfor([Match => $matchop,]
1267 [String => $string,]
1268 [Binmode => $mode,]
1269 [Errmode => $errmode,]
1270 [Telnetmode => $mode,]
1271 [Timeout => $secs,]);
1272 ($prematch, $match) = $obj->waitfor($matchop);
1274 ($prematch, $match) = $obj->waitfor([Match => $matchop,]
1275 [String => $string,]
1276 [Binmode => $mode,]
1277 [Errmode => $errmode,]
1278 [Telnetmode => $mode,]
1279 [Timeout => $secs,]);
1280 This method reads until a pattern match or string is found in the
1282 input stream. All the characters before and including the match
1283 are removed from the input stream.
1284 In a list context the characters before the match and the matched
1286 characters are returned in $prematch and $match. In a scalar
1287 context, the matched characters and all characters before it are
1288 discarded and 1 is returned on success. On time-out, eof, or other
1289 failures, for both list and scalar context, the error mode action
1290 is performed. See "errmode()".
1291 You can specify more than one pattern or string by simply providing
1293 multiple Match and/or String named parameters. A $matchop must be
1294 a string representing a valid Perl pattern match operator. The
1295 $string is just a substring to find in the input stream.
1296 Use "dump_log()" to debug when this method keeps timing-out and you
1298 don't think it should.
1299 An optional named parameter is provided to override the current
1301 setting of timeout.
1302 To avoid unexpected backslash interpretation, always use single
1304 quotes instead of double quotes to construct a match operator
1305 argument for "prompt()" and "waitfor()" (e.g. '/bash\$ $/'). If
1306 you're constructing a DOS like file path, you'll need to use four
1307 backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').
1308 Of course don't forget about regexp metacharacters like ".", "[",
1310 or "$". You'll only need a single backslash to quote them. The
1311 anchor metacharacters "^" and "$" refer to positions in the input
1312 buffer.
1313 Optional named parameters are provided to override the current
1315 settings of binmode, errmode, telnetmode, and timeout.
1316
1318 RFC 854
1319 TELNET Protocol Specification
1320 http://tools.ietf.org/html/rfc854
1322 RFC 1143
1324 Q Method of Implementing TELNET Option Negotiation
1325 http://tools.ietf.org/html/rfc1143
1327 TELNET Option Assignments
1329 http://www.iana.org/assignments/telnet-options
1330
1332 Setting "prompt()" to match a user's shell prompt can be tricky. This
1333 example logs in without knowing the shell prompt and then sets it to
1334 match "prompt()". It requires /usr/bin/env and /bin/sh on the remote
1335 host.
1336 my $host = 'your_destination_host_here';
1338 my $user = 'your_username_here';
1339 my $passwd = 'your_password_here';
1340 my ($t, @output);
1341 ## Create a Net::Telnet object.
1343 use Net::Telnet ();
1344 $t = new Net::Telnet (Timeout => 10);
1345 ## Connect and login.
1347 $t->open($host);
1348 $t->waitfor('/login: ?$/i');
1350 $t->print($user);
1351 $t->waitfor('/password: ?$/i');
1353 $t->print($passwd);
1354 ## Switch to a known shell, using a known prompt.
1356 $t->prompt('/<xPROMPTx> $/');
1357 $t->errmode("return");
1358 $t->cmd("exec /usr/bin/env 'PS1=<xPROMPTx> ' /bin/sh -i")
1360 or die "login failed to remote host $host";
1361 $t->errmode("die");
1363 ## Now you can do cmd() to your heart's content.
1365 @output = $t->cmd("uname -a");
1366 print @output;
1367 exit;
1369 Usually you want the remote TERM environment variable to be set to
1371 something like "dumb" so you don't read escape sequences meant to be
1372 interpreted by a display terminal. It is best to set it via "cmd()",
1373 or via "waitfor()" and "print()". It is also possible to negotiate the
1374 terminal type via telnet. Here is how to do that.
1375 ## Module import.
1377 use Net::Telnet qw(TELNET_IAC TELNET_SB TELNET_SE TELOPT_TTYPE);
1378 ## Global variables.
1380 my $Term;
1381 ## Main program.
1383 {
1384 my $host = "your_destination_host_here";
1385 my $user = "your_username_here";
1386 my $passwd = "your_password_here";
1387 my $prompt = '/bash\$ $/'; # your regexp for shell prompt here
1388 my $t;
1389 $t = new Net::Telnet (Prompt => $prompt);
1391 ## Set up callbacks to negotiate terminal type.
1393 $t->option_callback(sub {});
1394 $t->suboption_callback(\&subopt_callback);
1395 $t->option_accept(Do => TELOPT_TTYPE);
1396 ## Login and print value of TERM.
1398 $Term = "dumb";
1399 $t->open($host);
1400 $t->login($user, $passwd);
1401 print $t->cmd('hostname');
1402 print "TERM=", $t->cmd('echo $TERM');
1403 $t->close;
1404 exit;
1406 } # end main program
1407 sub subopt_callback {
1409 my ($t, $option, $parameters) = @_;
1410 my $telcmd;
1411 if ($option == TELOPT_TTYPE) {
1413 $telcmd = pack("C4 A* C2", TELNET_IAC, TELNET_SB, TELOPT_TTYPE, 0,
1414 $Term, TELNET_IAC, TELNET_SE);
1415 $t->put(String => $telcmd,
1416 Telnetmode => 0);
1417 }
1418 1;
1420 } # end sub subopt_callback
1421 You can also use Net::Telnet to interact with local programs. This
1423 example changes a user's login password. It introduces the "spawn()"
1424 subroutine to start a program and associate a filehandle with its
1425 standard I/O. Because the passwd program always prompts for passwords
1426 on its controlling terminal, the IO::Pty module is used to create a new
1427 pseudo terminal for use by passwd. The Net::Telnet object reads and
1428 writes to that pseudo terminal. To use the code below, substitute
1429 "changeme" with the actual old and new passwords.
1430 ## Main program. {
1432 my ($pty, $passwd);
1433 my $oldpw = "changeme";
1434 my $newpw = "changeme";
1435 ## Start passwd program.
1437 $pty = spawn("passwd");
1438 ## Create a Net::Telnet object to perform I/O on passwd's tty.
1440 use Net::Telnet;
1441 $passwd = new Net::Telnet (-fhopen => $pty,
1442 -timeout => 2,
1443 -output_record_separator => "\r",
1444 -telnetmode => 0,
1445 -cmd_remove_mode => 1);
1446 $passwd->errmode("return");
1447 ## Send existing password.
1449 $passwd->waitfor('/password: ?$/i')
1450 or die "no old password prompt: ", $passwd->lastline;
1451 $passwd->print($oldpw);
1452 ## Send new password.
1454 $passwd->waitfor('/new (\w+\s)?password: ?$/i')
1455 or die "bad old password: ", $passwd->lastline;
1456 $passwd->print($newpw);
1457 ## Send new password verification.
1459 $passwd->waitfor('/new (\w+\s)?password: ?$/i')
1460 or die "bad new password: ", $passwd->lastline;
1461 $passwd->print($newpw);
1462 ## Display success or failure.
1464 $passwd->waitfor('/(changed|updated)/')
1465 or die "bad new password: ", $passwd->lastline;
1466 print $passwd->lastline;
1467 $passwd->close;
1469 exit;
1470 } # end main program
1471 sub spawn {
1473 my (@cmd) = @_;
1474 my ($pid, $pty, $tty, $tty_fd);
1475 ## Create a new pseudo terminal.
1477 use IO::Pty ();
1478 $pty = new IO::Pty
1479 or die $!;
1480 ## Execute the program in another process.
1482 unless ($pid = fork) { # child process
1483 die "problem spawning program: $!\n" unless defined $pid;
1484 ## Disassociate process from its controlling terminal.
1486 use POSIX ();
1487 POSIX::setsid()
1488 or die "setsid failed: $!";
1489 ## Associate process with a new controlling terminal.
1491 $pty->make_slave_controlling_terminal;
1492 $tty = $pty->slave;
1493 $tty_fd = $tty->fileno;
1494 close $pty;
1495 ## Make standard I/O use the new controlling terminal.
1497 open STDIN, "<&$tty_fd" or die $!;
1498 open STDOUT, ">&$tty_fd" or die $!;
1499 open STDERR, ">&STDOUT" or die $!;
1500 close $tty;
1501 ## Execute requested program.
1503 exec @cmd
1504 or die "problem executing $cmd[0]\n";
1505 } # end child process
1506 $pty;
1508 } # end sub spawn
1509 Here is an example that uses the openssh program to connect to a remote
1511 host. It uses the "spawn()" subroutine, from the password changing
1512 example above, to start the ssh program and then read and write to it
1513 via a Net::Telnet object. This example turns off ssh host key
1514 checking, which reduces your ability to know when someone on the
1515 network is impersonating the remote host. To use the code below,
1516 substitute "changeme" with the actual host, user, password, and command
1517 prompt.
1518 ## Main program.
1520 {
1521 my $host = "changeme";
1522 my $user = "changeme";
1523 my $passwd = "changeme";
1524 my $prompt = '/changeme\$ $/';
1525 my ($buf, $match, $pty, $ssh, @lines);
1526 ## Start ssh program.
1528 $pty = spawn("ssh",
1529 "-l", $user,
1530 "-e", "none",
1531 "-F", "/dev/null",
1532 "-o", "PreferredAuthentications=password",
1533 "-o", "NumberOfPasswordPrompts=1",
1534 "-o", "StrictHostKeyChecking=no",
1535 "-o", "UserKnownHostsFile=/dev/null",
1536 $host);
1537 ## Create a Net::Telnet object to perform I/O on ssh's tty.
1539 use Net::Telnet;
1540 $ssh = new Net::Telnet (-fhopen => $pty,
1541 -prompt => $prompt,
1542 -telnetmode => 0,
1543 -output_record_separator => "\r",
1544 -cmd_remove_mode => 1);
1545 ## Wait for the password prompt and send password.
1547 $ssh->waitfor(-match => '/password: ?$/i',
1548 -errmode => "return")
1549 or die "problem connecting to \"$host\": ", $ssh->lastline;
1550 $ssh->print($passwd);
1551 ## Wait for the shell prompt.
1553 (undef, $match) = $ssh->waitfor(-match => $ssh->prompt,
1554 -match => '/^Permission denied/m',
1555 -errmode => "return")
1556 or return $ssh->error("login failed: expected shell prompt ",
1557 "doesn't match actual\n");
1558 return $ssh->error("login failed: bad login-name or password\n")
1559 if $match =~ /^Permission denied/m;
1560 ## Run commands on remote host.
1562 print $ssh->cmd("hostname");
1563 print $ssh->cmd("uptime");
1564 $ssh->close;
1566 exit;
1567 } # end main program
1568 Some shells have a rather restrictive 255 character line limit. If you
1570 run into this problem, here is an example for sending lines longer than
1571 254 as a sequence of shorter lines.
1572 ## Main program.
1574 {
1575 my $host = "changeme";
1576 my $user = "changeme";
1577 my $passwd = "changeme";
1578 my $prompt = '/changeme\$ $/';
1579 my $cmd = join("", "echo ",
1580 "11111111112222222222333333333344444444445555555555",
1581 "66666666667777777777888888888899999999990000000000",
1582 "11111111112222222222333333333344444444445555555555",
1583 "66666666667777777777888888888899999999990000000000",
1584 "11111111112222222222333333333344444444445555555555",
1585 "66666666667777777777888888888899999999990000000000");
1586 use Net::Telnet ();
1588 my $t = new Net::Telnet (-prompt => $prompt);
1589 $t->open($host);
1590 $t->login($user, $passwd);
1591 my @output = cmd_unixlong($t, $cmd);
1593 print @output;
1594 exit;
1596 } # end main program
1597 sub cmd_unixlong {
1599 my ($obj, $cmd) = @_;
1600 my ($line, $pos);
1601 my $max_tty_line = 254;
1602 ## Start a Bourne shell.
1604 $obj->cmd(-string => "/usr/bin/env " .
1605 "'PS1=<xPROMPTx> ' 'PS2=<xPROMPTx> ' /bin/sh -i",
1606 -prompt => '/<xPROMPTx> $/')
1607 or return;
1608 ## Break-up the one large command line and send as shorter lines.
1610 $pos = 0;
1611 while (1) {
1612 $line = substr $cmd, $pos, $max_tty_line;
1613 $pos += length $line;
1614 last unless $pos < length $cmd;
1615 ## Send the line with continuation char.
1617 $obj->cmd(-string => "$line\\",
1618 -prompt => '/<xPROMPTx> $/')
1619 or return;
1620 }
1621 ## Send the last line and return the output.
1623 $obj->cmd("$line ; exit");
1624 } # end sub cmd_unixlong
1625
1627 Jay Rogers <jay@rgrs.com>
1628
1630 Dave Martin, Dave Cardosi
1631
1633 Copyright 1997, 2000, 2002, 2013 by Jay Rogers. All rights reserved.
1634 This program is free software; you can redistribute it and/or modify it
1635 under the same terms as Perl itself.
1636
1638 Hey! The above document had some coding errors, which are explained
1639 below:
1640 Around line 5169:
1642 Expected text after =item, not a bullet
1643 Around line 5217:
1645 Expected text after =item, not a bullet
1646perl v5.32.1 2021-01-27 Net::Telnet(3)