telnetsrv 0.3.1

To Use

Import the TelnetHandler base class and command function decorator from either the green class or threaded class, then subclass TelnetHandler to add your own commands as specially named methods.

Threaded:

> from telnetsrv.threaded import TelnetHandler, command
> class MyHandler(TelnetHandler):
>    ...

Green:

> from telnetsrv.green import TelnetHandler, command
> class MyHandler(TelnetHandler):
>    ...

Add Commands

Commands can be defined by using the command function decorator.

>   @command('echo')
>   def command_echo(self, params):
>      ...

Telnet Server> echo 1  "2    3"

>   params == ['1', '2    3']
>   self.raw_input == 'echo 1 "2    3"'

Telnet Server> echo 1 \
... 2 "3
... 4"  "5\
... 6"

>   params == ['1', '2', '3\n4', '56']

Telnet Server> echo 1\ 2

>   params == ['1 2']

>    @command('echo')
>    def command_echo(self, params):
>        '''<text to echo>
>        Echo text back to the console.
>        This command simply echos the provided text
>        back to the console.
>        '''
>        pass

Telnet Server> help
? [<command>] - Display help
BYE - Exit the command shell
ECHO <text to echo> - Echo text back to the console.
...


Telnet Server> help echo
ECHO <text to echo>

This command simply echos the provided text
back to the console.
Telnet Server>

>   @command(['echo', 'copy'])
>   def comand_echo(self, params):
>      ...

>   @command('echo')
>   @command(['copy', 'repeat'])
>   @command('ditto')
>   def comand_echo(self, params):
>      ...

>   @command('echo', hidden=True)
>   def comand_echo(self, params):
>      ...

Console Communication

To communicate with the connected Telnet client, use:

• self.writeline( TEXT )

• self.write( TEXT )

• self.readline( prompt=TEXT )

• self.writemessage( TEXT ) - for clean, asynchronous writing. Any interrupted input is rebuilt.

• self.writeresult( TEXT ) - to emit a line of expected output

• self.writeerror( TEXT ) - to emit error messages

The writemessage method is intended to send messages to the console without interrupting any current input. If the user has entered text at the prompt, the prompt and text will be seamlessly regenerated following the message. It is ideal for asynchronous messages that aren’t generated from the direct user input.

Handler Options

Override these class members to change the handler’s behavior.

logging

Default: pass

PROMPT

Default: "Telnet Server> "

CONTINUE_PROMPT

Default: "... "

WELCOME

Displayed after a successful connection, after the username/password is accepted, if configured.

Default: "You have connected to the telnet server."

session_start(self)

Called after the WELCOME text is displayed.

Default: pass

session_end(self)

Called after the console is disconnected.

Default: pass

authCallback(self, username, password)

Reference to authentication function. If this is not defined, no username or password is requested. Should raise an exception if authentication fails

Default: None

authNeedUser

Should a username be requested?

Default: False

authNeedPass

Should a password be requested?

Default: False

Handler Display Modification

If you want to change how the output is displayed, override one or all of the write classes. Make sure you call back to the base class when doing so. This is a good way to provide color to your console by using ANSI color commands. See http://en.wikipedia.org/wiki/ANSI_escape_code

• writemessage( TEXT )

• writeresult( TEXT )

• writeerror( TEXT )

>    def writeerror(self, text):
>        '''Write errors in red'''
>        TelnetHandler.writeerror(self, "\x1b[91m%s\x1b[0m" % text )

Serving the Handler

Now you have a shiny new handler class, but it doesn’t serve itself - it must be called from an appropriate server. The server will create an instance of the TelnetHandler class for each new connection. The handler class will work with either a gevent StreamServer instance (for the green version) or with a SocketServer.TCPServer instance (for the threaded version).

> import SocketServer
> class TelnetServer(SocketServer.TCPServer):
>     allow_reuse_address = True
>
> server = TelnetServer(("0.0.0.0", 8023), MyHandler)
> server.serve_forever()

> import gevent.server
> server = gevent.server.StreamServer(("", 8023), MyHandler.streamserver_handle)
> server.server_forever()

Short Example

> import gevent, gevent.server
> from telnetsrv.green import TelnetHandler, command
>
> class MyTelnetHandler(TelnetHandler):
>     WELCOME = "Welcome to my server."
>
>     @command(['echo', 'copy', 'repeat'])
>     def command_echo(self, params):
>         '''<text to echo>
>         Echo text back to the console.
>
>         '''
>         self.writeresult( ' '.join(params) )
>
>     @command('timer')
>     def command_timer(self, params):
>         '''<time> <message>
>         In <time> seconds, display <message>.
>         Send a message after a delay.
>         <time> is in seconds.
>         If <message> is more than one word, quotes are required.
>         example:
>         > TIMER 5 "hello world!"
>         '''
>         try:
>             timestr, message = params[:2]
>             time = int(timestr)
>         except ValueError:
>             self.writeerror( "Need both a time and a message" )
>             return
>         self.writeresult("Waiting %d seconds...", time)
>         gevent.spawn_later(time, self.writemessage, message)
>
>
> server = gevent.server.StreamServer(("", 8023), MyTelnetHandler.streamserver_handle)
> server.server_forever()

Longer Example

See https://github.com/ianepperson/telnetsrvlib/blob/master/test.py