INSTALL - How to install Herbrip
================================

By Philip Hunt, last altered 28-Jan-2002.


* Firstly, you must download the herbrip tarball and untar it. You
must have got that far to be reading this.

* Make sure you have Python and OpenSSL installed. You need Python
2.0 (I've not tried it on later versions), and OpenSSL 0.9.6 or
0.9.6a. The openssl executable should be at:

   /usr/local/ssl/bin/openssl
   
If it isn't, you must either create this file (e.g. as a symbolic
link to the real executable, or alter this line 9about line 50)
in herbrip/src/encwrap.py:

   OPENSSL_CL = "/usr/local/ssl/bin/openssl"

* Add the herbrip/src/ directory to your path. 

* Go into herbrip/test/ and run the test program:

   $ python test_herbrip.py
   
When you run this, you will get a lot of messages on your console.
Assuming everything works, the last line will be something like:

   ***** TESTS COMPLETED SUCCESSFULLY ! *****

* Initialise Herbrip. 

From the command line type:

   $ herbrip --create
   
This will create a Herbrip directory, ~/.herbivore/   

It will also create your public/private keypair. There is a file
<~/.herbivore/config> that contains configuration values; you will
have to edit this later.

To check that Herbrop has initialised, type:

   $ herbrip --info
   
It will reply something like:   

   herbrip-0.3.2. Copyright (c) 1999-2002 Philip Hunt.
   
   Herbivore protocol version: 0.3.1
   Herbivore directory: /home/demouser/.herbivore
   secret key file: /home/demouser/.herbivore/secret_keys
   public key file: /home/demouser/.herbivore/public_keys
   user has 0 public keys.
   Configuration values:
      dest = 'file:mess_out_%(ix)s'
      log = 1
      logItems = ('cmd', 'comment') 

* set up herbrip to automatically intercept your incoming and
outgoing email. This is the most complex step, so firstly a note on
how email works. This may not apply exactly to your installation,
so please be prepared to experiment.

Incoming email comes in using the POP3, IMAP or smtp protocols. The
first two are often fetched by the client (i.e. your PC) pulling
the data off a POP3/IMAP server; the fetchmail program is often
used to do this; fetchmail typically sends the messages to sendmail
for further processing. The last is likely from a remote smtp server
pushing emails onto your smtp server (which is likely to be
sendmail).

Sendmail can be set up to send incoming email to procmail. Procmail
is a program for pre-processing incoming mail, which is ideal for
our needs. So we need to set up procmail.

To do this create va file ~/.forward with this line in it:

   "|/usr/bin/procmail"  
   
Then create a file ~/.procmailrc. Mine looks like this:

   # .procmailrc
   # for Philip Hunt
   # last altered 27-Jan-2002

   # Directory for storing procmail configuration and log files
   PMDIR=$HOME/Procmail

   # Logging:
   LOGFILE=$PMDIR/log
   LOG="
   "
   VERBOSE=no
   MAILDIR=$HOME/Mail      # Make sure this directory exists!

   :0 f
   * ^X-Herbivore.*
   | /home/philh/proj/herbrip/src/herbrip_pin

   #end .procmailrc

(If you have difficulty setting up Procmail, there are instructions
at: <http://www.ii.com/internet/robots/procmail/qs/>).

This deals with processing of incoming email. Now we need to
intercept outgoing email. This is done by sending the output that
would go from the MUA to sendmail, and sending it to herbrip_csm
instead.

With the kmail MUA, this is achieved by:

   * from the menubar, select Settings -> Configuration...
   * this displays a dialog box. Select "Network" on the left
   * under "Sending mail" select the "sendmail" radio button
   * in the "Location:" field type in the full path to your herbrip_csm
     executable; on my system this is:
        /home/philh/proj/herbrip/src/herbrip_csm

* After herbrip_csm has processed the mail message, it needs to know 
where to send it for final output. This is determined by the (dest)
variable in the ~/.herbivore/config file. You need to edit this file,
telling herbrip that you are using the sendmail protocol and the
full path to the sendmail executable on your system. On my system, the
dest variable is defined as:

   dest = "sendmail:/usr/sbin/sendmail"

Set your up appropriately.

Anmd that's it! You are now ready to use Herbrip! 

;end.
