$Cambridge: hermes/src/prayer/docs/INSTALL,v 1.6 2008/04/10 09:52:07 dpc22 Exp $

Important
=========

Prayer v1.1.0 automatically upgrades existing preferences mailboxes to
UTF-8. If you need to downgrade for any reason, use v1.0.20, which
transliterates back to ISO-8859-1. Otherwise preferences are discarded.

Systems
=======

Prayer has been ported to the following operating systems so far:
    SLES 10          (this is what we currently use)
    SuSE Linux 9.x
    Redhat Linux 9.x (I suspect that Fedora will work fine)
    FreeBSD 4.x
    Solaris 2.6 and 8.

    Other Unices should work with minimal porting effect: there is very
    little OS specific code in Prayer.

Requirements:
  imap-2007 c-client toolkit
  A decent iconv library, such as GNU iconv.
  zlib                         (optional, if GZIP compression desired)
  openssl-0.9.6.               (optional, if SSL desired)
  Berkeley DB 3 or 4           (optional, if SSL session cache desired)
  GNU make. GCC (or SUNWspro compiler on Solaris).

INSTALL procedure:

1) Create a system account user and group named "prayer". On Redhat Linux:

     # useradd -r prayer

2) Configure your mail transfer agent so that the prayer user or group is
   able to change the envelope sender field using the "-f" command line
   option. Otherwise mail bounces will all go to the Prayer user.

   Exim:      "trusted_users" or "trusted_groups" option
   Sendmail:  T option or Class "t" (/etc/mail/trusted-users on Redhat).
   Other MTA: Please read the documentation that comes with your MTA.

   Prayer may eventually send messages using SMTP to a nominated SMTP
   smarthost. This route just seemed simpler for the first iteration...

3) Install the PRNG package if your system doesn't provide /dev/urandom for
   crypographically secure random numbers (at the moment this only applies
   to Solaris). PRNGD can be found at:

    http://ftp.aet.TU-Cottbus.DE/personen/jaenicke/postfix_tls/prngd.html

4) Install the OpenSSL libary if you want to support secure logins.
   Redhat Linux RPMs: openssl and openssl-devel 

5) Install Berkley DB v3 or v4 if you have installed OpenSSL and want an
   SSL session cache. Redhat Linux RPMs: db3 and db3-devel

   The latest version of Berkeley DB should be available at:

      http://www.sleepycat.com/download.html

6) Install the c-client library. Prayer should be compatible with the
   IMAP 2000, 2001 and 2002 distributions. Redhat Linux RPM: imap-devel.

   The latest version of c-client should be available at:

      ftp://ftp.cac.washington.edu/imap/imap.tar.Z

   If you want Prayer to support IMAP sessions tunnelled over SSL as well
   as HTTP connections tunnelled over SSL then you will need to build c-client
   with SSL support. e.g:

     make slx SSLTYPE=unix SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib

  You may find that you need to set up a certificate authority bundle so
  that c-client recognises the certificate used by the server.

  An OpenSSL installation will typically look for its certificate bundle as
  a file named cert.pem in its installation directory (this file is
  preinstalled on RedHat). Alternatively you can add a "/novalidate-cert"
  flag to the end of the imapd_server option outlined below).

The rest of this build process defaults to a c-client distrution which
is unpacked at the same level as Prayer with a symbolic link "imap" e.g:

   lrwxrwxrwx 1 dpc22 dpc22 30   May 31 17:32  imap -> imap-2001.BETA.SNAP...
   drwxr-xr-x 6 dpc22 dpc22 4096 Sep 27 09:37  prayer-0.7.0

However this is easy enough to change in the Config file in the next step.

7) Check "Config" in the root directory of the distribution. This file
   defines compiler options and the location of files and is included by
   all the Makefiles in this and subsiduary directories.

8) Build the prayer binaries (needs GNU make)

     $ make

9) [Optional] Make a self-signed certificate for testing purposes:

     $ make cert

10) [Optional]. Test the ./prayer binary in the "prayer" subdirectory.

     $ cd prayer
     $ ./prayer --config-file=./prayer-debug.cf

     The standard prayer-debug configuration connects to the IMAP server on
     localhost. This can be overridden by changing the configuration file
     or adding a --config-option to override settings in the file. Examples:

        --config-option imapd_server=remote_system      # Plaintext IMAP
        --config-option imapd_server=remote_system/ssl  # IMAP over SSL
        --config-option imapd_server=localhost:8143     # SSH Port forwarding

  This should start up a Prayer Webmail service listening for plaintext
  HTTP connections on port 8080. It is easy to add SSL HTTP connections on
  port 8081 (using a self-signed certificate for the SSL connections),
  by uncommenting the "use_https_port" line in the configuration file.

11) Install the binaries and support files.

     # make install

   This automatically runs "make install-config" and "make install-cert"
   if the relevant files do not already exist.

12) Edit the main prayer configuration file to match your needs. The
    location is defined in the CONFIG file and the default location is
    "/usr/local/prayer/etc/prayer.cf". The values most likely to change are
    at the top of the file. The section "SSL NOTES" above applies here too.

13) Create a suitable startup file. On Redhat Linux: "make redhat-start" does:

     # cp defaults/prayer-redhat /etc/rc.d/init.d/prayer
     # chkconfig prayer on
     # /etc/init.d/prayer start

Regular maintainance:
=====================

prayer-ssl-prune:
  Removes expired sessions from the SSL session cache 
  (Sessions set up to expire after config->ssl_session_timeout seconds)

prayer-db-prune:
  Clear obsolete entries from the Berkeley DB transaction log used
  by the SSL session cache. Otherwise it will grow indefinitely.

prayer-sem-prune:
  Remove a give semaphore after prayer is shut down.
  Only use this if MUTEX_SEMAPHORE is in use.

