=head1 NAME

newslog - Description of INN log files

=head1 DESCRIPTION

Most log files created by Usenet programs reside in the I<pathlog> directory
set in F<inn.conf> and have a C<.log> extension.  Several versions are usually
kept with an additional extension such as C<.1>, C<.2>, etc. S<-- the> higher
the number, the older the log.  These old versions are stored in I<pathlog>/OLD;
they may be compressed and thus may have a C<.1.gz>, C<.2.gz>, etc. extension,
up to C<.nn.gz> where C<nn> is the number of old logs kept by B<scanlogs>
which is set by I<logcycles> in F<inn.conf>.

The B<scanlogs> script and related utilities are responsible for rotating
and compressing these files.  Some log files always have data (like
F<news.notice>), others only have data if there is a problem (like
F<news.err>), and others are only created if a particular program is used
(like F<send-uucp.log> used by B<send-uucp>) or if a configuration parameter
is set (like F<innfeed.log> used by B<innfeed> when I<debug-level> is set
in F<innfeed.conf>).

Besides, the B<innstat> script monitors the size of all log files.

Here are the log files used by INN:

=over 4

=item F<control.log>

This file maintains a count of the number of newgroup and rmgroup control
messages seen for each newsgroup.  The count is of the number of control
messages with the indicated arguments, regardless if they were actually
processed.  All control arguments, including invalid ones, are counted.
An example of lines which can be found in that log file is:

    3 Control: newgroup foo.bar moderated
    3 Control: rmgroup misc.removed
    1 Control: newgroup misc.created

This file is updated by B<tally.control>, which is invoked by B<scanlogs>
if either one of these two log files exists in I<pathlog>:

    newgroup.log
    rmgroup.log

These two log files contain a summary line describing the control message
and the action taken by B<controlchan>, followed by the article indented
by four spaces, and a blank line.  Whereas these files are rotated,
F<control.log> is not rotated so as to keep the count of seen control
messages.

Note that other control log files are also rotated by B<scanlogs>, if they
exist, but their contents are not summarized.  Here are their names:

    checkgroups.log
    default.log
    ihave.log
    miscctl.log
    sendme.log
    sendsys.log
    senduuname.log
    version.log

In order to create these files, the <type> and <action> fields of
relevant F<control.ctl> entries should be correctly set.  For instance:

    Type            Action              Meaning
    ----            ------              -------
    all             log=miscctl         Log all messages by default.
    newgroup        doit=newgroup       Create group and log message.
    newgroup        log=newgroup        Log message.
    rmgroup         verify-*=rmgroup    PGP verify, remove group and log message.
    checkgroups     doit=checkgroups    Process and log message.

=item F<controlbatch.log>

The B<controlbatch> program appends all status messages to this file.  It is
rotated by B<scanlogs>.

=item F<errlog>

This file contains the standard output and standard error of any program
spawned by B<innd>, such as channel feeds configured in F<newsfeeds>.
This file should normally be empty.  B<scanlogs> will print the 50
first lines of this log file if it is non-empty so that they appear
in daily Usenet reports generated by B<news.daily>.  Then, B<scanlogs>
rotates this log file.

=item F<expire.log>

By default, when B<news.daily> is going to expire old news articles, it writes
the name of the program it invokes, followed by C<start> and the time it has
started.  Any output from that program is then written, indented by four
spaces.  Then, the name of the program is written, followed by C<end> and
the time it has ended.

Programs called, if needed, are in order: B<expireover>, B<ctlinnd>
(with the C<lowmark> option), B<expirerm> and B<expire>.  Removed articles
are listed in F<expire.list> and low marks for each newsgroup (that
is to say the number of the oldest article available in the newsgroup) in
F<expire.lastlowmark>.

After the expiry process, B<scanlogs> rotates F<expire.log>.

=item F<innfeed.log>

When I<debug-level> is set in F<innfeed.conf>, B<innfeed> appends debugging
messages to this file.  Note that the name of this file can be changed with
the I<log-file> parameter in F<innfeed.conf>.  Be that as it may, the right
log file is rotated by B<scanlogs>.

B<innfeed> also logs its status in F<innfeed.status> (or the name set in
I<status-file>) if I<gen-html> is set to false but this log file is not
processed by B<scanlogs>.

=item F<news>

This file logs articles received by B<innd>.  Typical lines are:

    Aug 25 13:37:41.839 + news.server.fr <cancel.4066@foo.com> 1658 a.peer other.server.org inpaths!
    Aug 25 13:37:41.839 c news.server.fr <cancel.4066@foo.com> Cancelling <m070725@foo.com>
    Aug 25 13:37:54.638 - a.peer <23k82@bar.net> 437 Poison newsgroup

The first one indicates that an article from C<news.server.fr> has been
accepted (C<+>).  Its Message-ID is C<< <cancel.4066@foo.com> >> and we will
send the article to two peers (C<a.peer> and C<other.server.org>, as specified
in F<newsfeeds>) and C<inpaths!> (see B<ninpaths> for more details
about it).  The second line mentions that this previous article is a
cancel message (C<c>) for C<< <m070725@foo.com> >> and that it has been
processed (inndeed, B<controlchan> processes all control articles except for
cancels which are handled by B<innd>).  The third line indicates that
the article whose Message-ID is C<< <23k82@bar.net> >> has been rejected (C<->)
because it is posted to a poison newsgroup (a Perl or a Python filter
located in I<pathfilter> must have brought that reject along).

See the "LOGGING" section of the innd(8) man page for more information about
the format of this log file.

B<innreport> summarizes the rejected articles reported in this file
and B<scanlogs> rotates it.

=item F<news.crit>

All critical error messages issued by B<innd> are appended to this
file via syslog.  This log file should normally be empty.  B<scanlogs>
will print the first 50 lines of this log file if it is non-empty so
that they appear in daily Usenet reports generated by B<news.daily>.
Then, B<scanlogs> rotates this log file.

You should have the following line in your system F<syslog.conf> file, using
a tab character for the delimiter:

    news.crit		<pathlog>/news.crit

(A typical entry is shown; it should agree with I<pathlog> in F<inn.conf>
and be tab-delimited.)

=item F<news.err>

All major error messages issued by B<innd> are appended to this file
via syslog.  This log file should normally be empty.  B<scanlogs>
will print the first 50 lines of this log file if it is non-empty so
that they appear in daily Usenet reports generated by B<news.daily>.
Then, B<scanlogs> rotates this log file.

You should have the following line in your system F<syslog.conf> file, using
a tab character for the delimiter:

    news.err		<pathlog>/news.err

(A typical entry is shown; it should agree with I<pathlog> in F<inn.conf>
and be tab-delimited.)

=item F<news.notice>

All standard error messages and status messages issued by B<innd>,
B<innfeed>, B<nnrpd> and some other programs are appended to this file
via syslog.  B<scanlogs> uses the Perl script B<innreport> to summarize
this file.  B<innreport> will also print the first I<max_unknown>
unknown lines of this log file if such unrecognized lines are found in
F<news.notice> so that they appear in daily Usenet reports generated
by B<news.daily>.  This parameter can be set in F<innreport.conf>.
Then, B<scanlogs> rotates this log file.

You should have the following line in your system F<syslog.conf> file, using
a tab character for the delimiter:

    news.notice		<pathlog>/news.notice

(A typical entry is shown; it should agree with I<pathlog> in F<inn.conf>
and be tab-delimited.)

=item F<nntpsend.log>

The B<nntpsend> program appends all status messages to this file.  It is
rotated by B<scanlogs>.

=item F<perl-nocem.log>

The B<perl-nocem> program appends all status messages to this file if
C<Sys::Syslog> is not used (otherwise, such messages are appended to
F<news.notice>).  It is rotated by B<scanlogs>.

=item F<send-ihave.log>

The B<send-ihave> program appends all status messages to this file.  It is
rotated by B<scanlogs>.

=item F<send-uucp.log>

The B<send-uucp> program appends all status messages to this file.  It is
rotated by B<scanlogs>.

=item F<unwanted.log>

This log maintains a count of the number of articles that were rejected
because they were posted to newsgroups that do not exist at the local site.
This file is updated by B<innreport> while processing the F<news.notice>
log file and it is maintained in reverse numeric order (the most popular
rejected group first).  This file is not rotated so as to keep the count
of the articles posted to newsgroups which are absent from the F<active>
file of the news server.

Note that I<logtrash> has to be set to true in F<inn.conf> for this file
to be generated.

=back

Finally, these files are also rotated by B<scanlogs>, if they exist, but
their contents are not summarized.  Here are their names:

    badcontrol.log
    badpgp.log
    failedpgp.log

They can be used by programs which PGP verify articles.

=head1 HISTORY

Written by Landon Curt Noll <chongo@toad.com> and Rich $alz
<rsalz@uunet.uu.net> for InterNetNews.  Rewritten and converted
to POD by Julien Elie.

=head1 SEE ALSO

control.ctl(5), ctlinnd(8), expire(8), expireover(8), expirerm(8),
inn.conf(5), innd(8), innfeed.conf(5), innreport(8), innreport.conf(5),
news.daily(8), nnrpd(8), nntpsend(8), scanlogs(8), send-ihave(8),
send-uucp(8), syslog.conf(5), tally.control(8).

=cut
