Basic instructions for running the user agent:

N.B.: I've been running on debian unstable. If you're using debian/stable,
you may need to manually install some stuff. The canonical install process
for python modules (like the perl Makefile.PL recipe) is:

 unpack tarball
 python ./setup.py build
 python ./setup.py install --prefix=/usr/local


DEPENDENCIES:

 python-2.3
  (debian package python2.3, python2.3-dev [for distutils])

 twisted-1.1.0 or newer
   if running debian 'unstable'
     add 'deb http://twisted.sourceforge.net/debian/ ./' to your
     /etc/apt/sources.list, install 'python2.3-twisted'

 gnupg
  (debian package gnupg)
  (this is not strictly necessary because it requires code in Twisted that
   hasn't been released yet. If you are running Twisted-1.1.1 or later, you
   can comment out the line that talks about 'FakeEncryptionAgent' in gui.py
   to enable real crypto. Once a version of twisted with childFDs={} support
   is released, real crypto will become the default)

 python-gtk bindings
  (debian packages python2.3-gtk2, python2.3-glade2, python2.3-gnome2)

 python-imaging
  (needed to run a ticket server, or to run the self-tests)


SETUP:

 You must decide how you will receive messages. There are currently four
 possibilities:

 IMAP: specify an IMAP server and the usual parameters (host/port, username,
       password, folder name, polling interval). The agent will poll the
       server for messages. It will consume any that have a subject line of
       "PETMAIL MESSAGE" and should leave the others untouched. It is a good
       idea to route your petmail messages to a separate folder.

 Maildir: set up a .qmail-petmail that delivers messages to a separate
   maildir, say with:

     maildirmake ~/Maildir-petmail
     echo "./Maildir-petmail/" >~/.qmail-petmail

 Mailsocket: choose an unused TCP port, then set up a .qmail or .forward which
   dumps the messages into that port, like:

     echo "nc localhost 9999" >.qmail-petmail

 Direct TCP connection (over PB): pick an unused (globally-visible) TCP port,
   and senders will connect to it directly. Only useable if your host (or at
   least that port) is reachable from the internet-at-large
   

RUNNING:

 'petmail'

 This will create a new Gtk-based agent and put all saved state in the
 "~/.petmail/" directory. The agent will default to using fake crypto stubs
 (until the new Twisted release comes out). You can see what other options
 are available by doing 'petmail --help'.


SETUP:

 The first step is to set up the generic configuration of your agent. You do
 this through the 'Setup' option from the File menu, and you should at least
 set the "Address Lookup" field before creating any new Identities.

  Address Lookup: this tells the agent where it should go when it needs to
   turn an address into an IDRecord. It also specifies where your IDRecord
   should be published whenever it changes. For now choose the PB option,
   hostname "lothar.ath.cx" and port 9998, as I am running a simple address
   server there. There is a web page at <http://lothar.ath.cx:9999/> at which
   you can see a list of all published records and their contents. There are
   also links to let you delete the records from that server, since during
   testing we'll probably create lots of temporary identities that will need
   to be discarded easily.

  SMTP: This tells the agent how to send outgoing SMTP mail (for recipients
   who have specified a 'Maildir' or 'Mailsocket' inlet). It provides a way
   to specify that all outbound mail should go through a remailer, but for
   now it just gives you a way to specify a smarthost and the "from" address
   for all messages. The 'from' address doesn't really matter (PETMail
   ignores it on receipt), but is a good idea to help recipients figure out
   where these strange messages are coming from.

   If your host is running a capable MTA like qmail or exim or postfix or
   whatever, use "localhost" as the relay host and fill in your email address
   for the From field. If you must send all your mail through, say, your ISP,
   use your ISP's SMTP host as the relay host instead.

  NNTP: ignore this for now, it is intended to let you tell the agent how to
   get to an NNTP server (for transports that involve posting messages to
   alt.anonymous.messages).

 The next step is to create a new Identity. Eventually this will be replaced
 by some kind of walk-through wizard or something. The "Me" pane covers
 everything about yourself. Hit the "Create New Identity" button, then edit
 the following fields of the pane that pops up:

  Local name: this gives the Identity a local name to distinguish it from
   any other Identities you might create. It is used in two places: the
   first is AddressBook pane, where you choose which address book to look at
   (each Identity has a separate addrss book). The other is the From field
   of the message composition window (the Send pane). You can use any name
   you wish here: it is never published or transmitted.

  Name: fill in the name you would like to be known as. This will appear in
   the IDRecord and in a recipient's address book entry for you (until they
   assign you a local pet name).

  Addresses: for now, pick an arbitrary email address. This is published in
   your IDRecord as one of the addresses that you are known by. It is only
   used for address lookups, not for transport.

  Inlet: based upon what kind of setup you picked earlier, provide an "Inlet
   String". For Maildir and Mailsocket, this will include the email address
   that dump mail into the inlet. (the local maildir location or mailsocket
   port number are not published, but the email address to which senders
   must deliver their encoded messages will be). Some examples:

   PB : localhost : 9998
    this tells senders to connect directly to localhost:9998, and is obviously
    only useful for testing on the same host

   PB : lothar.com : 9998
    this would be useful if the agent is reachable from the outside world on
    host lothar.com

   IMAP : host/port/user/passwd/folder : warner-petmail@lothar.com
    This tells the rest of the world to send their messages to
    warner-petmail@lothar.com, and tells the agent that it should poll an
    IMAP server for those messages.

   Maildir : ~/Maildir-petmail : warner-petmail@lothar.com
    This tells the rest of the world to send their messages to
    warner-petmail@lothar.com, and tells the agent that it should poll a
    maildir in ~/Maildir-petmail/ for those messages. It requires that
    you've set up a .qmail or equivalent to get those messages into the
    right maildir.

   Mailsocket : 9998 : warner-petmail@lothar.com
    This tells the rest of the world to send messages to
    warner-petmail@lothar.com, and tells the agent to listen for simple TCP
    connections on port 9998. This requires that our .qmail or .forward uses
    'nc' or an equivalent to dump messages into our local TCP port 9998.

 Once you've filled in all of these fields, press "OK". That will save your
 configuration to disk and also publish it to the address server. (then hit
 Close to close the window). Look at <http://lothar.ath.cx:9999/> and make
 sure that your entry is now there.

 You can change any field and the "Ok" button will become active once more:
 pushing it again will re-publish your record. You can access this Identity
 panel by double-clicking on the entry in the "Me" pane.

 You can test out the IMAP and Maildir polling routines by bringing up the
 Owner pane and hitting the "Poll Now" button. A short while later, a dialog
 box should pop up to display the success or failure of the result.

SENDING MAIL:

 Go to the "Send" pane, type in an address in the "To:" field, a subject and
 body, and then hit "Send". This will go through the permission-checking
 process and send the message.

 The From: field lets you choose which Identity will be used to send the
 message. "-anonymous-" is not yet implemented, but will eventually make the
 message anonymous (unsigned and sent through a source-hiding channel if
 possible). The names shown here are your local names for the Identities, the
 same as shown in the list on the "Me" panel.

 The To: field will accept either a "pet name" or an Address. Addresses are
 looked up with the Address Server to figure out how to send the message.
 Each time an address is looked up this way, the resulting ID Record is
 added to a new entry in your address book.

RECEIVING MAIL:

 Go to the "Inbox" pane. Any inbound messages will be displayed there. Note
 that the inbox is not currently persistent: when you quit, all these
 messages will disappear.

ADDRESS BOOK:

 Go to the "Addresses" pane. New entries are added to your address book in
 one of three ways:

  typing an address into the panel at the bottom and pushing "Lookup".

  sending a message by address (instead of by pet name)

  receiving a message from a new sender

 Select an entry from the list on the left to see details about this
 identity. You can specify a local "pet name" for each by typing it into the
 "Pet Name" field at the top and hitting RETURN. Most of the fields are
 read-only, and correspond to fields in that identity's owner's "Me" pane.

 You can set per-sender inbound restrictions by changing the entries for
 "minimum inter-message time", "maximum message size", and "accept HTML
 mail". (note that these are not yet implemented).

PERMISSION SERVERS:

 To specify that you require new senders to include a ticket from a CAPTCHA
 server, you put the URLs of those ticket servers (comma separated) in the
 "Ticket URLs" field in the "Identity" pane. This is a part of your ID
 Record: once you add the URLs, push the "Ok" button to publish the updated
 record.

 For now, the only permission server is a simple one I'm running at home,
 with a URL of: "PB:lothar.ath.cx:10002".

QUITTING:

 Use the File/Quit menu item to quit, so any changes you have made will be
 saved.

Good luck!
 -Brian