Introduction

telnetlib3 is a full-featured Telnet Client and Server library for python3.8 and newer.

Modern asyncio and legacy blocking API's are provided.

The python telnetlib.py module removed by Python 3.13 is also re-distributed as a backport.

Overview

telnetlib3 provides multiple interfaces for working with the Telnet protocol:

Legacy telnetlib

An unadulterated copy of Python 3.12's telnetlib.py See Legacy telnetlib below.

Asyncio Protocol

Modern async/await interface for both client and server, supporting concurrent connections. See the Guidebook for examples and the API documentation.

Command-line Utilities

Two CLI tools are included: telnetlib3-client for connecting to servers and telnetlib3-server for hosting. See Command-line below.

Blocking API

A synchronous interface modeled after telnetlib (client) and miniboa (server), with enhancements. See the sync API documentation.

Enhancements over standard telnetlib:

• Full RFC 854 protocol negotiation (NAWS, TTYPE, BINARY, ECHO, SGA)
• wait_for() method to block until specific option states are negotiated
• get_extra_info() for terminal type, size, and other metadata
• Context manager support (with TelnetConnection(...) as conn:)
• Thread-safe operation with asyncio running in background

Enhancements over miniboa for server-side:

• Thread-per-connection model with blocking I/O (vs poll-based)
• readline() and read_until() blocking methods
• Full telnet option negotiation and inspection
• miniboa-compatible properties: active, address, terminal_type, columns, rows, idle(), duration(), deactivate()

Quick Example

A simple telnet server:

import asyncio
import telnetlib3

async def shell(reader, writer):
    writer.write('\r\nWould you like to play a game? ')
    inp = await reader.read(1)
    if inp:
        writer.echo(inp)
        writer.write('\r\nThey say the only way to win '
                     'is to not play at all.\r\n')
        await writer.drain()
    writer.close()

async def main():
    server = await telnetlib3.create_server(port=6023, shell=shell)
    await server.wait_closed()

asyncio.run(main())

More examples are available in the Guidebook and the bin/ directory.

Legacy telnetlib

This library also contains a copy of telnetlib.py from the standard library of Python 3.12 before it was removed in Python 3.13. asyncio is not required to use it.

To migrate code, change import statements:

# OLD imports:
import telnetlib

# NEW imports:
import telnetlib3

Command-line

Two command-line scripts are distributed with this package, telnetlib3-client and telnetlib3-server.

Both accept argument --shell=my_module.fn_shell describing a python module path to a function of signature async def shell(reader, writer).

telnetlib3-client nethack.alt.org
telnetlib3-client xibalba.l33t.codes 44510
telnetlib3-client --shell bin.client_wargame.shell 1984.ws 666
telnetlib3-server --pty-exec /bin/bash -- --login
telnetlib3-server 0.0.0.0 6023 --shell='bin.server_wargame.shell

Encoding

Use --encoding and --force-binary for non-ASCII terminals:

telnetlib3-client --encoding=cp437 --force-binary blackflag.acid.org

The default encoding is UTF-8, but all text is limited to ASCII until BINARY mode is agreed by compliance of their respective RFCs.

However, many clients and servers that are capable of non-ascii encodings like utf-8 or cp437 may not be capable of negotiating about BINARY, NEW_ENVIRON, or CHARSET to demand about it.

In this case, use --force-binary argument for clients and servers to enforce that the specified --encoding is always used, no matter what.

Features

The following RFC specifications are implemented:

• rfc-727, "Telnet Logout Option," Apr 1977.
• rfc-779, "Telnet Send-Location Option", Apr 1981.
• rfc-854, "Telnet Protocol Specification", May 1983.
• rfc-855, "Telnet Option Specifications", May 1983.
• rfc-856, "Telnet Binary Transmission", May 1983.
• rfc-857, "Telnet Echo Option", May 1983.
• rfc-858, "Telnet Suppress Go Ahead Option", May 1983.
• rfc-859, "Telnet Status Option", May 1983.
• rfc-860, "Telnet Timing mark Option", May 1983.
• rfc-885, "Telnet End of Record Option", Dec 1983.
• rfc-1073, "Telnet Window Size Option", Oct 1988.
• rfc-1079, "Telnet Terminal Speed Option", Dec 1988.
• rfc-1091, "Telnet Terminal-Type Option", Feb 1989.
• rfc-1096, "Telnet X Display Location Option", Mar 1989.
• rfc-1123, "Requirements for Internet Hosts", Oct 1989.
• rfc-1184, "Telnet Linemode Option (extended options)", Oct 1990.
• rfc-1372, "Telnet Remote Flow Control Option", Oct 1992.
• rfc-1408, "Telnet Environment Option", Jan 1993.
• rfc-1571, "Telnet Environment Option Interoperability Issues", Jan 1994.
• rfc-1572, "Telnet Environment Option", Jan 1994.
• rfc-2066, "Telnet Charset Option", Jan 1997.

Further Reading

Further documentation available at https://telnetlib3.readthedocs.io/