chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / 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