
                          Pynfo README

  Please send problems and feedback to exarkun@twistedmatrix.com

Contents:
=========

0. What is Pynfo?
1. Dependencies
2. Installation
3. Running
4. Plugins
   4.1 Plugin API
   4.2 InfoBotFactory

0. What is Pynfo?
=================

  Pynfo is a combination IRC infobot, search bot, and network relay.  It
supports basic fact definition (with persistence between runs), searching of
Google and Freshmeat.  As a network relay, it can "bridge" channels on
multiple networks - that is, pass messages between them.  It also has a
plugin interface, allowing users to easily define new commands.


1. Dependencies
===============

  1) Python 2.2 or later     - http://www.python.org/
  2) Twisted 1.0.2 or later  - http://www.twistedmatrix.com/
  3) PyCrypto 1.9 or later   - http://pycrypto.sourceforge.net/


2. Installation
===============

  First, ensure that Twisted and PyCrypto are in your PYTHONPATH environment
variable or your Python site-packages/ directory.  If they are, the command

    python -c "import twisted; import Crypto"

  will run with no errors (and no other output).

  Pynfo uses Python's distutils package for installation.  If you're on
Windows, this means you just run the installer.  If you're on *nix, just run

    python setup.py install

  and you're [almost] set.  To install to a path other than the system-wide
Python install directory, you can specify the --prefix parameter.  You will
have to modify PYTHONPATH to ensure that the alternate install directory is
in Python's search path.  One cavaet: neither of the two plugins.tml files
will be correctly installed if you specify the --prefix parameter.  You will
have to copy them both into the correct directories before Pynfo will
function properly. 

  See the NEWS file for release-specific notes.

3. Running
==========

exarkun:~$ mktap infobot --help
Usage: mktap infobot [options]
Options:
      --pwdauth    Use password authentication
  -n, --nick=      Bot nickname [default: pynfo]
  -s, --server=    IRC server hostname [default: irc.freenode.net]
  -p, --port=      IRC server port [default: 6667]
  -a, --alias=     IRC network alias [default: opn]
      --datadir=   Path to place database files [default: info.db]
  -b, --bits=      Bits in secure command RSA key [default: 128]
  -h, --webhost=   Hostname on which to listen for http queries [default:
                   your.host.name]
  -w, --webport=   Port to listen on for Shorter Link connections
  -d, --distport=  Port to on which to publish distributed resources
      --owner=     The name of a user to grant special access
      --version
      --help       Display this help and exit.
      --channel=   The name of a channel to join upon connecting to the server


  Unless you plan to run the bot on OPN (Now Freenode), you'll want to
specify the --server and --alias options.  Specify at least your own nick
with --owner, or you won't be able to direct the bot to perform any actions.
After running this command, you will have "infobot.tap" as well as an
info.db/ directory.  Run

    twistd -f infobot.tap

  to have the bot connect to the network.  The bot will write error and info
messages to twistd.log.  To shut the bot down, run

    kill `cat twistd.pid`

  This will cause "infobot-shutdown.tap" to be created.  Simply move this
file over the original "infobot.tap" file.

  Pynfo creates an RSA key to authenticate "secure"-level commands.  This
key is stored within the info.db/ directory.  Keep it safe -- anyone who
obtains a copy of it may be able to execute arbitrary code on your computer. 
The --bits option controls how many bits will be in the secure key; note
that the more bits, the longer the challenge and response phrases will be.
Use the bin/respond script in the source tree to generate the proper
responses to the challenges; either run it in the directory that contains
the info.db/ directory, or specify the path to info.db/ as an argument to
the script.

  Challenges are sent through private queries, but network operators may be 
able to monitor these.  Because an RSA key can be cracked in a relatively 
short amount of time (several weeks on a relatively modern CPU or several 
days on a dedicated cluster), you should have any bots you run on a regular 
basis regenerate their keys with the "regenerate" command, or remove any 
potentially dangerous plugins (including the built-in "spill"!).  Also note 
that Pynfo has not been security audited.  I believe the code to be secure 
(with the above exception), but I make no promises!

  The --webport and --distport options specify the port Pynfo's shorter link
and conversation webserver will listen on.  --webport is for normal HTTP
connections and --distport is for Twisted's Distributed Web service.  If
--webport is not specified, Pynfo will not announce shortened links to the
channel, though it will still maintain an internal cache of shortening
links.  If neither option is specified, neither the shorter links nor the
conversation logs will be available via any URL.

  The --pwdauth option causes users issuing privinfo-level commands to be
authenticated using a password query, rather than checking the network's
Services to see that the user has identified themself with NickServ.  For
networks without Services, this option is a must.


4. Plugins
==========

  Recently, support for arbitrary command plugins was added to Pynfo. 
Plugins are loaded with Twisted's standard plugin framework, so writing a
new plugin (or set of plugins) consists of four steps:

 1) Create a package:
   A package is any directory with a file named __init__.py in it.

 2) Place plugin modules in the package directory:
   These should be python code modules that define functions beginning with
   'info_', 'privinfo_' or 'secure_'.  See the include plugins for examples.

 3) Create a plugins.tml file and place it in the package directory:
   This registers your plugins.  An example of what might be in this file:

    register('Operator commands',
             'pkg.operator',
             description="Commands to let Infobot act as a channel op",
             type="infobot")

    The first string is the name of the plugin; the second is the qualified
    name of the module for import.

 4) Lastly, ensure the newly created package is in the import search path. 
    This is system dependant, but entails adding the directory the package
    is in (*not* the package directory itself) to the PYTHONPATH environment
    variable.

4.1. Plugin API
===============

  A plugin module can optionally define one or both of the names "init" and
"fini".  init will be called when the plugin is first loaded, and again
after a "rebuild" command is successfully issued.  fini will be called when
the application is preparing to shut-down, as well as before a "rebuild"
command is executed.

  Each of these functions is passed the InfoBotFactory instance as the only
parameter.

4.2. InfoBotFactory
===================

  The InfoBotFactory currently has adapters for two interfaces, IStorage and
IScheduler.  These interfaces are defined in "interfaces.py".  For example
usage, see the pypi plugin.
