Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`telnetlib` --- Telnet client |
| 2 | ================================== |
| 3 | |
| 4 | .. module:: telnetlib |
| 5 | :synopsis: Telnet client class. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Christian Heimes | 895627f | 2007-12-08 17:28:33 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Skip Montanaro <skip@pobox.com> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | **Source code:** :source:`Lib/telnetlib.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | .. index:: single: protocol; Telnet |
| 12 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 13 | -------------- |
| 14 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the |
| 16 | Telnet protocol. See :rfc:`854` for details about the protocol. In addition, it |
| 17 | provides symbolic constants for the protocol characters (see below), and for the |
| 18 | telnet options. The symbolic names of the telnet options follow the definitions |
| 19 | in ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names |
| 20 | of options which are traditionally not included in ``arpa/telnet.h``, see the |
| 21 | module source itself. |
| 22 | |
| 23 | The symbolic constants for the telnet commands are: IAC, DONT, DO, WONT, WILL, |
| 24 | SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP |
| 25 | (Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase |
| 26 | Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin). |
| 27 | |
| 28 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 29 | .. class:: Telnet(host=None, port=0[, timeout]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
| 31 | :class:`Telnet` represents a connection to a Telnet server. The instance is |
| 32 | initially not connected by default; the :meth:`open` method must be used to |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 33 | establish a connection. Alternatively, the host name and optional port |
Tim Golden | fe5ac52 | 2015-04-08 16:52:27 +0100 | [diff] [blame] | 34 | number can be passed to the constructor too, in which case the connection to |
Georg Brandl | d25a5da | 2010-05-21 21:33:23 +0000 | [diff] [blame] | 35 | the server will be established before the constructor returns. The optional |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 36 | *timeout* parameter specifies a timeout in seconds for blocking operations |
Georg Brandl | d25a5da | 2010-05-21 21:33:23 +0000 | [diff] [blame] | 37 | like the connection attempt (if not specified, the global default timeout |
| 38 | setting will be used). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
| 40 | Do not reopen an already connected instance. |
| 41 | |
| 42 | This class has many :meth:`read_\*` methods. Note that some of them raise |
| 43 | :exc:`EOFError` when the end of the connection is read, because they can return |
| 44 | an empty string for other reasons. See the individual descriptions below. |
| 45 | |
R David Murray | 4f09806 | 2015-11-28 12:24:52 -0500 | [diff] [blame] | 46 | A :class:`Telnet` object is a context manager and can be used in a |
Serhiy Storchaka | 2b57c43 | 2018-12-19 08:09:46 +0200 | [diff] [blame] | 47 | :keyword:`with` statement. When the :keyword:`!with` block ends, the |
R David Murray | 4f09806 | 2015-11-28 12:24:52 -0500 | [diff] [blame] | 48 | :meth:`close` method is called:: |
| 49 | |
| 50 | >>> from telnetlib import Telnet |
| 51 | >>> with Telnet('localhost', 23) as tn: |
| 52 | ... tn.interact() |
| 53 | ... |
| 54 | |
| 55 | .. versionchanged:: 3.6 Context manager support added |
| 56 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | .. seealso:: |
| 59 | |
| 60 | :rfc:`854` - Telnet Protocol Specification |
| 61 | Definition of the Telnet protocol. |
| 62 | |
| 63 | |
| 64 | .. _telnet-objects: |
| 65 | |
| 66 | Telnet Objects |
| 67 | -------------- |
| 68 | |
| 69 | :class:`Telnet` instances have the following methods: |
| 70 | |
| 71 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 72 | .. method:: Telnet.read_until(expected, timeout=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 74 | Read until a given byte string, *expected*, is encountered or until *timeout* |
| 75 | seconds have passed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 77 | When no match is found, return whatever is available instead, possibly empty |
| 78 | bytes. Raise :exc:`EOFError` if the connection is closed and no cooked data |
| 79 | is available. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
| 81 | |
| 82 | .. method:: Telnet.read_all() |
| 83 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 84 | Read all data until EOF as bytes; block until connection closed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | |
| 87 | .. method:: Telnet.read_some() |
| 88 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 89 | Read at least one byte of cooked data unless EOF is hit. Return ``b''`` if |
| 90 | EOF is hit. Block if no data is immediately available. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
| 92 | |
| 93 | .. method:: Telnet.read_very_eager() |
| 94 | |
| 95 | Read everything that can be without blocking in I/O (eager). |
| 96 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 97 | Raise :exc:`EOFError` if connection closed and no cooked data available. |
| 98 | Return ``b''`` if no cooked data available otherwise. Do not block unless in |
| 99 | the midst of an IAC sequence. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | |
| 102 | .. method:: Telnet.read_eager() |
| 103 | |
| 104 | Read readily available data. |
| 105 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 106 | Raise :exc:`EOFError` if connection closed and no cooked data available. |
| 107 | Return ``b''`` if no cooked data available otherwise. Do not block unless in |
| 108 | the midst of an IAC sequence. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
| 110 | |
| 111 | .. method:: Telnet.read_lazy() |
| 112 | |
| 113 | Process and return data already in the queues (lazy). |
| 114 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 115 | Raise :exc:`EOFError` if connection closed and no data available. Return |
| 116 | ``b''`` if no cooked data available otherwise. Do not block unless in the |
| 117 | midst of an IAC sequence. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
| 119 | |
| 120 | .. method:: Telnet.read_very_lazy() |
| 121 | |
| 122 | Return any data available in the cooked queue (very lazy). |
| 123 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 124 | Raise :exc:`EOFError` if connection closed and no data available. Return |
| 125 | ``b''`` if no cooked data available otherwise. This method never blocks. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
| 128 | .. method:: Telnet.read_sb_data() |
| 129 | |
| 130 | Return the data collected between a SB/SE pair (suboption begin/end). The |
| 131 | callback should access these data when it was invoked with a ``SE`` command. |
| 132 | This method never blocks. |
| 133 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 135 | .. method:: Telnet.open(host, port=0[, timeout]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
| 137 | Connect to a host. The optional second argument is the port number, which |
| 138 | defaults to the standard Telnet port (23). The optional *timeout* parameter |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 139 | specifies a timeout in seconds for blocking operations like the connection |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 140 | attempt (if not specified, the global default timeout setting will be used). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
| 142 | Do not try to reopen an already connected instance. |
| 143 | |
Steve Dower | 60419a7 | 2019-06-24 08:42:54 -0700 | [diff] [blame^] | 144 | .. audit-event:: telnetlib.Telnet.open "self host port" |
| 145 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 147 | .. method:: Telnet.msg(msg, *args) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
| 149 | Print a debug message when the debug level is ``>`` 0. If extra arguments are |
| 150 | present, they are substituted in the message using the standard string |
| 151 | formatting operator. |
| 152 | |
| 153 | |
| 154 | .. method:: Telnet.set_debuglevel(debuglevel) |
| 155 | |
| 156 | Set the debug level. The higher the value of *debuglevel*, the more debug |
| 157 | output you get (on ``sys.stdout``). |
| 158 | |
| 159 | |
| 160 | .. method:: Telnet.close() |
| 161 | |
| 162 | Close the connection. |
| 163 | |
| 164 | |
| 165 | .. method:: Telnet.get_socket() |
| 166 | |
| 167 | Return the socket object used internally. |
| 168 | |
| 169 | |
| 170 | .. method:: Telnet.fileno() |
| 171 | |
| 172 | Return the file descriptor of the socket object used internally. |
| 173 | |
| 174 | |
| 175 | .. method:: Telnet.write(buffer) |
| 176 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 177 | Write a byte string to the socket, doubling any IAC characters. This can |
Antoine Pitrou | 5574c30 | 2011-10-12 17:53:43 +0200 | [diff] [blame] | 178 | block if the connection is blocked. May raise :exc:`OSError` if the |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 179 | connection is closed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
Steve Dower | 60419a7 | 2019-06-24 08:42:54 -0700 | [diff] [blame^] | 181 | .. audit-event:: telnetlib.Telnet.write "self buffer" |
| 182 | |
Antoine Pitrou | 5574c30 | 2011-10-12 17:53:43 +0200 | [diff] [blame] | 183 | .. versionchanged:: 3.3 |
| 184 | This method used to raise :exc:`socket.error`, which is now an alias |
| 185 | of :exc:`OSError`. |
| 186 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
| 188 | .. method:: Telnet.interact() |
| 189 | |
| 190 | Interaction function, emulates a very dumb Telnet client. |
| 191 | |
| 192 | |
| 193 | .. method:: Telnet.mt_interact() |
| 194 | |
| 195 | Multithreaded version of :meth:`interact`. |
| 196 | |
| 197 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 198 | .. method:: Telnet.expect(list, timeout=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 199 | |
| 200 | Read until one from a list of a regular expressions matches. |
| 201 | |
| 202 | The first argument is a list of regular expressions, either compiled |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 203 | (:ref:`regex objects <re-objects>`) or uncompiled (byte strings). The |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 204 | optional second argument is a timeout, in seconds; the default is to block |
| 205 | indefinitely. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 206 | |
| 207 | Return a tuple of three items: the index in the list of the first regular |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 208 | expression that matches; the match object returned; and the bytes read up |
| 209 | till and including the match. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 210 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 211 | If end of file is found and no bytes were read, raise :exc:`EOFError`. |
| 212 | Otherwise, when nothing matches, return ``(-1, None, data)`` where *data* is |
| 213 | the bytes received so far (may be empty bytes if a timeout happened). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | |
| 215 | If a regular expression ends with a greedy match (such as ``.*``) or if more |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 216 | than one expression can match the same input, the results are |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 217 | non-deterministic, and may depend on the I/O timing. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | |
| 219 | |
| 220 | .. method:: Telnet.set_option_negotiation_callback(callback) |
| 221 | |
| 222 | Each time a telnet option is read on the input flow, this *callback* (if set) is |
Serhiy Storchaka | f47036c | 2013-12-24 11:04:36 +0200 | [diff] [blame] | 223 | called with the following parameters: callback(telnet socket, command |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | (DO/DONT/WILL/WONT), option). No other action is done afterwards by telnetlib. |
| 225 | |
| 226 | |
| 227 | .. _telnet-example: |
| 228 | |
| 229 | Telnet Example |
| 230 | -------------- |
| 231 | |
| 232 | .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de> |
| 233 | |
| 234 | |
| 235 | A simple example illustrating typical use:: |
| 236 | |
| 237 | import getpass |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | import telnetlib |
| 239 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | HOST = "localhost" |
Georg Brandl | 8d5c392 | 2007-12-02 22:48:17 +0000 | [diff] [blame] | 241 | user = input("Enter your remote account: ") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 242 | password = getpass.getpass() |
| 243 | |
| 244 | tn = telnetlib.Telnet(HOST) |
| 245 | |
Benjamin Peterson | 3de7fb8 | 2008-10-15 20:54:24 +0000 | [diff] [blame] | 246 | tn.read_until(b"login: ") |
| 247 | tn.write(user.encode('ascii') + b"\n") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | if password: |
Benjamin Peterson | 3de7fb8 | 2008-10-15 20:54:24 +0000 | [diff] [blame] | 249 | tn.read_until(b"Password: ") |
| 250 | tn.write(password.encode('ascii') + b"\n") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 251 | |
Benjamin Peterson | 3de7fb8 | 2008-10-15 20:54:24 +0000 | [diff] [blame] | 252 | tn.write(b"ls\n") |
| 253 | tn.write(b"exit\n") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 254 | |
Benjamin Peterson | aaebe1c | 2008-10-15 22:28:54 +0000 | [diff] [blame] | 255 | print(tn.read_all().decode('ascii')) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 256 | |