News::Gateway version 0.42
(Robomoderation and mail to news gatewaying toolkit)
Copyright 1997, 1998 by Russ Allbery <
[email protected]>. This program
is free software; you may redistribute it and/or modify it under the
same terms as Perl itself.
Individual modules and examples may be written by other authors; if so,
they will have their own copyright information at the beginning of the
code.
INTRODUCTION
Welcome to my attempt to do robomoderation, moderation support, mail to
news gatewaying, and news to mail gatewaying right.
Essentially, robomoderators, moderation support programs, and mail to
news gateways are all the same thing. They take an incoming message,
from either an MTA or from a user filtering program like procmail, or
perhaps even directly from a user's MUA, perform a variety of rewrites
required to turn an RFC 822 message into an RFC 1036 message, possibly
perform a variety of checks and additional rewrites suited to the
particular application, and then hand the message off to a news server.
News to mail gateways just do exactly the same thing in reverse.
From extremely simple procmail hacks through Rich Salz's newsgate
program to the variety of robomoderators and moderation support packages
written (most notably, Igor Chudov's STUMP), a variety of people have
tackled different aspects of this problem, but nearly every effort was
aimed at a particular view or hard-coded various assumptions, and as a
result the wheel has been reinvented a ridiculous number of times.
This is an attempt to generalize out the framework, so that people don't
have to keep writing the same code to read e-mail messages, post
messages, send e-mail messages, and do the common rewrites, and instead
can concentrate on the *interesting* parts, namely the checks and
rewrites they need for their specific application. News::Gateway is
*not* a robomoderator or gateway in and of itself. Rather, it's a
toolkit for *building* robomoderators and gateways that attempts to take
care of all of the nitpicking details for you and drastically decrease
the amount of code you have to write. And if your problem happens to
coincide with one of the supplied example programs, you may not have to
write any code at all.
It furthermore sets up a consistent interface for those additional
checks and rewrites, so once they're done they can be generalized and
included in the News::Gateway distribution and someone else who is
trying to solve the same problem can just use (or work with) the
existing code. This concept of News::Gateway as a library of reusable
modules is inherent in its design.
REQUIREMENTS
News::Gateway being a Perl module, it obviously requires Perl. With
great restraint, I've kept myself from requiring Perl 5.004. But
version 5.003 is probably required; earlier versions have some fairly
severe bugs. I highly recommend you upgrade to 5.004 if at all possible
since there are very significant bug fixes over 5.003.
News::Gateway also requires Andrew Gierth's excellent News::Article
module (and in fact can be viewed largely as a wrapper around that
module). It may require Net::NNTP depending on what you're doing, and
News::Article also requires Net::NNTP and PGP::Sign, both of which are
on CPAN. All required modules are available from CPAN. News::Article
is also at <URL:
http://www.erlenstar.demon.co.uk/perl/index.html>, and
both the latest version of this module and PGP::Sign can be obtained
from <URL:
ftp://ftp.eyrie.org/pub/software/modules/>.
OVERVIEW
I view the process of constructing a robomoderator or mail to news
gateway as having fundamentally three levels. First, there's the basic
framework that reads in the incoming message, reads any implementation-
specific information, runs a variety of checks and rewrites, and posts
the result. Next, there is the implementation of the checks and
rewrites. Finally, there's the code that specifies what checks and
rewrites to apply in any given case, provides implementation-specific
(or even invocation-specific) arguments to them, and takes fallback
actions based on the outcome.
This package implements the first level, and provides a framework for
collecting implementations of the second level (along with providing a
bunch of standard second-level modules). So far, the only third-level
support provided is a few examples.
News::Gateway takes its information on what to do to incoming articles
from three basic sources. First, one tells it what what modules to
apply to incoming articles. Some modules take no additional information
and just do one simple thing the same way to every message. Second, for
those modules that do require additional information, News::Gateway can
read and parse a configuration file and pass directives along to
individual modules, or you can give it configuration directives
directly. Each module registers an interface that tells the
News::Gateway core code which directives it's interested in. Third,
there are some pieces of information modules need to know which may be
invocation-specific. For example, for a mail to news gateway, the same
script and configuration file may be usable for every newsgroup being
gatewayed, but each particular invocation of the program will want to
tell the mailtonews module what default newsgroup to use. To allow for
passing that information in, News::Gateway can take module arguments
when told what modules to apply, and will pass those arguments along to
the modules.
For complete information on using News::Gateway, including documentation
of all available modules, follow the below installation instructions to
the point of typing make and then read News/Gateway.pod (which is
generated from all of the documentation in the pod directory). The
documentation is in POD format and can therefore either be read straight
or (preferably) by running perldoc on the POD file.
Some additional documentation is also available in the doc directory.
INSTALLATION
If you want to install News::Gateway in the system site_perl directory
and have the privileges necessary to do so, follow the standard
installation procedure for Perl modules, which is to type the following
commands:
perl Makefile.PL
make
make install
(There is no test suite for this module yet, but it's high on the list
of things to be added in the future.) You will probably have to do the
last step as root.
If you would instead like to install News::Gateway in your own account,
you can use the standard Perl module facility for doing so. Just
specify a LIB value to Makefile.PL when you run it. For example, if you
want to put all of your personal Perl modules in ~/perl, instead of the
first command given above, type:
perl Makefile.PL LIB=~/perl
and then continue as normal. (The man pages may not be installed if you
use this method, but the POD documentation will be and you can run
perldoc on it directly.)
You can do exactly the same to install News::Article, PGP::Sign, and
other required modules in your home directory, and in fact this method
should work with nearly any Perl module.
To use modules installed in this fashion, you'll need to put the line:
use lib "$ENV{HOME}/perl";
at the beginning of your Perl scripts (replace $ENV{HOME} with the
actual path to your home directory if you wish).
SUPPORT
THIS IS AN ALPHA RELEASE. Translated, that means many features are
missing or not fully implemented, and there are known bugs which have
not yet been fixed. When using this release, please realize that the
interface may still be unstable and that there are some outstanding
problems. I welcome any bug reports or requests for new features; any
bug reports that lead to solving a problem or feature suggestions that
are included in later versions will result in having your name featured
prominently in the THANKS file.
See the TODO file for a list of known bugs and outstanding feature
requests.
If you are interested in being notified of new releases, helping with
development, developing, testing, or using new modules, or even just
getting tips on how to use this module, there is a mailing list
available. To subscribe, send mail to
[email protected] with:
subscribe gateway-users
in the body. New patches and modules are always welcome, whether from
people on the list or not, and can be mailed to the address listed
below.
See the THANKS file for credits.
The latest version of this module will always be available from
<URL:
ftp://ftp.eyrie.org/pub/software/modules/>.
Russ Allbery
[email protected]
