telgo

README

Simple Telnet control interface for go applications

This golang ackage contains a simple telnet server which can be used as a control/debug interface for applications. The telgo telnet server does all the client handling and runs configurable commands as go routines. It also supports handling of basic inline telnet commands used by variaus telnet clients to configure the client connection. For now every negotiable telnet option will be discarded but the telnet command IP (interrupt process) is understood and can be used to terminate long running user commands.

Status

This is currently on development. The API is in a semi-stable state. This means i'm trying not to break anything but i'm not yet in a place where i can guarantee that it won't happen.

API

Source code.

Licence

© 2015 Christian Pointner <equinox@spreadspace.org>    3-clause BSD

Documentation

Overview

Package telgo contains a simple telnet server which can be used as a control/debug interface for applications. The telgo telnet server does all the client handling and runs configurable commands as go routines. It also supports handling of basic inline telnet commands used by variaus telnet clients to configure the connection. For now every negotiable telnet option will be discarded but the telnet command IP (interrupt process) is understood and can be used to terminate long running user commands. If the environment contains the variable TELGO_DEBUG logging will be enabled. By default telgo doesn't log anything.

Index

• type Client
  • func (c *Client) Say(format string, a ...interface{}) bool
  • func (c *Client) Sayln(format string, a ...interface{}) bool
  • func (c *Client) WriteString(text string) bool
• type Cmd
• type CmdList
• type Greeter
• type Server
  • func NewServer(addr, prompt string, commands CmdList, userdata interface{}) (s *Server, err error)
  • func NewServerFromListener(ln net.Listener, prompt string, commands CmdList, userdata interface{}) (s *Server, err error)
  • func (s *Server) Run(params ...interface{}) error

Types

type Client

type Client struct {
	Conn     net.Conn
	UserData interface{}
	Cancel   chan bool

	Prompt string
	// contains filtered or unexported fields
}

Client is used to export the raw tcp connection to the client as well as the UserData to telgo command functions. The Prompt variable my be used to override the server prompt. Set it to the empty string to get the default prompt. The Cancel channel will get ready for reading when the user hits Ctrl-C or the connection got terminated. This can be used to abort long running telgo commands.

func (*Client) Say

func (c *Client) Say(format string, a ...interface{}) bool

Say is a simple Printf-like interface which sends responses to the client. If it returns false the client connection is about to be closed and therefore no output has been sent.

func (*Client) Sayln

func (c *Client) Sayln(format string, a ...interface{}) bool

Sayln is the same as Say but also adds a new-line at the end of the string.

func (*Client) WriteString

func (c *Client) WriteString(text string) bool

WriteString writes a 'raw' string to the client. For most purposes the usage of Say and Sayln is recommended. WriteString will take care of escaping IAC bytes inside your string. This function returns false if the client connection has been closed and the client is about to go away.

type Cmd

type Cmd func(c *Client, args []string) bool

Cmd is the signature of telgo command functions. It receives a pointer to the telgo client struct and a slice of strings containing the arguments the user has supplied. The first argument is always the command name itself. If this function returns true the client connection will be terminated.

type CmdList

type CmdList map[string]Cmd

CmdList is a list of telgo commands using the command name as the key.

type Greeter

type Greeter interface {
	Exec(c *Client, args []string) bool
}

The Greeter interface is used to distinguish between default and greet functions supplied to run()

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server contains all values needed to run the server. Use NewServer to create and Run to actually run the server.

func NewServer

func NewServer(addr, prompt string, commands CmdList, userdata interface{}) (s *Server, err error)

NewServer creates a new telnet server struct. addr is the address to bind/listen to on and will be passed through to net.Listen(). The prompt will be sent to the client whenever the telgo server is ready for a new command. commands is a list of telgo commands to be used and userdata will be made available to called telgo commands through the client struct.

func NewServerFromListener

func NewServerFromListener(ln net.Listener, prompt string, commands CmdList, userdata interface{}) (s *Server, err error)

NewServerFromListener does the same as NewServer takes a net listener except for an address.

func (*Server) Run

func (s *Server) Run(params ...interface{}) error

Run opens the server socket and runs the telnet server which spawns go routines for every connecting client. This function takes 2 optional parameters. Parameter who implement the Greeter interface will be passed to clients as greet function. These functions will be called before the first command prompt is shown. If the greeter function returns true the connection will be closed after it's completion. In this case the user won't be able to send any commands but might abort the running greet command using CTRl-C. If the parameter is a normal command function it will be used as a default command which will be called if the user entered an unknown command.