Instructions on Setup and Use of the Robomod

Instructions on Setup and Use of the Robomod

Attention! Before reading instructions, please read the specification and description of how the robomoderator works.

Contents


Where to get HELP

First of all, please take your time and be prepared to be patient. Since configurations of local systems and newsgroups are different, setting them up takes some time. There are two ways you can get help. The first one is free, the second is not. If you know something about Unix, you probably can try to go the first route. If you are not a Unix person, second route may be the way to go.

Initial Setup

The steps outlined in this chapter should be done only once, when you start setting up the robomoderator. Suppose that you, John Doe < johndoe@yoursite.com> are the supporter of the newly created group comp.sys.foobars.moderated , and your users like to refer to your group as csfm.

Setting up a separate Unix account. [SYSADMIN]

You need a separate user ID to run your robomoderator program. There are two compelling reasons for that. First of all, submissions to your newsgroup will arrive to the moderation address by email. It is very easy to confuse submissions and personal emails. Imagine how disappointed would be your private correspondents if you mistakenly post their private emails!

Second, and more important, reason for having a separate account for personal work and robomoderator is security. Internet is a wild and dangerous place full of people willing to inflict serious harm on others just for the sheer fun of it. I have proofread and verified all moderation scripts for security, and built extensive protection against malicious attacks aiming to hack robomoderation account. However, I cannot give you a 100% assurance that robomoderation process is secure.

If you operate robomoderator from your private account and someone manages to hack it, all your private files will be open for prying eyes of people whom you do not even know. If it happens in an isolated account, the damage will be much more limited.

All in all though, you can get along with just using your Unix account.

Note: If you do not want to deal with setting up a Unix account, I offer a complete moderation site hosting service called ReadySTUMP.

If you do not have superuser privileges, you cannot set up a legitimate account. Please ask your system administrator to do it for you. A good name for such account would be comprised of first letters of your newsgroup name. For example, account for soc.culture.russian.moderated is called scrm@algebra.com (I am the sysadmin of algebra.com).

You may call the robomod's account csfm@yoursite.com.

Setting up sendmail aliases. [SYSADMIN]

Remember that robomoderator performs several functions:

For each such purpose, a separate email address must be established. Note the distinction between an email address and a user id: several email addresses may correspond to one user ID. These addresses should normally be sendmail aliases. These aliases are [normally] defined in file /etc/aliases. You should ask your systems adminiastrator to establish these aliases for your group. Below is the example of the part of aliases file for Comp.Sys.FooBars.Moderated.

###################################################################### CSFM # Comp.Sys.FooBars.Moderated Aliases # ###################################### # # submissions csfm-submit: csfm # To me, technical problems csfm-admin: johndoe # Moderators' list csfm-mods: csfm # Non-technical complaints, same as "board" above csfm-board: csfm-mods # Mail errors, go to hell csfm-errors: /dev/null # Approved and rejected messages csfm-approved: csfm # Approval key autoreply Bot csfm-approval-key: csfm # for posters who do not want autoacknowledgments: csfm-noack: csfm # alternative names, for absent-minded posters comp-sys-foobars-moderated: csfm-submit comp.sys.foobars.moderated: csfm-submit As you can easily see, messages to all of these addresses go to the robomoderator's address.

Note also, that if you have only one address and a sendmail-based system, and a non-cooperative sysadmin, you can try to get around the requirement to have several sendmail aliases. If addresses like yourname+comment@yoursite.com work, then you can use addresses like "csfm+approved@yoursite.com" instead. Make sure that they do in fact work (it is not guaranteed) and then edit your stump/etc/procmailrc accordingly.

Setting up procmail

You should set up procmail - an excellent, free third-party tool for flexible processing of incoming email messages. It works on any Unix. You can download it from ftp://ftp.informatik.rwth-aachen.de/pub/packages/procmail . Also, you can follow this link for an excellent introduction (and more!) to procmail.

Procmail binary is provided for Linux and FreeBSD, see the main STUMP page for the reference.

Look at the sample .procmailrc file that is used by soc.culture.russian.moderated.

Setting up PGP

NOTE: Not all moderators need to set up PGP. You only need PGP if you plan to use PGP Moose for authentication of approvals. Skip the rest of this section if you are not interested. You can always return to it later. Make sure that the settings in the stump/etc/modenv file are correct. If you plan to NOT use PGP, keep PGP set to "none" in the "stump/etc/modenv" file.

Set up and familiarize yourself with PGP, an excellent third-party encryption and authentification program.

Download it from this link. If you are not residing in the US or cannot download PGP from that page, try this link and try to find PGP there.

Another link (in Norway) is this: download PGP from Net sites outside.

PGP binary is provided for Linux and FreeBSD, see the main STUMP page for the reference.

Setting up Perl

Most likely you already have a perl interpreter. Simply type at your unix command prompt:

$ perl -v If you see some meaningful output, you are fine and you have perl. Otherwise you need to install it. Try this link and follow instructions. Installing perl may be quite an effort, but good chances are that you do not need to do it.


Starting with Robomoderator

Unpacking Source

Got to the home directory of your robomoderation account. Put there the stump-....tar.gz file that you just downloaded. Do this command:

$ whoami csfm $ cd $HOME $ zcat stump_2_3.tar.gz | tar xvf - This command will produce a lot of files under the $HOME/stump subdirectory.

Creating ..../etc directory

In the distribution that you receive, under $HOME/stump, there is directory $HOME/stump/etc.dist. It should be renamed to $HOME/stump/etc, and you should do the same with bin.dist, tmp.dist and data.dist directories. etc contains files that you need to customize. The reason for such renaming is that when you receive upgrades of the robomod, the upgrade does not override the files that you customized.

Go through files in etc directory, and edit them carefully.

Most of them are self explanatory. I put lots of comments in them. You should begin with editing the stump/etc/modenv file.

Create a symbolic links for procmail:

$ /bin/ln -s $HOME/stump/etc/procmailrc $HOME/.procmailrc mkdir $HOME/Mail # Creates directory for mail chmod 700 $HOME.Mail # Make it safe Edit your $HOME/stump/procmailrc to tailor it to the needs of your newsgroup. Do it carefully.

IMPORTANT: Later you MUST make sure that procmail processes all your incoming mail correctly and that all rules are written right. For logs of all procmail activity you may look into $HOME/Mail/from logfile. You can set VERBOSE=ON in the procmailrc file if you want to see detailed output.

NOTE: file Mail/from is an excellent source of debugging information.

Editing Data Files in ..../data

Rename data.dist to data.

You can (and should) edit some of the files in the data directory. These files are good.guys.list, bad.guys.list, bad.words.list. They contain Perl's regular expressions for detecting messages from preapproved and blacklisted posters, and suspicious words, respectively.

Edit them and leave them blank (no spaces).

Setting .profile for robomod support

It is very important that you source modenv file from the etc directory in your .profile (or .login) file. You need to have several environment variables, including PATH, to be set correctly in order to support robomod properly.

Put this in your .profile or .login file:

source $HOME/stump/etc/modenv

Creating ONE PAIR of PGP keys.

[Skip this part if you do not plan on using PGP Moose].

According to the specification of the robomod, you have to have one PGP key - for signing approved articles with PGP Moose application.

Pick a passphrase that is not too hard to type and remember. Usage of these PGP keys is not a very high-security application, so you can select 512-bit key sizes. Save this passphrase in file $HOME/.pgp-passphrase

. Make sure that this passphrase is not readable by anyone except the robomod user.

Name the key by analogy with the key used for SCRM (see modenv file and user names there). Your PGP Key must be named like this:

pub   512/ABB554F5 1996/02/26 CSFM Approval Key <csfm-approval-key@yoursite.com>

PGP Keys are generated using command

pgp -kg -u "CSFM Approval Key <csfm-approval-key@yoursite.com>" Copy your keyring to a specially designated place for STUMP: cp $HOME/.pgp/pubring.pgp $HOME/stump/data/pubring.pgp

Compiling C programs in stump/c directory

Go to the c directory and type ./compile. That should do it. If it does not, figure out on your own. The programs are extremely simple. Perhaps you can change the setting of CC to gcc, especially if you use Sun computers.

Creating List for reasons of Rejection and Rejection Messages

You should think what broad categories for reasons of rejection you will have in your group. Give them simple names. Edit file etc/reject and edit part that consists of calls to subroutine addReason. Customize it to your taste. After that, go to directory etc/messages and make sure that files there have exactly the names that you listed as first parameters in calls to addReason. Make sure they have comprehensive and polite messages corresponding to the broad reasons for rejection that you made up.

These messages will be sent to users when their articles are rejected for specified reasons. The messages that I supplied are not bad.

Make sure that you keep the following files: Edit file rejection-reasons.lst and put there the reasons that your moderators are allowed to choose for rejections. They should have names corresponding to the filenames in etc/messages, separated from comments by double colon ::.

Example:

offtopic::Message is grossly off topic (spam, turks, etc)
charter::Technical violation of charter (binary, exc. quoting)
harassing::Message of harassing/insulting/hatemongering content

Testing Your Setup

First of all, your default setup uses my free WebSTUMP service, so that you have a Web based interface for moderation. This means that you install and host STUMP, and you use my installation of WebSTUMP to moderate articles. WebSTUMP is a web based moderation tool, which is nice but a pain to set up. (it requires running setuid code and cgi-bin capability).

To test your newsgroup, first write to ichudov @ algebra . com , and ask me to create a newsgroup account for you in webstump. Please tell me your newsgroup name and the approved address (such as csfm-approved@your.site.com). Free WebSTUMP is located at

http://freewebstump.algebra.com/stump-cgi/webstump.cgi

You should test your setup of the robomoderator very extensively. If the robomod fails when your group goes to production, you will be ashamed. When you are testing, look at file $HOME/Mail/from, which contains all standard error output of your programs. Try to send submissions by email to your moderation address. Do

tail -f $HOME/Mail/from to see what's going on.

Choosing a "victim" group

I suggest that you use misc.jobs.misc for your testing. It is a dead newsgroup infested by spamsters. Nobody will bother and complain about your postings.

Edit file etc/modenv and put misc.jobs.misc in the assignment to NEWSGROUP, for testing purposes.

Things to Test

Test at least these conditions:
Testing Schedule
Test Case Test Goal
Moderators' list Moderators receive all message submitted to the address for thir private list.
Ackonwledgments of Receipt Submitters receive polite and informative messages for every message that they submit (you can turn ack mode off for individuals or even altogether)
Distribution of Submissions Each message submitted to the robomoderator gets sent to a randomly selected human moderator in an appropriate format.
Approvals work Messages approved by human moderators actually get posted.
Rejections Work Messages rejected by human moderators do not get posted; submitters receive polite and informative explanations of the reasons of rejection, and pointers to FAQ and Charter of your newsgroup.
White List Works Messages sent by users whose "From: " addresses match regular expressions in the good.guys.list file.

**The End**