modtool v2.0 ============ (C) Christian Alice Scarborough 1996 Email: ccs95@aber.ac.uk Released under the GNU public licence - see file COPYING for details Abstract -------- modtool is a general purpose Perl program for moderating mailing lists and/or Usenet newsgroups from a UNIX shell. It does the following things. o Displays submitted articles o Posts accepted articles, allowing the moderator to edit them first if necessary. o Automatically checks for other moderated groups, and mails article to next moderator in line if necessary. o Sends form rejection letters, prepared in advance, to the poster (further comments can be added, or a personalised reply sent if desired). o Cancels forged postings to the group o Creates and mails RFC1153 compliant digests either as articles are approved, or by reading the group. o Automatically replies to incoming submissions when used in conjunction with a mail filter. o Allows moderation of multiple groups/lists by using multiple configuration files. Prerequisites ------------- modtool requires the following to be installed on the UNIX system which it is run from. 1) Perl v5.000 or greater 2) A pager (more should work, less is better) 3) A UNIX editor (if you want to use the editing facilities) 4) Mail to the moderation address stored in a standard UNIX mailbox file. Caveat ------ modtool is my first ever Perl program. It represents about 48 hours coding time (including the time taken to learn Perl). It is not neat. It is not efficient. It is not likely to handle something extremely odd happening in an incoming article (eg no Subject: field). It does, however, seem to work. Use at your own risk. I will attempt to support it by email, but only as and when I have time, so you should consider it UNSUPPORTED software. If you do decide to use it, please send me email, so that I can inform you when bugfixes and updates are available. You can use modtool completely free of charge, but if you find it especially useful then please bear in mind that I'm an impoverished research student, and any donation you can afford would not go amiss. Installation ------------ o Unpack the files in this archive into a directory of their own. Edit the .modtoolrc file in your favourite editor, and change all the variables so that they refer to your newsgroup or mailing list and setup. All of the variables are documented within the .modtoolrc file itself. (Note that lines beginning with a # are comments, and are ignored by modtool.) o You may want to edit the 'rejections' file too. The first word of each line is the name of a file (in the working directory of the program) which contains the text of a form rejection letter. The rest of the line is a short description of each letter that the program uses to help you choose the letter you wish to send. You can have up to ten of these letters. o You should also edit the mod.sig file to contain the information you want putting at the bottom of each message. If you don't want a sig, leave it empty, but it must be there, or the program will fail. (You can change the filename by editing one of the variables though.) Usage ----- Modtool has several modes of invocation. To help help on the command line switches, type modtool -h TO run modtool, change to the directory containing the program and type modtool The first message will be displayed. Once you have seen the whole message, you can either accept (post) it, reject it, junk (erase) it, display it again, save it to a different mailbox, or quit. You should press the appropriate letter at the prompt. The letter inside the brackets is the one that you press (eg press 'j' to (J)unk an article). The 'n' and 'p' keys allow you to skip between all of the articles in the file. If you opt to post the article, you are offered a further menu that allows you to send the article, edit the article you are about to post, to list the article as it will be posted (note: this is a Good Idea, as the program changes a lot of the headers around), or cancel and return to the previous menu. Canceling will not delete the current article. If you decide to reject an article, a menu comes up detailing the stock responses that you have written. To choose one of these, press the appropriate number (0-9), or you can write your own response. Once this is done, you are given the opportunity to edit the reply, or send it back to the poster. Junking an article throws it away. You can't get it back, so be careful with this option. It will ask you to confirm your action. The save function copies the mail to another folder (the name of which is again specified in the configuration file), and removes it from the incoming post file. This is in case people send mail to the moderators to the submission address instead of the admin address. You will be prompted for a file name, but can just press return to use the default from the configuration file. If the file does not exist, modtool will ask you to confirm creation of this file. You can quit after any article (the current article will not be deleted). When there are no more articles left, the program ends. A note about multiple moderated groups -------------------------------------- Modtool will automatically detect other moderated groups in the Newsgroups: line of any post, provided that they exist on the news server at the moderator's home system. Modtool will assume that any groups appearing before the moderator's group on the Newsgroups: line have been seen by the appropriate moderator, and have been passed on by them for approval. Modtool will print a warning message if it makes such an assumption, so you can check that it really has been approved. If not, you might want to save it out to a separate file for manual processing. Modtool will also check if groups appearing after the moderators group in the Newsgroups: line have been approved by PGP Moose. Note that modtool will not check the validity of the PGP Moose X-App: header - if the header exists, it will simply assume that the signature is valid, and will consider this article to have been approved by the moderator in question. This means that if such approval has been forged, the article may later be cancelled by a PGP Moose daemon. If there are any moderated groups remaining, then modtool will take the next such group on the Newsgroups: line and mail the article to the moderator of that group. Note that, unlike PGP Moose, modtool does not alter the order of newsgroups within the header. (The author considers this sort of behaviour to be a Bad Thing.) Canceling articles ------------------ To use modtool to cancel forged submissions, use the following command: modtool -c < This sends out a cancel message for the article in question. modtool assumes the -c parameter if you invoke it as 'cancel'. Thus I have a symbolic link to modtool in my News directory, so to cancel an offending article from within trn, I just type | cancel on the trn command line at the end of the message. Auto-replying ------------- You can get modtool to send out automatic replies to incoming submissions, to acknowledge receipt, for example. The syntax of the command is modtool -r < You can also create a symbolic link ending in "reply" which will cause modtool to assume the -r switch. The idea here is that before your mail filtering program saves a copy of each new message to the incoming file, you should pipe the message to modtool. Modtool will then send back mail telling the sender that their mail has been received. The method for doing this varies from filter to filter, but here's the recipe that I use in procmail :0 * ^TOcomp(\.|-)org(\.|-)team-os2@ { :0 c | modtool -r :0: cot } Modtool will not cause any mail loops to occur, because it stores email addresses that it has sent replies to that day, an will not send a reply to any one address more than once in a day. You can use the special symbol %subject% within the text of your reply, which will be replaced with the Subject: line from the original mail. See the configuration file for more details. Digests ------- Modtool provides a way for you to archive posts to your group or list in a RFC1153 compliant digest. It will even mail them out when completed if you have a mailing list set up to distribute the group or list in digest form. The relevant section of the configuration file explains the mechanics of this process. Modtool normally archives the submissions as you approve them, but where multiple moderators work on one group, this is sometimes undesirable, since only the posts that you approve will be added to the archive. Modtool does provide a solution to this problem in that it allows the user to turn of digest generation when the message is approved, and instead to create digests by reading approved posts directly from the newsgroup itself. The syntax here is modtool -d (or again, a symbolic link to something ending in "digest" will make the -d implicit). This should be run at regular intervals (say every day), and is probably best accomplished using a cron job (type "man crontab" at a command line for details of how to set this up). The posts are then read directly from the newsgroup using NNTP and placed into digests, thus picking up any posts approved by other moderators. If you are using a cron job, then you should redirect output to /dev/null, otherwise you will get lots of messages from root containing the output from the command. Doing this will not prevent error messages being recorded and sent to you in this way. For example, in my crontab file, I have 27 01 * * * modtool/modtool -d > /dev/null Advanced configuration file whizzyness -------------------------------------- By default modtool looks for a configuration file called .modtoolrc, but it is possible to specify an alternate configuration file on the command line. For example, to use the configuration file .mycfg, type modtool -f .myfile In addition, you can specify the a configuration file in the MODTOOLRC environment variable, and modtool will use this as the default configuration file instead. Modtool looks for configuration files in the current directory, the same directory as modtool is run from, and the user's home directory, as well as on an explicit path if you specify one. If you moderate multiple groups, multiple configuration files are the only way to use modtool to moderate all of these groups. You may like to use a shell script to make your life easier - something like: #! /bin/sh modtool -f group1 modtool -f group2 modtool -f group3 To invoke modtool for each group that you moderate in turn. Since many of the variables that you use will be duplicated between these different files, you can use the special command include= within a config file to cause modtool to read and include the variables defined in in addition to those in the current file. You may occasionally wish to undefine variables defined in an included file. To do this use the statement = (ie just press return after the equals sign). Here is a configuration file that I use for sending out automatic replys. The machine that receives and processes mail is different to the one that I normally run modtool on, so a few changes to the configuration are necessary # Load in the usual defaults include=.modtoolrc # Working directory is differently named on this machine wd=/aber/ccs95/cot # Also requires a different date command datecmd=date -u +"%a, %d %h %y %H:%M:%S GMT" # Again, this file is stored in a different path on this machine arepfile=docs/ack # the digest files aren't here, so we disable digests here digest= Hopefully this makes some sort of sense. Future plans ------------ I don't really have any plans for a modtool 2.1. Let me know if there is anything that you think is missing. Acknowledgements ---------------- modtool contains code that is based in places upon code snippets provided by the following people: The anonymous author of one of the Perl man pages Thomas Koenig David C. Lawrence I'd also like to thank my Mother and Father, without whom this program would have been impossible to write. Revision History ---------------- v2.0 - 23rd Oct 1996 o Several minor bugfixes and efficiency increases. o Can create RFC1153 compliant digests from accepted posts, or directly from the newsgroup o Configuration data is now stored in and read from a separate configuration file. o can automatically reply to incoming mail when invoked from a mail filtering program. o Minor enhancements to save to file feature. o Command line help / checking added v1.1 - 15th Sept 1996 o No longer requires inews or sendmail, since it can now do mail and news transfers via SMTP and NNTP respectively. o Can now cancel posts to your group, should you decide they shouldn't be there. o Messages no longer have to be processed sequentially. o A rather nasty bug which meant that any moderation mail received whilst in modtool was lost has been fixed. v1.0 - initial release o Viewing, Posting, rejection, save to file, Junk features implemented. Legal Gibberish --------------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.