Setting Up a Custom SSH Server

The command line is an incredibly efficient interface for certain tasks. System administrators love the ability to manage applications by typing commands without having to click through a graphical user interface. An SSH shell is even better, as it's accessible from anywhere on the Internet.

You can use twisted.conch to create an SSH server that provides access to a custom shell with commands you define. This shell will even support some extra features like command history, so that you can scroll through the commands you've already typed.

10.1.1. How Do I Do That?

Write a subclass of twisted.conch.recvline.HistoricRecvLine that implements your shell protocol. HistoricRecvLine is similar to twisted.protocols.basic.LineReceiver, but with higher-level features for controlling the terminal.

To make your shell available through SSH, you need to implement a few different classes that twisted.conch needs to build an SSH server. First, you need the twisted.cred authentication classes : a portal, credentials checkers, and a realm that returns avatars. Use twisted.conch.avatar.ConchUser as the base class for your avatar. Your avatar class should also implement twisted.conch.interfaces.ISession, which includes an openShell method in which you create a Protocol to manage the user's interactive session. Finally, create a twisted.conch.ssh.factory.SSHFactory object and set its portal attribute to an instance of your portal.

Example 10-1 demonstrates a custom SSH server that authenticates users by their username and password . It gives each user a shell that provides several commands.

Example 10-1.

from twisted.cred import portal, checkers, credentials

from twisted.conch import error, avatar, recvline, interfaces as conchinterfaces

from twisted.conch.ssh import factory, userauth, connection, keys, session, common

from twisted.conch.insults import insults

from twisted.application import service, internet

from zope.interface import implements

import os

class SSHDemoProtocol(recvline.HistoricRecvLine):

 def _ _init_ _(self, user):

 self.user = user

 def connectionMade(self):


 self.terminal.write("Welcome to my test SSH server.")

 self.terminal.nextLine( )

 self.do_help( )

 self.showPrompt( )

 def showPrompt(self):

 self.terminal.write("$ ")

 def getCommandFunc(self, cmd):

 return getattr(self, 'do_' + cmd, None)

 def lineReceived(self, line):

 line = line.strip( )

 if line:

 cmdAndArgs = line.split( )

 cmd = cmdAndArgs[0]

 args = cmdAndArgs[1:]

 func = self.getCommandFunc(cmd)

 if func:



 except Exception, e:

 self.terminal.write("Error: %s" % e)

 self.terminal.nextLine( )


 self.terminal.write("No such command.")

 self.terminal.nextLine( )

 self.showPrompt( )

 def do_help(self, cmd=''):

 "Get help on a command. Usage: help command"

 if cmd:

 func = self.getCommandFunc(cmd)

 if func:

 self.terminal.write(func._ _doc_ _)

 self.terminal.nextLine( )


 publicMethods = filter(

 lambda funcname: funcname.startswith('do_'), dir(self))

 commands = [cmd.replace('do_', '', 1) for cmd in publicMethods]

 self.terminal.write("Commands: " + " ".join(commands))

 self.terminal.nextLine( )

 def do_echo(self, *args):

 "Echo a string. Usage: echo my line of text"

 self.terminal.write(" ".join(args))

 self.terminal.nextLine( )

 def do_whoami(self):

 "Prints your user name. Usage: whoami"


 self.terminal.nextLine( )

 def do_quit(self):

 "Ends your session. Usage: quit"

 self.terminal.write("Thanks for playing!")

 self.terminal.nextLine( )

 self.terminal.loseConnection( )

 def do_clear(self):

 "Clears the screen. Usage: clear"

 self.terminal.reset( )

class SSHDemoAvatar(avatar.ConchUser):


 def _ _init_ _(self, username):

 avatar.ConchUser._ _init_ _(self)

 self.username = username


 def openShell(self, protocol):

 serverProtocol = insults.ServerProtocol(SSHDemoProtocol, self)



 def getPty(self, terminal, windowSize, attrs):

 return None

 def execCommand(self, protocol, cmd):

 raise NotImplementedError

 def closed(self):


class SSHDemoRealm:


 def requestAvatar(self, avatarId, mind, *interfaces):

 if conchinterfaces.IConchUser in interfaces:

 return interfaces[0], SSHDemoAvatar(avatarId), lambda: None


 raise Exception, "No supported interfaces found."

def getRSAKeys( ):

 if not (os.path.exists('public.key') and os.path.exists('private.key')):

 # generate a RSA keypair

 print "Generating RSA keypair..."

 from Crypto.PublicKey import RSA

 KEY_LENGTH = 1024

 rsaKey = RSA.generate(KEY_LENGTH, common.entropy.get_bytes)

 publicKeyString = keys.makePublicKeyString(rsaKey)

 privateKeyString = keys.makePrivateKeyString(rsaKey)

 # save keys for next time

 file('public.key', 'w+b').write(publicKeyString)

 file('private.key', 'w+b').write(privateKeyString)

 print "done."


 publicKeyString = file('public.key').read( )

 privateKeyString = file('private.key').read( )

 return publicKeyString, privateKeyString

if __name__ == "_ _main_ _":

 sshFactory = factory.SSHFactory( )

 sshFactory.portal = portal.Portal(SSHDemoRealm( ))

 users = {'admin': 'aaa', 'guest': 'bbb'}



 pubKeyString, privKeyString = getRSAKeys( )

 sshFactory.publicKeys = {

 'ssh-rsa': keys.getPublicKeyString(data=pubKeyString)}

 sshFactory.privateKeys = {

 'ssh-rsa': keys.getPrivateKeyObject(data=privKeyString)}

 from twisted.internet import reactor

 reactor.listenTCP(2222, sshFactory) ) will run an SSH server on port 2222. Connect to this server with an SSH client using the username admin and password aaa, and try typing some commands:

 $ ssh admin@localhost -p 2222

 admin@localhost's password: aaa

 >>> Welcome to my test SSH server.

 Commands: clear echo help quit whoami

 $ whoami


 $ help echo

 Echo a string. Usage: echo my line of text

 $ echo hello SSH world!

 hello SSH world!

 $ quit

 Connection to localhost closed.

If you've already been using an SSH server on your local machine, you might get an error when you try to connect to the server in this example. You'll get a message saying something like "Remote host identification has changed" or "Host key verification failed," and your SSH client will refuse to connect.

The reason you get this error message is that your SSH client is remembering the public key used by your regular localhost SSH server. The server in Example 10-1 has its own key, and when the client sees that the keys are different, it gets suspicious that this new server may be an impostor pretending to be your regular localhost SSH server. To fix this problem, edit your ~/.ssh/known_hosts file (or wherever your SSH client keeps its list of recognized servers) and remove the localhost entry.


10.1.2. How Does That Work?

The SSHDemoProtocol class in Example 10-1 inherits from twisted.conch.recvline.HistoricRecvline. HistoricRecvLine is a protocol with built-in features for building command-line shells . It gives your shell features that most people take for granted in a modern shell, including backspacing, the ability to use the arrow keys to move the cursor forwards and backwards on the current line, and a command history that can be accessed using the up and down arrows. twisted.conch.recvline also provides a plain RecvLine class that works the same way, but without the command history.

The lineReceived method in HistoricRecvLine is called whenever a user enters a line. Example 10-1 shows how you might override this method to parse and execute commands. There are a couple of differences between HistoricRecvLine and a regular Protocol, which come from the fact that with HistoricRecvLine you're actually manipulating the current contents of a user's terminal window, rather than just printing out text. To print a line of output, use self.terminal.write; to go to the next line, use self.nextLine.

The twisted.conch.avatar.ConchUser class represents the actions available to an authenticated SSH user. By default, ConchUser doesn't allow the client to do anything. To make it possible for the user to get a shell, make his avatar implement twisted.conch.interfaces.ISession. The SSHDemoAvatar class in Example 10-1 doesn't actually implement all of ISession; it only implements enough for the user to get a shell. The openShell method will be called with a twisted.conch.ssh.session.SSHSessionProcessProtocol object that represents the encrypted client's end of the encrypted channel. You have to perform a few steps to connect the client's protocol to your shell protocol so they can communicate with each other. First, wrap your protocol class in a twisted.conch.insults.insults.ServerProtocol object. You can pass extra arguments to insults.ServerProtocol, and it will use them to initialize your protocol object. This sets up your protocol to use a virtual terminal. Then use makeConnection to connect the two protocols to each other. The client's protocol actually expects makeConnection to be called with a an object implementing the lower-level twisted.internet.interfaces.ITransport interface, not a Protocol; the twisted.conch.session.wrapProtocol function wraps a Protocol in a minimal ITransport interface.

The library traditionally used for manipulating a Unix terminal is called curses. So the Twisted developers, never willing to pass up the chance to use a pun in a module name, chose the name insults for this library of classes for terminal programming.

To make a realm for your SSH server , write a class that has a requestAvatar method. The SSH server will call requestAvatar with the username as avatarId and twisted.conch.interfaces.IAvatar as one of the interfaces. Return your subclass of twisted.conch.avatar.ConchUser.

There's only one more thing you'll need to have a complete SSH server: a unique set of public and private keys. Example 10-1 demonstrates how you can use the Crypto.PublicKey.RSA module to generate these keys. RSA.generate takes a key length as the first argument and an entropy-generating function as the second argument; the twisted.conch.ssh.common module provides the entropy.get_bytes function for this purpose. RSA.generate returns a Crypto.PublicKey.RSA.RSAobj object. You extract public and private key strings from the RSAobj by passing it to the getPublicKeyString and getPrivateKeyString functions from the twisted.conch.ssh.keys module. Example 10-1 saves its keys to disk after generating them the first time it runs: you need to keep these keys preserved between clients so clients can identify and trust your sever.

Note that you wouldn't want to call RSA.generate after your program has entered the Twisted event loop. RSA.generate is a blocking function that can take quite some time to complete.

To run the SSH server , create a twisted.conch.ssh.factory.SSHFactory object. Set its portal attribute to a portal using your realm, and register a credentials checker that can handle twisted.cred.credentials.IUsernamePassword credentials. Set the SSHFactory's publicKeys attribute to a dictionary that matches encryption algorithms to key string objects. To get the RSA key string object, pass your public key as the data keyword to keys.getPublicKeyString . Then set the privateKeys attribute to a dictionary that matches protocols to key objects. To get the RSA private key object , pass your private key as the data keyword to keys.getPrivateKey . Both getPublicKeyString and getPrivateKey can take a filename keyword instead, to load a key directly from a file. Once the SSHFactory has the keys, it's ready to go. Call reactor.listenTCP to have it start listening on a port and you've got an SSH server .

Getting Started

Building Simple Clients and Servers

Web Clients

Web Servers

Web Services and RPC


Mail Clients

Mail Servers

NNTP Clients and Servers


Services, Processes, and Logging

Twisted Network Programming Essentials
Twisted Network Programming Essentials
ISBN: 0596100329
EAN: 2147483647
Year: 2004
Pages: 107
Authors: Abe Fettig © 2008-2020.
If you may any questions please contact us: