changes

smmapdfw/doc/smmapdfw.texi

@@ -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.
 
 
@@ -209,9 +213,48 @@ feature is part of this distribution.
 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 Using from sendmail, Configuration, Overview, Top
+@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.
+
+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