216 lines
7.0 KiB
TeX
216 lines
7.0 KiB
TeX
\section{\module{telnetlib} ---
|
|
Telnet client}
|
|
|
|
\declaremodule{standard}{telnetlib}
|
|
\modulesynopsis{Telnet client class.}
|
|
\sectionauthor{Skip Montanaro}{skip@mojam.com}
|
|
|
|
\index{protocol!Telnet}
|
|
|
|
The \module{telnetlib} module provides a \class{Telnet} class that
|
|
implements the Telnet protocol. See \rfc{854} for details about the
|
|
protocol. In addition, it provides symbolic constants for the protocol
|
|
characters (see below), and for the telnet options. The
|
|
symbolic names of the telnet options follow the definitions in
|
|
\code{arpa/telnet.h}, with the leading \code{TELOPT_} removed. For
|
|
symbolic names of options which are traditionally not included in
|
|
\code{arpa/telnet.h}, see the module source itself.
|
|
|
|
The symbolic constants for the telnet commands are: IAC, DONT, DO,
|
|
WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data
|
|
Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT
|
|
(Are You There), EC (Erase Character), EL (Erase Line), GA (Go Ahead),
|
|
SB (Subnegotiation Begin).
|
|
|
|
|
|
\begin{classdesc}{Telnet}{\optional{host\optional{, port}}}
|
|
\class{Telnet} represents a connection to a Telnet server. The
|
|
instance is initially not connected by default; the \method{open()}
|
|
method must be used to establish a connection. Alternatively, the
|
|
host name and optional port number can be passed to the constructor,
|
|
to, in which case the connection to the server will be established
|
|
before the constructor returns.
|
|
|
|
Do not reopen an already connected instance.
|
|
|
|
This class has many \method{read_*()} methods. Note that some of them
|
|
raise \exception{EOFError} when the end of the connection is read,
|
|
because they can return an empty string for other reasons. See the
|
|
individual descriptions below.
|
|
\end{classdesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seerfc{854}{Telnet Protocol Specification}{
|
|
Definition of the Telnet protocol.}
|
|
\end{seealso}
|
|
|
|
|
|
|
|
\subsection{Telnet Objects \label{telnet-objects}}
|
|
|
|
\class{Telnet} instances have the following methods:
|
|
|
|
|
|
\begin{methoddesc}{read_until}{expected\optional{, timeout}}
|
|
Read until a given string, \var{expected}, is encountered or until
|
|
\var{timeout} seconds have passed.
|
|
|
|
When no match is found, return whatever is available instead,
|
|
possibly the empty string. Raise \exception{EOFError} if the connection
|
|
is closed and no cooked data is available.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_all}{}
|
|
Read all data until \EOF; block until connection closed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_some}{}
|
|
Read at least one byte of cooked data unless \EOF{} is hit.
|
|
Return \code{''} if \EOF{} is hit. Block if no data is immediately
|
|
available.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_very_eager}{}
|
|
Read everything that can be without blocking in I/O (eager).
|
|
|
|
Raise \exception{EOFError} if connection closed and no cooked data
|
|
available. Return \code{''} if no cooked data available otherwise.
|
|
Do not block unless in the midst of an IAC sequence.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_eager}{}
|
|
Read readily available data.
|
|
|
|
Raise \exception{EOFError} if connection closed and no cooked data
|
|
available. Return \code{''} if no cooked data available otherwise.
|
|
Do not block unless in the midst of an IAC sequence.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_lazy}{}
|
|
Process and return data already in the queues (lazy).
|
|
|
|
Raise \exception{EOFError} if connection closed and no data available.
|
|
Return \code{''} if no cooked data available otherwise. Do not block
|
|
unless in the midst of an IAC sequence.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_very_lazy}{}
|
|
Return any data available in the cooked queue (very lazy).
|
|
|
|
Raise \exception{EOFError} if connection closed and no data available.
|
|
Return \code{''} if no cooked data available otherwise. This method
|
|
never blocks.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read_sb_data}{}
|
|
Return the data collected between a SB/SE pair (suboption begin/end).
|
|
The callback should access these data when it was invoked with a
|
|
\code{SE} command. This method never blocks.
|
|
|
|
\versionadded{2.3}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{open}{host\optional{, port}}
|
|
Connect to a host.
|
|
The optional second argument is the port number, which
|
|
defaults to the standard Telnet port (23).
|
|
|
|
Do not try to reopen an already connected instance.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{msg}{msg\optional{, *args}}
|
|
Print a debug message when the debug level is \code{>} 0.
|
|
If extra arguments are present, they are substituted in the
|
|
message using the standard string formatting operator.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{set_debuglevel}{debuglevel}
|
|
Set the debug level. The higher the value of \var{debuglevel}, the
|
|
more debug output you get (on \code{sys.stdout}).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Close the connection.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get_socket}{}
|
|
Return the socket object used internally.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{fileno}{}
|
|
Return the file descriptor of the socket object used internally.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{write}{buffer}
|
|
Write a string to the socket, doubling any IAC characters.
|
|
This can block if the connection is blocked. May raise
|
|
\exception{socket.error} if the connection is closed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{interact}{}
|
|
Interaction function, emulates a very dumb Telnet client.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{mt_interact}{}
|
|
Multithreaded version of \method{interact()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{expect}{list\optional{, timeout}}
|
|
Read until one from a list of a regular expressions matches.
|
|
|
|
The first argument is a list of regular expressions, either
|
|
compiled (\class{re.RegexObject} instances) or uncompiled (strings).
|
|
The optional second argument is a timeout, in seconds; the default
|
|
is to block indefinitely.
|
|
|
|
Return a tuple of three items: the index in the list of the
|
|
first regular expression that matches; the match object
|
|
returned; and the text read up till and including the match.
|
|
|
|
If end of file is found and no text was read, raise
|
|
\exception{EOFError}. Otherwise, when nothing matches, return
|
|
\code{(-1, None, \var{text})} where \var{text} is the text received so
|
|
far (may be the empty string if a timeout happened).
|
|
|
|
If a regular expression ends with a greedy match (such as \regexp{.*})
|
|
or if more than one expression can match the same input, the
|
|
results are indeterministic, and may depend on the I/O timing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{set_option_negotiation_callback}{callback}
|
|
Each time a telnet option is read on the input flow, this
|
|
\var{callback} (if set) is called with the following parameters :
|
|
callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other
|
|
action is done afterwards by telnetlib.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{Telnet Example \label{telnet-example}}
|
|
\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
|
|
|
|
A simple example illustrating typical use:
|
|
|
|
\begin{verbatim}
|
|
import getpass
|
|
import sys
|
|
import telnetlib
|
|
|
|
HOST = "localhost"
|
|
user = raw_input("Enter your remote account: ")
|
|
password = getpass.getpass()
|
|
|
|
tn = telnetlib.Telnet(HOST)
|
|
|
|
tn.read_until("login: ")
|
|
tn.write(user + "\n")
|
|
if password:
|
|
tn.read_until("Password: ")
|
|
tn.write(password + "\n")
|
|
|
|
tn.write("ls\n")
|
|
tn.write("exit\n")
|
|
|
|
print tn.read_all()
|
|
\end{verbatim}
|