INN commit: branches/2.4 (control/perl-nocem.in doc/man/perl-nocem.8)

INN Commit Russ_Allbery at isc.org
Sun Apr 6 09:16:20 UTC 2008


    Date: Sunday, April 6, 2008 @ 02:16:20
  Author: iulius
Revision: 7733

* perl-nocem will now check for a timeout and re-open the socket
  if required.  Additionally, perl-nocem will switch to
  cancel_ctlinnd in case cancel_nntp fails after sending
  the Message-ID.  Thanks to Christoph Biedl for the patch.
* Fix the count of the time spent in do_nocem():  the $start and $diff
  variables were consecutive.
* Use "%d" instead of "$nr" in sprintf.
* Documentation fixes:
    * perl-nocem does not expect a message but a token.
    * Add "--no-default-keyring" because gpg otherwise uses the one
      in ~/.gnupg (strange).
    * Mention the keyring and improve a lot this documentation.

Modified:
  branches/2.4/control/perl-nocem.in
  branches/2.4/doc/man/perl-nocem.8

-----------------------+
 control/perl-nocem.in |  167 +++++++++++++++++++++++++++++++++++++++---------
 doc/man/perl-nocem.8  |  147 ++++++++++++++++++++++++++++++++----------
 2 files changed, 253 insertions(+), 61 deletions(-)

Modified: control/perl-nocem.in
===================================================================
--- control/perl-nocem.in	2008-04-06 08:47:48 UTC (rev 7732)
+++ control/perl-nocem.in	2008-04-06 09:16:20 UTC (rev 7733)
@@ -6,6 +6,14 @@
 # Copyright 2000 by Miquel van Smoorenburg <miquels at cistron.nl>
 # Copyright 2001 by Marco d'Itri <md at linux.it>
 # This program is licensed under the terms of the GNU General Public License.
+#
+# List of changes:
+#
+# 2002: Patch by Steven M. Christey for untrusted printf input.
+# 2007: Patch by Christoph Biedl for checking a timeout.
+# Documentation improved by Jeffrey M. Vinocur (2002), Russ Allbery (2006)
+# and Julien Elie (2007).
+#
 ##############################################################################
 
 require 5.00403;
@@ -31,13 +39,15 @@
 #    return 1;
 #}
 
-# no user servicable parts below this line ###################################
+# no user serviceable parts below this line ###################################
 
 # global variables
 my ($working, $got_sighup, $got_sigterm, @ncmperm, $cancel);
 my $use_syslog = 0;
 my $log_open = 0;
 my $nntp_open = 0;
+my $last_cancel = 0;
+my $socket_timeout = $inn::peertimeout - 100;
 
 my $logfile = $inn::pathlog . '/perl-nocem.log';
 
@@ -92,6 +102,7 @@
 # Process one NoCeM notice.
 sub do_nocem {
     my $token = shift;
+    my $start = time;
 
     # open the article and verify the notice
     my $artfh = open_article($token);
@@ -102,11 +113,10 @@
 
     &$cancel($nocems);
     logmsg("Articles cancelled: " . join(' ', @$nocems), 'debug');
-    my $start = time;
     my $diff = (time - $start) || 0.01;
     my $nr = scalar @$nocems;
-    logmsg(sprintf("processed notice %s by %s ($nr ids, %.5f s, %.1f/s)",
-        $nid, $issuer, $diff, $nr / $diff));
+    logmsg(sprintf("processed notice %s by %s (%d ids, %.5f s, %.1f/s)",
+        $nid, $issuer, $nr, $diff, $nr / $diff));
 }
 
 # - Check if it is a PGP signed NoCeM notice
@@ -181,7 +191,7 @@
 #        return;
 #    }
 
-    # we do want it, so read the entire article. Also copy it to
+    # We do want it, so read the entire article.  Also copy it to
     # a temp file so that we can check the PGP signature when done.
     my $tmpfile = "$inn::pathtmp/nocem.$$";
     if (not open(OFD, ">$tmpfile")) {
@@ -289,7 +299,8 @@
             return 0;
         }
     }
-#    logmsg("Command line was: $inn::gpg $pgpargs $art", 'debug');
+#    logmsg("Command line was: $inn::gpgv --status-fd=1"
+#         . ($keyring ? ' --keyring=' . $keyring : '') . " $art", 'debug');
 #    logmsg("Full PGP output: >>>$_<<<", 'debug');
 
     if (/^\[GNUPG:\]\s+GOODSIG\s+\S+\s+(.*)/m) {
@@ -337,7 +348,7 @@
     return undef;
 }
 
-# Cancel a number of message-ids. We use ctlinnd to do this,
+# Cancel a number of Message-IDs.  We use ctlinnd to do this,
 # and we run up to 15 of them at the same time (10 usually).
 sub cancel_ctlinnd {
     my @ids = @{$_[0]};
@@ -371,6 +382,11 @@
     my $ids = shift;
     my $r;
     
+    if ($nntp_open and time - $socket_timeout > $last_cancel) {
+        logmsg('Close socket for timeout');
+        close (NNTP);
+        $nntp_open = 0;
+    }
     if (not $nntp_open) {
         use Socket;
         if (not socket(NNTP, PF_UNIX, SOCK_STREAM, 0)) {
@@ -400,11 +416,15 @@
         if (($r = <NNTP>) !~ /^289/) {
             $r =~ s/\r\n$//;
             logmsg("cannot cancel $_: $r", 'err');
+            goto ERR;
         }
     }
+    $last_cancel = time;
     return;
 
 ERR:
+    # discard unusable socket
+    close (NNTP);
     logmsg('Switching to ctlinnd...', 'err');
     cancel_ctlinnd($ids);
     $cancel = \&cancel_ctlinnd;
@@ -463,56 +483,147 @@
 
 # lint food
 print $inn::pathrun.$inn::pathlog.$inn::pathetc.$inn::newsbin.$inn::pathbin
-    . $inn::pathtmp;
+    .$inn::pathtmp.$inn::peertimeout.$inn::syslog_facility;
 
 __END__
 
 =head1 NAME
 
-perl-nocem - A NoCeM-on-spool implementation for INN 2.x
+perl-nocem - A NoCeM-on-spool implementation for S<INN 2.x>
 
 =head1 SYNOPSIS
 
-perl-nocem < I<message>
+perl-nocem
 
 =head1 DESCRIPTION
 
-Add to the newsfeeds file an entry like this one:
+NoCeM, which is pronounced I<No See 'Em>, is a protocol enabling
+authenticated third-parties to issue notices which can be used
+to cancel unwanted articles (like spam and articles in moderated
+newsgroups which were not approved by their moderators).  It can
+also be used by readers as a I<third-party killfile>.  It is
+intended to eventually replace the protocol for third-party cancel
+messages.
 
-    nocem:!*,alt.nocem.misc,news.lists.filter\
-        :Tc,Wf,Ap:/usr/local/news/bin/perl-nocem
+B<perl-nocem> processes third-party, PGP-signed article cancellation
+notices.  It is possible not to honour all NoCeM notices but only those
+which are sent by people whom you trust (that is to say if you trust
+the PGP key they use to sign their NoCeM notices).  Indeed, it is up
+to you to decide whether you wish to honour their notices, depending
+on the criteria they use.
 
-Import new keys with:
+Processing NoCeM notices is easy to set up:
 
-    gpg --primary-keyring /usr/local/news/etc/pgp/ncmring.gpg --import
-        <key-file>
+=over 4
 
-where <key-file> is the file containing the key.  For old PGP-generated
-keys, you may have to use B<--allow-non-selfsigned-uid> if they're not
-properly self-signed, but anyone creating a key really should self-sign
-the key.  Current PGP implementations do this automatically.
+=item 1.
 
-The nocem.ctl config file contains lines like:
+Import the keys of the NoCeM issuers you trust in order to check
+the authenticity of their notices.  You can do:
 
-    annihilator-1 at erlenstar.demon.co.uk:*
-    clewis at ferret:mmf,spam
+    gpg --no-default-keyring --primary-keyring <pathetc>/pgp/ncmring.gpg --import <key-file>
 
+where <pathetc> is the value of the I<pathetc> parameter set in F<inn.conf>
+and <key-file> the file containing the key(s) to import.  The keyring
+must be located in I<pathetc>/pgp/ncmring.gpg (create the directory
+before using B<gpg>).  For old PGP-generated keys, you may have to use
+B<--allow-non-selfsigned-uid> if they are not properly self-signed,
+but anyone creating a key really should self-sign the key.  Current
+PGP implementations do this automatically.
+
+The keys of NoCeM issuers can be found in the web site of I<The NoCeM Registry>:
+L<http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html>.  You can even
+download there a unique file which contains all the keys.
+
+=item 2.
+
+Create a F<nocem.ctl> config file in I<pathetc> indicating the NoCeM issuers
+and notices you want to follow.  This permission file contains lines like:
+
+    annihilator-1:*
+    clewis at ferret.ocunix:mmf
+    stephane at asynchrone:mmf,openproxy,spam
+
+This will remove all articles for which the issuer (first part of the line,
+before the colon C<:>) has issued NoCeM notices corresponding to the
+criteria specified after the colon.
+
+You will also find information about that on the web site of
+I<The NoCeM Registry>.
+
+=item 3.
+
+Add to the F<newsfeeds> file an entry like this one in order to feed
+B<perl-nocem> the NoCeM notices posted to alt.nocem.misc and
+news.lists.filters:
+
+    nocem!\
+        :!*,alt.nocem.misc,news.lists.filters\
+        :Tc,Wf,Ap:<pathbin>/perl-nocem
+
+with the correct path to B<perl-nocem>, located in <pathbin>.  Then, reload
+the F<newsfeeds> file (C<ctlinnd reload newsfeeds 'NoCeM channel feed'>).
+
+Note that you should at least carry news.lists.filters on your news
+server (or other newsgroups where NoCeM notices are sent) if you wish
+to process them.
+
+=item 4.
+
+Everything should now work.  However, do not hesitate to manually test
+B<perl-nocem> with a NoCeM notice, using:
+
+    grephistory '<Message-ID>' | perl-nocem
+
+Indeed, B<perl-nocem> expects tokens on its standard input, and
+B<grephistory> can easily give it the token of a known article,
+thanks to its Message-ID.
+
+=back
+
+When you have verified that everything works, you can eventually turn
+off regular spam cancels, if you want, not processing any longer
+cancels containing C<cyberspam> in the Path: header (see the
+I<refusecybercancels> parameter in F<inn.conf>).
+
 =head1 FILES
 
-/usr/local/news/etc/nocem.ctl
+=over 4
 
+=item I<pathbin>/perl-nocem
+
+The Perl script itself used to process NoCeM notices.
+
+=item I<pathetc>/nocem.ctl
+
+The configuration file which specifies the NoCeM notices to be processed.
+
+=item I<pathetc>/pgp/ncmring.gpg
+
+The keyring which contains the public keys of trusted NoCeM issuers.
+
+=back
+
 =head1 BUGS
 
-The Subject header is not checked for the @@NCM string and there is no
-check for the presence of the References header.
+The Subject: header is not checked for the @@NCM string and there is no
+check for the presence of the References: header.
 
-The Newsgroups pseudo header is not checked, but this can be done in
+The Newsgroups: pseudo header is not checked, but this can be done in
 local_want_cancel_id().
 
-The Hierarchies header is ignored.
+The Hierarchies: header is ignored.
 
 =head1 HISTORY
 
 Copyright 2000 by Miquel van Smoorenburg <miquels at cistron.nl>.
 
 Copyright 2001 by Marco d'Itri <md at linux.it>.
+
+$Id$
+
+=head1 SEE ALSO
+
+gpgv(1), grephistory(1), inn.conf(5), newsfeeds(5), pgp(1).
+
+=cut

Modified: doc/man/perl-nocem.8
===================================================================
--- doc/man/perl-nocem.8	2008-04-06 08:47:48 UTC (rev 7732)
+++ doc/man/perl-nocem.8	2008-04-06 09:16:20 UTC (rev 7733)
@@ -1,5 +1,4 @@
-.\" Automatically generated by Pod::Man version 1.19
-.\" Thu Aug 16 19:16:09 2001
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -22,16 +21,15 @@
 ..
 .de Ve \" End verbatim text
 .ft R
-
 .fi
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote.  | will give a
-.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
@@ -130,43 +128,126 @@
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
-.IX Title "perl-nocem 8"
-.TH perl-nocem 8 "INN 2.4.0" "2001-08-16" "InterNetNews Documentation"
-.UC
+.IX Title "PERL-NOCEM 8"
+.TH PERL-NOCEM 8 "2008-04-06" "INN 2.4.4" "InterNetNews Documentation"
 .SH "NAME"
-perl-nocem \- a NoCeM-on-spool implementation for \s-1INN\s0 2.x
+perl\-nocem \- A NoCeM\-on\-spool implementation for INN\ 2.x
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-Add to the newsfeeds file an entry like this one:
+perl-nocem
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+NoCeM, which is pronounced \fINo See 'Em\fR, is a protocol enabling
+authenticated third-parties to issue notices which can be used
+to cancel unwanted articles (like spam and articles in moderated
+newsgroups which were not approved by their moderators).  It can
+also be used by readers as a \fIthird-party killfile\fR.  It is
+intended to eventually replace the protocol for third-party cancel
+messages.
 .PP
-.Vb 2
-\&    nocem:!*,alt.nocem.misc,news.lists.filter\e
-\&        :Tc,Wf,Ap:/usr/local/news/bin/perl-nocem
-.Ve
-Import new keys with:
+\&\fBperl-nocem\fR processes third\-party, PGP-signed article cancellation
+notices.  It is possible not to honour all NoCeM notices but only those
+which are sent by people whom you trust (that is to say if you trust
+the \s-1PGP\s0 key they use to sign their NoCeM notices).  Indeed, it is up
+to you to decide whether you wish to honour their notices, depending
+on the criteria they use.
 .PP
-.Vb 2
-\&    gpg --keyring=/usr/local/news/etc/pgp/ncmring.gpg --import \e
-\&        --allow-non-selfsigned-uid
+Processing NoCeM notices is easy to set up:
+.IP "1." 4
+Import the keys of the NoCeM issuers you trust in order to check
+the authenticity of their notices.  You can do:
+.Sp
+.Vb 1
+\&    gpg \-\-no\-default\-keyring \-\-primary\-keyring <pathetc>/pgp/ncmring.gpg \-\-import <key\-file>
 .Ve
-The nocem.ctl config file contains lines like:
+.Sp
+where <pathetc> is the value of the \fIpathetc\fR parameter set in \fIinn.conf\fR
+and <key\-file> the file containing the key(s) to import.  The keyring
+must be located in \fIpathetc\fR/pgp/ncmring.gpg (create the directory
+before using \fBgpg\fR).  For old PGP-generated keys, you may have to use
+\&\fB\-\-allow\-non\-selfsigned\-uid\fR if they are not properly self\-signed,
+but anyone creating a key really should self-sign the key.  Current
+\&\s-1PGP\s0 implementations do this automatically.
+.Sp
+The keys of NoCeM issuers can be found in the web site of \fIThe NoCeM Registry\fR:
+<http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html>.  You can even
+download there a unique file which contains all the keys.
+.IP "2." 4
+Create a \fInocem.ctl\fR config file in \fIpathetc\fR indicating the NoCeM issuers
+and notices you want to follow.  This permission file contains lines like:
+.Sp
+.Vb 3
+\&    annihilator\-1:*
+\&    clewis at ferret.ocunix:mmf
+\&    stephane at asynchrone:mmf,openproxy,spam
+.Ve
+.Sp
+This will remove all articles for which the issuer (first part of the line,
+before the colon \f(CW\*(C`:\*(C'\fR) has issued NoCeM notices corresponding to the
+criteria specified after the colon.
+.Sp
+You will also find information about that on the web site of
+\&\fIThe NoCeM Registry\fR.
+.IP "3." 4
+Add to the \fInewsfeeds\fR file an entry like this one in order to feed
+\&\fBperl-nocem\fR the NoCeM notices posted to alt.nocem.misc and
+news.lists.filters:
+.Sp
+.Vb 3
+\&    nocem!\e
+\&        :!*,alt.nocem.misc,news.lists.filters\e
+\&        :Tc,Wf,Ap:<pathbin>/perl\-nocem
+.Ve
+.Sp
+with the correct path to \fBperl-nocem\fR, located in <pathbin>.  Then, reload
+the \fInewsfeeds\fR file (\f(CW\*(C`ctlinnd reload newsfeeds 'NoCeM channel feed'\*(C'\fR).
+.Sp
+Note that you should at least carry news.lists.filters on your news
+server (or other newsgroups where NoCeM notices are sent) if you wish
+to process them.
+.IP "4." 4
+Everything should now work.  However, do not hesitate to manually test
+\&\fBperl-nocem\fR with a NoCeM notice, using:
+.Sp
+.Vb 1
+\&    grephistory '<Message\-ID>' | perl\-nocem
+.Ve
+.Sp
+Indeed, \fBperl-nocem\fR expects tokens on its standard input, and
+\&\fBgrephistory\fR can easily give it the token of a known article,
+thanks to its Message\-ID.
 .PP
-.Vb 2
-\&    annihilator-1 at erlenstar.demon.co.uk:*
-\&    clewis at ferret:mmf,spam
-.Ve
+When you have verified that everything works, you can eventually turn
+off regular spam cancels, if you want, not processing any longer
+cancels containing \f(CW\*(C`cyberspam\*(C'\fR in the Path: header (see the
+\&\fIrefusecybercancels\fR parameter in \fIinn.conf\fR).
 .SH "FILES"
 .IX Header "FILES"
-/usr/local/news/etc/nocem.ctl
+.IP "\fIpathbin\fR/perl\-nocem" 4
+.IX Item "pathbin/perl-nocem"
+The Perl script itself used to process NoCeM notices.
+.IP "\fIpathetc\fR/nocem.ctl" 4
+.IX Item "pathetc/nocem.ctl"
+The configuration file which specifies the NoCeM notices to be processed.
+.IP "\fIpathetc\fR/pgp/ncmring.gpg" 4
+.IX Item "pathetc/pgp/ncmring.gpg"
+The keyring which contains the public keys of trusted NoCeM issuers.
 .SH "BUGS"
 .IX Header "BUGS"
-The Subject header is not checked for the @@NCM string and there is no
-check for the presence of the References header.
-The Newsgroups pseudo header is not checked, but this can be done in
+The Subject: header is not checked for the @@NCM string and there is no
+check for the presence of the References: header.
+.PP
+The Newsgroups: pseudo header is not checked, but this can be done in
 \&\fIlocal_want_cancel_id()\fR.
-The Hierarchies header is ignored.
-.SH "AUTHORS"
-.IX Header "AUTHORS"
+.PP
+The Hierarchies: header is ignored.
+.SH "HISTORY"
+.IX Header "HISTORY"
 Copyright 2000 by Miquel van Smoorenburg <miquels at cistron.nl>.
 .PP
 Copyright 2001 by Marco d'Itri <md at linux.it>.
+.PP
+$Id$
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIgpgv\fR\|(1), \fIgrephistory\fR\|(1), \fIinn.conf\fR\|(5), \fInewsfeeds\fR\|(5), \fIpgp\fR\|(1).



More information about the inn-committers mailing list