  .--.  __  __  __ _  ___  /..-   __                            
 /___/ /_  /__+/_ /_\  /  /\   / /   /.-                     
/   \ /__ /   /__/  / /  /  \ / /__ / \    

"Eggdrops Most EFfective Repeat/Flood handling"

Written by Darren Coleman
Email: durzel@barrysworld.com -or- durzel@nildram.co.uk

INSTALLATION
============

** VERY IMPORTANT **
Before you can run 'Repeatkick', you will need to set a variable, 'scriptdir'
in your eggdrop.conf.  This must be set to the relative path of your eggdrop
scripts dir...  

For example: '/home/usr/users/john/eggdrop/scripts/"

The last "/" (or "\" if you are running a Windows eggdrop) is important also,
do not omit it.

You will of course need to add a 'source' line to your eggdrop.conf in order
to source in the TCL file when the eggdrop first starts... basically your
config should have something like this in:

set scriptdir "/home/usr/users/john/eggdrop/scripts/"
source scripts/repeatkick.tcl


BACKGROUND
==========

This script was borne out of a need to regulate a rather large Quake 2
based public channel on Quakenet IRC (http://www.quakenet.eu.org).  It was 
originally based on a repeatkicking script I found somewhere (sorry, cant
remember the author), but has since been totally rewritten and optimised 
to be completely customisable through the bot (ie. through MSG and DCC
commands).

The purpose of this script is to detect and subsequently act upon any 
repeats or floods that occur in a channel that the bot has ops on.  Now
what governs a 'repeat' is entirely up to you.  You may decide 5 lines
of the same thing constitutes a repeat, I personally think 3 is excessive, 
hence the default 'repeatkick' value for new channels is 3.

This script should hopefully reduce 'spam' and unnecessary repeating in
your channel - or at least make people very wary of doing it! :)


FEATURES
========

  - Fully customisable settings on a per channel basis.  You can have
    different repeatkick settings depending on the nature of the channel,
    or even have no repeatkick'ing functionality at all.  It's entirely up
    to you.

  - Unparalleled repeat detection.  As well as catching the obvious plain
    line repeats, 'Repeatkick' is also capable of distinguishing (to a level
    of strictness customisable by the user) "veiled repeats" by people
    residing on your channel.  This means that people will not be able to
    trick the bot but changing one letter on each line, etc. :)

  - Intelligent banning.  Repeatkick's banning mechanism is almost human in
    its application!  If a user rejoins after having been banned, 'Repeatkick'
    will in most cases detect them via a number of checks on their host, ident
    and nick.  If they are shown to have rejoined when they shouldn't have, 
    they get rebanned on their new host and the old ban is removed (to allow
    other people using that dialup host to connect)

  - Link together 2 or more bots using repeatkick for parallel concurrency!
    Repeatkick has been programmed so as to evenly distribute the processing
    requirements across other bots that are running the same script (see
    'Linking' later on).  This means that only one bot will 'evaluate' a repeat,
    the other bots will realise it is doing it and simply carry on with other
    tasks.

  - Self-upgrading.  When another bot rehashes a newly amended script, other
    bots that are linked will request that file from it, and then rehash 
    themselves.  You wont have to FTP to each and every one of the bots to 
    upload the changed script, just rehash it on one of them and watch the 
    others sort out the rest themselves!

  - Concurrency.  Linked bots will share INI file settings and synchronise
    timers to ensure that they are performing in sync with eachother (ie. no
    spurious kicks for repeating, etc)

  - ..and much more!


VARIABLES
=========

'Repeatkick' uses a number of channel variables that determine the way it operates 
and carries out punishments for repeats etc.  These variables are set on a 
channel-by-channel basis, and are as follows:

- repeatkick ...determines how many lines of text constitutes a repeat (default: 3)
- repeattime ...indicates 'sampling' time (ie. no. of repeats in <x> seconds) (def: 20)
- repeatmsg  ...message that is given when kicking for repeating (def: 'Repeating')
- floodmsg   ...message that is given when kicking for flooding (def: 'Flooding')
- repeatban  ...if set to 1, ANY repeat which is caught results in a ban (def: 0)
- repeatbantime ...signifies how long a person is banned for on 3rd repeat (def: 15 mins)
- repeatonoff ..used to disable (0) or enable (1) repeatkicking on the channel (def: 1)
- floodonoff ...used to disable (0) or enable (1) floodkicking on the channel (def: 1)
- logging    ...toggles logging of repeat/floodkicks off (0) or on (1) on chan. (def: 1)
- chartolerance  ..used to signify 'character tolerance' level (def: 95%)
- postolerance  ...user to signify 'positional tolerance' level (def: 45%)

Each of these variables is set by doing: /msg <bot> repeatset <#channel> <variable> [value]
[value] is optional for the 'toggle' variables (ie. 'repeatonoff', etc)
eg. /msg bob repeatset #efnet repeatkick 10   - would set 'repeatkick' to 10 on #EFnet chan


REPEAT DETECTION (the meaning of 'char tolerance' and 'pos tolerance')
======================================================================

'Repeatkick' uses a series of advanced tests to determine whether or not a person
is repeating on a given channel.  One of these tests is to determine the character
and positional tolerance of what someone says on channel, to what they said
previously.  'Char tolerance' works by counting the occurences of each character in
the passed text, and matching it to the number of occurences of that character in
what was previously said.  'Pos tolerance' simply shows how many characters match
the positions of the same characters in something said before..


DEBUG mode
==========

The main purpose of DEBUG mode (type '.rkdebug' to enable in partyline) is to
finetune the char. and pos. tolerance factors to your own choosing.  From my 
experience 95% char. and 45% pos. has proven to be very effective and I haven't
*as yet* seen any false positives (ie. false kickings).

The format of what is shown in DEBUG mode on partyline is as follows (example):

[12:38] -- RK: [unr]spog: char: 1/9 (11%), pos: 0/3 (0%), repeat_num: 1.. 
(cur: 'iliketheslopes;P', last: 'bah')

'[unr]spog' denotes the name of the person who has said the line.
'char: 1/9 (11%)' denotes the character tolerance reading for the line
'pos: 0/3 (0%)' denotes the positional tolerance reading for the line
'repeat_num: 1' denotes the number of actual positive repeats so far for this user
'cur: <text>' denotes the current text output from that user
'last: <text>' denotes what they previously said

Type: '.rkdebug' in partyline chat to switch DEBUG mode off again.


LINKING explained...
====================

'Repeatkick' can be run on more than 1 bot simultaneously, and unlike other scripts
where both bots would 'take action' on detection of a repeat, the bots actively 
interact with eachother to ensure that only one bot takes action at any given time.
Not only does this look professional (ie. people dont get kicked twice for the same 
offence), but it also helps lower the processing load on the individual bot that is
*not* doing the repeat kick.

By default linking is ENABLED, and there shouldn't really be any need to turn it
off (for a single bot, even if linking is enabled, it'll still function correctly
on its own).  The purpose of having linking enabled, is that when another bot joins
the partyline, or executes the script, it will 'call out' to all other bots to
confirm if they too are running 'Repeatkick'.  If they respond to this, the new
bot will attempt to syncronise files and timers with the bot already running the
script, to ensure that all bots on the BOTNET are using the same script, INI file, etc.

You can also switch bot linking off and on as you choose by using the DCC Partyline
command: '.rklink'  (NB. Toggling '.rklink' on has the same effect as a bot that has
just rehashed the script, ie. it polls all other bots for 'Repeatkick running' 
confirmation).


MSG commands
============

What script would be complete without a requisite amount of MSG commands? :)
As far as 'Repeatkick' is concerned, there are only 4 MSG commands available:

- repeatchk    - this will list all currently recorded repeatkick's thats have
                 been made, together with the relevant user(s)' host, nick, etc.

- repeatvars   - another useful debugging tool.  This command will list a number
                 of userfile record variables for repeatkick'd people, like
                 repeat_num, repeat_host, badnick, etc.

- repeatinfo <#channel> - this will present you with a list of channel Repeatkick
                          variables (see 'VARIABLES' section)

- repeatset    - <explained earlier> (see 'VARIABLES' section)


ISSUES, BUGS, etc
=================

Known bugs so far are:
   
   * The method for synching .INI files between bots is a little cumbersome as it
     requires that linking bots are on the same channels.  If a bot running Repeatkick
     is on a different set of channels to another bot that is running Repeatkick, and
     they link, the one with the 'older' INI file will wrongly assume it needs to have
     it updated.  For that reason, INI file sharing is *OFF* by default in the script.
     If you wish to switch it back on, you will need to modify the variable explicitly
     in the TCL file.  This will be fixed shortly.

   * The 'check_banned' procedure occasionally reports:

     'Tcl error [check_banned]: can't read "repeat_num(<user>)": No such element in
      array'

     From what I can see this is an entirely spurious error which, I believe, is 
     tied in to the timer fireing and 'unset'ing the repeat_num array.  I will be
     looking into this shortly.


CONTACT info
============

Darren Coleman
durzel@barrysworld.com
http://www.durzel.dircon.co.uk

You can find me on Quakenet IRC (http://www.quakenet.eu.org) on #quake2.uk as well
as a number of other channels.  (try server: irc.barrysworld.com:6667)

     
              
