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, timeout=None):
 188         """Constructor.
 189
 190         When called without arguments, create an unconnected instance.
 191         With a hostname argument, it connects the instance; a port
 192         number is optional.
 193
 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=None):
 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         """
 220         self.eof = 0
 221         if not port:
 222             port = TELNET_PORT
 223         self.host = host
 224         self.port = port
 225         if timeout is not None:
 226             self.timeout = timeout
 227         self.sock = socket.create_connection((host, port), self.timeout)
 228
 229     def __del__(self):
 230         """Destructor -- close the connection."""
 231         self.close()
 232
 233     def msg(self, msg, *args):
 234         """Print a debug message, when the debug level is > 0.
 235
 236         If extra arguments are present, they are substituted in the
 237         message using the standard string formatting operator.
 238
 239         """
 240         if self.debuglevel > 0:
 241             print 'Telnet(%s,%d):' % (self.host, self.port),
 242             if args:
 243                 print msg % args
 244             else:
 245                 print msg
 246
 247     def set_debuglevel(self, debuglevel):
 248         """Set the debug level.
 249
 250         The higher it is, the more debug output you get (on sys.stdout).
 251
 252         """
 253         self.debuglevel = debuglevel
 254
 255     def close(self):
 256         """Close the connection."""
 257         if self.sock:
 258             self.sock.close()
 259         self.sock = 0
 260         self.eof = 1
 261         self.iacseq = ''
 262         self.sb = 0
 263
 264     def get_socket(self):
 265         """Return the socket object used internally."""
 266         return self.sock
 267
 268     def fileno(self):
 269         """Return the fileno() of the socket object used internally."""
 270         return self.sock.fileno()
 271
 272     def write(self, buffer):
 273         """Write a string to the socket, doubling any IAC characters.
 274
 275         Can block if the connection is blocked.  May raise
 276         socket.error if the connection is closed.
 277
 278         """
 279         if IAC in buffer:
 280             buffer = buffer.replace(IAC, IAC+IAC)
 281         self.msg("send %r", buffer)
 282         self.sock.sendall(buffer)
 283
 284     def read_until(self, match, timeout=None):
 285         """Read until a given string is encountered or until timeout.
 286
 287         When no match is found, return whatever is available instead,
 288         possibly the empty string.  Raise EOFError if the connection
 289         is closed and no cooked data is available.
 290
 291         """
 292         n = len(match)
 293         self.process_rawq()
 294         i = self.cookedq.find(match)
 295         if i >= 0:
 296             i = i+n
 297             buf = self.cookedq[:i]
 298             self.cookedq = self.cookedq[i:]
 299             return buf
 300         s_reply = ([self], [], [])
 301         s_args = s_reply
 302         if timeout is not None:
 303             s_args = s_args + (timeout,)
 304             from time import time
 305             time_start = time()
 306         while not self.eof and select.select(*s_args) == s_reply:
 307             i = max(0, len(self.cookedq)-n)
 308             self.fill_rawq()
 309             self.process_rawq()
 310             i = self.cookedq.find(match, i)
 311             if i >= 0:
 312                 i = i+n
 313                 buf = self.cookedq[:i]
 314                 self.cookedq = self.cookedq[i:]
 315                 return buf
 316             if timeout is not None:
 317                 elapsed = time() - time_start
 318                 if elapsed >= timeout:
 319                     break
 320                 s_args = s_reply + (timeout-elapsed,)
 321         return self.read_very_lazy()
 322
 323     def read_all(self):
 324         """Read all data until EOF; block until connection closed."""
 325         self.process_rawq()
 326         while not self.eof:
 327             self.fill_rawq()
 328             self.process_rawq()
 329         buf = self.cookedq
 330         self.cookedq = ''
 331         return buf
 332
 333     def read_some(self):
 334         """Read at least one byte of cooked data unless EOF is hit.
 335
 336         Return '' if EOF is hit.  Block if no data is immediately
 337         available.
 338
 339         """
 340         self.process_rawq()
 341         while not self.cookedq and not self.eof:
 342             self.fill_rawq()
 343             self.process_rawq()
 344         buf = self.cookedq
 345         self.cookedq = ''
 346         return buf
 347
 348     def read_very_eager(self):
 349         """Read everything that's possible without blocking in I/O (eager).
 350
 351         Raise EOFError if connection closed and no cooked data
 352         available.  Return '' if no cooked data available otherwise.
 353         Don't block unless in the midst of an IAC sequence.
 354
 355         """
 356         self.process_rawq()
 357         while not self.eof and self.sock_avail():
 358             self.fill_rawq()
 359             self.process_rawq()
 360         return self.read_very_lazy()
 361
 362     def read_eager(self):
 363         """Read readily available data.
 364
 365         Raise EOFError if connection closed and no cooked data
 366         available.  Return '' if no cooked data available otherwise.
 367         Don't block unless in the midst of an IAC sequence.
 368
 369         """
 370         self.process_rawq()
 371         while not self.cookedq and not self.eof and self.sock_avail():
 372             self.fill_rawq()
 373             self.process_rawq()
 374         return self.read_very_lazy()
 375
 376     def read_lazy(self):
 377         """Process and return data that's already in the queues (lazy).
 378
 379         Raise EOFError if connection closed and no data available.
 380         Return '' if no cooked data available otherwise.  Don't block
 381         unless in the midst of an IAC sequence.
 382
 383         """
 384         self.process_rawq()
 385         return self.read_very_lazy()
 386
 387     def read_very_lazy(self):
 388         """Return any data available in the cooked queue (very lazy).
 389
 390         Raise EOFError if connection closed and no data available.
 391         Return '' if no cooked data available otherwise.  Don't block.
 392
 393         """
 394         buf = self.cookedq
 395         self.cookedq = ''
 396         if not buf and self.eof and not self.rawq:
 397             raise EOFError, 'telnet connection closed'
 398         return buf
 399
 400     def read_sb_data(self):
 401         """Return any data available in the SB ... SE queue.
 402
 403         Return '' if no SB ... SE available. Should only be called
 404         after seeing a SB or SE command. When a new SB command is
 405         found, old unread SB data will be discarded. Don't block.
 406
 407         """
 408         buf = self.sbdataq
 409         self.sbdataq = ''
 410         return buf
 411
 412     def set_option_negotiation_callback(self, callback):
 413         """Provide a callback function called after each receipt of a telnet option."""
 414         self.option_callback = callback
 415
 416     def process_rawq(self):
 417         """Transfer from raw queue to cooked queue.
 418
 419         Set self.eof when connection is closed.  Don't block unless in
 420         the midst of an IAC sequence.
 421
 422         """
 423         buf = ['', '']
 424         try:
 425             while self.rawq:
 426                 c = self.rawq_getchar()
 427                 if not self.iacseq:
 428                     if c == theNULL:
 429                         continue
 430                     if c == "\021":
 431                         continue
 432                     if c != IAC:
 433                         buf[self.sb] = buf[self.sb] + c
 434                         continue
 435                     else:
 436                         self.iacseq += c
 437                 elif len(self.iacseq) == 1:
 438                     # 'IAC: IAC CMD [OPTION only for WILL/WONT/DO/DONT]'
 439                     if c in (DO, DONT, WILL, WONT):
 440                         self.iacseq += c
 441                         continue
 442
 443                     self.iacseq = ''
 444                     if c == IAC:
 445                         buf[self.sb] = buf[self.sb] + c
 446                     else:
 447                         if c == SB: # SB ... SE start.
 448                             self.sb = 1
 449                             self.sbdataq = ''
 450                         elif c == SE:
 451                             self.sb = 0
 452                             self.sbdataq = self.sbdataq + buf[1]
 453                             buf[1] = ''
 454                         if self.option_callback:
 455                             # Callback is supposed to look into
 456                             # the sbdataq
 457                             self.option_callback(self.sock, c, NOOPT)
 458                         else:
 459                             # We can't offer automatic processing of
 460                             # suboptions. Alas, we should not get any
 461                             # unless we did a WILL/DO before.
 462                             self.msg('IAC %d not recognized' % ord(c))
 463                 elif len(self.iacseq) == 2:
 464                     cmd = self.iacseq[1]
 465                     self.iacseq = ''
 466                     opt = c
 467                     if cmd in (DO, DONT):
 468                         self.msg('IAC %s %d',
 469                             cmd == DO and 'DO' or 'DONT', ord(opt))
 470                         if self.option_callback:
 471                             self.option_callback(self.sock, cmd, opt)
 472                         else:
 473                             self.sock.sendall(IAC + WONT + opt)
 474                     elif cmd in (WILL, WONT):
 475                         self.msg('IAC %s %d',
 476                             cmd == WILL and 'WILL' or 'WONT', ord(opt))
 477                         if self.option_callback:
 478                             self.option_callback(self.sock, cmd, opt)
 479                         else:
 480                             self.sock.sendall(IAC + DONT + opt)
 481         except EOFError: # raised by self.rawq_getchar()
 482             self.iacseq = '' # Reset on EOF
 483             self.sb = 0
 484             pass
 485         self.cookedq = self.cookedq + buf[0]
 486         self.sbdataq = self.sbdataq + buf[1]
 487
 488     def rawq_getchar(self):
 489         """Get next char from raw queue.
 490
 491         Block if no data is immediately available.  Raise EOFError
 492         when connection is closed.
 493
 494         """
 495         if not self.rawq:
 496             self.fill_rawq()
 497             if self.eof:
 498                 raise EOFError
 499         c = self.rawq[self.irawq]
 500         self.irawq = self.irawq + 1
 501         if self.irawq >= len(self.rawq):
 502             self.rawq = ''
 503             self.irawq = 0
 504         return c
 505
 506     def fill_rawq(self):
 507         """Fill raw queue from exactly one recv() system call.
 508
 509         Block if no data is immediately available.  Set self.eof when
 510         connection is closed.
 511
 512         """
 513         if self.irawq >= len(self.rawq):
 514             self.rawq = ''
 515             self.irawq = 0
 516         # The buffer size should be fairly small so as to avoid quadratic
 517         # behavior in process_rawq() above
 518         buf = self.sock.recv(50)
 519         self.msg("recv %r", buf)
 520         self.eof = (not buf)
 521         self.rawq = self.rawq + buf
 522
 523     def sock_avail(self):
 524         """Test whether data is available on the socket."""
 525         return select.select([self], [], [], 0) == ([self], [], [])
 526
 527     def interact(self):
 528         """Interaction function, emulates a very dumb telnet client."""
 529         if sys.platform == "win32":
 530             self.mt_interact()
 531             return
 532         while 1:
 533             rfd, wfd, xfd = select.select([self, sys.stdin], [], [])
 534             if self in rfd:
 535                 try:
 536                     text = self.read_eager()
 537                 except EOFError:
 538                     print '*** Connection closed by remote host ***'
 539                     break
 540                 if text:
 541                     sys.stdout.write(text)
 542                     sys.stdout.flush()
 543             if sys.stdin in rfd:
 544                 line = sys.stdin.readline()
 545                 if not line:
 546                     break
 547                 self.write(line)
 548
 549     def mt_interact(self):
 550         """Multithreaded version of interact()."""
 551         import thread
 552         thread.start_new_thread(self.listener, ())
 553         while 1:
 554             line = sys.stdin.readline()
 555             if not line:
 556                 break
 557             self.write(line)
 558
 559     def listener(self):
 560         """Helper for mt_interact() -- this executes in the other thread."""
 561         while 1:
 562             try:
 563                 data = self.read_eager()
 564             except EOFError:
 565                 print '*** Connection closed by remote host ***'
 566                 return
 567             if data:
 568                 sys.stdout.write(data)
 569             else:
 570                 sys.stdout.flush()
 571
 572     def expect(self, list, timeout=None):
 573         """Read until one from a list of a regular expressions matches.
 574
 575         The first argument is a list of regular expressions, either
 576         compiled (re.RegexObject instances) or uncompiled (strings).
 577         The optional second argument is a timeout, in seconds; default
 578         is no timeout.
 579
 580         Return a tuple of three items: the index in the list of the
 581         first regular expression that matches; the match object
 582         returned; and the text read up till and including the match.
 583
 584         If EOF is read and no text was read, raise EOFError.
 585         Otherwise, when nothing matches, return (-1, None, text) where
 586         text is the text received so far (may be the empty string if a
 587         timeout happened).
 588
 589         If a regular expression ends with a greedy match (e.g. '.*')
 590         or if more than one expression can match the same input, the
 591         results are undeterministic, and may depend on the I/O timing.
 592
 593         """
 594         re = None
 595         list = list[:]
 596         indices = range(len(list))
 597         for i in indices:
 598             if not hasattr(list[i], "search"):
 599                 if not re: import re
 600                 list[i] = re.compile(list[i])
 601         if timeout is not None:
 602             from time import time
 603             time_start = time()
 604         while 1:
 605             self.process_rawq()
 606             for i in indices:
 607                 m = list[i].search(self.cookedq)
 608                 if m:
 609                     e = m.end()
 610                     text = self.cookedq[:e]
 611                     self.cookedq = self.cookedq[e:]
 612                     return (i, m, text)
 613             if self.eof:
 614                 break
 615             if timeout is not None:
 616                 elapsed = time() - time_start
 617                 if elapsed >= timeout:
 618                     break
 619                 s_args = ([self.fileno()], [], [], timeout-elapsed)
 620                 r, w, x = select.select(*s_args)
 621                 if not r:
 622                     break
 623             self.fill_rawq()
 624         text = self.read_very_lazy()
 625         if not text and self.eof:
 626             raise EOFError
 627         return (-1, None, text)
 628
 629
 630 def test():
 631     """Test program for telnetlib.
 632
 633     Usage: python telnetlib.py [-d] ... [host [port]]
 634
 635     Default host is localhost; default port is 23.
 636
 637     """
 638     debuglevel = 0
 639     while sys.argv[1:] and sys.argv[1] == '-d':
 640         debuglevel = debuglevel+1
 641         del sys.argv[1]
 642     host = 'localhost'
 643     if sys.argv[1:]:
 644         host = sys.argv[1]
 645     port = 0
 646     if sys.argv[2:]:
 647         portstr = sys.argv[2]
 648         try:
 649             port = int(portstr)
 650         except ValueError:
 651             port = socket.getservbyname(portstr, 'tcp')
 652     tn = Telnet()
 653     tn.set_debuglevel(debuglevel)
 654     tn.open(host, port, timeout=0.5)
 655     tn.interact()
 656     tn.close()
 657
 658 if __name__ == '__main__':
 659     test()