Asyncio Protocol

Modern async/await interface for both client and server, supporting concurrentconnections. See theGuidebook for examples and theAPI documentation.

Blocking API

A traditional synchronous interface modeled aftertelnetlib.py (client) andminiboa (server),with various enhancements in protocol negotiation is provided. Blocking API calls for complexarrangements of clients and servers typically require threads.

Seesync API documentation for more.

Command-line Utilities

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

Both tools argument--shell=my_module.fn_shell describing a pythonmodule path to a function of signatureasync def shell(reader, writer).The server also provides--pty-exec argument to host a stand-aloneprogram.

telnetlib3-client nethack.alt.orgtelnetlib3-client xibalba.l33t.codes 44510telnetlib3-client --shell bin.client_wargame.shell 1984.ws 666telnetlib3-server 0.0.0.0 1984 --shell=bin.server_wargame.shelltelnetlib3-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 (prettytableanducs-detect):

pip install telnetlib3[extras]

Usage:

export TELNETLIB3_DATA_DIR=./datatelnetlib3-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 aspython-m <module> <filepath>. The built-in post-script pretty-prints the JSONand integrates withucs-detect for terminal capability probing:

export TELNETLIB3_DATA_DIR=./fingerprintsexport TELNETLIB3_FINGERPRINT_POST_SCRIPT=telnetlib3.fingerprintingtelnetlib3-server --shell telnetlib3.fingerprinting_server_shell

Ifucs-detect is installed and available in PATH, the post-script automaticallyruns it to probe terminal capabilities (colors, sixel, kitty graphics, etc.) andadds the results to the fingerprint data asterminal-fingerprint-data.

Legacy telnetlib

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

To migrate code, change import statements:

# OLD imports:importtelnetlib# NEW imports:importtelnetlib3

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

Seesync 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 Telnetprotocol textshould be limited to ASCII until BINARY mode is agreed bycompliance of their respective RFCs.

However, many clients and servers that are capable of non-ascii encodings likeUTF-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 ofthe remote end is known.

Go-Ahead (GA)

When a client does not negotiate Suppress Go-Ahead (SGA), the server sendsIAC GA after output to signal that the client may transmit. This iscorrect behavior for MUD clients like Mudlet that expect prompt detectionvia 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 avoidinjecting GA in the middle of streaming output.

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 athttps://telnetlib3.readthedocs.io/