# Twisted Plugin Example

## Goal

The Goal of this repo is to provide the basic template around which you can quickly create a twisted server that is installable from 'setup.py' into a virtualenv that will start on boot.

## Service Definition

Look at exampleproject.examplemodule, this module is a quick skeleton that shows you one way to quickly start a server running on a custom listening endpoint.

String endpoints are a twisted technique for defining addresses for listening or connection that allow us to swap out tcp for unix sockets or ssl without a fuss. Example endpoints are 'tcp:8080', 'tcp:1000:interface=12.34.56.12', 'unix:/var/tmp/foo'.

If you examine exampleproject.examplemodule.make_service you can see how to set up an arbitrary number of servers listening on different endpoints, and SetupService can be used to do whatever extra initialisation your software requires before it can be run.

## Running The Example

Provided that the exampleproject is in the PYTHONPATH you may run these commands:

# help on the twistd flags
twistd --help

# help on the plugin flags
twistd example --help

# start the daemon in various different configurations
twistd -n example --strport tcp:8081
twistd -n example --strport tcp:8082 --debug
twistd -n -r epoll example --strport unix:/var/tmp/example-unix-socket


You may specify any reactor in the twistd -r argument, you may specify any endpoint description in the strport, and it will set up a little listening server.

## Running on Boot

This is an appropriate way of running a daemon on boot, from a supervisor of some kind, or from an init.d script:

/usr/bin/twistd --reactor=epoll --nodaemon \
--syslog --prefix=example \
--pidfile=/var/run/example.pid \
--uid=nobody --gid=nobody \
example --strport tcp:81


Breaking down these options:

• --reactor=epoll is a more efficient reactor implementation.
• --nodaemon stops twisted from daemonising, and will run it in the foreground omit --nodaemon, unless you are running under a supervisor.
• --syslog and --prefix provide logging to your OS syslog daemon.
• --pidfile will save the pid in an appropriate place.
• --uid and --gid will drop privs to the nobody user (uid 1)

No output will be seen on your terminal if you test this command. Look in /var/log/syslog or /var/log/messages to see the logs.