The main() function here is wired to the command line tool by name telnetlib3-server. If this server’s PID receives the SIGTERM signal, it attempts to shutdown gracefully.

The TelnetServer class negotiates a character-at-a-time (WILL-SGA, WILL-ECHO) session with support for negotiation about window size, environment variables, terminal type name, and to automatically close connections clients after an idle period.

class TelnetServer(term='unknown', cols=80, rows=25, timeout=300, *args, **kwargs)

Bases: telnetlib3.server_base.BaseServer

Telnet Server protocol performing common negotiation.


Called when the connection is lost or closed.

Parameters:exc (Exception) – exception. None indicates close by EOF.

Time elapsed since client connected, in seconds as float.

encoding(outgoing=None, incoming=None)

Return encoding for the given stream direction.

  • outgoing (bool) – Whether the return value is suitable for encoding bytes for transmission to client end.
  • incoming (bool) – Whether the return value is suitable for decoding bytes received from the client.

TypeError – when a direction argument, either outgoing or incoming, was not set True.


'US-ASCII' for the directions indicated, unless BINARY RFC 856 has been negotiated for the direction indicated or :attr`force_binary` is set True.

Return type:


Value resolution order (first-matching):

  • value set by set_encoding().
  • value of get_extra_info() using key argument, LANG.
  • value of default_encoding.
  • US-ASCII when binary transmission not allowed.

Called when the other end calls write_eof() or equivalent.

This callback may be exercised by the nc(1) client argument -z.

get_extra_info(name, default=None)

Get optional server protocol or transport information.


Time elapsed since data last received, in seconds as float.


Whether advanced negotiation should commence.

Return type:bool
Returns:True if advanced negotiation should be permitted.

The base implementation returns True if any negotiation options were affirmatively acknowledged by client, more than likely options requested in callback begin_negotiation().


Callback for CHARSET response, RFC 2066.


Callback receives NEW_ENVIRON response, RFC 1572.

on_naws(rows, cols)

Callback receives NAWS response, RFC 1073.

  • rows (int) – screen size, by number of cells in height.
  • cols (int) – screen size, by number of cells in width.

Definition for CHARSET request by client, RFC 2066.

This method is a callback from TelnetWriter.request_charset(), first entered on receipt of (WILL, CHARSET) by server. The return value defines the request made to the client for encodings.

Rtype list:

a list of unicode character strings of US-ASCII characters, indicating the encodings offered by the server in its preferred order.

Any empty return value indicates that no encodings are offered.

The default return value begins:

['UTF-8', 'UTF-16', 'LATIN1', 'US-ASCII', 'BIG5', 'GBK', ...]

Definition for NEW_ENVIRON request of client, RFC 1572.

This method is a callback from TelnetWriter.request_environ(), first entered on receipt of (WILL, NEW_ENVIRON) by server. The return value defines the request made to the client for environment values.

Rtype list:

a list of unicode character strings of US-ASCII characters, indicating the environment keys the server requests of the client. If this list contains the special byte constants, USERVAR or VAR, the client is allowed to volunteer any other additional user or system values.

Any empty return value indicates that no request should be made.

The default return value is:


Callback received on session timeout.

Default implementation writes “Timeout.” bound by CRLF and closes.

This can be disabled by calling set_timeout() with duration value of 0 or value of the same for keyword argument timeout.

on_tspeed(rx, tx)

Callback for TSPEED response, RFC 1079.


Callback for TTYPE response, RFC 930.


Callback for XDISPLOC response, RFC 1096.


Restart or unset timeout for client.

Parameters:duration (int) – When specified as a positive integer, schedules Future self.waiter_timeout with attached instance callback timeout(). When -1, the value of get_extra_info() for keyword timeout is used. When non-True, waiter_timeout is cancelled.
create_server(host=None, port=23, protocol_factory=<class 'telnetlib3.server.TelnetServer'>, **kwds)

Create a TCP Telnet server.

  • host (str) – The host parameter can be a string, in that case the TCP server is bound to host and port. The host parameter can also be a sequence of strings, and in that case the TCP server is bound to all hosts of the sequence.
  • port (int) – listen port for TCP Server.
  • protocol_factory (server_base.BaseServer) – An alternate protocol factory for the server, when unspecified, TelnetServer is used.
  • shell (asyncio.coroutine) – A coroutine that is called after negotiation completes, receiving arguments (reader, writer). The reader is a TelnetStreamReader instance, the writer is a TelnetStreamWriter instance.
  • log (logging.Logger) – target logger, if None is given, one is created using the namespace 'telnetlib3.server'.
  • encoding (str) –

    The default assumed encoding, or False to disable unicode support. Encoding may be negotiation to another value by the client through NEW_ENVIRON RFC 1572 by sending environment value of LANG, or by any legal value for CHARSET RFC 2066 negotiation.

    The server’s attached reader, writer streams accept and return unicode, unless this value explicitly set False. In that case, the attached streams interfaces are bytes-only.

  • encoding_errors (str) – Same meaning as codecs.Codec. Default value is strict.
  • force_binary (bool) – When True, the encoding specified is used for both directions even when BINARY mode, RFC 856, is not negotiated for the direction specified. This parameter has no effect when encoding=False.
  • term (str) – Value returned for writer.get_extra_info('term') until negotiated by TTYPE RFC 930, or NAWS RFC 1572. Default value is 'unknown'.
  • cols (int) – Value returned for writer.get_extra_info('cols') until negotiated by NAWS RFC 1572. Default value is 80 columns.
  • rows (int) – Value returned for writer.get_extra_info('rows') until negotiated by NAWS RFC 1572. Default value is 25 rows.
  • timeout (int) – Causes clients to disconnect if idle for this duration, in seconds. This ensures resources are freed on busy servers. When explicitly set to False, clients will not be disconnected for timeout. Default value is 300 seconds (5 minutes).
  • connect_maxwait (float) – If the remote end is not complaint, or otherwise confused by our demands, the shell continues anyway after the greater of this value has elapsed. A client that is not answering option negotiation will delay the start of the shell by this amount.
  • limit (int) – The buffer limit for the reader stream.
Return asyncio.Server:

The return value is the same as loop.create_server(), An object which can be used to stop the service.

This function is a coroutine().

run_server(host='localhost', port=6023, loglevel='info', logfile=None, logfmt='%(asctime)s %(levelname)s %(filename)s:%(lineno)d %(message)s', shell=<function telnet_server_shell>, encoding='utf8', force_binary=False, timeout=300, connect_maxwait=4.0)

Program entry point for server daemon.

This function configures a logger and creates a telnet server for the given keyword arguments, serving forever, completing only upon receipt of SIGTERM.