innfeed.conf documentation

[Julien ÉLIE]

Hi all,

I have just (at last) finished to double-check our documentation for
innfeed.conf (source code, man page and sample configuration file).

I wanted to do this before going on integrating Florian's patches about
inncheck & other files.
It is true that innfeed.conf seriously needs to use the new INN parser
because it is not easy at all to know what are the required parameters,
the optional ones, the default values, etc.
Dieter Stussy once spotted that.
The sample file and the documentation now mention all the possible
parameters and their default (or recommended) values.  Confusions
between default/recommended may still exist in the man page but anyway,
it is better than nothing :-)


The reasons why I am writing are the following:


> * Add fast-exit, debug-shrinking and initial-sleep in both the
> documentation and the sample file.

These are "new" (previously undocumented) parameters for they who want
to use them.
The documentation I suggest is the following one.  I am still wondering 
whether initial-sleep is really necessary to have.  One can of course 
set it to 0 if wanted :-)

=item I<fast-exit>

This key requires a boolean value and defaults to false.  If set to 
true, when B<innfeed> receives a SIGTERM or SIGQUIT signal, it will 
close its listeners as soon as it can, even if it means dropping articles.

=item I<debug-shrinking>

This key requires a boolean value and defaults to false (the debug file
is allowed to grow without bound).  If set to true, this file is 
truncated when its size reaches a certain limit.  See I<backlog-limit> 
for more details.

=item I<initial-sleep>

This key requires a positive integer.  A common value is C<2>.  It 
defines the number of seconds to wait when B<innfeed> (or a fork) 
starts, before beginning to open connections to remote hosts.



 > * To match what innfeed does by default :
 > - change host-queue-highwater from 200 to 10 in the sample file
 > - change max-connections from 5 to 2 in the sample file
 > - change dynamic-backlog-low from 25.0 to 20.0 in the sample file

I chose to update the sample file instead of updating the default value 
used by innfeed.
Do not hesitate to tell if you think the other way should be done.
Maybe max-connections could be increased by default.  I updated the 
documentation to say that 2 is a common value but may be increased if 
needed or for a larger feed.  That's perhaps enough for our documentation.



 > * innfeed/host.c was expecting "backlog-limit-high" whereas
 > innfeed/tape.c was properly using "backlog-limit-highwater" (which is
 > the one mentioned in the innfeed.conf configuration file and the
 > documentation).  It then appears that innfeed was not taking the
 > value into account and always using the default value of 0.

That's the most problematic change.
I think modifying the source code is better since our documentation and 
sample file have mentioned another thing for years.

I will put a note in the changelog for INN 2.5.3, to highlight that 
change.  It is normally minor, and more a bug fix than anything.


I also dropped the mention of innfeed 0.9.3, 1.0 and similar very old 
stuff in our documentation.  innfeed should have the same version number 
as INN nowadays; therefore, innfeed 2.5.2 for the currently stable release.


Feel free to comment these suggestions.  The commit is only on INN 2.6.0 
and I will merge it in INN 2.5.3 if nobody complains with these (minor) 
adaptations.

-- 
Julien ÉLIE

« Some joys are better expressed in silence as a smile holds more
   meaning than words. »