telnetlib3

By default, telnetlib3 uses encoding="utf8". In this mode, the shell callback receives TelnetReaderUnicode and TelnetWriterUnicode objects, which work with Python str objects.

To work with raw bytes (useful for low-level protocols like XMODEM or legacy systems), pass encoding=False to create_server or open_connection. The shell will then receive TelnetReader and TelnetWriter objects which work with bytes.

Important: Line Endings Regardless of mode, the Telnet protocol (RFC 854) requires \r\n (CR LF) for NVT output. The write() method does not automatically convert \n to \r\n. Always use \r\n for maximum compatibility.

# Unicode Mode (Default)
async def shell(reader, writer):
    writer.write("Hello, world!\r\n")  # writes str
    data = await reader.read(1)         # returns str

# Binary Mode
async def binary_shell(reader, writer):
    writer.write(b"Hello, world!\r\n")  # writes bytes
    data = await reader.read(1)         # returns bytes

await telnetlib3.create_server(
    host="127.0.0.1", port=6023,
    shell=binary_shell, encoding=False
)

The default implementation of telnetlib3 provides remote line editing and triggers the line_received callback when it detects various end-of-line sequences.

Supported signaling mechanisms include:

• CR LF (Carriage Return, Linefeed): The standard Telnet end-of-line. The default implementation strips this and fires line_received on the CR byte.
• CR NUL (Carriage Return, Null): Often used to distinguish between 'return' and 'enter' keys. The default implementation strips this and fires line_received on the CR byte.
• CR (Carriage Return): Handled by stripping the byte and firing line_received.
• LF (Linefeed): Handled by stripping the byte and firing line_received.

Note for Implementers: If you need to distinguish between these specific sequences (e.g., for raw file transfers or differentiating 'return' vs 'enter'), do not rely on the default line_received behavior. Instead, you should directly override data_received, or derive your own implementations of editing_received and character_received.

If you are migrating from miniboa, the telnetlib3.sync.ServerConnection class (provided to your handler) offers several compatible properties and methods:

Compatible Properties and Methods

• active: Connection status
• address: Connection address
• port: Connection port
• terminal_type: Terminal type
• columns / rows: Terminal dimensions
• send(data): Sends data, automatically normalizing \n to \r\n for miniboa compatibility.
• addrport(): Returns address and port.
• idle(): Returns idle time.
• duration(): Returns connection duration.
• deactivate(): Deactivates the connection.

Key Differences

• Threading: telnetlib3 uses a thread-per-connection model instead of miniboa's poll-based loop.
• Reading: Use blocking readline() or read() instead of get_command() or cmd_ready.

from telnetlib3.sync import BlockingTelnetServer

def handler(client):
    # Miniboa-compatible properties
    print(f"Connected: {client.addrport()}")
    print(f"Terminal: {client.terminal_type}")
    print(f"Size: {client.columns}x{client.rows}")

    # Miniboa-compatible send (converts \n to \r\n)
    client.send("Welcome!\n")

    while client.active:
        if client.idle() > 300:
            client.send("Timeout.\n")
            client.deactivate()
            break

        try:
            line = client.readline(timeout=1)
        except TimeoutError:
            continue
        if line:
            client.send(f"Echo: {line}")

server = BlockingTelnetServer('0.0.0.0', 6023, handler=handler)
server.serve_forever()

Telnet over TLS (TELNETS) encrypts the connection from the start. This is not STARTTLS.

Server-side:

• Use --ssl-certfile and --ssl-keyfile via CLI.
• Programmatically, pass an ssl.SSLContext to the ssl parameter in create_server.
• Use --tls-auto to allow both TLS and plain telnet on the same port. The server peeks at the first byte to detect a TLS ClientHello.

Client-side:

• Use --ssl to connect to a server with a CA-signed certificate.
• Use --ssl --ssl-cafile cert.pem for self-signed certificates.
• Use --ssl-no-verify to skip certificate verification (insecure, use for testing only).
• Programmatically, pass ssl=True or a custom ssl.SSLContext to open_connection.

# Programmatic TLS Server
import ssl
import telnetlib3

ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ctx.load_cert_chain("cert.pem", keyfile="key.pem")

server = await telnetlib3.create_server(host="0.0.0.0", port=6023, shell=shell, ssl=ctx)

# Programmatic TLS Client (CA-signed)
reader, writer = await telnetlib3.open_connection("dunemud.net", 6788, ssl=True)

# Programmatic TLS Client (Self-signed)
ctx = ssl.create_default_context(cafile="cert.pem")
reader, writer = await telnetlib3.open_connection("localhost", 6023, ssl=ctx)

If asyncio is too complex for your application, telnetlib3 provides a synchronous interface via telnetlib3.sync. This interface runs an asyncio event loop in a background thread, allowing you to use familiar blocking methods.

Client Usage

Use TelnetConnection to create a blocking client. It is recommended to use it as a context manager to ensure proper cleanup.

Server Usage

Use BlockingTelnetServer to create a blocking server. By default, it uses a thread-per-connection model, spawning a new thread for every client that connects.

from telnetlib3.sync import TelnetConnection

# Recommended: Using context manager
with TelnetConnection('localhost', 6023) as conn:
    conn.write('hello\r\n')
    response = conn.readline()
    print(response)

# Alternative: Manual lifecycle
conn = TelnetConnection('localhost', 6023, encoding='utf8')
conn.connect()
try:
    conn.write('command\r\n')
    data = conn.read_until(b'>>> ')
    print(data)
finally:
    conn.close()