doc/hook-tcl

   1 NOTE:  The Tcl support described in this file is disabled.  The code is
   2 all still there, but you have to define DO_TCL manually while compiling to
   3 enable it.  Compiling in Tcl filtering was causing random innd segfaults
   4 even if no Tcl filters were defined, so it's been turned off to prevent
   5 confusion.
   6
   7 The Tcl code will be removed in the next major release of INN since no one
   8 appears to be using it and the code is unmaintained and has no champion.
   9 If you want to resurrect it, it may be better to start from scratch, since
  10 a lot has changed about INN since the filters were originally written and
  11 the Perl and Python filters have far more capabilities.
  12
  13
  14 Note, you need tcl 7.4. Rumour has it that 7.5 won't work.
  15 ---------------------------------------------------------------------------
  16 Subject: TCL-based Filtering for INN 1.5
  17 Date: Mon, 07 Feb 94 12:36:47 -0800
  18 From: Bob Heiney <heiney@pa.dec.com>
  19
  20
  21 Several times in the past few months, a site or two has started posting
  22 the same article over and over again, but with a different message id.
  23 Usually this is caused by broken software (e.g. mail <-> news gateways,
  24 which many have written, but few have written correctly).
  25 Occasionally, however, the reposting is intentional.  A recent example
  26 would be the "Global Alert: Jesus Is Coming" message which was posted
  27 to over 2200 newsgroups (each copy with its own message id).
  28
  29 I expect this to happen more often as the Internet continues its explosive
  30 growth.  Although my site (decwrl) usually has enough excess capacity to
  31 weather these problems, many other sites cannot.  One problem on
  32 comp.sys.sgi.misc several months ago spewed 40MB of duplicate articles
  33 before the offending sites were fixed, and this overflowed the spool at
  34 many sites.  Even for sites with lots of resources, there's still no need
  35 to propagate erroneous or malicious duplicates.
  36
  37 I wanted a way to protect my site that was highly specific, flexible, and
  38 quick.
  39
  40 Examination of duplicated articles showed that although the message ids
  41 were different, it was usually easy for a news admin to come up with a
  42 few rules based on the headers of the article that could be used to
  43 differentiate the duplicates from other articles.  (E.g. from
  44 John.Doe@foo.com to comp.sys.sgi.misc with 'foobar' in the subject".)
  45 I concluded that modifying innd to let me say "kill things that look
  46 like _this_" would solve my problem.
  47
  48 I also wanted to allow enough flexibilty in the design that I could
  49 later work on automatic detection and elimination of excessive
  50 duplicates (using a body checksum instead of headers).
  51
  52 Since I needed a fairly powerful language to do all this, and since the
  53 world doesn't need yet another special language, my solution was to add TCL
  54 support to INN.  I then modified "ARTpost" to call a TCL procedure which
  55 could then accept or reject the article.  The TCL code has access to an
  56 associative array called "Headers", which contains all of the articles
  57 headers.  The TCL code may also call a 32-bit article-body checksum
  58 procedure (this is to aid in future automatic detection of duplicates).
  59
  60 Here's what a sample TCL filter procedure looks like:
  61
  62 proc filter_news {} {
  63   global o Headers
  64   set sum [checksum_article]
  65   puts $o "$Headers(Message-ID) $sum"
  66   set newsgroups [split $Headers(Newsgroups) ,]
  67   foreach i $newsgroups {
  68     if {$i=="alt.test" && [string match "*heiney@pa.dec.com*" $Headers(From)]} {
  69       return "dont like alt.test from heiney"
  70     }
  71   }
  72   return "accept"
  73 }
  74
  75 The above TCL code does a few things.  First it computes a 32-bit
  76 checksum and writes it and the message ID to a file.  It then rejects
  77 articles from me to alt.test.
  78
  79 The work I've done is totally integrated into the INN build and runtime
  80 environments.  For example, to turn filtering off, you'd just type
  81
  82         ctlinnd filter n
  83
  84 To reload the TCL code that does the filtering, you just say
  85
  86         ctlinnd reload filter.tcl 'your comment here'
  87
  88 (You may specify TCL callbacks to be executed right before and/or right
  89 after reloading, in case your filter is doing fancy stuff.)  See the
  90 ctlinnd man page for more info.
  91
  92 Filtering capability that's this powerful can be used for many
  93 purposes, some benign and useful (excessive duplicate detections,
  94 on-the-fly statistics), others abusive.  I would ask that news admins
  95 think carefully about any filtering they do.
  96
  97 /Bob
  98
  99