Update to version 2.9.3a

[tropbot.git] / README.txt

-------------------------------------------------------------------------------
  TropBot v2.9
  Documentation written by Francois Fleuret
  Contact <francois.fleuret@inria.fr> for comments & bug reports
  Check http://www.eleves.ens.fr:8080/home/fleuret for latest version
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
I - INTRODUCTION --------------------------------------------------------------
-------------------------------------------------------------------------------

TropBot is an IRC bot for UNIX system. If you don't know what is IRC,
you should get some infos about it before trying to use TropBot.

Many IRC Bots exist, and most of them are just extensions of
"classical" bots like VladBot. TropBot was written from scratch, in
C++. My goal was at first to make a short and easy to extend bot, just
a small thing used in emergency cases on the #france channel on
EFNet. After few months, TropBot became a real bot, with many
features. He's still a fast and small bot, but he can defend a channel
by himself. The version 2.2.0 was so stable that I have run one on
#france for longer than one month with no reboot (when I finally
killed it it was just to run a newer version). The last version
(2.9.0) runs under Purify(tm) with no error.

-------------------------------------------------------------------------------
II - TROPBOT CAPABILITIES -----------------------------------------------------
-------------------------------------------------------------------------------

TropBot has all the main functions of an IRC bot. First, he has a list
of friends. A friend is a pattern which matches nick!user@host
stuff. Each of those pattern is associated with a level beetween 1 and
4. Anybody matching one of those pattern will be considered to have
the associated level.

* Level 1 (FRIEND) allows someone to use the simplest functions of the
bot (asking for the level of people, the shit-list, etc.)

* Level 2 (OP) is the op level. With this level, one will get the +o
automatically after a short delay, and will be allowed to use the
shit-list (see below).

* Level 3 (DEFENCE) is almost the same thing as level 2, except that
the person will gain the +o without delay. This level is reserved to
other bots of the channel. That way, during collide-attacks, the
TropBot will re-op them faster.

* Level 4 (MASTER) is the highest level and allows the person to use
all the functions (like adding friends, etc.)

The shit-list is a list of people who shouldn't be in the
channel. Each entry of this list is a pattern, associated with a delay
and a comment. Each time someone matching the pattern enters the
channel, he will be banned & kicked with the comment. This feature is
usefull against unpleasant people.

Since v2.0.0, the TropBot has a smart handling of ban-list. He has in
memory a copy of the ban list, so he is able to detect people entering
the channel using hack and kick them; and he is also able to ban or
unban only the required banid and avoid redudant +b/-b change mode.

TropBot has also a anti-flood procedure. Each person sending more than
4 lines in 2 s will be kicked. TropBot detects all kind of lines
(PRIVMSG, NOTICE, NICK and even JOIN). It's pretty hard to make a good
flood-detection algorithm. TropBot's one is far from perfection, but
works quite nicely. If you have smart ideas to improve it, please mail
me (I wrote a site-flood detection, but didn't include it ... I also
made a routine that counts the number of caractere lines on the
screen, but this kind of algorithm kick both bad and good guys :-))

Since v2.3.4 TropBot accepts passwords for users on unsafe sites
(i.e. sites where other people can fake their login). It's done in a
very primitive way, so I guess one should use them only in critical
situations. To use a command when you are a user with passwd, you just
have to add &passwd before all command. In any case, the bot won't be
able to recognize you after a split.

Since v2.5.5, TropBot accepts DCC CHAT connections; those are direct
socket connections, with no use of servers. This has few interests :
the connection is most of the time faster, you can keep the connection
even if splits occurs and if the bot and you are not on the same part
of the net, there are no flood detection and you won't loose the
connection even if the bots send you a lot of datas, etc. This kind of
connection is great for commands like "who" "help" "shitlist" etc.

Since v2.8.0, TropBot has new features to handle big channels. First,
it has in memory a list of 'restricted' sites. The bot will detect and
kick/ban any group of users who are on the same machine. The main idea
is to protect the channel from clone bots. The second important
feature is the 'cop-mode'. When this mode is switch ON, the bot will
detect any graphical effect (caps, reverse, mIrc colors, beeps,
art-chars, repeated chars, etc.), wil also ban any user who is kicked
3 times or more in less than 10 minutes, and will ban all site where
more than 3 people are banned.

The v2.9.0 is a more stable version, debugged using Purify(tm)

-------------------------------------------------------------------------------
II - HOW TO INSTALL TROPBOT ---------------------------------------------------
-------------------------------------------------------------------------------

I assume you've already downloaded & detared all the stuff, so you are
supposed to have some files like tblic.cc, tblic.h, tropbot.cc,
Makefile, etc. You just have to do a "make -k", and after a short
compilation, you should obtain a tropbot executable file. I developped
this program on both a Linux system, SunOS and SOLARIS (with gcc
2.7.*), I really don't know what can happen on other systems ... hope
it will work :-) If it doesn't, I fear I can't help you, I'm
definitively NOT a UNIX wizard :-P

-------------------------------------------------------------------------------
III - HOW TO RUN TROPBOT ------------------------------------------------------
-------------------------------------------------------------------------------

The main goal of a bot is to stay in a channel 24h/day to keep the +o
privileges so that he can give them to his friends when they enter the
channel. To do that, a bot must run on a station which is connected to
the net all the time.

To run the TropBot, you need a tropbot binary (obtained after
compilation). Then, just type "./tropbot" to run it. If you don't
indicate any parameter, you will run a tropbot with the nickname
"TropBot", connected to the server "sil.polytechnique.fr" on the port
6667, and this bot will go to the channel "#tropbot". So, the best way
to run a TropBot is the following :

       nohup ./tropbot -n nickname -c "#channel" -h server

The 'nohup' UNIX command will make the bot go on running even after
you log out, and the parameters will set the nickname, the channel and
the server (you MUST use your local servers, AFTER you have got an
autorization from an IRCop ! Using a bot on a server without
autorization can make you be killed or even K-lined. Being K-lined
means that you'll never be able to use this server again).

      NEVER PUT A BOT ON A SERVER WITH NO AUTHORIZATION FROM AN IRCOP

The options you can use in the command lines are the following :

 -c <#channel>       sets the channel
 -d <delay in s>     sets the reconnection delay
 -h <hostname>       sets the server name
 -j <jam nickname>   sets the pattern nick for collision
 -l <user>           sets the user in the user@host stuff
 -n <nickname>       sets the nickname
 -o <friends file>   loads config file
 -od <op delay>      set the delay before +o of level 2 people
 -p <port number>    sets the server port
 -?                  shows help

Most of those options are quite clear. The -d option allowed you to
modify the delay the bot will wait before he tries to reconnect after
he lost his connection. The -j option is used to give the bot a
"generic nickname". The form of such a nickname is a caractere string
with some '?' which will be replaced with random digits before
use. That way the bot is able to generate random nicks if the nick you
gave him is already used, or after a nick collision (by default the
jam nick is "TB-????"). The -o option is used to load a configuration
file (see below).

-------------------------------------------------------------------------------
IV - TROPBOT CONFIGURATION FILE -----------------------------------------------
-------------------------------------------------------------------------------

If you use the '-o' option, or the 'load' command on IRC, the TropBot
will load a configuration file (.tropbotrc by default, but can be
changed by both the '-o' option and the 'load'/'save' commands).

The configuration file contains two kinds of lines. The "FRIEND"
lines, who indicate a new friend, and the "SHIT" lines, who indicate
who is supposed to be shit-listed.

If you want this bot to op all people from united kingdom, just put in
the configuration file the following line :

FRIEND 2 *!*@*.uk

This way, the bot will give a level 2 to all people whose
nick!user@host matches *!*@*.uk, and a level 2 is an op level.

          YOU MUST BE IN THIS LIST TO MAKE THE BOT RECOGNIZE YOU

If you want the bot to shit-list all people from Ecole Polytechnique
in France for 2 days (172800 s), with the comment "I don't like people
with strange hats", just add :

SHIT *!*@*.polytechnique.fr 172800 I don't like people with strange hats

You can add a password in the configuration file just as a third
parameter. For example

FRIEND 2 *!*@*.fr trululu

will make all people from France able to execute functions with a
level 2 if they use the password trululu.

You can also specify a list of restricted sites. For example, if you
want to avoid to have more than one personne on a same adress
containing "ppp", just put

RESTRICTED *!*@*ppp*

-------------------------------------------------------------------------------
V - TROPBOT FUNCTIONS ---------------------------------------------------------
-------------------------------------------------------------------------------

The functions you can use on a TropBot depend with your level in his
list. For functions that accept both <nick> or <pattern> parameter, a
pattern must contain at least one '@' and one '!' or the bot will
consider it as a nickname.

LEVEL 1 FUNCTIONS :

"www" prints the URL of my home page, where you can find the latest
version of TropBot

"level [<nick>]" prints the level of the given person (or your own
level if you don't give any parameter).

"shitlist [<nick>!<pattern>]" (alias "sl") prints the shit-list, or
the shits matched by a given pattern, or the shits that match a nick.

LEVEL 2 & 3 FUNCTIONS :

"alert" (alias "a") will put the channel in +m, shit the site who
flooded the more during the last seconds, will kick all the nick on
this site, and then will put the channel -m. This command is VERY
usefull against clone bots.

"antifloodoff <duration>" (alias "ao") will make suppress the
anti-flood system for the given duration. This feature is interesting
when the bot lagged because of network troubles.

"cop" switch the cop-mode on/off

"ctcpreply" (alias "cr") switch the ctcp replies

"anticlones" (alias "ac") switch the "restricted-sites" stuff

"deban { list of patterns }" (alias "db") remove from the ban-list all
the entries who match one of the pattern

"filterkick <nick>!<pattern> [<comment>]" (alias "fk") will kick all
the people matching the pattern, or on the same site as the given nick

"home" sends back to the home channel

"join <#channel>" makes the bot leave the current channel and join
#channel

"op [{ nicks list }]" makes the bot give you the +o if no list is
given, and give the +o to the given nicks if there is a list

"pruneban <number>" (alias "pb") check the ban-list and keeps only the
<number> first bans

"punshit { <pattern> list }" (alias "pus") removes all the pattern
that matches <pattern> from the shit-list (so "punshit *" will clear
the shit-list).

"shit <nick>!<pattern> [<duration> [<comment>]]" (alias "s") adds a
pattern in the shit-list for a given duration. Each time a person
matching this pattern enters the channel, he will be banned & kicked
(with the given comment). If the parameter is a nickname, the bot will
compute a nick!user@host pattern by itself (matching all the person
with the same login, on the same site). The duration is the string
like #d#h#m#s where the # are integer numbers. For example, 2d4h means
2 days and 4 hours.

"shithost <nick> <duration> <comment>" (alias "sh") adds a pattern
that matches all the person from the <nick>'s host. Usefull for
providers'people who can easily change their login in the login@host
but have to hangup to change the modem/machine name.

"shitsite <nick> <duration> <comment>" (alias "ss") adds a pattern
that matches all the person from the <nick>'s site.

"synch" makes the bot give the +o to all the people in the channel
with a level greater than 2 (usefull when you want to re-synchronize a
channel after hacks/splits, etc.)

"unshit { <nick>!<pattern> list }" (alias "us") removes patterns from
the shit-list, or all the pattern who match a given user.

LEVEL 4 FUNCTIONS :

"save [<file>]" saves the configuration file

"load [<file>]" loads the configuration file

"reset" kills the connection, randoms the nickname, reconnects, and
rejoins.

"friend <pattern> <level> [<passwd>]" adds someone in the friend list
with the given level and passwd if specified

"clone [<nick>]" starts a new session with the given nick or a random
one

"die" kills the bot

"server <hostname> [<port>]" set the server name and the port number
(6667 by default)

"controlchar <char>" set the control character

"opdelay <delay in s>" set the delay before +o when level 2 enter the
channel

"debandelay <delay in s>" set the delay before -b in case of +b by
split

USING PASSWORDS :

If you have the password abcdef, to use a command with your level, you
just have to add &abcdef before any command. For example,

/msg TropBot &abcdef op

will make the bot op you.

USING DCCHAT :

With a DCC CHAT connection to tropbot, you can send all the commands
you use to send with /msg or with the control character in public. The
bot will send you back the answers throught the DCC CHAT too.

You gain two new commands, which can be used only in DCC CHAT :

"users" (alias "u") that gives you the nick!user@host of all the
people connected to the bot with DCC CHAT at the same time.

"talk <msg>" (alias "t") that send a message to all the people
connected with DCC CHAT.

-------------------------------------------------------------------------------
VI - CONCLUSION/BUGS ----------------------------------------------------------
-------------------------------------------------------------------------------

A bot is a complex program. This one, even if it's not very long has
to deal with many buffers and strings operations. Such kind of program
can't be 100% safe. I hope current version is stable, but I fear some
buggs are still creeping somewhere. The last version was checked with
Purify and is supposed to be kinda stable.

-------------------------------------------------------------------------------
- AUTHOR ----------------------------------------------------------------------
-------------------------------------------------------------------------------

Francois Fleuret

E-mail :  <francois.fleuret@inria.fr>.
IRCNICK : THX-1138 (EFNet, eureopean part, #france channel)

I really DON'T appreciate questions about compilation, and I HATE
questions whose answers are in this file. I appreciate suggestions and
bug reports :P

-------------------------------------------------------------------------------
- ACKNOWLEDGEMENT -------------------------------------------------------------
-------------------------------------------------------------------------------

Linux, GCC, Emacs and XFree86 people ... I love you men ! :-)

Jim Frost <jimf@world.std.com> for http://world.std.com/~jimf/sockets.html

-------------------------------------------------------------------------------