Lib/telnetlib.py

   1 r"""TELNET client class.
   2
   3 Based on RFC 854: TELNET Protocol Specification, by J. Postel and
   4 J. Reynolds
   5
   6 Example:
   7
   8 >>> from telnetlib import Telnet
   9 >>> tn = Telnet('www.python.org', 79)   # connect to finger port
  10 >>> tn.write('guido\r\n')
  11 >>> print tn.read_all()
  12 Login       Name               TTY         Idle    When    Where
  13 guido    Guido van Rossum      pts/2        <Dec  2 11:10> snag.cnri.reston..
  14
  15 >>>
  16
  17 Note that read_all() won't read until eof -- it just reads some data
  18 -- but it guarantees to read at least one byte unless EOF is hit.
  19
  20 It is possible to pass a Telnet object to select.select() in order to
  21 wait until more data is available.  Note that in this case,
  22 read_eager() may return '' even if there was data on the socket,
  23 because the protocol negotiation may have eaten the data.  This is why
  24 EOFError is needed in some cases to distinguish between "no data" and
  25 "connection closed" (since the socket also appears ready for reading
  26 when it is closed).
  27
  28 To do:
  29 - option negotiation
  30 - timeout should be intrinsic to the connection object instead of an
  31   option on one of the read calls only
  32
  33 """
  34
  35
  36 # Imported modules
  37 import sys
  38 import socket
  39 import select
  40
  41 __all__ = ["Telnet"]
  42
  43 # Tunable parameters
  44 DEBUGLEVEL = 0
  45
  46 # Telnet protocol defaults
  47 TELNET_PORT = 23
  48
  49 # Telnet protocol characters (don't change)
  50 IAC  = chr(255) # "Interpret As Command"
  51 DONT = chr(254)
  52 DO   = chr(253)
  53 WONT = chr(252)
  54 WILL = chr(251)
  55 theNULL = chr(0)
  56
  57 SE  = chr(240)  # Subnegotiation End
  58 NOP = chr(241)  # No Operation
  59 DM  = chr(242)  # Data Mark
  60 BRK = chr(243)  # Break
  61 IP  = chr(244)  # Interrupt process
  62 AO  = chr(245)  # Abort output
  63 AYT = chr(246)  # Are You There
  64 EC  = chr(247)  # Erase Character
  65 EL  = chr(248)  # Erase Line
  66 GA  = chr(249)  # Go Ahead
  67 SB =  chr(250)  # Subnegotiation Begin
  68
  69
  70 # Telnet protocol options code (don't change)
  71 # These ones all come from arpa/telnet.h
  72 BINARY = chr(0) # 8-bit data path
  73 ECHO = chr(1) # echo
  74 RCP = chr(2) # prepare to reconnect
  75 SGA = chr(3) # suppress go ahead
  76 NAMS = chr(4) # approximate message size
  77 STATUS = chr(5) # give status
  78 TM = chr(6) # timing mark
  79 RCTE = chr(7) # remote controlled transmission and echo
  80 NAOL = chr(8) # negotiate about output line width
  81 NAOP = chr(9) # negotiate about output page size
  82 NAOCRD = chr(10) # negotiate about CR disposition
  83 NAOHTS = chr(11) # negotiate about horizontal tabstops
  84 NAOHTD = chr(12) # negotiate about horizontal tab disposition
  85 NAOFFD = chr(13) # negotiate about formfeed disposition
  86 NAOVTS = chr(14) # negotiate about vertical tab stops
  87 NAOVTD = chr(15) # negotiate about vertical tab disposition
  88 NAOLFD = chr(16) # negotiate about output LF disposition
  89 XASCII = chr(17) # extended ascii character set
  90 LOGOUT = chr(18) # force logout
  91 BM = chr(19) # byte macro
  92 DET = chr(20) # data entry terminal
  93 SUPDUP = chr(21) # supdup protocol
  94 SUPDUPOUTPUT = chr(22) # supdup output
  95 SNDLOC = chr(23) # send location
  96 TTYPE = chr(24) # terminal type
  97 EOR = chr(25) # end or record
  98 TUID = chr(26) # TACACS user identification
  99 OUTMRK = chr(27) # output marking
 100 TTYLOC = chr(28) # terminal location number
 101 VT3270REGIME = chr(29) # 3270 regime
 102 X3PAD = chr(30) # X.3 PAD
 103 NAWS = chr(31) # window size
 104 TSPEED = chr(32) # terminal speed
 105 LFLOW = chr(33) # remote flow control
 106 LINEMODE = chr(34) # Linemode option
 107 XDISPLOC = chr(35) # X Display Location
 108 OLD_ENVIRON = chr(36) # Old - Environment variables
 109 AUTHENTICATION = chr(37) # Authenticate
 110 ENCRYPT = chr(38) # Encryption option
 111 NEW_ENVIRON = chr(39) # New - Environment variables
 112 # the following ones come from
 113 # http://www.iana.org/assignments/telnet-options
 114 # Unfortunately, that document does not assign identifiers
 115 # to all of them, so we are making them up
 116 TN3270E = chr(40) # TN3270E
 117 XAUTH = chr(41) # XAUTH
 118 CHARSET = chr(42) # CHARSET
 119 RSP = chr(43) # Telnet Remote Serial Port
 120 COM_PORT_OPTION = chr(44) # Com Port Control Option
 121 SUPPRESS_LOCAL_ECHO = chr(45) # Telnet Suppress Local Echo
 122 TLS = chr(46) # Telnet Start TLS
 123 KERMIT = chr(47) # KERMIT
 124 SEND_URL = chr(48) # SEND-URL
 125 FORWARD_X = chr(49) # FORWARD_X
 126 PRAGMA_LOGON = chr(138) # TELOPT PRAGMA LOGON
 127 SSPI_LOGON = chr(139) # TELOPT SSPI LOGON
 128 PRAGMA_HEARTBEAT = chr(140) # TELOPT PRAGMA HEARTBEAT
 129 EXOPL = chr(255) # Extended-Options-List
 130 NOOPT = chr(0)
 131
 132 class Telnet:
 133
 134     """Telnet interface class.
 135
 136     An instance of this class represents a connection to a telnet
 137     server.  The instance is initially not connected; the open()
 138     method must be used to establish a connection.  Alternatively, the
 139     host name and optional port number can be passed to the
 140     constructor, too.
 141
 142     Don't try to reopen an already connected instance.
 143
 144     This class has many read_*() methods.  Note that some of them
 145     raise EOFError when the end of the connection is read, because
 146     they can return an empty string for other reasons.  See the
 147     individual doc strings.
 148
 149     read_until(expected, [timeout])
 150         Read until the expected string has been seen, or a timeout is
 151         hit (default is no timeout); may block.
 152
 153     read_all()
 154         Read all data until EOF; may block.
 155
 156     read_some()
 157         Read at least one byte or EOF; may block.
 158
 159     read_very_eager()
 160         Read all data available already queued or on the socket,
 161         without blocking.
 162
 163     read_eager()
 164         Read either data already queued or some data available on the
 165         socket, without blocking.
 166
 167     read_lazy()
 168         Read all data in the raw queue (processing it first), without
 169         doing any socket I/O.
 170
 171     read_very_lazy()
 172         Reads all data in the cooked queue, without doing any socket
 173         I/O.
 174
 175     read_sb_data()
 176         Reads available data between SB ... SE sequence. Don't block.
 177
 178     set_option_negotiation_callback(callback)
 179         Each time a telnet option is read on the input flow, this callback
 180         (if set) is called with the following parameters :
 181         callback(telnet socket, command, option)
 182             option will be chr(0) when there is no option.
 183         No other action is done afterwards by telnetlib.
 184
 185     """
 186
 187     def __init__(self, host=None, port=0,
 188                  timeout=socket._GLOBAL_DEFAULT_TIMEOUT):
 189         """Constructor.
 190
 191         When called without arguments, create an unconnected instance.
 192         With a hostname argument, it connects the instance; port number
 193         and timeout are optional.
 194         """
 195         self.debuglevel = DEBUGLEVEL
 196         self.host = host
 197         self.port = port
 198         self.timeout = timeout
 199         self.sock = None
 200         self.rawq = ''
 201         self.irawq = 0
 202         self.cookedq = ''
 203         self.eof = 0
 204         self.iacseq = '' # Buffer for IAC sequence.
 205         self.sb = 0 # flag for SB and SE sequence.
 206         self.sbdataq = ''
 207         self.option_callback = None
 208         if host is not None:
 209             self.open(host, port, timeout)
 210
 211     def open(self, host, port=0, timeout=socket._GLOBAL_DEFAULT_TIMEOUT):
 212         """Connect to a host.
 213
 214         The optional second argument is the port number, which
 215         defaults to the standard telnet port (23).
 216
 217         Don't try to reopen an already connected instance.
 218         """
 219         self.eof = 0
 220         if not port:
 221             port = TELNET_PORT
 222         self.host = host
 223         self.port = port
 224         self.timeout = timeout
 225         self.sock = socket.create_connection((host, port), timeout)
 226
 227     def __del__(self):
 228         """Destructor -- close the connection."""
 229         self.close()
 230
 231     def msg(self, msg, *args):
 232         """Print a debug message, when the debug level is > 0.
 233
 234         If extra arguments are present, they are substituted in the
 235         message using the standard string formatting operator.
 236
 237         """
 238         if self.debuglevel > 0:
 239             print 'Telnet(%s,%d):' % (self.host, self.port),
 240             if args:
 241                 print msg % args
 242             else:
 243                 print msg
 244
 245     def set_debuglevel(self, debuglevel):
 246         """Set the debug level.
 247
 248         The higher it is, the more debug output you get (on sys.stdout).
 249
 250         """
 251         self.debuglevel = debuglevel
 252
 253     def close(self):
 254         """Close the connection."""
 255         if self.sock:
 256             self.sock.close()
 257         self.sock = 0
 258         self.eof = 1
 259         self.iacseq = ''
 260         self.sb = 0
 261
 262     def get_socket(self):
 263         """Return the socket object used internally."""
 264         return self.sock
 265
 266     def fileno(self):
 267         """Return the fileno() of the socket object used internally."""
 268         return self.sock.fileno()
 269
 270     def write(self, buffer):
 271         """Write a string to the socket, doubling any IAC characters.
 272
 273         Can block if the connection is blocked.  May raise
 274         socket.error if the connection is closed.
 275
 276         """
 277         if IAC in buffer:
 278             buffer = buffer.replace(IAC, IAC+IAC)
 279         self.msg("send %r", buffer)
 280         self.sock.sendall(buffer)
 281
 282     def read_until(self, match, timeout=None):
 283         """Read until a given string is encountered or until timeout.
 284
 285         When no match is found, return whatever is available instead,
 286         possibly the empty string.  Raise EOFError if the connection
 287         is closed and no cooked data is available.
 288
 289         """
 290         n = len(match)
 291         self.process_rawq()
 292         i = self.cookedq.find(match)
 293         if i >= 0:
 294             i = i+n
 295             buf = self.cookedq[:i]
 296             self.cookedq = self.cookedq[i:]
 297             return buf
 298         s_reply = ([self], [], [])
 299         s_args = s_reply
 300         if timeout is not None:
 301             s_args = s_args + (timeout,)
 302             from time import time
 303             time_start = time()
 304         while not self.eof and select.select(*s_args) == s_reply:
 305             i = max(0, len(self.cookedq)-n)
 306             self.fill_rawq()
 307             self.process_rawq()
 308             i = self.cookedq.find(match, i)
 309             if i >= 0:
 310                 i = i+n
 311                 buf = self.cookedq[:i]
 312                 self.cookedq = self.cookedq[i:]
 313                 return buf
 314             if timeout is not None:
 315                 elapsed = time() - time_start
 316                 if elapsed >= timeout:
 317                     break
 318                 s_args = s_reply + (timeout-elapsed,)
 319         return self.read_very_lazy()
 320
 321     def read_all(self):
 322         """Read all data until EOF; block until connection closed."""
 323         self.process_rawq()
 324         while not self.eof:
 325             self.fill_rawq()
 326             self.process_rawq()
 327         buf = self.cookedq
 328         self.cookedq = ''
 329         return buf
 330
 331     def read_some(self):
 332         """Read at least one byte of cooked data unless EOF is hit.
 333
 334         Return '' if EOF is hit.  Block if no data is immediately
 335         available.
 336
 337         """
 338         self.process_rawq()
 339         while not self.cookedq and not self.eof:
 340             self.fill_rawq()
 341             self.process_rawq()
 342         buf = self.cookedq
 343         self.cookedq = ''
 344         return buf
 345
 346     def read_very_eager(self):
 347         """Read everything that's possible without blocking in I/O (eager).
 348
 349         Raise EOFError if connection closed and no cooked data
 350         available.  Return '' if no cooked data available otherwise.
 351         Don't block unless in the midst of an IAC sequence.
 352
 353         """
 354         self.process_rawq()
 355         while not self.eof and self.sock_avail():
 356             self.fill_rawq()
 357             self.process_rawq()
 358         return self.read_very_lazy()
 359
 360     def read_eager(self):
 361         """Read readily available data.
 362
 363         Raise EOFError if connection closed and no cooked data
 364         available.  Return '' if no cooked data available otherwise.
 365         Don't block unless in the midst of an IAC sequence.
 366
 367         """
 368         self.process_rawq()
 369         while not self.cookedq and not self.eof and self.sock_avail():
 370             self.fill_rawq()
 371             self.process_rawq()
 372         return self.read_very_lazy()
 373
 374     def read_lazy(self):
 375         """Process and return data that's already in the queues (lazy).
 376
 377         Raise EOFError if connection closed and no data available.
 378         Return '' if no cooked data available otherwise.  Don't block
 379         unless in the midst of an IAC sequence.
 380
 381         """
 382         self.process_rawq()
 383         return self.read_very_lazy()
 384
 385     def read_very_lazy(self):
 386         """Return any data available in the cooked queue (very lazy).
 387
 388         Raise EOFError if connection closed and no data available.
 389         Return '' if no cooked data available otherwise.  Don't block.
 390
 391         """
 392         buf = self.cookedq
 393         self.cookedq = ''
 394         if not buf and self.eof and not self.rawq:
 395             raise EOFError, 'telnet connection closed'
 396         return buf
 397
 398     def read_sb_data(self):
 399         """Return any data available in the SB ... SE queue.
 400
 401         Return '' if no SB ... SE available. Should only be called
 402         after seeing a SB or SE command. When a new SB command is
 403         found, old unread SB data will be discarded. Don't block.
 404
 405         """
 406         buf = self.sbdataq
 407         self.sbdataq = ''
 408         return buf
 409
 410     def set_option_negotiation_callback(self, callback):
 411         """Provide a callback function called after each receipt of a telnet option."""
 412         self.option_callback = callback
 413
 414     def process_rawq(self):
 415         """Transfer from raw queue to cooked queue.
 416
 417         Set self.eof when connection is closed.  Don't block unless in
 418         the midst of an IAC sequence.
 419
 420         """
 421         buf = ['', '']
 422         try:
 423             while self.rawq:
 424                 c = self.rawq_getchar()
 425                 if not self.iacseq:
 426                     if c == theNULL:
 427                         continue
 428                     if c == "\021":
 429                         continue
 430                     if c != IAC:
 431                         buf[self.sb] = buf[self.sb] + c
 432                         continue
 433                     else:
 434                         self.iacseq += c
 435                 elif len(self.iacseq) == 1:
 436                     # 'IAC: IAC CMD [OPTION only for WILL/WONT/DO/DONT]'
 437                     if c in (DO, DONT, WILL, WONT):
 438                         self.iacseq += c
 439                         continue
 440
 441                     self.iacseq = ''
 442                     if c == IAC:
 443                         buf[self.sb] = buf[self.sb] + c
 444                     else:
 445                         if c == SB: # SB ... SE start.
 446                             self.sb = 1
 447                             self.sbdataq = ''
 448                         elif c == SE:
 449                             self.sb = 0
 450                             self.sbdataq = self.sbdataq + buf[1]
 451                             buf[1] = ''
 452                         if self.option_callback:
 453                             # Callback is supposed to look into
 454                             # the sbdataq
 455                             self.option_callback(self.sock, c, NOOPT)
 456                         else:
 457                             # We can't offer automatic processing of
 458                             # suboptions. Alas, we should not get any
 459                             # unless we did a WILL/DO before.
 460                             self.msg('IAC %d not recognized' % ord(c))
 461                 elif len(self.iacseq) == 2:
 462                     cmd = self.iacseq[1]
 463                     self.iacseq = ''
 464                     opt = c
 465                     if cmd in (DO, DONT):
 466                         self.msg('IAC %s %d',
 467                             cmd == DO and 'DO' or 'DONT', ord(opt))
 468                         if self.option_callback:
 469                             self.option_callback(self.sock, cmd, opt)
 470                         else:
 471                             self.sock.sendall(IAC + WONT + opt)
 472                     elif cmd in (WILL, WONT):
 473                         self.msg('IAC %s %d',
 474                             cmd == WILL and 'WILL' or 'WONT', ord(opt))
 475                         if self.option_callback:
 476                             self.option_callback(self.sock, cmd, opt)
 477                         else:
 478                             self.sock.sendall(IAC + DONT + opt)
 479         except EOFError: # raised by self.rawq_getchar()
 480             self.iacseq = '' # Reset on EOF
 481             self.sb = 0
 482             pass
 483         self.cookedq = self.cookedq + buf[0]
 484         self.sbdataq = self.sbdataq + buf[1]
 485
 486     def rawq_getchar(self):
 487         """Get next char from raw queue.
 488
 489         Block if no data is immediately available.  Raise EOFError
 490         when connection is closed.
 491
 492         """
 493         if not self.rawq:
 494             self.fill_rawq()
 495             if self.eof:
 496                 raise EOFError
 497         c = self.rawq[self.irawq]
 498         self.irawq = self.irawq + 1
 499         if self.irawq >= len(self.rawq):
 500             self.rawq = ''
 501             self.irawq = 0
 502         return c
 503
 504     def fill_rawq(self):
 505         """Fill raw queue from exactly one recv() system call.
 506
 507         Block if no data is immediately available.  Set self.eof when
 508         connection is closed.
 509
 510         """
 511         if self.irawq >= len(self.rawq):
 512             self.rawq = ''
 513             self.irawq = 0
 514         # The buffer size should be fairly small so as to avoid quadratic
 515         # behavior in process_rawq() above
 516         buf = self.sock.recv(50)
 517         self.msg("recv %r", buf)
 518         self.eof = (not buf)
 519         self.rawq = self.rawq + buf
 520
 521     def sock_avail(self):
 522         """Test whether data is available on the socket."""
 523         return select.select([self], [], [], 0) == ([self], [], [])
 524
 525     def interact(self):
 526         """Interaction function, emulates a very dumb telnet client."""
 527         if sys.platform == "win32":
 528             self.mt_interact()
 529             return
 530         while 1:
 531             rfd, wfd, xfd = select.select([self, sys.stdin], [], [])
 532             if self in rfd:
 533                 try:
 534                     text = self.read_eager()
 535                 except EOFError:
 536                     print '*** Connection closed by remote host ***'
 537                     break
 538                 if text:
 539                     sys.stdout.write(text)
 540                     sys.stdout.flush()
 541             if sys.stdin in rfd:
 542                 line = sys.stdin.readline()
 543                 if not line:
 544                     break
 545                 self.write(line)
 546
 547     def mt_interact(self):
 548         """Multithreaded version of interact()."""
 549         import thread
 550         thread.start_new_thread(self.listener, ())
 551         while 1:
 552             line = sys.stdin.readline()
 553             if not line:
 554                 break
 555             self.write(line)
 556
 557     def listener(self):
 558         """Helper for mt_interact() -- this executes in the other thread."""
 559         while 1:
 560             try:
 561                 data = self.read_eager()
 562             except EOFError:
 563                 print '*** Connection closed by remote host ***'
 564                 return
 565             if data:
 566                 sys.stdout.write(data)
 567             else:
 568                 sys.stdout.flush()
 569
 570     def expect(self, list, timeout=None):
 571         """Read until one from a list of a regular expressions matches.
 572
 573         The first argument is a list of regular expressions, either
 574         compiled (re.RegexObject instances) or uncompiled (strings).
 575         The optional second argument is a timeout, in seconds; default
 576         is no timeout.
 577
 578         Return a tuple of three items: the index in the list of the
 579         first regular expression that matches; the match object
 580         returned; and the text read up till and including the match.
 581
 582         If EOF is read and no text was read, raise EOFError.
 583         Otherwise, when nothing matches, return (-1, None, text) where
 584         text is the text received so far (may be the empty string if a
 585         timeout happened).
 586
 587         If a regular expression ends with a greedy match (e.g. '.*')
 588         or if more than one expression can match the same input, the
 589         results are undeterministic, and may depend on the I/O timing.
 590
 591         """
 592         re = None
 593         list = list[:]
 594         indices = range(len(list))
 595         for i in indices:
 596             if not hasattr(list[i], "search"):
 597                 if not re: import re
 598                 list[i] = re.compile(list[i])
 599         if timeout is not None:
 600             from time import time
 601             time_start = time()
 602         while 1:
 603             self.process_rawq()
 604             for i in indices:
 605                 m = list[i].search(self.cookedq)
 606                 if m:
 607                     e = m.end()
 608                     text = self.cookedq[:e]
 609                     self.cookedq = self.cookedq[e:]
 610                     return (i, m, text)
 611             if self.eof:
 612                 break
 613             if timeout is not None:
 614                 elapsed = time() - time_start
 615                 if elapsed >= timeout:
 616                     break
 617                 s_args = ([self.fileno()], [], [], timeout-elapsed)
 618                 r, w, x = select.select(*s_args)
 619                 if not r:
 620                     break
 621             self.fill_rawq()
 622         text = self.read_very_lazy()
 623         if not text and self.eof:
 624             raise EOFError
 625         return (-1, None, text)
 626
 627
 628 def test():
 629     """Test program for telnetlib.
 630
 631     Usage: python telnetlib.py [-d] ... [host [port]]
 632
 633     Default host is localhost; default port is 23.
 634
 635     """
 636     debuglevel = 0
 637     while sys.argv[1:] and sys.argv[1] == '-d':
 638         debuglevel = debuglevel+1
 639         del sys.argv[1]
 640     host = 'localhost'
 641     if sys.argv[1:]:
 642         host = sys.argv[1]
 643     port = 0
 644     if sys.argv[2:]:
 645         portstr = sys.argv[2]
 646         try:
 647             port = int(portstr)
 648         except ValueError:
 649             port = socket.getservbyname(portstr, 'tcp')
 650     tn = Telnet()
 651     tn.set_debuglevel(debuglevel)
 652     tn.open(host, port, timeout=0.5)
 653     tn.interact()
 654     tn.close()
 655
 656 if __name__ == '__main__':
 657     test()