use Net::Telnet ();
see METHODS section below
This example prints who's logged-on to the remote host sparky:
$sparky = new Net::Telnet (Host => "sparky",
Timeout => 10,
Prompt => '/[$%#>] $/');
$sparky->login($username, $passwd);
@lines = $sparky->cmd("/usr/bin/who");
print @lines;
$sparky->close;
Methods login() and cmd() use the prompt setting in the object
to determine when a login or command is complete. If the prompt
doesn't match, it's likely those commands will timeout.
Other reasons to use this class than strictly with a TELNET port are:
Please note some important differences with most other Perl I/O calls. All input is buffered, while all output is flushed. The output record separator for print() is set to \n by default, so there's no need to append all your commands with a newline. See output_record_separator() to change the default. In the input stream, each sequence of \r\n is converted to \n. In the output stream, each occurrence of \n is converted to a sequence of \r\n. See binmode() to change the default. TCP protocols typically use the ASCII sequence carriage-return newline to designate a newline.
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 the standard Perl distribution. If you have the IO:: libraries then methods are inherited from the class IO::Socket::INET, otherwise FileHandle is used as a base class.
Special methods are provided to handle errors. Normally when an error or timeout is encountered using a telnet object, the program dies with an error message printed to standard error. You may arrange for the methods to return with an undefined value instead by using errmode() or the errmode option to new(). See errmode() for other sophisticated error mode settings. The error message itself may be obtained using the errmsg().
Note that eof is not considered an error while timing-out is.
While debugging your program use input_log() or dump_log() to see what's actually being received and sent.
Two different styles of named arguments 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);For more help, see the EXAMPLES section below.
This is an alpha version - meaning that the interface may change in future versions. Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have suggestions for improvement.
$obj = Net::Telnet->new([Binmode => $mode,]
[Dump_Log => $filename,]
[Errmode => $errmode,]
[Fhopen => $filehandle,]
[Host => $host,]
[Input_log => $file,]
[Input_record_separator => $char,]
[Output_log => $file,]
[Output_record_separator => $char,]
[Port => $port,]
[Prompt => $matchop,]
[Telnetmode => $mode,]
[Timeout => $secs,]);
This is the constructor for Net::Telnet objects. A new object is
returned on success, the $errmode action is performed on failure -
see errmode(). The 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 arguments:
$prev = $obj->binmode($mode);This method controls whether or not sequences of \r\n are translated. By default they are translated (i.e. binmode is off).
If $mode is missing or 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 \r\n is converted to \n and in the output stream, each occurrence of \n is converted to a sequence of \r\n.
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.
$ok = $obj->break;This method sends the TELNET break character. This character is provided because it's a signal outside the USASCII 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.
$ok = $obj->close;This method closes the socket, file, or pipe associated with the object.
$ok = $obj->cmd($string);
$ok = $obj->cmd(String => $string,
[Output => $ref,]
[Prompt => $match,]
[Timeout => $secs,]);
@output = $obj->cmd($string);
@output = $obj->cmd(String => $string,
[Output => $ref,]
[Prompt => $match,]
[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.
In a scalar context the characters read are discarded and a boolean is returned indicating the success or failure of sending the command string and reading the prompt. Note that in order to return on error, errmode() must not be set to die.
In an array 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, an array containing one element, the null string is returned. This is so the array will indicate true in a boolean context.
Optional named arguments are provided to override the current settings of prompt and timeout.
The output named argument provides an alternative method of receiving command output. If you pass a scalar reference, the output 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.
$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 current log filehandle is returned. A null string indicates logging is off.
To stop logging, use a null string as an argument.
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 file is opened and a filehandle to it is returned.
$eof = $obj->eof;This method indicates if end of file has been read. 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.
$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 then when an error is encountered using the object, the program dies and an error message is printed on standard error.
When mode is return then the method generating the error places an error message in the object and returns the undefined value in a scalar context and a null 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 a null 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 a null list depending on context.
$msg = $obj->errmsg;
$prev = $obj->errmsg(@msgs);The first calling sequence returns the error message associated with the object. The null 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.
$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. Also see errmode().
If the error mode doesn't cause the program to die then the undefined value or a null list is returned depending on context.
This method is primarily used by this class or a sub-class to perform the user requested action when an error is encountered.
$ok = $obj->fhopen($fh);This method associates the open filehandle $fh with the object for further I/O.
This method provides a way to use this module with a filehandle that's already opened. Suppose you want to use the features of this module to do I/O to something other than a TCP port. Instead of opening the object for I/O to a TCP port by passing a host arg to new() or invoking open(), call this method instead.
$data = $obj->get([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 timeout or other errors the error mode action is performed.
$line = $obj->getline([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 the timeout. You can override the object's timeout for this method using $secs. Also see timeout().
On eof an undefined value is returned. On timeout or other errors the error mode action is performed.
@lines = $obj->getlines([Timeout => $secs,]);This method reads and returns the next available lines 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 one or more lines, or the timeout. You can override the object's timeout for this method using $secs. Also see timeout().
On eof a null array is returned. On timeout or other errors the error mode action is performed.
$host = $obj->host;
$prev = $obj->host($host);This method designates the remote host. With no argument this method returns the current host name set in the object. With an argument it sets the current host name to $host and returns the previous host name. You may indicate the remote host using either a hostname or an IP address.
$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, its 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 null string indicates logging is off.
To stop logging, use a null string as an argument.
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 file is opened for logging and a filehandle to it is returned.
$rs = $obj->input_record_separator;
$prev = $obj->input_record_separator($rs);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 $rs and returns the previous value.
$line = $obj->lastline;
$prev = $obj->lastline($line);This method saves 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.
$ok = $obj->login($username, $password);
$ok = $obj->login(Name => $username,
Password => $password,
[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 the prompts sent don't match what's
expected, the method will timeout - unless timeout is turned off.
Login prompts must match either of the patterns:
/login[: ]*$/i
/username[: ]*$/i
Password prompts must match the pattern:
/password[: ]*$/iThe command interpreter prompt must match the current value of prompt().
Optional named arguments are provided to override the current settings of prompt and timeout.
$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 (1MB). The input buffer can grow much larger than the block size when you 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.
$ok = $obj->open($host);
$ok = $obj->open([Host => $host,]
[Port => $port,]
[Timeout => $secs,]);
This method opens a TCP connection to $port on $host. If either
argument is missing then the current value of host() or port()
is used.
An optional named argument is provided to override the current setting of timeout.
Timeouts don't work for this method on machines that don't implement SIGALRM. 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.
$ofs = $obj->output_field_separator;
$prev = $obj->output_field_separator($ofs);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 $ofs and returns the previous value.
$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, its 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 null string indicates logging is off.
To stop logging, use a null string as an argument.
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 file is opened for logging and a filehandle to it is returned.
$ors = $obj->output_record_separator;
$prev = $obj->output_record_separator($ors);This method designates the output record separator for print(). Ordinarily the print operator simply prints out the comma separated fields you specify, with no trailing newline or record separator assumed. Set this variable to specify what's printed at the end of the print.
Note: the output record separator is set to \n by default, so there's no need to append all your commands with a newline.
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 $ors and returns the previous value.
$port = $obj->port;
$prev = $obj->port($port);This method designates the remote TCP port. 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 service name, then first it's converted to a port number using the perl function getservbyname().
$ok = $obj->print(@list);This method prints a string or a comma-separated list of strings to the opened object and returns non-zero if all data was successfully written.
By default, the output_record_separator() is set to \n in order to have 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.
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 timeout occurred.
$num = $obj->print_length;This returns the number of bytes successfully written by the most recent print().
$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. If the pattern chosen doesn't match what's sent, then it's likely those commands will timeout.
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 to construct $matchop to avoid unintended backslash interpretation. Using single quotes, you only need add extra backslashes to quote patterns containing \' or \\.
$prev = $obj->telnet($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 $mode is 0 then telnet mode is off. If $mode is missing or 1 then telnet mode is on.
$boolean = $obj->timed_out;
$prev = $obj->timed_out($boolean);This method indicates if a previous read or write method timed-out.
With no argument this method returns true if a previous method timed-out. With an argument it sets the indicator. Generally this is used by internal methods to clear it.
$secs = $obj->timeout;
$prev = $obj->timeout($secs);This method sets the timeout interval that's 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.
The timeout may be expressed as a relative or absolute value. If $secs is greater than or equal to the time the program was started, as determined by $^T, then it's the absolute time when timeout occurs. Also see the perl function time(). A relative timeout happens $secs from when the I/O method begins.
If $secs is 0 then timeout occurs if the data cannot be immediately read or written. Use the undefined value to turn off timing-out.
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.
$ok = $obj->waitfor($matchop);
$ok = $obj->waitfor([Match => $matchop,]
[String => $string,]
[Timeout => $secs,]);
($prematch, $match) = $obj->waitfor($matchop);
($prematch, $match) = $obj->waitfor([Match => $matchop,]
[String => $string,]
[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. On eof an undefined value is returned.
On timeout or other errors the error mode action is performed.
In an array context the characters before the match and the matched characters are returned in $prematch and $match.
You can specify more than one pattern or string by simply providing multiple Match and/or String named arguments. 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.
An optional named argument is provided to override the current setting of timeout.
Always use single quotes to construct $matchop to avoid unintended backslash interpretation. Using single quotes, you only need add extra backslashes to quote patterns containing \' or \\.
use Net::Telnet ();
my($forecast, $t);
$t = new Net::Telnet (-host => "rainmaker.wunderground.com");
## Wait for first prompt and "hit return".
$t->waitfor('/continue:.*$/');
$t->print("");
## Wait for second prompt and respond with city code.
$t->waitfor('/city code:.*$/');
$t->print("BRD");
## Read and print the first page of forecast.
($forecast) = $t->waitfor('/[ \t]+press return to continue/i');
print $forecast;
exit;This example checks a POP server to see if you have mail.
use Net::Telnet ();
my($hostname, $line, $passwd, $pop, $username);
$hostname = "your_destination_host_here";
$username = "your_username_here";
$passwd = "your_password_here";
$pop = new Net::Telnet (-host => $hostname,
-port => 110,
-telnetmode => '');
## Read connection message.
$line = $pop->getline;
die $line unless $line =~ /^\+OK/;
## Send user name.
$pop->print("user $username");
$line = $pop->getline;
die $line unless $line =~ /^\+OK/;
## Send password.
$pop->print("pass $passwd");
$line = $pop->getline;
die $line unless $line =~ /^\+OK/;
## Request status of messages.
$pop->print("list");
$line = $pop->getline;
print $line;
exit;Here's an example you can use to down load a file of any type. The file is read from the remote host's standard output using cat. To prevent any output processing, the remote host's standard output is put in raw mode using the Bourne shell. The Bourne shell is used because some shells, notably tcsh, prevent changing tty modes. Upon completion, FTP style statistics are printed to stderr.
use Net::Telnet;
my($block, $filename, $host, $hostname, $k_per_sec, $line,
$num_read, $passwd, $prevblock, $prompt, $size, $size_bsd,
$size_sysv, $start_time, $total_time, $username);
$hostname = "your_destination_host_here";
$username = "your_username_here";
$passwd = "your_password_here";
$filename = "your_download_file_here";
## Connect and login.
$host = new Net::Telnet (Host => $hostname,
Timeout => 30,
Prompt => '/[%#>] $/');
$host->login($username, $passwd);
## Make sure prompt won't match anything in send data.
$prompt = '_funkyPrompt_';
$host->prompt("/$prompt\$/");
$host->cmd("set prompt = '$prompt'");
## Get size of file.
($line) = $host->cmd("/usr/bin/ls -l $filename");
($size_bsd, $size_sysv) = (split ' ', $line)[3,4];
if ($size_sysv =~ /^\d+$/) {
$size = $size_sysv;
}
elsif ($size_bsd =~ /^\d+$/) {
$size = $size_bsd;
}
else {
die "$filename: no such file on $hostname";
}
## Start sending the file.
binmode STDOUT;
$host->binmode;
$host->print("/usr/bin/sh -c 'stty raw; cat $filename'");
$host->getline; # discard echoed back line
## Read file a block at a time.
$num_read = 0;
$prevblock = '';
$start_time = time;
while (($block = $host->get) and ($block !~ /$prompt$/o)) {
if (length $block >= length $prompt) {
print $prevblock;
$num_read += length $prevblock;
$prevblock = $block;
}
else {
$prevblock .= $block;
}
}
$host->close;
## Print last block without trailing prompt.
$prevblock .= $block;
$prevblock =~ s/$prompt$//;
print $prevblock;
$num_read += length $prevblock;
die "error: expected size $size, received size $num_read\n"
unless $num_read == $size;
## Print totals.
$total_time = (time - $start_time) || 1;
$k_per_sec = ($size / 1024) / $total_time;
$k_per_sec = sprintf "%3.1f", $k_per_sec;
warn("$num_read bytes received in $total_time seconds ",
"($k_per_sec Kbytes/s)\n");
exit;Here's an example that shows how to talk to a program that must communicate via a terminal. In this case we're talking to the telnet program via a pseudo-terminal. We use the Comm package to start the telnet program and return a filehandle to the pseudo-terminal. This example sends some initial commands and then allows the user to type commands to the telnet session.
use Net::Telnet;
my($comm_pty, $host, $hostname, $passwd, $pty,
$username, @lines);
$hostname = "your_host_here";
$username = "your_name_here";
$passwd = "your_passwd_here";
## Start the telnet program so we can talk to it via a
## pseudo-terminal.
{
local $^W = 0; # Comm.pl isn't warning clean
require "Comm.pl";
&Comm::init("close_it", "interact",
"open_proc", "stty_raw", "stty_sane");
$comm_pty = &open_proc("telnet $hostname")
or die "open_proc failed";
## Unfortunately the Comm package doesn't
## return us a fully qualified filehandle. We
## must keep the filehandle Comm returned for
## its use and we must build another filehandle
## qualified with the current package for our
## use.
$pty = "main::" . $comm_pty;
}
## Obtain a new Net::Telnet object that does I/O to the
## pseudo-terminal attached to the running telnet
## program. The "Telnetmode" is "off" because we're
## not talking directly to a telnet port as we normally
## do, we're talking to a pseudo-terminal. The
## "Output_record_separator" is now a carriage-return
## because that's what you'd normally hit when you get
## done typing a line at a terminal.
$host = new Net::Telnet (Fhopen => $pty,
Timeout => 10,
Prompt => '/[%#>] $/',
Telnetmode => 0,
Output_record_separator => "\r");
## Issue some commands.
$host->login($username, $passwd);
$host->cmd("setenv DISPLAY $ENV{DISPLAY}");
print $host->cmd("who");
## Allow the user to interact with telnet program until
## they exit.
{
no strict 'subs'; # so we can refer to STDIN
local $^W = 0; # Comm.pl isn't warning clean
&stty_raw(STDIN);
&interact($comm_pty);
&stty_sane(STDIN);
&close_it($comm_pty);
}
print "Exited telnet\n";
exit;