Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Telnet(3)	      User Contributed Perl Documentation	Net::Telnet(3)

NAME
       Net::Telnet - interact with TELNET port or other	TCP ports

SYNOPSIS
       "use Net::Telnet	();"

       see METHODS or EXAMPLES sections	below

DESCRIPTION
       Net::Telnet allows you to make client connections to a TCP port and do
       network I/O, especially to a port using the TELNET protocol.  Simple
       I/O methods such	as print, get, and getline are provided.  More
       sophisticated interactive features are provided because connecting to a
       TELNET port ultimately means communicating with a program designed for
       human interaction.  These interactive features include the ability to
       specify a time-out and to wait for patterns to appear in	the input
       stream, such as the prompt from a shell.	 IPv6 support is available
       when using perl 5.14 or later (see "family()".

       Other reasons to	use this module	than strictly with a TELNET port are:

       o You're	not familiar with sockets and you want a simple	way to make
	 client	connections to TCP services.

       o You want to be	able to	specify	your own time-out while	connecting,
	 reading, or writing.

       o You're	communicating with an interactive program at the other end of
	 some socket or	pipe and you want to wait for certain patterns to
	 appear.

       Here's an example that prints who's logged-on to	a remote host.	In
       addition	to a username and password, you	must also know the user's
       shell prompt, which for this example is "bash$ "

	   use Net::Telnet ();
	   $t =	new Net::Telnet	(Timeout => 10,
				 Prompt	=> '/bash\$ $/');
	   $t->open($host);
	   $t->login($username,	$passwd);
	   @lines = $t->cmd("who");
	   print @lines;

       See the EXAMPLES	section	below for more examples.

       Usage questions should be directed to the perlmonks.org discussion
       group.  Bugs can	be viewed or reported at cpan.org on the Net::Telnet
       page.

   What	To Know	Before Using
       o All output is flushed while all input is buffered.  Each object
	 contains its own input	buffer.

       o The output record separator for "print()" and "cmd()" is set to "\n"
	 by default, so	that you don't have to append all your commands	with a
	 newline.  To avoid printing a trailing	"\n" use "put()" or set	the
	 output_record_separator to "".

       o The methods "login()" and "cmd()" use the prompt setting in the
	 object	to determine when a login or remote command is complete.
	 Those methods will fail with a	time-out if you	don't set the prompt
	 correctly.

       o Use a combination of "print()"	and "waitfor()"	as an alternative to
	 "login()" or "cmd()" when they	don't do what you want.

       o Errors	such as	timing-out are handled according to the	error mode
	 action.  The default action is	to print an error message to standard
	 error and have	the program die.  See the "errmode()" method for more
	 information.

       o When constructing the match operator argument for "prompt()" or
	 "waitfor()", always use single	quotes instead of double quotes	to
	 avoid unexpected backslash interpretation (e.g. '/bash\$ $/').	 If
	 you're	constructing a DOS like	file path, you'll need to use four
	 backslashes to	represent one (e.g. '/c:\\\\users\\\\bill>$/i').

	 Of course don't forget	about regexp metacharacters like ".", "[", or
	 "$".  You'll only need	a single backslash to quote them.  The anchor
	 metacharacters	"^" and	"$" refer to positions in the input buffer.
	 To avoid matching characters read that	look like a prompt, it's a
	 good idea to end your prompt pattern with the "$" anchor.  That way
	 the prompt will only match if it's the	last thing read.

       o In the	input stream, each sequence of carriage	return and line	feed
	 (i.e. "\015\012" or CR	LF) is converted to "\n".  In the output
	 stream, each occurrence of "\n" is converted to a sequence of CR LF.
	 See "binmode()" to change the behavior.  TCP protocols	typically use
	 the ASCII sequence, carriage return and line feed to designate	a
	 newline.

       o Timing-out while making a connection is disabled for machines that
	 don't support the "alarm()" function.	Most notably these include MS-
	 Windows machines.

       o You'll	need to	be running at least Perl version 5.002 to use this
	 module.  This module does not require any libraries that don't
	 already come with a standard Perl distribution.

	 If you	have the IO:: libraries	installed (they	come standard with
	 perl5.004 and later) then IO::Socket::INET is used as a base class,
	 otherwise FileHandle is used.

   Debugging
       The typical usage bug causes a time-out error because you've made
       incorrect assumptions about what	the remote side	actually sends.	 The
       easiest way to reconcile	what the remote	side sends with	your
       expectations is to use "input_log()" or "dump_log()".

       "dump_log()" allows you to see the data being sent from the remote side
       before any translation is done, while "input_log()" shows you the
       results after translation.  The translation includes converting end of
       line characters,	removing and responding	to TELNET protocol commands in
       the data	stream.

   Style of Named Parameters
       Two different styles of named parameters	are supported.	This document
       only shows the IO:: style:

	   Net::Telnet->new(Timeout => 20);

       however the dash-option style is	also allowed:

	   Net::Telnet->new(-timeout =>	20);

   Connecting to a Remote MS-Windows Machine
       By default MS-Windows doesn't come with a TELNET	server.	 However third
       party TELNET servers are	available.  Unfortunately many of these
       servers falsely claim to	be a TELNET server.  This is especially	true
       of the so-called	"Microsoft Telnet Server" that comes installed with
       some newer versions MS-Windows.

       When a TELNET server first accepts a connection,	it must	use the	ASCII
       control characters carriage-return and line-feed	to start a new line
       (see RFC854).  A	server like the	"Microsoft Telnet Server" that doesn't
       do this,	isn't a	TELNET server.	These servers send ANSI	terminal
       escape sequences	to position to a column	on a subsequent	line and to
       even position while writing characters that are adjacent	to each	other.
       Worse, when sending output these	servers	resend previously sent command
       output in a misguided attempt to	display	an entire terminal screen.

       Connecting Net::Telnet to one of	these false TELNET servers makes your
       job of parsing command output very difficult.  It's better to replace a
       false TELNET server with	a real TELNET server.  The better TELNET
       servers for MS-Windows allow you	to avoid the ANSI escapes by turning
       off something some of them call console mode.

METHODS
       In the calling sequences	below, square brackets [] represent optional
       parameters.

       new - create a new Net::Telnet object
	       $obj = new Net::Telnet ([$host]);

	       $obj = new Net::Telnet ([Binmode	   => $mode,]
				       [Cmd_remove_mode	=> $mode,]
				       [Dump_Log   => $filename,]
				       [Errmode	   => $errmode,]
				       [Family	   => $family,]
				       [Fhopen	   => $filehandle,]
				       [Host	   => $host,]
				       [Input_log  => $file,]
				       [Input_record_separator => $chars,]
				       [Localfamily => $family,]
				       [Localhost   => $host,]
				       [Max_buffer_length => $len,]
				       [Ofs	   => $chars,]
				       [Option_log => $file,]
				       [Ors	   => $chars,]
				       [Output_field_separator => $chars,]
				       [Output_log => $file,]
				       [Output_record_separator	=> $chars,]
				       [Port	   => $port,]
				       [Prompt	   => $matchop,]
				       [Rs	   => $chars,]
				       [Telnetmode => $mode,]
				       [Timeout	   => $secs,]);

	   This	is the constructor for Net::Telnet objects.  A new object is
	   returned on success,	the error mode action is performed on failure
	   - see "errmode()".  The optional arguments are short-cuts to
	   methods of the same name.

	   If the $host	argument is given then the object is opened by
	   connecting to TCP $port on $host.  Also see "open()".  The new
	   object returned is given the	following defaults in the absence of
	   corresponding named parameters:

	   o   The default Host	is "localhost"

	   o   The default Port	is 23

	   o   The default Family is "ipv4"

	   o   The default Prompt is '/[\$%#>] $/'

	   o   The default Timeout is 10

	   o   The default Errmode is "die"

	   o   The default Output_record_separator is "\n".  Note that Ors is
	       synonymous with Output_record_separator.

	   o   The default Input_record_separator is "\n".  Note that Rs is
	       synonymous with Input_record_separator.

	   o   The default Binmode is 0, which means do	newline	translation.

	   o   The default Telnetmode is 1, which means	respond	to TELNET
	       commands	in the data stream.

	   o   The default Cmd_remove_mode is "auto"

	   o   The defaults for	Dump_log, Input_log, Option_log, and
	       Output_log are "", which	means that logging is turned-off.

	   o   The default Max_buffer_length is	1048576	bytes, i.e. 1 MiB.

	   o   The default Output_field_separator is "".  Note that Ofs	is
	       synonymous with Output_field_separator.

	   o   The default Localhost is	""

	   o   The default Localfamily is "ipv4"

       binmode - toggle	newline	translation
	       $mode = $obj->binmode;

	       $prev = $obj->binmode($mode);

	   This	method controls	whether	or not sequences of carriage returns
	   and line feeds (CR LF or more specifically "\015\012") are
	   translated.	By default they	are translated (i.e. binmode is	0).

	   If no argument is given, the	current	mode is	returned.

	   If $mode is 1 then binmode is on and	newline	translation is not
	   done.

	   If $mode is 0 then binmode is off and newline translation is	done.
	   In the input	stream,	each sequence of CR LF is converted to "\n"
	   and in the output stream, each occurrence of	"\n" is	converted to a
	   sequence of CR LF.

	   Note	that input is always buffered.	Changing binmode doesn't
	   effect what's already been read into	the buffer.  Output is not
	   buffered and	changing binmode will have an immediate	effect.

       break - send TELNET break character
	       $ok = $obj->break;

	   This	method sends the TELNET	break character.  This character is
	   provided because it's a signal outside the ASCII character set
	   which is currently given local meaning within many systems.	It's
	   intended to indicate	that the Break Key or the Attention Key	was
	   hit.

	   This	method returns 1 on success, or	performs the error mode	action
	   on failure.

       buffer -	scalar reference to object's input buffer
	       $ref = $obj->buffer;

	   This	method returns a scalar	reference to the input buffer for
	   $obj.  Data in the input buffer is data that	has been read from the
	   remote side but has yet to be read by the user.  Modifications to
	   the input buffer are	returned by a subsequent read.

       buffer_empty - discard all data in object's input buffer
	       $obj->buffer_empty;

	   This	method removes all data	in the input buffer for	$obj.

       close - close object
	       $ok = $obj->close;

	   This	method closes the socket, file,	or pipe	associated with	the
	   object.  It always returns a	value of 1.

       cmd - issue command and retrieve	output
	       $ok = $obj->cmd($string);
	       $ok = $obj->cmd(String	=> $string,
			       [Output	=> $ref,]
			       [Cmd_remove_mode	=> $mode,]
			       [Errmode	=> $mode,]
			       [Input_record_separator => $chars,]
			       [Ors	=> $chars,]
			       [Output_record_separator	=> $chars,]
			       [Prompt	=> $match,]
			       [Rs	=> $chars,]
			       [Timeout	=> $secs,]);

	       @output = $obj->cmd($string);
	       @output = $obj->cmd(String   => $string,
				   [Output  => $ref,]
				   [Cmd_remove_mode => $mode,]
				   [Errmode => $mode,]
				   [Input_record_separator => $chars,]
				   [Ors	    => $chars,]
				   [Output_record_separator => $chars,]
				   [Prompt  => $match,]
				   [Rs	    => $chars,]
				   [Timeout => $secs,]);

	   This	method sends the command $string, and reads the	characters
	   sent	back by	the command up until and including the matching
	   prompt.  It's assumed that the program to which you're sending is
	   some	kind of	command	prompting interpreter such as a	shell.

	   The command $string is automatically	appended with the
	   output_record_separator, by default it is "\n".  This is similar to
	   someone typing a command and	hitting	the return key.	 Set the
	   output_record_separator to change this behavior.

	   In a	scalar context,	the characters read from the remote side are
	   discarded and 1 is returned on success.  On time-out, eof, or other
	   failures, the error mode action is performed.  See "errmode()".

	   In a	list context, just the output generated	by the command is
	   returned, one line per element.  In other words, all	the characters
	   in between the echoed back command string and the prompt are
	   returned.  If the command happens to	return no output, a list
	   containing one element, the empty string is returned.  This is so
	   the list will indicate true in a boolean context.  On time-out,
	   eof,	or other failures, the error mode action is performed.	See
	   "errmode()".

	   The characters that matched the prompt may be retrieved using
	   "last_prompt()".

	   Many	command	interpreters echo back the command sent.  In most
	   situations, this method removes the first line returned from	the
	   remote side (i.e. the echoed	back command).	See
	   "cmd_remove_mode()" for more	control	over this feature.

	   Use "dump_log()" to debug when this method keeps timing-out and you
	   don't think it should.

	   Consider using a combination	of "print()" and "waitfor()" as	an
	   alternative to this method when it doesn't do what you want,	e.g.
	   the command you send	prompts	for input.

	   The Output named parameter provides an alternative method of
	   receiving command output.  If you pass a scalar reference, all the
	   output (even	if it contains multiple	lines) is returned in the
	   referenced scalar.  If you pass an array or hash reference, the
	   lines of output are returned	in the referenced array	or hash.  You
	   can use "input_record_separator()" to change	the notion of what
	   separates a line.

	   Optional named parameters are provided to override the current
	   settings of cmd_remove_mode,	errmode, input_record_separator, ors,
	   output_record_separator, prompt, rs,	and timeout.  Rs is synonymous
	   with	input_record_separator and ors is synonymous with
	   output_record_separator.

       cmd_remove_mode - toggle	removal	of echoed commands
	       $mode = $obj->cmd_remove_mode;

	       $prev = $obj->cmd_remove_mode($mode);

	   This	method controls	how to deal with echoed	back commands in the
	   output returned by cmd().  Typically, when you send a command to
	   the remote side, the	first line of output returned is the command
	   echoed back.	 Use this mode to remove the first line	of output
	   normally returned by	cmd().

	   If no argument is given, the	current	mode is	returned.

	   If $mode is 0 then the command output returned from cmd() has no
	   lines removed.  If $mode is a positive integer, then	the first
	   $mode lines of command output are stripped.

	   By default, $mode is	set to "auto".	Auto means that	whether	or not
	   the first line of command output is stripped, depends on whether or
	   not the remote side offered to echo.	 By default, Net::Telnet
	   always accepts an offer to echo by the remote side.	You can	change
	   the default to reject such an offer using "option_accept()".

	   A warning is	printed	to STDERR when attempting to set this
	   attribute to	something that is not "auto" or	a non-negative
	   integer.

       dump_log	- log all I/O in dump format
	       $fh = $obj->dump_log;

	       $fh = $obj->dump_log($fh);

	       $fh = $obj->dump_log($filename);

	   This	method starts or stops dump format logging of all the object's
	   input and output.  The dump format shows the	blocks read and
	   written in a	hexadecimal and	printable character format.  This
	   method is useful when debugging, however you	might want to first
	   try "input_log()" as	it's more readable.

	   If no argument is given, the	log filehandle is returned.  A
	   returned empty string indicates logging is off.

	   To stop logging, use	an empty string	as an argument.	 The stopped
	   filehandle is not closed.

	   If an open filehandle is given, it is used for logging and
	   returned.  Otherwise, the argument is assumed to be the name	of a
	   file, the filename is opened	for logging and	a filehandle to	it is
	   returned.  If the filehandle	is not already opened or the filename
	   can't be opened for writing,	the error mode action is performed.

       eof - end of file indicator
	       $eof = $obj->eof;

	   This	method returns 1 if end	of file	has been read, otherwise it
	   returns an empty string.  Because the input is buffered this	isn't
	   the same thing as $obj has closed.  In other	words $obj can be
	   closed but there still can be stuff in the buffer to	be read.
	   Under this condition	you can	still read but you won't be able to
	   write.

       errmode - define	action to be performed on error
	       $mode = $obj->errmode;

	       $prev = $obj->errmode($mode);

	   This	method gets or sets the	action used when errors	are
	   encountered using the object.  The first calling sequence returns
	   the current error mode.  The	second calling sequence	sets it	to
	   $mode and returns the previous mode.	 Valid values for $mode	are
	   "die" (the default),	"return", a coderef, or	an arrayref.

	   When	mode is	"die" and an error is encountered using	the object,
	   then	an error message is printed to standard	error and the program
	   dies.

	   When	mode is	"return" then the method generating the	error places
	   an error message in the object and returns an undefined value in a
	   scalar context and an empty list in list context.  The error
	   message may be obtained using "errmsg()".

	   When	mode is	a coderef, then	when an	error is encountered coderef
	   is called with the error message as its first argument.  Using this
	   mode	you may	have your own subroutine handle	errors.	 If coderef
	   itself returns then the method generating the error returns
	   undefined or	an empty list depending	on context.

	   When	mode is	an arrayref, the first element of the array must be a
	   coderef.  Any elements that follow are the arguments	to coderef.
	   When	an error is encountered, the coderef is	called with its
	   arguments.  Using this mode you may have your own subroutine	handle
	   errors.  If the coderef itself returns then the method generating
	   the error returns undefined or an empty list	depending on context.

	   A warning is	printed	to STDERR when attempting to set this
	   attribute to	something that is not "die", "return", a coderef, or
	   an arrayref whose first element isn't a coderef.

       errmsg -	most recent error message
	       $msg = $obj->errmsg;

	       $prev = $obj->errmsg(@msgs);

	   The first calling sequence returns the error	message	associated
	   with	the object.  The empty string is returned if no	error has been
	   encountered yet.  The second	calling	sequence sets the error
	   message for the object to the concatenation of @msgs	and returns
	   the previous	error message.	Normally, error	messages are set
	   internally by a method when an error	is encountered.

       error - perform the error mode action
	       $obj->error(@msgs);

	   This	method concatenates @msgs into a string	and places it in the
	   object as the error message.	 Also see "errmsg()".  It then
	   performs the	error mode action.  Also see "errmode()".

	   If the error	mode doesn't cause the program to die, then an
	   undefined value or an empty list is returned	depending on the
	   context.

	   This	method is primarily used by this class or a sub-class to
	   perform the user requested action when an error is encountered.

       family -	IP address family for remote host
	       $family = $obj->family;

	       $prev   = $obj->family($family);

	   This	method designates which	IP address family "host()" refers to,
	   i.e.	IPv4 or	IPv6.  IPv6 support is available when using perl 5.14
	   or later.  With no argument it returns the current value set	in the
	   object.  With an argument it	sets the current address family	to
	   $family and returns the previous address family.  Valid values are
	   "ipv4", "ipv6", or "any".  When "any", the "host()" can be a
	   hostname or IP address for either IPv4 or IPv6.  After connecting,
	   you can use "sockfamily()" to determine which IP address family was
	   used.

	   The default value is	"ipv4".

	   The error mode action is performed when attempting to set this
	   attribute to	something that isn't "ipv4", "ipv6", or	"any".	It is
	   also	performed when attempting to set it to "ipv6" when the Socket
	   module is less than version 1.94 or IPv6 is not supported in	the OS
	   as indicated	by Socket::AF_INET6 not	being defined.

       fhopen -	use already open filehandle for	I/O
	       $ok = $obj->fhopen($fh);

	   This	method associates the open filehandle $fh with $obj for
	   further I/O.	 Filehandle $fh	must already be	opened.

	   Suppose you want to use the features	of this	module to do I/O to
	   something other than	a TCP port, for	example	STDIN or a filehandle
	   opened to read from a process.  Instead of opening the object for
	   I/O to a TCP	port by	using "open()" or "new()", call	this method
	   instead.

	   The value 1 is returned success, the	error mode action is performed
	   on failure.

       get - read block	of data
	       $data = $obj->get([Binmode    =>	$mode,]
				 [Errmode    =>	$errmode,]
				 [Telnetmode =>	$mode,]
				 [Timeout    =>	$secs,]);

	   This	method reads a block of	data from the object and returns it
	   along with any buffered data.  If no	buffered data is available to
	   return, it will wait	for data to read using the timeout specified
	   in the object.  You can override that timeout using $secs.  Also
	   see "timeout()".  If	buffered data is available to return, it also
	   checks for a	block of data that can be immediately read.

	   On eof an undefined value is	returned.  On time-out or other
	   failures, the error mode action is performed.  To distinguish
	   between eof or an error occurring when the error mode is not	set to
	   "die", use "eof()".

	   Optional named parameters are provided to override the current
	   settings of binmode,	errmode, telnetmode, and timeout.

       getline - read next line
	       $line = $obj->getline([Binmode	 => $mode,]
				     [Errmode	 => $errmode,]
				     [Input_record_separator =>	$chars,]
				     [Rs	 => $chars,]
				     [Telnetmode => $mode,]
				     [Timeout	 => $secs,]);

	   This	method reads and returns the next line of data from the
	   object.  You	can use	"input_record_separator()" to change the
	   notion of what separates a line.  The default is "\n".  If a	line
	   isn't immediately available,	this method blocks waiting for a line
	   or a	time-out.

	   On eof an undefined value is	returned.  On time-out or other
	   failures, the error mode action is performed.  To distinguish
	   between eof or an error occurring when the error mode is not	set to
	   "die", use "eof()".

	   Optional named parameters are provided to override the current
	   settings of binmode,	errmode, input_record_separator, rs,
	   telnetmode, and timeout.  Rs	is synonymous with
	   input_record_separator.

       getlines	- read next lines
	       @lines =	$obj->getlines([Binmode	   => $mode,]
				       [Errmode	   => $errmode,]
				       [Input_record_separator => $chars,]
				       [Rs	   => $chars,]
				       [Telnetmode => $mode,]
				       [Timeout	   => $secs,]
				       [All	   => $boolean,]);

	   This	method reads and returns all the lines of data from the	object
	   until end of	file is	read.  You can use "input_record_separator()"
	   to change the notion	of what	separates a line.  The default is
	   "\n".  A time-out error occurs if all the lines can't be read
	   within the time-out interval.  See "timeout()".

	   The behavior	of this	method was changed in version 3.03.  Prior to
	   version 3.03	this method returned just the lines available from the
	   next	read.  To get that old behavior, use the optional named
	   parameter All and set $boolean to ""	or 0.

	   If only eof is read then an empty list is returned.	On time-out or
	   other failures, the error mode action is performed.	Use "eof()" to
	   distinguish between reading only eof	or an error occurring when the
	   error mode is not set to "die".

	   Optional named parameters are provided to override the current
	   settings of binmode,	errmode, input_record_separator, rs,
	   telnetmode, and timeout.  Rs	is synonymous with
	   input_record_separator.

       host - name or IP address of remote host
	       $host = $obj->host;

	       $prev = $obj->host($host);

	   This	method designates the remote host for "open()".	 It is either
	   a hostname or an IP address.	 With no argument it returns the
	   current value set in	the object.  With an argument it sets the
	   current host	name to	$host and returns the previous value.  Use
	   "family()" to control which IP address family, IPv4 or IPv6,	host
	   refers to.

	   The default value is	"localhost".  It may also be set by "open()"
	   or "new()".

       input_log - log all input
	       $fh = $obj->input_log;

	       $fh = $obj->input_log($fh);

	       $fh = $obj->input_log($filename);

	   This	method starts or stops logging of input.  This is useful when
	   debugging.  Also see	"dump_log()".  Because most command
	   interpreters	echo back commands received, it's likely all your
	   output will also be in this log.  Note that input logging occurs
	   after newline translation.  See "binmode()" for details on newline
	   translation.

	   If no argument is given, the	log filehandle is returned.  A
	   returned empty string indicates logging is off.

	   To stop logging, use	an empty string	as an argument.	 The stopped
	   filehandle is not closed.

	   If an open filehandle is given, it is used for logging and
	   returned.  Otherwise, the argument is assumed to be the name	of a
	   file, the filename is opened	for logging and	a filehandle to	it is
	   returned.  If the filehandle	is not already opened or the filename
	   can't be opened for writing,	the error mode action is performed.

       input_record_separator -	input line delimiter
	       $chars =	$obj->input_record_separator;

	       $prev = $obj->input_record_separator($chars);

	   This	method designates the line delimiter for input.	 It's used
	   with	"getline()", "getlines()", and "cmd()" to determine lines in
	   the input.

	   With	no argument this method	returns	the current input record
	   separator set in the	object.	 With an argument it sets the input
	   record separator to $chars and returns the previous value.  Note
	   that	$chars must have length.

	   A warning is	printed	to STDERR when attempting to set this
	   attribute to	a string with no length.

       last_prompt - last prompt read
	       $string = $obj->last_prompt;

	       $prev = $obj->last_prompt($string);

	   With	no argument this method	returns	the last prompt	read by	cmd()
	   or login().	See "prompt()".	 With an argument it sets the last
	   prompt read to $string and returns the previous value.  Normally,
	   only	internal methods set the last prompt.

       lastline	- last line read
	       $line = $obj->lastline;

	       $prev = $obj->lastline($line);

	   This	method retrieves the last line read from the object.  This may
	   be a	useful error message when the remote side abnormally closes
	   the connection.  Typically the remote side will print an error
	   message before closing.

	   With	no argument this method	returns	the last line read from	the
	   object.  With an argument it	sets the last line read	to $line and
	   returns the previous	value.	Normally, only internal	methods	set
	   the last line.

       localfamily - IP	address	family for local host
	       $localfamily = $obj->localfamily;

	       $prev   = $obj->localfamily($family);

	   This	method designates which	IP address family "localhost()"	refers
	   to, i.e. IPv4 or IPv6.  IPv6	support	is available when using	perl
	   5.14	or later.  With	no argument it returns the current value set
	   in the object.  With	an argument it sets the	current	local address
	   family to $family and returns the previous address family.  Valid
	   values are "ipv4", "ipv6", or "any".	 When "any", the "localhost()"
	   can be a hostname or	IP address for either IPv4 or IPv6.

	   The default value is	"ipv4".

	   The error mode action is performed when attempting to set this
	   attribute to	something that isn't "ipv4", "ipv6", or	"any".	It is
	   also	performed when attempting to set it to "ipv6" when the Socket
	   module is less than version 1.94 or IPv6 is not supported in	the OS
	   as indicated	by Socket::AF_INET6 not	being defined.

       localhost - bind	local socket to	a specific network interface
	       $localhost = $obj->localhost;

	       $prev = $obj->localhost($host);

	   This	method designates the local socket IP address for "open()".
	   It is either	a hostname, an IP address, or a	null string (i.e. "").
	   A null string disables this feature.

	   Normally the	OS picks which local network interface to use.	This
	   method is useful when the local machine has more than one network
	   interface and you want to bind to a specific	one.  With no argument
	   it returns the current value	set in the object.  With an argument
	   it sets the current local host name to $host	and returns the
	   previous value.  Use	"localfamily()"	to control which IP address
	   family, IPv4	or IPv6, local host refers to.

	   The default value is	"".

       login - perform standard	login
	       $ok = $obj->login($username, $password);

	       $ok = $obj->login(Name	  => $username,
				 Password => $password,
				 [Errmode => $mode,]
				 [Prompt  => $match,]
				 [Timeout => $secs,]);

	   This	method performs	a standard login by waiting for	a login	prompt
	   and responding with $username, then waiting for the password	prompt
	   and responding with $password, and then waiting for the command
	   interpreter prompt.	If any of those	prompts	sent by	the remote
	   side	don't match what's expected, this method will time-out,	unless
	   timeout is turned off.

	   Login prompt	must match either of these case	insensitive patterns:

	       /login[:	]*$/i
	       /username[: ]*$/i

	   Password prompt must	match this case	insensitive pattern:

	       /password[: ]*$/i

	   The command interpreter prompt must match the current setting of
	   prompt.  See	"prompt()".

	   Use "dump_log()" to debug when this method keeps timing-out and you
	   don't think it should.

	   Consider using a combination	of "print()" and "waitfor()" as	an
	   alternative to this method when it doesn't do what you want,	e.g.
	   the remote host doesn't prompt for a	username.

	   On success, 1 is returned.  On time out, eof, or other failures,
	   the error mode action is performed.	See "errmode()".

	   Optional named parameters are provided to override the current
	   settings of errmode,	prompt,	and timeout.

       max_buffer_length - maximum size	of input buffer
	       $len = $obj->max_buffer_length;

	       $prev = $obj->max_buffer_length($len);

	   This	method designates the maximum size of the input	buffer.	 An
	   error is generated when a read causes the buffer to exceed this
	   limit.  The default value is	1,048,576 bytes	(1 MiB).  The input
	   buffer can grow much	larger than the	block size when	you
	   continuously	read using "getline()" or "waitfor()" and the data
	   stream contains no newlines or matching waitfor patterns.

	   With	no argument, this method returns the current maximum buffer
	   length set in the object.  With an argument it sets the maximum
	   buffer length to $len and returns the previous value.  Values of
	   $len	smaller	than 512 will be adjusted to 512.

	   A warning is	printed	to STDERR when attempting to set this
	   attribute to	something that isn't a positive	integer.

       ofs - field separator for print
	       $chars =	$obj->ofs

	       $prev = $obj->ofs($chars);

	   This	method is synonymous with "output_field_separator()".

       open - connect to port on remote	host
	       $ok = $obj->open($host);

	       $ok = $obj->open([Host	     =>	$host,]
				[Port	     =>	$port,]
				[Family	     =>	$family,]
				[Errmode     =>	$mode,]
				[Timeout     =>	$secs,]
				[Localhost   =>	$host,]
				[Localfamily =>	$family,]);

	   This	method opens a TCP connection to $port on $host	for the	IP
	   address $family.  If	any of those arguments are missing then	the
	   current attribute value for the object is used.  Specifing Host
	   sets	that attribute for the object.	Specifing any of the other
	   optional named parameters overrides the current setting.

	   The default IP address family is "ipv4".  $family may be set	to
	   "ipv4", "ipv6", or "any".  See "family()" for more details.

	   Localhost is	used to	bind to	a specific local network interface.

	   If the object is already open, it is	closed before attempting a
	   connection.

	   On success 1	is returned.  On time-out or other connection
	   failures, the error mode action is performed.  See "errmode()".

	   Time-outs don't work	for this method	on machines that don't
	   implement SIGALRM - most notably MS-Windows machines.  For those
	   machines, an	error is returned when the system reaches its own
	   time-out while trying to connect.

	   A side effect of this method	is to reset the	alarm interval
	   associated with SIGALRM.

       option_accept - indicate	willingness to accept a	TELNET option
	       $fh = $obj->option_accept([Do   => $telopt,]
					 [Dont => $telopt,]
					 [Will => $telopt,]
					 [Wont => $telopt,]);

	   This	method is used to indicate whether to accept or	reject an
	   offer to enable a TELNET option made	by the remote side.  If	you're
	   using Do or Will to indicate	a willingness to enable, then a
	   notification	callback must have already been	defined	by a prior
	   call	to "option_callback()".	 See "option_callback()" for details
	   on receiving	enable/disable notification of a TELNET	option.

	   You can give	multiple Do, Dont, Will, or Wont arguments for
	   different TELNET options in the same	call to	this method.

	   The following example describes the meaning of the named
	   parameters.	A TELNET option, such as "TELOPT_ECHO" used below, is
	   an integer constant that you	can import from	Net::Telnet.  See the
	   source in file Telnet.pm for	the complete list.

	   o   Do => "TELOPT_ECHO"

	       o   we'll accept	an offer to enable the echo option on the
		   local side

	   o   Dont => "TELOPT_ECHO"

	       o   we'll reject	an offer to enable the echo option on the
		   local side

	   o   Will => "TELOPT_ECHO"

	       o   we'll accept	an offer to enable the echo option on the
		   remote side

	   o   Wont => "TELOPT_ECHO"

	       o   we'll reject	an offer to enable the echo option on the
		   remote side

	   Use "option_send()" to send a request to the	remote side to enable
	   or disable a	particular TELNET option.

       option_callback - define	the option negotiation callback
	       $coderef	= $obj->option_callback;

	       $prev = $obj->option_callback($coderef);

	   This	method defines the callback subroutine that is called when a
	   TELNET option is enabled or disabled.  Once defined,	the
	   option_callback may not be undefined.  However, calling this	method
	   with	a different $coderef changes it.

	   A warning is	printed	to STDERR when attempting to set this
	   attribute to	something that isn't a coderef.

	   Here	are the	circumstances that invoke $coderef:

	   o   An option becomes enabled because the remote side requested an
	       enable and "option_accept()" had	been used to arrange that it
	       be accepted.

	   o   The remote side arbitrarily decides to disable an option	that
	       is currently enabled.  Note that	Net::Telnet always accepts a
	       request to disable from the remote side.

	   o   "option_send()" was used	to send	a request to enable or disable
	       an option and the response from the remote side has just	been
	       received.  Note,	that if	a request to enable is rejected	then
	       $coderef	is still invoked even though the option	didn't change.

	   Here	are the	arguments passed to _$coderef:

	       &$coderef($obj, $option,	$is_remote,
			 $is_enabled, $was_enabled, $buf_position);

	   o   1.  $obj	is the Net::Telnet object

	   o   2.  $option is the TELNET option.  Net::Telnet exports
	       constants for the various TELNET	options	which just equate to
	       an integer.

	   o   3.  $is_remote is a boolean indicating for which	side the
	       option applies.

	   o   4.  $is_enabled is a boolean indicating the option is enabled
	       or disabled

	   o   5.  $was_enabled	is a boolean indicating	the option was
	       previously enabled or disabled

	   o   6.  $buf_position is an integer indicating the position in the
	       object's	input buffer where the option takes effect.  See
	       "buffer()" to access the	object's input buffer.

       option_log - log	all TELNET options sent	or received
	       $fh = $obj->option_log;

	       $fh = $obj->option_log($fh);

	       $fh = $obj->option_log($filename);

	   This	method starts or stops logging of all TELNET options being
	   sent	or received.  This is useful for debugging when	you send
	   options via "option_send()" or you arrange to accept	option
	   requests from the remote side via "option_accept()".	 Also see
	   "dump_log()".

	   If no argument is given, the	log filehandle is returned.  An	empty
	   string indicates logging is off.

	   To stop logging, use	an empty string	as an argument.	 The stopped
	   filehandle is not closed.

	   If an open filehandle is given, it is used for logging and
	   returned.  Otherwise, the argument is assumed to be the name	of a
	   file, the filename is opened	for logging and	a filehandle to	it is
	   returned.  If the filehandle	is not already opened or the filename
	   can't be opened for writing,	the error mode action is performed.

       option_send - send TELNET option	negotiation request
	       $ok = $obj->option_send([Do    => $telopt,]
				       [Dont  => $telopt,]
				       [Will  => $telopt,]
				       [Wont  => $telopt,]
				       [Async => $boolean,]);

	   This	method is not yet implemented.	Look for it in a future
	   version.

       option_state - get current state	of a TELNET option
	       $hashref	= $obj->option_state($telopt);

	   This	method returns a hashref containing a copy of the current
	   state of TELNET option $telopt.

	   Here	are the	values returned	in the hash:

	   o   $hashref->{remote_enabled}

	       o   boolean that	indicates if the option	is enabled on the
		   remote side.

	   o   $hashref->{remote_enable_ok}

	       o   boolean that	indicates if it's ok to	accept an offer	to
		   enable this option on the remote side.

	   o   $hashref->{remote_state}

	       o   string used to hold the internal state of option
		   negotiation for this	option on the remote side.

	   o   $hashref->{local_enabled}

	       o   boolean that	indicates if the option	is enabled on the
		   local side.

	   o   $hashref->{local_enable_ok}

	       o   boolean that	indicates if it's ok to	accept an offer	to
		   enable this option on the local side.

	   o   $hashref->{local_state}

	       o   string used to hold the internal state of option
		   negotiation for this	option on the local side.

       ors - output line delimiter
	       $chars =	$obj->ors;

	       $prev = $obj->ors($chars);

	   This	method is synonymous with "output_record_separator()".

       output_field_separator -	field separator	for print
	       $chars =	$obj->output_field_separator;

	       $prev = $obj->output_field_separator($chars);

	   This	method designates the output field separator for "print()".
	   Ordinarily the print	method simply prints out the comma separated
	   fields you specify.	Set this to specify what's printed between
	   fields.

	   With	no argument this method	returns	the current output field
	   separator set in the	object.	 With an argument it sets the output
	   field separator to $chars and returns the previous value.

	   By default it's set to an empty string.

       output_log - log	all output
	       $fh = $obj->output_log;

	       $fh = $obj->output_log($fh);

	       $fh = $obj->output_log($filename);

	   This	method starts or stops logging of output.  This	is useful when
	   debugging.  Also see	"dump_log()".  Because most command
	   interpreters	echo back commands received, it's likely all your
	   output would	also be	in an input log.  See "input_log()".  Note
	   that	output logging occurs before newline translation.  See
	   "binmode()" for details on newline translation.

	   If no argument is given, the	log filehandle is returned.  A
	   returned empty string indicates logging is off.

	   To stop logging, use	an empty string	as an argument.	 The stopped
	   filehandle is not closed.

	   If an open filehandle is given, it is used for logging and
	   returned.  Otherwise, the argument is assumed to be the name	of a
	   file, the filename is opened	for logging and	a filehandle to	it is
	   returned.  If the filehandle	is not already opened or the filename
	   can't be opened for writing,	the error mode action is performed.

       output_record_separator - output	line delimiter
	       $chars =	$obj->output_record_separator;

	       $prev = $obj->output_record_separator($chars);

	   This	method designates the output line delimiter for	"print()" and
	   "cmd()".  Set this to specify what's	printed	at the end of
	   "print()" and "cmd()".

	   The output record separator is set to "\n" by default, so there's
	   no need to append all your commands with a newline.	To avoid
	   printing the	output_record_separator	use "put()" or set the
	   output_record_separator to an empty string.

	   With	no argument this method	returns	the current output record
	   separator set in the	object.	 With an argument it sets the output
	   record separator to $chars and returns the previous value.

       peerhost	- IP address of	the other end of the socket connection
	       $ipaddr = $obj->peerhost;

	   This	method returns a string	which is the IPv4 or IPv6 address the
	   remote socket is bound to (i.e. it is the IP	address	of "host()").
	   It returns "" when not connected.

       peerport	- TCP port of the other	end of the socket connection
	       $port = $obj->peerport;

	   This	method returns the port	number which the remote	socket is
	   bound to.  It is the	same as	the "port()" number when connected.
	   It returns "" when not connected.

       port - remote port
	       $port = $obj->port;

	       $prev = $obj->port($port);

	   This	method designates the remote TCP port for "open()".  With no
	   argument this method	returns	the current port number.  With an
	   argument it sets the	current	port number to $port and returns the
	   previous port.  If $port is a TCP service name, then	it's first
	   converted to	a port number using the	perl function
	   "getservbyname()".

	   The default value is	23.

	   The error mode action is performed when attempting to set this
	   attribute to	something that is not a	positive integer or a valid
	   TCP service name.

       print - write to	object
	       $ok = $obj->print(@list);

	   This	method writes @list followed by	the output_record_separator to
	   the open object and returns 1 if all	data was successfully written.
	   On time-out or other	failures, the error mode action	is performed.
	   See "errmode()".

	   By default, the "output_record_separator()" is set to "\n" so all
	   your	commands automatically end with	a newline.  In most cases your
	   output is being read	by a command interpreter which won't accept a
	   command until newline is read.  This	is similar to someone typing a
	   command and hitting the return key.	To avoid printing a trailing
	   "\n"	use "put()" instead or set the output_record_separator to an
	   empty string.

	   On failure, it's possible that some data was	written.  If you
	   choose to try and recover from a print timing-out, use
	   "print_length()" to determine how much was written before the error
	   occurred.

	   You may also	use the	output field separator to print	a string
	   between the list elements.  See "output_field_separator()".

       print_length - number of	bytes written by print
	       $num = $obj->print_length;

	   This	returns	the number of bytes successfully written by the	most
	   recent "print()" or "put()".

       prompt -	pattern	to match a prompt
	       $matchop	= $obj->prompt;

	       $prev = $obj->prompt($matchop);

	   This	method sets the	pattern	used to	find a prompt in the input
	   stream.  It must be a string	representing a valid perl pattern
	   match operator.  The	methods	"login()" and "cmd()" try to read
	   until matching the prompt.  They will fail with a time-out error if
	   the pattern you've chosen doesn't match what	the remote side	sends.

	   With	no argument this method	returns	the prompt set in the object.
	   With	an argument it sets the	prompt to $matchop and returns the
	   previous value.

	   The default prompt is '/[\$%#>] $/'

	   Always use single quotes, instead of	double quotes, to construct
	   $matchop (e.g. '/bash\$ $/').  If you're constructing a DOS like
	   file	path, you'll need to use four backslashes to represent one
	   (e.g. '/c:\\\\users\\\\bill>$/i').

	   Of course don't forget about	regexp metacharacters like ".",	"[",
	   or "$".  You'll only	need a single backslash	to quote them.	The
	   anchor metacharacters "^" and "$" refer to positions	in the input
	   buffer.

	   The error mode action is performed when attempting to set this
	   attribute with a match operator missing its opening delimiter.

       put - write to object
	       $ok = $obj->put($string);

	       $ok = $obj->put(String	   => $string,
			       [Binmode	   => $mode,]
			       [Errmode	   => $errmode,]
			       [Telnetmode => $mode,]
			       [Timeout	   => $secs,]);

	   This	method writes $string to the opened object and returns 1 if
	   all data was	successfully written.  This method is like "print()"
	   except that it doesn't write	the trailing output_record_separator
	   ("\n" by default).  On time-out or other failures, the error	mode
	   action is performed.	 See "errmode()".

	   On failure, it's possible that some data was	written.  If you
	   choose to try and recover from a put	timing-out, use
	   "print_length()" to determine how much was written before the error
	   occurred.

	   Optional named parameters are provided to override the current
	   settings of binmode,	errmode, telnetmode, and timeout.

       rs - input line delimiter
	       $chars =	$obj->rs;

	       $prev = $obj->rs($chars);

	   This	method is synonymous with "input_record_separator()".

       sockfamily - IP address family of connected local socket
	       $sockfamily = $obj->sockfamily;

	   This	method returns which IP	address	family "open()"	used to
	   successfully	connect.  It is	most useful when the requested address
	   "family()" for "open()" was "any".  Values returned may be "ipv4",
	   "ipv6", or "" (when not connected).

       sockhost	- IP address of	this end of the	socket connection
	       $ipaddr = $obj->sockhost;

	   This	method returns a string	which is the IPv4 or IPv6 address the
	   local socket	is bound to.  It returns "" when not connected.

       sockport	- TCP port of this end of the socket connection
	       $port = $obj->sockport;

	   This	method returns the port	number which the local socket is bound
	   to.	It returns "" when not connected.

       telnetmode - turn off/on	telnet command interpretation
	       $mode = $obj->telnetmode;

	       $prev = $obj->telnetmode($mode);

	   This	method controls	whether	or not TELNET commands in the data
	   stream are recognized and handled.  The TELNET protocol uses
	   certain character sequences sent in the data	stream to control the
	   session.  If	the port you're	connecting to isn't using the TELNET
	   protocol, then you should turn this mode off.  The default is on.

	   If no argument is given, the	current	mode is	returned.

	   If $mode is 0 then telnet mode is off.  If $mode is 1 then telnet
	   mode	is on.

       timed_out - time-out indicator
	       $boolean	= $obj->timed_out;

	       $prev = $obj->timed_out($boolean);

	   This	method indicates if a previous read, write, or open method
	   timed-out.  Remember	that timing-out	is itself an error.  To	be
	   able	to invoke "timed_out()"	after a	time-out error,	you'd have to
	   change the default error mode to something other than "die".	 See
	   "errmode()".

	   With	no argument this method	returns	1 if the previous method
	   timed-out.  With an argument	it sets	the indicator.	Normally, only
	   internal methods set	this indicator.

       timeout - I/O time-out interval
	       $secs = $obj->timeout;

	       $prev = $obj->timeout($secs);

	   This	method sets the	timeout	interval used when performing I/O or
	   connecting to a port.  When a method	doesn't	complete within	the
	   timeout interval then it's an error and the error mode action is
	   performed.

	   A timeout may be expressed as a relative or absolute	value.	If
	   $secs is greater than or equal to the time the program started, as
	   determined by $^T, then it's	an absolute time value for when	time-
	   out occurs.	The perl function "time()" may be used to obtain an
	   absolute time value.	 For a relative	time-out value less than $^T,
	   time-out happens $secs from when the	method begins.

	   If $secs is 0 then time-out occurs if the data cannot be
	   immediately read or written.	 Use the undefined value to turn off
	   timing-out completely.

	   With	no argument this method	returns	the timeout set	in the object.
	   With	an argument it sets the	timeout	to $secs and returns the
	   previous value.  The	default	timeout	value is 10 seconds.

	   A warning is	printed	to STDERR when attempting to set this
	   attribute to	something that is not an "undef" or a non-negative
	   integer.

       waitfor - wait for pattern in the input
	       $ok = $obj->waitfor($matchop);
	       $ok = $obj->waitfor([Match      => $matchop,]
				   [String     => $string,]
				   [Binmode    => $mode,]
				   [Errmode    => $errmode,]
				   [Telnetmode => $mode,]
				   [Timeout    => $secs,]);

	       ($prematch, $match) = $obj->waitfor($matchop);
	       ($prematch, $match) = $obj->waitfor([Match      => $matchop,]
						   [String     => $string,]
						   [Binmode    => $mode,]
						   [Errmode    => $errmode,]
						   [Telnetmode => $mode,]
						   [Timeout    => $secs,]);

	   This	method reads until a pattern match or string is	found in the
	   input stream.  All the characters before and	including the match
	   are removed from the	input stream.

	   In a	list context the characters before the match and the matched
	   characters are returned in $prematch	and $match.  In	a scalar
	   context, the	matched	characters and all characters before it	are
	   discarded and 1 is returned on success.  On time-out, eof, or other
	   failures, for both list and scalar context, the error mode action
	   is performed.  See "errmode()".

	   You can specify more	than one pattern or string by simply providing
	   multiple Match and/or String	named parameters.  A $matchop must be
	   a string representing a valid Perl pattern match operator.  The
	   $string is just a substring to find in the input stream.

	   Use "dump_log()" to debug when this method keeps timing-out and you
	   don't think it should.

	   An optional named parameter is provided to override the current
	   setting of timeout.

	   To avoid unexpected backslash interpretation, always	use single
	   quotes instead of double quotes to construct	a match	operator
	   argument for	"prompt()" and "waitfor()" (e.g. '/bash\$ $/').	 If
	   you're constructing a DOS like file path, you'll need to use	four
	   backslashes to represent one	(e.g. '/c:\\\\users\\\\bill>$/i').

	   Of course don't forget about	regexp metacharacters like ".",	"[",
	   or "$".  You'll only	need a single backslash	to quote them.	The
	   anchor metacharacters "^" and "$" refer to positions	in the input
	   buffer.

	   Optional named parameters are provided to override the current
	   settings of binmode,	errmode, telnetmode, and timeout.

SEE ALSO
       RFC 854
	 TELNETA ProtocolA Specification

	 http://tools.ietf.org/html/rfc854

       RFC 1143
	 QA MethodA ofA	ImplementingA TELNETA OptionA Negotiation

	 http://tools.ietf.org/html/rfc1143

       TELNET Option Assignments
	 http://www.iana.org/assignments/telnet-options

EXAMPLES
       Setting "prompt()" to match a user's shell prompt can be	tricky.	 This
       example logs in without knowing the shell prompt	and then sets it to
       match "prompt()".  It requires /usr/bin/env and /bin/sh on the remote
       host.

	   my $host = 'your_destination_host_here';
	   my $user = 'your_username_here';
	   my $passwd =	'your_password_here';
	   my ($t, @output);

	   ## Create a Net::Telnet object.
	   use Net::Telnet ();
	   $t =	new Net::Telnet	(Timeout  => 10);

	   ## Connect and login.
	   $t->open($host);

	   $t->waitfor('/login:	?$/i');
	   $t->print($user);

	   $t->waitfor('/password: ?$/i');
	   $t->print($passwd);

	   ## Switch to	a known	shell, using a known prompt.
	   $t->prompt('/<xPROMPTx> $/');
	   $t->errmode("return");

	   $t->cmd("exec /usr/bin/env 'PS1=<xPROMPTx> '	/bin/sh	-i")
	       or die "login failed to remote host $host";

	   $t->errmode("die");

	   ## Now you can do cmd() to your heart's content.
	   @output = $t->cmd("uname -a");
	   print @output;

	   exit;

       Usually you want	the remote TERM	environment variable to	be set to
       something like "dumb" so	you don't read escape sequences	meant to be
       interpreted by a	display	terminal.  It is best to set it	via "cmd()",
       or via "waitfor()" and "print()".  It is	also possible to negotiate the
       terminal	type via telnet.  Here is how to do that.

	   ## Module import.
	   use Net::Telnet qw(TELNET_IAC TELNET_SB TELNET_SE TELOPT_TTYPE);

	   ## Global variables.
	   my $Term;

	   ## Main program.
	   {
	       my $host	= "your_destination_host_here";
	       my $user	= "your_username_here";
	       my $passwd = "your_password_here";
	       my $prompt = '/bash\$ $/';  # your regexp for shell prompt here
	       my $t;

	       $t = new	Net::Telnet (Prompt => $prompt);

	       ## Set up callbacks to negotiate	terminal type.
	       $t->option_callback(sub {});
	       $t->suboption_callback(\&subopt_callback);
	       $t->option_accept(Do => TELOPT_TTYPE);

	       ## Login	and print value	of TERM.
	       $Term = "dumb";
	       $t->open($host);
	       $t->login($user,	$passwd);
	       print $t->cmd('hostname');
	       print "TERM=", $t->cmd('echo $TERM');
	       $t->close;

	       exit;
	   } # end main	program

	   sub subopt_callback {
	       my ($t, $option,	$parameters) = @_;
	       my $telcmd;

	       if ($option == TELOPT_TTYPE) {
		   $telcmd = pack("C4 A* C2", TELNET_IAC, TELNET_SB, TELOPT_TTYPE, 0,
				  $Term, TELNET_IAC, TELNET_SE);
		   $t->put(String => $telcmd,
			   Telnetmode => 0);
	       }

	       1;
	   } # end sub subopt_callback

       You can also use	Net::Telnet to interact	with local programs.  This
       example changes a user's	login password.	 It introduces the "spawn()"
       subroutine to start a program and associate a filehandle	with its
       standard	I/O.  Because the passwd program always	prompts	for passwords
       on its controlling terminal, the	IO::Pty	module is used to create a new
       pseudo terminal for use by passwd.  The Net::Telnet object reads	and
       writes to that pseudo terminal.	To use the code	below, substitute
       "changeme" with the actual old and new passwords.

       ## Main program.	 {
	   my ($pty, $passwd);
	   my $oldpw = "changeme";
	   my $newpw = "changeme";

	   ## Start passwd program.
	   $pty	= spawn("passwd");

	   ## Create a Net::Telnet object to perform I/O on passwd's tty.
	   use Net::Telnet;
	   $passwd = new Net::Telnet (-fhopen => $pty,
				      -timeout => 2,
				      -output_record_separator => "\r",
				      -telnetmode => 0,
				      -cmd_remove_mode => 1);
	   $passwd->errmode("return");

	   ## Send existing password.
	   $passwd->waitfor('/password:	?$/i')
	       or die "no old password prompt: ", $passwd->lastline;
	   $passwd->print($oldpw);

	   ## Send new password.
	   $passwd->waitfor('/new (\w+\s)?password: ?$/i')
	       or die "bad old password: ", $passwd->lastline;
	   $passwd->print($newpw);

	   ## Send new password	verification.
	   $passwd->waitfor('/new (\w+\s)?password: ?$/i')
	       or die "bad new password: ", $passwd->lastline;
	   $passwd->print($newpw);

	   ## Display success or failure.
	   $passwd->waitfor('/(changed|updated)/')
	       or die "bad new password: ", $passwd->lastline;
	   print $passwd->lastline;

	   $passwd->close;
	   exit;
       } # end main program

       sub spawn {
	   my (@cmd) = @_;
	   my ($pid, $pty, $tty, $tty_fd);

	   ## Create a new pseudo terminal.
	   use IO::Pty ();
	   $pty	= new IO::Pty
	       or die $!;

	   ## Execute the program in another process.
	   unless ($pid	= fork)	{  # child process
	       die "problem spawning program: $!\n" unless defined $pid;

	       ## Disassociate process from its	controlling terminal.
	       use POSIX ();
	       POSIX::setsid()
		   or die "setsid failed: $!";

	       ## Associate process with a new controlling terminal.
	       $pty->make_slave_controlling_terminal;
	       $tty = $pty->slave;
	       $tty_fd = $tty->fileno;
	       close $pty;

	       ## Make standard	I/O use	the new	controlling terminal.
	       open STDIN, "<&$tty_fd" or die $!;
	       open STDOUT, ">&$tty_fd"	or die $!;
	       open STDERR, ">&STDOUT" or die $!;
	       close $tty;

	       ## Execute requested program.
	       exec @cmd
		   or die "problem executing $cmd[0]\n";
	   } # end child process

	   $pty;
       } # end sub spawn

       Here is an example that uses the	openssh	program	to connect to a	remote
       host.  It uses the "spawn()" subroutine,	from the password changing
       example above, to start the ssh program and then	read and write to it
       via a Net::Telnet object.  This example turns off ssh host key
       checking, which reduces your ability to know when someone on the
       network is impersonating	the remote host.  To use the code below,
       substitute "changeme" with the actual host, user, password, and command
       prompt.

	   ## Main program.
	   {
	       my $host	= "changeme";
	       my $user	= "changeme";
	       my $passwd = "changeme";
	       my $prompt = '/changeme\$ $/';
	       my ($buf, $match, $pty, $ssh, @lines);

	       ## Start	ssh program.
	       $pty = spawn("ssh",
			    "-l", $user,
			    "-e", "none",
			    "-F", "/dev/null",
			    "-o", "PreferredAuthentications=password",
			    "-o", "NumberOfPasswordPrompts=1",
			    "-o", "StrictHostKeyChecking=no",
			    "-o", "UserKnownHostsFile=/dev/null",
			    $host);

	       ## Create a Net::Telnet object to perform I/O on	ssh's tty.
	       use Net::Telnet;
	       $ssh = new Net::Telnet (-fhopen => $pty,
				       -prompt => $prompt,
				       -telnetmode => 0,
				       -output_record_separator	=> "\r",
				       -cmd_remove_mode	=> 1);

	       ## Wait for the password	prompt and send	password.
	       $ssh->waitfor(-match => '/password: ?$/i',
			     -errmode => "return")
		   or die "problem connecting to \"$host\": ", $ssh->lastline;
	       $ssh->print($passwd);

	       ## Wait for the shell prompt.
	       (undef, $match) = $ssh->waitfor(-match => $ssh->prompt,
					       -match => '/^Permission denied/m',
					       -errmode	=> "return")
		   or return $ssh->error("login	failed:	expected shell prompt ",
					 "doesn't match	actual\n");
	       return $ssh->error("login failed: bad login-name	or password\n")
		   if $match =~	/^Permission denied/m;

	       ## Run commands on remote host.
	       print $ssh->cmd("hostname");
	       print $ssh->cmd("uptime");

	       $ssh->close;
	       exit;
	   } # end main	program

       Some shells have	a rather restrictive 255 character line	limit.	If you
       run into	this problem, here is an example for sending lines longer than
       254 as a	sequence of shorter lines.

	   ## Main program.
	   {
	       my $host	= "changeme";
	       my $user	= "changeme";
	       my $passwd = "changeme";
	       my $prompt = '/changeme\$ $/';
	       my $cmd = join("", "echo	",
			      "11111111112222222222333333333344444444445555555555",
			      "66666666667777777777888888888899999999990000000000",
			      "11111111112222222222333333333344444444445555555555",
			      "66666666667777777777888888888899999999990000000000",
			      "11111111112222222222333333333344444444445555555555",
			      "66666666667777777777888888888899999999990000000000");

	       use Net::Telnet ();
	       my $t = new Net::Telnet (-prompt	=> $prompt);
	       $t->open($host);
	       $t->login($user,	$passwd);

	       my @output = cmd_unixlong($t, $cmd);
	       print @output;

	       exit;
	   } # end main	program

	   sub cmd_unixlong {
	       my ($obj, $cmd) = @_;
	       my ($line, $pos);
	       my $max_tty_line	= 254;

	       ## Start	a Bourne shell.
	       $obj->cmd(-string => "/usr/bin/env " .
			 "'PS1=<xPROMPTx> ' 'PS2=<xPROMPTx> ' /bin/sh -i",
			 -prompt => '/<xPROMPTx> $/')
		   or return;

	       ## Break-up the one large command line and send as shorter lines.
	       $pos = 0;
	       while (1) {
		   $line = substr $cmd,	$pos, $max_tty_line;
		   $pos	+= length $line;
		   last	unless $pos < length $cmd;

		   ## Send the line with continuation char.
		   $obj->cmd(-string =>	"$line\\",
			     -prompt =>	'/<xPROMPTx> $/')
		       or return;
	       }

	       ## Send the last	line and return	the output.
	       $obj->cmd("$line	; exit");
	   } # end sub cmd_unixlong

AUTHOR
       Jay Rogers <jay@rgrs.com>

CREDITS
       Dave Martin, Dave Cardosi

COPYRIGHT
       Copyright 1997, 2000, 2002, 2013	by Jay Rogers.	All rights reserved.
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 5169:
	   Expected text after =item, not a bullet

       Around line 5217:
	   Expected text after =item, not a bullet

perl v5.32.1			  2013-04-21			Net::Telnet(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | EXAMPLES | AUTHOR | CREDITS | COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Telnet&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help