A BRIEF INTRODUCTION

 Portnanny is a frontend for a TCP/IP service that classifies incoming
connections into classes and then applies limits and options based
on those classes. Unlike inetd it sits in front of only a single port
(in this respect and no other it is like Daniel Bernstein's tcpserver
program).

 Portnanny is used when one needs limitations such as 'internal users
can have 50 simultaneous connections; external users can have 30
simultaneous connections; and in no case will we allow more than 75
simultaneous connections overall'. It can limit connections based
on two criteria: simultaneous connections from a single IP address,
or simultaneous connections in a particular class (including the
class of all connections).

 Portnanny has a rich vocabulary of classification methods.

 As a front end, portnanny spawns another program to do the real
work. (Unless portnanny rejects a connection and has a rejection
message set, in which case that is handled internally.)


 CONTROL

 Portnanny has one overall configuration file; this file sets some
global options and then names the classification control file and the
limitations control file (classfile and limitsfile in much terminology).
The overall configuration file is loaded once, but the two subfiles
(and any files they include in turn) are reloaded dynamically when they
change. Parse errors are handled gracefully.

 Someday portnanny will have real documentation. In the mean time
there is the commentary in nanny.conf, in testclassfile, and in
testlimits. The commentary is believed to be both accurate and
complete, but the author can't speak for its clarity.

 INVOCATION

 Portnanny takes some options. See portnanny.tmpl's comments
at the top for what they are and what they do.


 OTHER THINGS YOU'LL NEED

 You'll need the Python modules netblock.py and ranges.py, which
should be available from where you got Portnanny.

 INSTALLATION

 See Makefile. Edit '/u/cks/share/python' into wherever you put
netblock.py and ranges.py. Edit elsewhere as appropriate. The
incantation for building the groups.so shared object is only
known to work on Red Hat Linux (7.1 & 7.3); you're on your own
for anything else. The author welcomes feedback.


 SECURITY

 Portnanny is written in Python and so should be free of buffer
overruns, barring a flaw in the Python implementation.

 Portnanny can be run as root so as to be able to bind to restricted
ports; in this case an alternate user can (and should) be specified.
When an alternate user is specified portnanny does its best to turn
itself into that user as fast as possible and to die if it fails to
do so.

 Portnanny is not controllable from the network in any way. In fact
it is only barely controllable from the local machine; it accepts
one signal to dump internal connection state to its reporting
method and that's it.


 COPYRIGHT

 Eventually there will be a nice GPL declaration here. In the mean
time please don't distribute this; this is a work in progress.