wn/smmapdfw
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

changes

Browse Source
This commit is contained in:
whottgen 2004-11-09 20:07:28 +00:00
parent b07243b9c4
commit b76313bfdb
1 changed files with 211 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
smmapdfw/doc/smmapdfw.texi
View File

@ -33,6 +33,7 @@ Copyright @copyright{} 2004 Wolfgang Hottgenroth
@menu
* Motivation::
* Overview::
* Building smmapd from the sources::
* Using from sendmail::
* Configuration::
* API::
@ -45,6 +46,11 @@ Overview
* Sender-address verification plugin::
* Cyrus mailbox check plugin::
Using from sendmail
* sender address verification::
* Cyrus IMAP server mailbox checks::
Configuration
* Global::
@ -92,7 +98,7 @@ More or less useful stuff
With release 8.13 sendmail introduces the socket map type. A map can
be defined where a query is sent over an socket to an external daemon,
doing some computations on the query to send back the result over the
socket too.
socket.
This opens another door to query data from external processes when
performing mail routing. Thereby the already rich feature set of
@ -107,17 +113,15 @@ task the socket map has to perform.
The particular socket map processor appears as a shared object which
is dynamically loaded by the daemon depending on the configuration.
@node Overview, Using from sendmail, Motivation, Top
@node Overview, Building smmapd from the sources, Motivation, Top
@chapter Overview
Overview over smmapdfw
smmapdfw consists of the actual server -- smmapd --, a library --
libsmmapdfw -- providing the API and three plugins, one useless
example and two more useful ones: a sender-address verifier and a
Cyrus mailbox checker.
The server reads the configuration file, loads all configured plugins
(socket map processors) and opens the configuration tcp socket. It
(socket map processors) and opens the configured tcp socket. It
accepts requests on this tcp socket from sendmail in netstring
encoding. For each connections it starts a thread. In this thread it
dispatches the requests (the map name is part of the request) -- after
@ -141,16 +145,16 @@ plugin and lasts for all requests coming in during the
connection.
The container setup function, which a plugin can implement, is called
at start up time, its return value is taken as container handle.
at start up time, and returns the container handle.
The worker setup function, which a plugin can implement, is called
when the first request of a connection is dispatched to the plugin,
its return value is taken as worker handle.
and returns the worker handle.
Both container and worker handle are provided to the worker function.
The framework stores both container and worker handle as void pointer,
so each plugin can define its own data structure.
so each plugin has to define its own handle data structure.
@menu
@ -182,7 +186,7 @@ returned to sendmail.
If no checker thread delivers a permanent result within the result
timeout, a temporary failure is returned. However, no checker thread
is aborted and the result of the first is then just stored in the
is aborted and the result of the first one is then just stored in the
cache.
@ -210,8 +214,47 @@ It hooks into the local parse ruleset and checks through the map
utilizing this plugin the Cyrus IMAP server to see whether the
particular mailbox can store more mail.
@node Building smmapd from the sources, Using from sendmail, Overview, Top
@chapter Building smmapd from the sources
smmapd comes with a autoconf @file{configure} script.
@node Using from sendmail, Configuration, Overview, Top
To get some help for the parameters it supports, say
@verbatim
./configure --help
@end verbatim
Important options are these:
@verbatim
--enable-stats Enables statistics collection. (default=no)
--with-bdb-lib-dir Directory for Berkeley DB library files
--with-bdb-inc-dir Directory for Berkeley include files
--with-djbdns-lib-dir Directory for Bernstein's djbdns library files
--with-djbdns-inc-dir Directory for Bernstein's djbdns include files
--with-netsnmp With Net-SNMP
--with-netsnmp-lib-dir Directory for Net-SNMP library files
--with-netsnmp-inc-dir Directory for Net-SNMP include files
--with-netsnmp-bin-dir Directory for Net-SNMP bin files, specifically
net-snmp-config
@end verbatim
The Berkeley DB (tested with version 4.1.25) is required for the cache
of the verifier plugin.
DJB's resolver library (djbdns) is required on systems where the
default resolver library is not thread-safe. (In my test-bed this was
true for Solaris 8.)
To gather statistic data, use @code{--enable-stats}, to be able to
retrieve statistic data through snmp use @code{--with-netsnmp}. snmp
requires @code{--enable-stats}. If there are no direct paths to the
Net-SNMP stuff (tested with Net-SNMP 5.1.2), use
@code{--with-netsnmp-lib-dir}, @code{--with-netsnmp-inc-dir} and
@code{--with-netsnmp-bin-dir}.
@node Using from sendmail, Configuration, Building smmapd from the sources, Top
@chapter Using from sendmail
To use a socket map in sendmail, it must be defined in the cf:
@ -237,6 +280,107 @@ Kdontknow socket -T<temp> inet:8884@127.0.0.1
(Here, the dispatcher of smmapdfw jumps in.)
@menu
* sender address verification::
* Cyrus IMAP server mailbox checks::
@end menu
@node sender address verification, Cyrus IMAP server mailbox checks, Using from sendmail, Using from sendmail
@section sender address verification
A sendmail feature file is delivered with smmapd to link the sender
address verification into the ruleset @code{check_mail} hook
@code{Local_check_mail}.
It takes three parameters and can be used in the @code{sendmail.mc}
like this:
@verbatim
FEATURE(`verifysender', `_mode_', `_return_', `_dummy_')
@end verbatim
@code{_mode_} must be replaced by either @code{black} or
@code{white}.
For @code{black} a blacklist in
@code{/etc/mail/verifier-black-list} is considered and only sender
addresses in there mentioned domains are verified.
The location of the blacklist can be configured using
@verbatim
define(`confVERIFIER_BLACKLIST', `hash -o /prod/sendmail/etc/verifier-black-list')
@end verbatim
For @code{white} a whitelist in
@code{/etc/mail/verifier-white-list} is considered and sender
addresses in the whitelist or in domains mentioned in the whitelist
are not verified.
The location of the whitelist can be configured using
@verbatim
define(`confVERIFIER_WHITELIST', `hash -o /prod/sendmail/etc/verifier-white-list')
@end verbatim
@code{confVERIFIER_BLACKLIST} and @code{confVERIFIER_WHITELIST} must
appear in the @code{sendmail.mc} before the feature is called.
@code{_return_} must be replaced by either @code{temp} or
@code{perm}.
If the sender address verification ends up in a permanent negative
response from the home-server of the address, for @code{temp} a
temporary failure (4xx), for @code{perm} a permanent
failure (5xx) is returned.
@code{_dummy_} must be replaced by either @code{active} or
@code{dummy}. If @code{dummy} is set here, the verifier is called but
its result is just logged and not further considered for the routing.
The connection to the smmapd is configured using
@code{define(`confVERIFIER_MAP')}.
The default is
@verbatim
define(`confVERIFIER_MAP', `inet:8884@127.0.0.1')
@end verbatim
@node Cyrus IMAP server mailbox checks, , sender address verification, Using from sendmail
@section Cyrus IMAP server mailbox checks
A sendmail feature file @code{cyruscheck.m4} is delivered with
smmapd. It provides a ruleset @code{cyruscheck}, which can by used in
ruleset @code{ParseLocal}.
It can be used in the @code{sendmail.mc} like this:
@verbatim
FEATURE(`cyruscheck', `_dummy_')
@end verbatim
@code{_dummy_} must be replaced by either @code{active} or
@code{dummy}. If @code{dummy} is set here, the verifier is called but
its result is just logged and not further considered for the routing.
However, remember that only the ruleset @code{cyruscheck} is
provided. You need to call it in your @code{LocalParse} ruleset on
your own.
The ruleset takes two parameters: The mailbox name on the Cyrus IMAP
server and the hostname of the Cyrus IMAP server, both in angle brackets.
The connection to the smmapd is configured using
@code{define(`confCYRUSCHECK_MAP')}.
The default is
@verbatim
define(`confCYRUSCHECK_MAP', `inet:8884@127.0.0.1')
@end verbatim
@node Configuration, API, Using from sendmail, Top
@chapter Configuration
@ -261,6 +405,10 @@ port = 8887
; plugin_dir = /home/who/Sources/sf/smmapdfw
; plugins = test_worker1 test_worker2 verifier cyruscheck lua_worker
plugins = verifier
enable_stats = 1
enable_snmp = 1
@end verbatim
@ -285,10 +433,53 @@ required, when plugins are installed in the lib path configured when
building smmapdfw. Only one path can be given.
@item plugins
Lists all plugins which should be loaded. The plugin name refers to
Lists all plugins separated by spaces which should be loaded. The plugin name refers to
the section name of the particular configuration section.
@item enable_stats
This enables the statistics output thread. It is only available when
smmapd was built with @code{--enable-stats}. Further configuration in
section @code{stats} is required.
@item enable_snmp
This enables the snmp AgentX subagent to retrieve statistic data. It
is only available when smmapd was built with @code{--enable-stats} and
@code{--with-netsnmp}. Further configuration in section @code{snmp} is required.
@end table
@section stats
@verbatim
[stats]
stdout_nice = 2
syslog_nice =1
period = 1
@end verbatim
The statistics output thread can write to stdout and/or syslog in two
different format, one more human-readable, the other one more
machine-readable.
The number after @code{stdout_nice} and @code{syslog_nice} specifies
the format. 0 means no output on this channel, 1 means
machine-readable output and 2 means human-readable output.
@code{period} specifies the time in seconds behind to statistic
outputs.
@section snmp
@verbatim
[snmp]
agentx_socket = /var/agentx/master
@end verbatim
The socket on which the snmpd is listening for AgentX subagents is
specified here.
@node Plugin, , Global, Configuration
@section Plugin
The section name of a plugin configuration section must be used in the
@ -708,6 +899,14 @@ address, no hostname.
@node safe_write.h, , smtp.h, More or less useful stuff
@subsection @code{safe_write.h}
@verbatim
ssize_t safe_write(int fd, const void *buf, size_t count);
@end verbatim
This is a @code{SIGPIPE} death avoiding write function. However, no
input should be expected when trying to write with this function,
since at least one input character is eaten up.
@bye