Introduction

telnetlib3 is a feature-rich Telnet Server and Client Protocol library for Python 3.9 and newer.

This library supports both modern asyncio and legacy Blocking API.

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

telnetlib3 provides multiple interfaces for working with the Telnet protocol:

Asyncio Protocol

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

Blocking API

A traditional synchronous interface modeled after telnetlib.py (client) and miniboa (server), with various enhancements in protocol negotiation is provided. Blocking API calls for complex arrangements of clients and servers typically require threads.

See sync API documentation for more.

Command-line Utilities

Two CLI tools are included: telnetlib3-client for connecting to servers and telnetlib3-server for hosting a server.

Both tools argument --shell=my_module.fn_shell describing a python module path to a function of signature async def shell(reader, writer). The server also provides --pty-exec argument to host a stand-alone program.

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

Fingerprinting Server

A built-in fingerprinting server shell is provided to uniquely identify telnet clients.

Install with optional dependencies for full fingerprinting support (prettytable and ucs-detect):

pip install telnetlib3[extras]

Usage:

export TELNETLIB3_DATA_DIR=./data
telnetlib3-server --shell telnetlib3.fingerprinting_server_shell

A public fingerprinting server you can try out yourself:

telnet 1984.ws 555

An optional post-fingerprint hook can process saved files. The hook is run as python -m <module> <filepath>. The built-in post-script pretty-prints the JSON and integrates with ucs-detect for terminal capability probing:

export TELNETLIB3_DATA_DIR=./fingerprints
export TELNETLIB3_FINGERPRINT_POST_SCRIPT=telnetlib3.fingerprinting
telnetlib3-server --shell telnetlib3.fingerprinting_server_shell

If ucs-detect is installed and available in PATH, the post-script automatically runs it to probe terminal capabilities (colors, sixel, kitty graphics, etc.) and adds the results to the fingerprint data as terminal-fingerprint-data.

Legacy telnetlib

This library contains an unadulterated copy of Python 3.12's telnetlib.py, from the standard library before it was removed in Python 3.13.

To migrate code, change import statements:

# OLD imports:
import telnetlib

# NEW imports:
import telnetlib3

telnetlib3 did not provide server support, while this library also provides both client and server support through a similar Blocking API interface.

See sync API documentation for details.

Encoding

Often required, --encoding and --force-binary:

telnetlib3-client --encoding=cp437 --force-binary 20forbeers.com 1337

The default encoding is the system locale, usually UTF-8, but all Telnet protocol text should be 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 negotiate about it.

In this case, use --force-binary and --encoding when the encoding of the remote end is known.

Go-Ahead (GA)

When a client does not negotiate Suppress Go-Ahead (SGA), the server sends IAC GA after output to signal that the client may transmit. This is correct behavior for MUD clients like Mudlet that expect prompt detection via GA.

If GA causes unwanted output for your use case, disable it:

telnetlib3-server --never-send-ga

For PTY shells, GA is sent after 500ms of output idle time to avoid injecting GA in the middle of streaming output.

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 of the repository.

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-930, "Telnet Terminal Type Option", Jan 1984.
• 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/