Include values.texi. Document SMTP timeouts

git-svn-id: file:///svnroot/mailfromd/branches/release_3_0_patches@839 7a8a7f39-df28-0410-adc6-e0d955640f24

1 files changed, 115 insertions, 25 deletions

diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index f2b4243c..3e2d9d90 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -20,6 +20,7 @@
 @include version.texi
 @include rendition.texi
 @include macros.texi
+@include values.texi
 
 @ifinfo
 @dircategory Email
@@ -102,6 +103,7 @@ Tutorial
 * Conditional Execution::
 * Domain Name System::
 * Checking Sender Address::
+* SMTP Timeouts::
 * Avoiding Verification Loops::
 * HELO Domain::
 * Controlling Number of Recipients::
@@ -685,6 +687,7 @@ interaction with the Mail Transport Agent.
 * Conditional Execution::
 * Domain Name System::
 * Checking Sender Address::
+* SMTP Timeouts::
 * Avoiding Verification Loops::
 * HELO Domain::
 * Controlling Number of Recipients::
@@ -1082,6 +1085,82 @@ done
 @end group
 @end smallexample
 
+@node SMTP Timeouts
+@section SMTP Timeouts
+
+  When using polling functions, it is important to take into account
+possible delay, which can occur in SMTP transactions.  Most often
+such delays are due to low network bandwidth, but sometimes remote
+sites insert them willingly, as a spam-fighting measure@footnote{My
+private opinion is that such practice is completely lame.}
+
+@cindex Timeouts, defined
+  @command{Mailfromd} polling functions implement three distinct
+@dfn{timeout} values:
+
+@table @dfn
+@cindex connection timeout
+@cindex timeout, connection
+@item Connection timeout
+  Maximum time for establishing the initial @acronym{TCP}
+connection to the remote host.  If the connection is not established
+within this time interval, the polling returns @code{temp_failure}.
+
+@cindex initial response timeout
+@cindex timeout, initial response
+@item Initial response timeout
+  Maximum time before receiving initial @acronym{SMTP} response from
+the remote host.
+
+@cindex I/O timeout
+@cindex timeout, I/O
+@cindex timeout, input/output
+@item I/O timeout
+  Maximum amount of time for finishing an input/output
+operation with the remote @acronym{SMTP} server.
+@end table
+
+  These three timeouts can be set using the following @dfn{pragmatic
+comments}@footnote{@xref{Pragmatic comments}, for the detailed
+description of pragmatic comments.} in the configuration file:
+
+@smallexample
+@group
+#pragma option connect-timeout @var{interval}
+#pragma option initial-response-timeout @var{interval}
+#pragma option io-timeout @var{interval}
+@end group
+@end smallexample
+
+  Here, @var{interval} is the time interval, expressed in usual
+time units@footnote{@xref{time interval specification}, for its
+detailed description.}, for example:
+
+@smallexample
+#pragma option initial-response-timeout 1 minute 30 seconds
+@end smallexample
+
+  The default values are:
+
+@smallexample
+@group
+#pragma option connect-timeout @value{CONNECT-TIMEOUT}
+#pragma option initial-response-timeout @value{INITIAL-RESPONSE-TIMEOUT}
+#pragma option io-timeout @value{IO-TIMEOUT}
+@end group
+@end smallexample
+
+@cindex CommuniGate Pro servers, lameness
+  You will most certainly encounter some servers that deliberately
+delay issuing the initial @acronym{SMTP} reply (in particular, I have
+noted that most @samp{CommuniGate Pro} servers are guilty of this lame
+practice).  The default @code{initial-response-timeout} value should
+be enough to cope with most of them.  If you encounter some server
+that delays more than 30 seconds, you can raise the
+@code{initial-response-timeout} value.  However, in this case, I'd
+recommend rather informing its admin that his server settings are not
+tolerable.
+  
 @node Avoiding Verification Loops
 @section Avoiding Verification Loops
 
@@ -1829,9 +1908,13 @@ database.
 specifying the database to operate upon with @option{--format}
 option.  Notice, that compacting a database needs roughly as 
 much disk space on the partition where the database resides as the
-database currently occupies.  While compacting, the database is
-locked, so the running copy of @command{mailfromd} is not able to
-write to it, but still can read the data from it. @FIXME-xref{locking}
+database currently occupies.  The simultaneous access prevention while
+compacting the database depends on the underlying @acronym{DBM}
+implementation.  In general, it is locked, so the running copy
+of @command{mailfromd} is not able to write to it, but still can read
+the data from it.  @FIXME{However, I need to verify the BerkeleyDB
+case, just to be sure.  Although I have never experienced any problems
+while compacting BDBs.}
 
 @anchor{compact cronjob}
 @xopindex{all, introduced}
@@ -2123,6 +2206,7 @@ and @samp{>}).}:
   This statement produces the same effect as if the contents of the
 named file were inserted at this line.
 
+@anchor{Pragmatic comments}
 @cindex Pragmatic comments
 @cindex #pragma
   If @samp{#} is immediately followed by word @samp{pragma} (with
@@ -2243,15 +2327,16 @@ corresponding @code{#pragma database} option.
 @xprindex{connect-timeout}
   Sets initial connection timeout.  If the connection is not
 established within this time, the corresponding probing function
-returns temporary failure.  Optionally, the connection can be retried
-several times, see @ref{pragma connect-retry}.  The default value is
-30 seconds.
+returns temporary failure.  The default value is
+@value{CONNECT-TIMEOUT}. @xref{SMTP Timeouts}, for the
+detailed description. 
 @end deffn
 
-@deffn {pragma option} connect-retry @var{number}
-@xprindex{connect-retry}
-  Sets number of attempts to establish initial connection.  Default is
-1 attempt.
+@deffn {pragma option} initial-response-timeout @var{interval}
+@xprindex{initial-response-timeout}
+  Sets the time to wait for the initial SMTP response.  Default is
+@value{INITIAL-RESPONSE-TIMEOUT}.  @xref{SMTP Timeouts}, for
+the detailed description. 
 @end deffn
 
 @deffn {pragma option} io-timeout @var{interval}
@@ -2259,16 +2344,17 @@ several times, see @ref{pragma connect-retry}.  The default value is
 @xprindex{io-timeout}
 @xprindex{timeout}
   Sets I/O operation timeout in seconds. @command{Mailfromd} will
-wait @var{number} of seconds for the success of each I/O operation
-with the remote MX.  If the remote party does not respond within this
-amount of time, @command{mailfromd} will retry the operation until the
-number of retries (@pxref{pragma io-retry}) is exhausted or the host finally
-responds.  Default timeout is 3 seconds.
+wait the given amount of time for the success of each I/O operation
+with the remote MX.  Default timeout is @value{IO-TIMEOUT}.
+@xref{SMTP Timeouts}, for the detailed description. 
 
   The form @code{timeout} is retained for backward compatibility and is
 considered deprecated.  
 @end deffn
 
+@ignore
+ -- This is to pacify make check-docs. These options are no longer
+ -- used but retained for backward compatibility.   
 @deffn {pragma option} io-retry @var{number}
 @deffnx {pragma option} retry @var{number}
 @xprindex{io-retry}
@@ -2280,6 +2366,13 @@ considered deprecated.
 considered deprecated.  
 @end deffn
 
+@deffn {pragma option} connect-retry @var{number}
+@xprindex{connect-retry}
+  Sets number of attempts to establish initial connection.  Default is
+1 attempt.
+@end deffn
+@end ignore
+
   The following options provide the default settings for @code{poll}
 statement (@pxref{Polling}).
 
@@ -2382,8 +2475,8 @@ port type is not yet supported.
 @deffn {pragma option} milter-timeout @var{interval}
 @xprindex{milter-timeout}
   Set the timeout value for connection between the filter
-and the MTA.  Default value 7210 seconds.  You normally do not need to
-change this value. 
+and the MTA.  Default value is @value{MILTER-TIMEOUT}.  You
+normally do not need to change this value. 
 @end deffn
 
   The following options can be used to tune database file locking:
@@ -3163,7 +3256,10 @@ toupper "mail" @result{} "MAIL"
 @node Polling functions
 @subsubsection Polling Functions
 
-@FIXME{it would be good to add reference to Checking Sender Address}
+  We have described the base notions about sender address verification
+(or @dfn{polling}, for short) in @ref{Checking Sender Address}.  Here
+we will describe the functions @command{mailfromd} offers for this
+purpose. 
 
 @deftypefn {Built-in Function} number _pollhost @
   (string @var{ip}, string @var{email}, string @var{domain}, @
@@ -5456,7 +5552,7 @@ analyze @kbd{mailfromd --list} output using text tools, such as
 @itemx  --user @var{name}
 Switch to this user privileges after startup. Overrides @samp{#pragma
 option user}, which you are advised to use instead (@pxref{pragma
-user}).  Default user is @samp{mail}.
+user}).  Default user is @samp{@value{DEFAULT-USER}}.
 @end table
 
 @node Timeout Control
@@ -5471,12 +5567,6 @@ Set MTA connection timeout.  Overrides @samp{#pragma option
 milter-timeout}, which you are advised to use instead (@pxref{pragma
 milter-timeout}. 
 
-@opsummary{retry}
-@item --retry=@var{number}
-Retry failed I/O operations @var{number} times.  Overrides
-@samp{#pragma option retry}, which you are advised to use instead
-(@pxref{pragma io-retry}).
-
 @opsummary{timeout}
 @item --timeout=@var{number}
 Set I/O operation timeout (seconds).  Overrides @samp{#pragma option