qpsmtpd/README

Qpsmtpd - qmail perl simple mail transfer protocol daemon
---------------------------------------------------------

web:
  http://develooper.com/code/qpsmtpd/

mailinglist:
  qpsmtpd-subscribe@perl.org


What is Qpsmtpd?
----------------

Qpsmtpd is an extensible smtp engine written in Perl.  No, make that
easily extensible!  See plugins/quit_fortune for a very useful, er,
cute example.


What's new in this release?
---------------------------

See the Changes file! :-)


What's new in version 0.1x from 0.0x?
-------------------------------------

Version 0.1x is all rearchitected, with an object oriented plugin
infrastructure.  Weeh, that sounds fancy!  Of course it is keeping the
well tested core code from version 0.0x which have had more than a
years production usage on many sites.

Noteworthy new features includes a SpamAssassin integration plugin,
more documentation and support for arbitrarily large messages without
exhausting memory (up to the size of whatever your file system
supports).


Installation
------------

Make a new user and a directory where you'll install qpsmtpd.  I
usually use "smtpd" for the user and /home/smtpd/qpsmtpd/ for the
directory.

Put the files there.  If you install from CVS you can just do
  cvs -d :pserver:anonymous@cvs.perl.org:/cvs/public co qpsmtpd
in the /home/smtpd/ dir.

chmod o+t ~smtpd/qpsmtpd/ (or whatever directory you installed qpsmtpd
in) to make supervise start the log process.

Edit the file config/IP and put the ip address you want to use for
qpsmtpd on the first line (or use 0 to bind to all interfaces).

If you use the supervise tools, then you are practically done now!
Just symlink /home/smtpd/qpsmtpd into your /services (or /var/services
or /var/svscan or whatever) directory.  Remember to shutdown
qmail-smtpd if you are replacing it with qpsmtpd.

If you don't use supervise, then you need to run the ./run script in
some other way.


Configuration
-------------

Configuration files can go into either /var/qmail/control or into the
config subdirectory of the qpsmtpd installation.  Configuration should
be compatible with qmail-smtpd making qpsmtpd a drop-in replacement.

If there is anything missing, then please send a patch (or just
information about what's missing) to the mailinglist or to
ask@develooper.com.


Better Performance
------------------

As of version 0.21 qpsmtpd supports "PPerl"
http://search.cpan.org/search?dist=PPerl

"PPerl turns ordinary perl scripts into long running daemons, making
subsequent executions extremely fast. It forks several processes for
each script, allowing many processes to call the script at once."


Problems
--------

First, check the logfile.  As default it goes into log/main/current.
Qpsmtpd can log a lot of debug information.  You can get more or less
by adjusting $TRACE_LEVEL in lib/Qpsmtpd.pm (sorry, no easy switch for
that yet).  Something between 1 and 3 should give you just a little
bit.  If you set it to 10 or higher you will get lots of information
in the logs.

If the logfile doesn't give away the problem, then post to the
mailinglist (subscription instructions above).  If possibly then put
the logfile on a webserver and include a reference to it in the mail.


Configuration files
-------------------

All the files used by qmail-smtpd should be supported; so see the man
page for qmail-smtpd.  Extra files used by qpsmtpd includes: 

   plugins

      List of plugins, one per line, to be loaded in the order they
      appear in the file.  Plugins are in the plugins directory (or in
      a subdirectory of there).


   rhsbl_zones
 
      Right hand side blocking lists, one per line. For example:

          dsn.rfc-ignorant.org does not accept bounces - http://www.rfc-ignorant.org/

      See http://www.rfc-ignorant.org/ for more examples.


   dnsbl_zones

      Normal ip based dns blocking lists ("RBLs"). For example:

         relays.ordb.org
         spamsources.fabel.dk


   require_resolvable_fromhost
         
      If this file contains anything but a 0 on the first line,
      envelope senders will be checked against DNS. If an A or a MX
      record can't be found the mail command will return a soft
      rejection (450).


   spool_dir

      If this file contains a directory, it will be the spool
      directory smtpd uses during the data transactions. If this file
      doesnt exist, it will default to use $ENV{HOME}/tmp/. This
      directory should be set with a mode of 700 and owned by the
      smtpd user.


  ... everything (?) that qmail-smtpd supports. 

      In my test qpsmtpd installation I have a "config/me" file
      containing the hostname I use for testing qpsmtpd (so it doesn't
      introduce itself with the normal name of the server).
     


Plugins
-------

The qpsmtpd core only implements the SMTP protocol.  No useful
function can be done by qpsmtpd without loading plugins.

Plugins are loaded on startup where each of them register their
interest in various "hooks" provided by the qpsmtpd core engine.

At least one plugin MUST allow or deny the RCPT command to enable
receiving mail.  The "check_relay" plugin is the standard plugin for
this.  Other plugins provides extra functionality related to this; for
example the require_resolvable_fromhost plugin described above.