1 .\" $Id: t-prot.1,v 1.178 2010/03/06 01:31:33 jochen Exp $
3 .TH T-PROT "1" "March 2010" "T-PROT"
5 t-prot \- TOFU Protection - Display Filter for RFC 5322 messages
7 .BI "t\-prot [" OPTIONS "]..."
10 This program is a filter to improve the readability of internet
11 messages (emails and usenet posts) by *hiding* some annoying parts,
12 e.g. mailing list footers, signatures, and TOFU (see definition below),
13 as well as squeezing sequences of blank lines or punctuation.
14 The program also detects TOFU or a high quoting ratio in a message (so
15 you may take appropriate action, e.g. when submitting messages to a mailing
16 list or a news server).
18 The filter is written in Perl and relies on input to be a single
19 message conforming to RFC 822 or its successors, RFC 2822 and RFC 5322.
20 In messages conforming to MIME (RFCs 2045-2049) t\-prot handles text/plain
21 parts, others are not touched.
23 Already reformatted messages are handled well: the script was
24 initially designed to cope with the output of the MUA mutt (which
25 is the reason for not using standard CPAN modules for handling
28 For easy usage, you can include the file muttrc.t\-prot in your
29 ~/.muttrc. Also coming with the t-prot package is the example S-Lang
30 macro t\-prot.sl for using t-prot from within slrn. There is a
31 proof\-of\-concept filter for INN2, which you will have to adapt to
32 the needs of the news site you host (please see the file for details).
35 If you do not specify any options, t\-prot does ... nothing. Every
36 feature you want must be turned on explicitely.
37 Admittedly, we have quite a number of options for t\-prot. To limit
38 confusion they are grouped into five sections: Input/Output Options,
39 Advertisement And Mailing List Footers, Filtering Options, Detection
40 Options, and Other Options. While the others should be quite clear,
41 filtering and detection might deserve a word (or two).
43 If you want to tune the appearance of your mail from within your MUA
44 (or news messages from within your NUA), then go for the Filtering
47 If you want to use t\-prot to check on mails before they are submitted
48 to mailing lists, fed to your news server, or delivered by your MDA,
49 then have a peek at the Detection Options section. You may accept or
50 reject/bounce messages depending on t\-prot's result.
51 .SH INPUT/OUTPUT OPTIONS
54 Defines an input file; default is '\-' i.e. STDIN.
57 Defines the output file; default is STDOUT.
60 Input consists just of the message's body. There are no RFC 5322 header
64 This does not work with \-\-pgp\-short, and multipart messages will not
65 be detected due to missing headers.
67 .B "\-\-lax\-security"
68 Allow insecure writing method. DO NOT USE UNLESS YOU REALLY KNOW WHAT
69 YOU ARE DOING. (This ugly workaround is needed for some early mutt versions
70 and should NEVER be used as a default, otherwise it will probably turn into
73 You can use this option safely to enable
74 .BR "\-o" " /dev/null."
76 .BR "\-\-max\-lines" =x
77 Maximum number of lines a message may count (with headers). If the message
78 is longer than x lines, the message will not be processed but printed
79 unmodified. Exit status will be EX_DATAERR except when called with \-Mmutt.
80 .SH ADVERTISEMENT AND MAILING LIST FOOTERS
83 "commercial signature":
84 Hides "footers" (signatures) from commercial email providers.
86 This option compares the last lines of the message body with any
87 footer file found in the directory specified with
88 .BR "\-A" " DIRECTORY"
89 (which is mandatory for this option). The comparison is done by perl's
96 This option is not needed if
101 "enable aggressive ad footer matching":
102 With this option enabled, t-prot makes footer detection really greedy: We
103 assume that commercial email providers aren't even frightened to append
104 changing texts *under* their ads which are appended to the message body.
105 Because these texts even have changing lengths we simply detect the
106 lines of the footer *anywhere* in the body of the message and assume that
107 everything below belongs to the footer. (Man, if life where always that
110 With this option even GMX ads should be easy to hide -- you buy this with
111 a slight performance hit (which is the reason this option is disabled by
112 default), and with the possibility that sometimes the algorithm is just a
116 This requires a directory with footer files to be given with option
117 .BR "\-A" " DIRECTORY".
119 .BR "\-A" " DIRECTORY"
120 "ad footer directory":
121 Defines the directory which contains the advertisement list footers (one
122 footer per file) which are to be tested when removing them with options
127 This option is also needed if you do not want signature lengths to be
128 counted wrong or fullquotes get undetected when an ad footer is
129 appended at the bottom of the message (especially when using
136 Hides "footers" (signatures) from mailing lists. Footer detection works like the
141 This requires a directory with footer files to be given with option
142 .BR "\-L" " DIRECTORY".
149 "enable aggressive mailing list footer matching":
150 With this option enabled t-prot makes footer detection really greedy: Should
151 be helpful with broken list servers, or even if your email provider munges
152 the bodies of your messages.
154 Works similar to \-\-ftr\-ad, just that it is intended for mailing list footers.
157 This requires a directory with footer files to be given with option
158 .BR "\-L" " DIRECTORY".
160 .BR "\-L" " DIRECTORY"
161 "list footer directory":
162 Defines the directory which contains the mailing list footers (one footer
163 per file) which are to be tested when removing them with the options
168 This option is also needed if you do not want signature lengths to be
169 counted wrong or fullquotes get undetected when a mailing list footer is
170 appended at the bottom of the message (especially when using
176 .BR "\-\-bigq" [=n[,x]]
178 Blocks of quotes with more than n lines will be shrunk to x lines.
179 Defaults are 30 for n and 10 for x.
183 Squeezes a sequence of blank lines to just n blank lines. n defaults to 2.
186 Tolerate unified diff (see
190 appended after the signature (which usually makes the signature too long
193 Also, protect diff standard output from hiding (which would otherwise be easy
199 Squeezes a sequence of four or more dots, exclamation marks, or question marks
200 to only three dots or marks, respectively.
203 Hides TOFU as produced by Novell Groupwise.
207 Tries (not too aggressively) to fix those broken zig-zag-shaped lines
208 wrapped around by some MUAs which are known as "Kammquoting" in German.
211 This option is considered stable by now. However, sometimes Kammquotes
212 should have been removed but weren't. Please send a bug report if this
213 happens to you (after carefully reading the BUGS and REPORTING BUGS
214 section of this man page, that is).
216 Please also note that enabling this option is quite a performance hit.
219 Minimum length difference between two lines for wrapped line detection on
220 Kammquotes. For details, please see the source code.
222 Anyway, lower values make the algorithm more aggressive, higher values
223 make Kammquotes harder to detect. Default is 20.
229 Maximum line length for wrapped line detection on Kammquotes. For
230 details, please see the source code.
232 Anyway, higher values make the algorithm more aggressive, lower values
233 make Kammquotes harder to detect. Default is 80.
239 Minimum line length for wrapped line detection on Kammquotes. For
240 details, please see the source code.
242 Anyway, lower values make the algorithm more aggressive, higher values
243 make Kammquotes harder to detect. Default is 65.
248 .BR "\-\-locale" =LOCALE
249 Specify which locale to use for correct parsing of your MUA's formatting
250 of the displayed message (usually it is the locale your MUA uses). Right
251 now this option is only used when
253 is specified, but this may change in future. You need the Perl module
262 with locales, t-prot will only work correctly if you specify the corresponding
263 locale string. Alternatively, you can use the environment variables
268 to specify the locale string.
271 You also have to make sure you are running t-prot
276 versions. T-prot detects
280 locales of the recent stable versions of those programs, earlier versions
281 might not work well with a recent version of t-prot. There are patches available
282 to make t-prot fit into environments with some other
288 .BR "\-M, \-\-mua" =MUA
290 Turn on special treatment for some mail user agents. (Right now only
292 is supported, but more might be added in future.)
294 If your MUA is supported by this feature you must ensure t-prot makes
295 use of it when called from within your MUA to work as desired.
299 Hides TOFU as given by some Microsoft mailers. (You all surely know these
300 fullquotes beginning with
302 "\-\-\-\-\- Original Message \-\-\-\-\-"
304 and some header lines...)
307 Burn CPU cycles trying to be smart with MS style TOFU: If there are PGP
308 signed parts inside the TOFU, the text still might conceal other message
309 parts and therefore should not be deleted.
311 Please note that this is probably just a waste of time because most
312 MS Outlook users who do produce this kind of TOFU won't care about
313 making their messages the least bit readable or even predictable. So
314 this option will probably just be interesting for mutt message hooks
315 (to activate it on demand when you
316 .BR know " the sender tries to write legible messages)."
323 Move PGP verification output to bottom; requires
326 .B \-\-pgp\-move\-vrf
327 Move PGP verification output to bottom only if verification shows a good signature
328 and the signature could be verified as authentic (using a trust path). If there is
329 any problem with the signature, the PGP output should not be moved so the user is
330 more likely to notice. Requires
334 If gpg is terminated before finished (e.g. hitting Ctrl-C, or using
336 we cannot always detect if the check was interrupted. Though t-prot tries
337 to be smart, there will be false positives.
340 Hide non-relevant PGP key uids; requires
345 Hides all mail header lines.
348 Subject lines with multiple reply prefixes (Re: and translations into other
349 languages) get squeezed to only one prefix.
352 "supression of overlong signatures":
353 Signatures are to be n lines (not including the one containing dash-dash-space)
354 or less. If there are more, it is probably not that spirited after all.
355 So with this option you trade it for a
359 If no n is given, default is 4. (We do not recommend using a value other
360 than 4. Consider this old-fashioned, but we actually do *like* RFC
364 The line containing "\-\- " ist not counted when testing for an overlong
365 signature, but it is included when displaying how many lines were deleted.
368 "signature deletion":
369 Hides signatures, i.e. all lines after a "signature dashes" line,
370 i.e. a line with three characters: dash-dash-space (no more, no less).
373 Sanitize headers "To:", "From:" and "Subject:": Quoted-printable gets
374 fixed to the corresponding chars. German Umlauts are translated to their
375 "ae", "oe", "ue" pendants.
377 Useful e.g. for searching by subject within MUAs like Berkeley mailx.
379 .BR "\-\-sigsmax" [=n]
380 "maximum number of tolerated signatures":
381 Here you can define how many signatures you accept to be treated as such.
382 (Most significant behaviour is when microsoft style quotes are removed.
383 Experts please see the code for the more subtle implications of this
386 Leave empty or specify zero to have an unlimited number of sigs.
390 "SpamAssassin workaround":
391 SpamAssassin (available at
392 .IR http://spamassassin.org/ ") often is configured that it adds some"
393 lines to the message body containing information about the spam criteria
394 which were found matching for the message. This option enables an extra
395 test to avoid false positives for Microsoft style TOFU on such messages.
399 Hides "traditional style" TOFU, where each line begins with an
400 indent string like "> ".
402 (You may edit the indent pattern in the script itself to suit your needs,
408 "whitespace deletion":
409 Hides trailing whitespace (sequences of space and tab).
410 CAVEAT: This may lead to interesting effects with crossposts
411 between mailing lists or with undetected signature attempts.
412 .SH DETECTION OPTIONS
415 "user defined bounce message for picky delivery":
416 You may specify your own bounce message to be returned when we try to deliver
417 an email and bounce it because there is TOFU inside. See
420 .BR "\-p" " [ADDRESS]"
422 If we really find some TOFU, abort with exit code
424 Otherwise redirect the message to ADDRESS if given.
426 Intended for use from within mail delivery agents (MDAs) or mail transport
427 agents (MTAs), or even from with INN, so the message bounces if TOFU is
428 detected, and does not get on *your* nerves. :)
430 As an example for usage with
432 put this line into your alias file and invoke
435 notofu: |"/usr/local/bin/t\-prot \-mt \-p=user@mydomain"
437 This will bounce messages for <notofu@domainname> if any TOFU is detected
438 inside the message, and deliver it to <user@mydomain> otherwise.
440 that TOFU is only detected if you specify
445 .B PLEASE be careful not to bounce messages to mailing lists!
447 .BR "\-\-check" [=FLAGS]
448 Run checks. If successful, print an error message and quit with
449 an appropriate exit code. Useful e.g. for rejecting messages from
452 Flags are separated by commas (no whitespaces), and can be the
453 following (right now just one flag):
457 If the quoting ratio is n or more, the message is rejected. Must be
458 between 0 and 1, or else it is entirely disabled. Default is 0.75
459 (i.e., 75% of the message lines are quotes).
462 Print envelope info to syslog when bouncing TOFU contaminated email.
463 Default syslog facility is mail.debug. Requires
468 Displays a short help text with a summary on all options, and exits.
470 .B "\-v, \-\-version"
471 Prints the current version number and exits.
473 The environment variables
478 are read and respected when interpreting output by mutt or gnupg
479 (unless they are overruled by the \-\-locale option). T-prot's own
480 output is English regardless of any locale setting.
482 On program exit, t-prot uses exit codes from
483 .I /usr/include/sysexits.h
484 and thus behaves in a manner that sendmail and others understand when
487 Currently, the codes used are
505 If, however, perl fails to compile and execute t-prot, perl's normal
506 exit codes will be returned.
508 TOFU is an abbreviation which mixes German and English words;
509 it expands to "text oben, full-quote unten" which means
510 "text above - full quote below" and describes the style of so
511 many users who let their mailer or newsreader quote everything
512 of the previous message and just add some text at the top;
513 obviously they think that quoted text must not be changed at all.
514 This is quite annoying as it needlessly sends a lot of data
515 even when it is not required. Some editing of messages is desired.
516 Please point these people to the page
517 .I http://www.river.com/users/share/etiquette/edit.html
520 There are several ways to fine-tune t-prot's performance:
522 Some command line options are quite grave a performance hit -- do not
523 use \-k and especially \-\-ms\-smart if you are content without them.
525 Checking for special footers is very costly as well. Put as few footer
526 files as absolutely needed in any footer directory.
528 All PGP related options are eating up lots of CPU time. Try to avoid them
529 on unsigned and unencrypted messages.
531 When calling t-prot from within mutt, you might use mutt's folder-hook
532 and message-hook facilities to turn options on only when needed, e.g. to
533 set up a different footer directory for each mailing list folder.
537 I want to make my mailing list footer files match more different mailing
538 list footers. Can I use regular expressions, or how can I accomplish
542 Nope, regexp's do not work here. The comparison is made by the perl
547 for more detailed info), so you must exactly match the beginning of the
548 line. The longer the line you specify, the more precise the match; if
549 your line is empty you match unconditionally.
553 I use the options \-l and \-L to supress mailing list footers when
554 displaying messages in
556 This does work sometimes, but sometimes it does not: the footer is not
557 detected, and therefore full quotes are not deleted and signatures are
558 detected as too long (which they aren't).
561 This might occur if the message is badly encoded, so mutt cannot resolve
562 all encoded characters, e.g. if you have an encoded message on a mailing
563 list, and majordomo appends a mailing list footer in a different encoding
564 (or even plain us-ascii). "\-\- " simply does not match "\-\-=20".
566 Another problem are non-us-ascii characters. Just avoid them, and
567 everything should work fine.
569 See the preceding Q+A for a solution.
573 I want to write a message which contains parts that should *not* be
574 deleted even when filtered with t-prot. Is this possible?
577 Yes, but please do not spread word of it. Make unobstrusive use of the
584 This line is protected from being filtered by t\-prot !!!!!!!
588 Text coming now is not.
590 Written by Jochen Striepe <t\-prot@tolot.escape.de>.
592 All of the documentation and software included in the t-prot releases
593 is copyrighted by Jochen Striepe (except when explicitly stated otherwise).
595 Copyright \(co 2001-2010 Jochen Striepe. All rights reserved.
597 Redistribution and use, with or without modification, are permitted
598 provided that the following conditions are met:
600 1. Redistributions of source code must retain the above copyright notice,
601 this list of conditions and the following disclaimer.
603 2. All advertising materials mentioning features or use of this software
604 must display the following acknowledgement:
606 This product includes software developed by Jochen Striepe and others.
608 3. Neither the name of the author nor the names of any contributors may
609 be used to endorse or promote products derived from this software without
610 specific prior written permission.
612 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY
613 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
614 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
615 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY
616 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
617 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
618 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
619 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
620 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
621 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
622 .SH IDEAS AND INSPIRATION
623 Many good ideas, bug reports and support from (in alphabetical order) Bjoern
624 Buerger, Bjoern Laessig, Christian Borss, Gerfried Fuchs, Martin Neitzel, Martin
625 Dietze, Matthias Kilian, Ralf Doeblitz, Sven Guckes and many more (see the
626 ChangeLog for active contributors). Many thanks to all of them!
628 Many thanks to Gerhard H. Wrodnigg who uses a TOFU protection script
629 in order to keep the responses to his cancel bot reasonably short. The
630 entire inspiration for this hack came from the "TOFU protection" line of
631 his script on many usenet postings.
633 You can get the latest version from
634 .IR http://www.escape.de/users/tolot/mutt/ .
636 There is a problem when mutt gives a PGP verified or even a multipart
637 message to t-prot: The information where the PGP encrypted/signed data
638 or even attachments begin and end is plainly embedded in the text, not
639 really cleanly recognizable for t-prot. The problem should be worked
640 around by now, please send a bug report if it does not work for you.
642 Please note that t-prot development happens on
643 .BR "current stable perl versions only" .
644 If you do run t-prot on earlier (or unstable) perl versions, you might
645 encounter perl compiler bugs (or funny t-prot behaviour). One solution
646 is to upgrade your perl, another is simply to write a bug report. If
647 you do not run a current perl version, please include this information
654 * you found it in the TODO file coming with the distribution. We do
655 know those and try to fix them as soon as possible.
657 * you have an old t-prot version. If you encounter a problem, first
658 see if there is a new t-prot version which fixes the issue. If you
659 upgraded to the latest version and it still occurs, a bug report is
662 If you noticed a bug when processing a message and want to provide the
663 t-prot team with some useful info, please:
665 * if invoking t-prot by mutt's
667 facility, just set display_filter to something like
669 "tee ~/foobar | t\-prot <your options>"
671 and include ~/foobar in the bug report -- this way we might reproduce
672 the bug much easier if you are using a different environment than we do.
674 * provide information on what command line options you use t-prot
675 with, what perl version t-prot runs on your system, and what else might
676 be important to enable us reproducing the bug.
678 Send your bug report to
679 .IR <t\-prot\-bugs@tolot.escape.de> .
684 section). Beside that, all main features should be implemented by now.
685 See the TODO file for more information.
689 and the part about "display_filter",
693 RFCs 2045-2049 and 5322,
695 .I http://freshmeat.net/articles/t\-prot/
696 (a nice, solid introduction),
698 .I http://got.to/quote/
701 .I http://www.river.com/users/share/etiquette/edit.html
702 (the Learn To Edit Messages HowTo has found a new home).
projects / pkg / t-prot.git / blob