Go to file
Ask Bjørn Hansen 48059c122c r4215@g5: ask | 2006-01-24 23:11:01 -0800
From:   gordonr@gormand.com.au
 Subject: Re: Submitting plugins (was Re: New plugin: denybounce)
 Date: January 24, 2006 9:02:35 PM PST
 To:   ask@develooper.com
 Cc:   gavin@openfusion.com.au, qpsmtpd@perl.org
 Message-Id: <43D7066B.3050106@gormand.com.au>
 
 Ask Bjørn Hansen wrote:
 On Jan 24, 2006, at 1:08 PM, Gordon Rowell wrote:
 - License statement - either as per qpsmtpd or as per Perl or  similar open license
 No, it really should be MIT licensed ("as per qpsmtpd") to go in the  distribution.
 There are a few exceptions (only your plugins at a cursory glance),  but those are mistakes.  :-)
 
 I don't have an issue with my qpsmtpd plugins being changed to state:
 
 
 =head1 AUTHOR
 
 Copyright 2005 Gordon Rowell <gordonr@gormand.com.au>
 
 This software is free software and may be distributed under the same
 terms as qpsmtpd itself.
 
 
 Though as a distro maintainer, we do have a sizeable issue with license proliferation. It really is a bit of a nightmare when two licenses are almost, but not completely, the same.
 
 Thanks,
 
 Gordon
 
 r4216@g5:  ask | 2006-01-24 23:12:21 -0800
 merge license fix from trunk


git-svn-id: https://svn.perl.org/qpsmtpd/trunk@603 958fd67b-6ff1-0310-b445-bb7760255be9
2006-01-25 07:12:34 +00:00
config.sample Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00
lib Fix problems with tls and relay_client. 2006-01-05 02:21:32 +00:00
log Add -p to mkdir in log/run (Rasjid Wilcox <rasjid@openminddev.net>) 2002-11-20 10:15:06 +00:00
plugins r4215@g5: ask | 2006-01-24 23:11:01 -0800 2006-01-25 07:12:34 +00:00
t Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00
.perltidyrc Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00
Changes Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00
CREDITS Fix off-by-one line numbers in warnings from plugins (thanks to 2005-05-05 07:44:34 +00:00
LICENSE update the MANIFEST 2005-07-02 02:08:37 +00:00
Makefile.PL Update PREREQ_PM 2005-07-06 19:09:07 +00:00
MANIFEST Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00
MANIFEST.SKIP MANIFEST details added (so building a package is easier) 2004-09-05 16:45:05 +00:00
qpsmtpd Add force-poll option (in case your epoll is buggy) 2005-12-30 19:41:06 +00:00
qpsmtpd-forkserver Get forkserver working again 2005-12-30 20:03:22 +00:00
README Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00
README.logging Revamp Qpsmtpd::Constants so it is possible to retrieve the text 2005-03-29 20:15:53 +00:00
README.plugins r491@dog: rspier | 2005-07-07 20:32:53 -0700 2005-07-08 03:37:09 +00:00
run pass -R to tcpserver 2003-03-18 09:46:52 +00:00
STATUS Merge branches/0.3x back to trunk. 2005-12-22 21:30:53 +00:00

#
#  this file is best read with `perldoc README`
#

=head1 NAME

Qpsmtpd - qmail perl simple mail transfer protocol daemon

web:
  http://smtpd.develooper.com/

mailinglist:
  qpsmtpd-subscribe@perl.org


=head1 DESCRIPTION

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.


=head2 What's new in this release?

See the Changes file! :-)


=head1 Installation

=head2 Required Perl Modules

The following Perl modules are required:
   Net::DNS
   MIME::Base64
   Mail::Header (part of the MailTools distribution)

If you use a version of Perl older than 5.8.0 you will also need
   Data::Dumper
   File::Temp
   Time::HiRes

The easiest way to install modules from CPAN is with the CPAN shell.
Run it with

  perl -MCPAN -e shell

=head2 qpsmtpd 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 Subversion you can just do
run the following command in the /home/smtpd/ directory.

   svn co http://svn.perl.org/qpsmtpd/trunk .

Beware that the trunk might be unstable and unsuitable for anything but development, so you might want to get a specific release, for example:

   svn co http://svn.perl.org/qpsmtpd/tags/0.31.1 .

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.

The smtpd user needs write access to ~smtpd/qpsmtpd/tmp/ but should
not need to write anywhere else.  This directory can be configured
with the "spool_dir" configuration.

As per version 0.25 the distributed ./run script runs tcpserver with
the -R flag to disable identd lookups.  Remove the -R flag if that's
not what you want.


=head2 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 qmail is installed in a nonstandard location you should set the
$QMAIL environment variable to that location in your "./run" file.

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.


=head1 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."

Running under PPerl is easy - just change your "run" file to contain
the following command:

  pperl -Tw -- --prefork=$MAXCLIENTS --maxclients=$MAXCLIENTS \
    --no-cleanup ./qpsmtpd 2>&1

As an alternative to PPerl (some users find PPerl unstable) we recommend using
the forkserver. This forks for every connection, but pre-loads all the plugins
to reduce the overhead.

=head1 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.


=head1 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: 

=over 4

=item 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).


=item 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.


=item dnsbl_zones

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

  relays.ordb.org
  spamsources.fabel.dk


=item 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).


=item 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.


=item 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).
     
=back



=head1 Problems

In case of problems always 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.