1 -------------------------------------------------------------------------------
3 Documentation written by Francois Fleuret
4 Contact <francois.fleuret@inria.fr> for comments & bug reports
5 Check http://www.eleves.ens.fr:8080/home/fleuret for latest version
6 -------------------------------------------------------------------------------
8 -------------------------------------------------------------------------------
9 I - INTRODUCTION --------------------------------------------------------------
10 -------------------------------------------------------------------------------
12 TropBot is an IRC bot for UNIX system. If you don't know what is IRC,
13 you should get some infos about it before trying to use TropBot.
15 Many IRC Bots exist, and most of them are just extensions of
16 "classical" bots like VladBot. TropBot was written from scratch, in
17 C++. My goal was at first to make a short and easy to extend bot, just
18 a small thing used in emergency cases on the #france channel on
19 EFNet. After few months, TropBot became a real bot, with many
20 features. He's still a fast and small bot, but he can defend a channel
21 by himself. The version 2.2.0 was so stable that I have run one on
22 #france for longer than one month with no reboot (when I finally
23 killed it it was just to run a newer version).
25 -------------------------------------------------------------------------------
26 II - TROPBOT CAPABILITIES -----------------------------------------------------
27 -------------------------------------------------------------------------------
29 TropBot has all the main functions of an IRC bot. First, he has a list
30 of friends. A friend is a pattern which matches nick!user@host
31 stuff. Each of those pattern is associated with a level beetween 1 and
32 4. Anybody matching one of those pattern will be considered to have
35 * Level 1 (FRIEND) allows someone to use the simplest functions of the
36 bot (asking for the level of people, the shit-list, etc.)
38 * Level 2 (OP) is the op level. With this level, one will get the +o
39 automatically after a short delay, and will be allowed to use the
40 shit-list (see below).
42 * Level 3 (DEFENCE) is almost the same thing as level 2, except that
43 the person will gain the +o without delay. This level is reserved to
44 other bots of the channel. That way, during collide-attacks, the
45 TropBot will re-op them faster.
47 * Level 4 (MASTER) is the highest level and allows the person to use
48 all the functions (like adding friends, etc.)
50 The shit-list is a list of people who shouldn't be in the
51 channel. Each entry of this list is a pattern, associated with a delay
52 and a comment. Each time someone matching the pattern enters the
53 channel, he will be banned & kicked with the comment. This feature is
54 usefull against unpleasant people.
56 Since v2.0.0, the TropBot has a smart handling of ban-list. He has in
57 memory a copy of the ban list, so he is able to detect people entering
58 the channel using hack and kick them; and he is also able to ban or
59 unban only the required banid and avoid redudant +b/-b change mode.
61 TropBot has also a anti-flood procedure. Each person sending more than
62 4 lines in 2 s will be kicked. TropBot detects all kind of lines
63 (PRIVMSG, NOTICE, NICK and even JOIN). It's pretty hard to make a good
64 flood-detection algorithm. TropBot's one is far from perfection, but
65 works quite nicely. If you have smart ideas to improve it, please mail
66 me (I wrote a site-flood detection, but didn't include it ... I also
67 made a routine that counts the number of caractere lines on the
68 screen, but this kind of algorithm kick both bad and good guys :-))
70 Since v2.3.4 TropBot accepts passwords for users on unsafe sites
71 (i.e. sites where other people can fake their login). It's done in a
72 very primitive way, so I guess one should use them only in critical
73 situations. To use a command when you are a user with passwd, you just
74 have to add &passwd before all command. In any case, the bot won't be
75 able to recognize you after a split.
77 Since v2.5.5, TropBot accepts DCC CHAT connections; those are direct
78 socket connections, with no use of servers. This has few interests :
79 the connection is most of the time faster, you can keep the connection
80 even if splits occurs and if the bot and you are not on the same part
81 of the net, there are no flood detection and you won't loose the
82 connection even if the bots send you a lot of datas, etc. This kind of
83 connection is great for commands like "who" "help" "shitlist" etc.
85 -------------------------------------------------------------------------------
86 II - HOW TO INSTALL TROPBOT ---------------------------------------------------
87 -------------------------------------------------------------------------------
89 I assume you've already downloaded & detared all the stuff, so you are
90 supposed to have some files like tblic.cc, tblic.h, tropbot.cc,
91 Makefile, etc. You just have to do a "make -k", and after a short
92 compilation, you should obtain a tropbot executable file. I developped
93 this program on both a Linux system, SunOS and SOLARIS (with gcc
94 2.7.*), I really don't know what can happen on other systems ... hope
95 it will work :-) If it doesn't, I fear I can't help you, I'm
96 definitively NOT a UNIX wizard :-P
98 -------------------------------------------------------------------------------
99 III - HOW TO RUN TROPBOT ------------------------------------------------------
100 -------------------------------------------------------------------------------
102 The main goal of a bot is to stay in a channel 24h/day to keep the +o
103 privileges so that he can give them to his friends when they enter the
104 channel. To do that, a bot must run on a station which is connected to
105 the net all the time.
107 To run the TropBot, you need a tropbot binary (obtained after
108 compilation). Then, just type "./tropbot" to run it. If you don't
109 indicate any parameter, you will run a tropbot with the nickname
110 "TropBot", connected to the server "sil.polytechnique.fr" on the port
111 6667, and this bot will go to the channel "#tropbot". So, the best way
112 to run a TropBot is the following :
114 nohup ./tropbot -n nickname -c "#channel" -h server
116 The 'nohup' UNIX command will make the bot go on running even after
117 you log out, and the parameters will set the nickname, the channel and
118 the server (you MUST use your local servers, AFTER you have got an
119 autorization from an IRCop ! Using a bot on a server without
120 autorization can make you be killed or even K-lined. Being K-lined
121 means that you'll never be able to use this server again).
123 NEVER PUT A BOT ON A SERVER WITH NO AUTHORIZATION FROM AN IRCOP
125 The options you can use in the command lines are the following :
127 -c <#channel> sets the channel
128 -d <delay in s> sets the reconnection delay
129 -h <hostname> sets the server name
130 -j <jam nickname> sets the pattern nick for collision
131 -l <user> sets the user in the user@host stuff
132 -n <nickname> sets the nickname
133 -o <friends file> loads config file
134 -od <op delay> set the delay before +o of level 2 people
135 -p <port number> sets the server port
138 Most of those options are quite clear. The -d option allowed you to
139 modify the delay the bot will wait before he tries to reconnect after
140 he lost his connection. The -j option is used to give the bot a
141 "generic nickname". The form of such a nickname is a caractere string
142 with some '?' which will be replaced with random digits before
143 use. That way the bot is able to generate random nicks if the nick you
144 gave him is already used, or after a nick collision (by default the
145 jam nick is "TB-????"). The -o option is used to load a configuration
148 -------------------------------------------------------------------------------
149 IV - TROPBOT CONFIGURATION FILE -----------------------------------------------
150 -------------------------------------------------------------------------------
152 If you use the '-o' option, or the 'load' command on IRC, the TropBot
153 will load a configuration file (.tropbotrc by default, but can be
154 changed by both the '-o' option and the 'load'/'save' commands).
156 The configuration file contains two kinds of lines. The "FRIEND"
157 lines, who indicate a new friend, and the "SHIT" lines, who indicate
158 who is supposed to be shit-listed.
160 If you want this bot to op all people from united kingdom, just put in
161 the configuration file the following line :
165 This way, the bot will give a level 2 to all people whose
166 nick!user@host matches *!*@*.uk, and a level 2 is an op level.
168 YOU MUST BE IN THIS LIST TO MAKE THE BOT RECOGNIZE YOU
170 If you want the bot to shit-list all people from Ecole Polytechnique
171 in France for 2 days (172800 s), with the comment "I don't like people
172 with strange hats", just add :
174 SHIT *!*@*.polytechnique.fr 172800 I don't like people with strange hats
176 You can add a password in the configuration file just as a third
177 parameter. For example
179 FRIEND 2 *!*@*.fr trululu
181 will make all people from France able to execute functions with a
182 level 2 if they use the password trululu.
184 -------------------------------------------------------------------------------
185 V - TROPBOT FUNCTIONS ---------------------------------------------------------
186 -------------------------------------------------------------------------------
188 The functions you can use on a TropBot depend with your level in his
189 list. For functions that accept both <nick> or <pattern> parameter, a
190 pattern must contain at least one '@' and one '!' or the bot will
191 consider it as a nickname.
195 "www" prints the URL of my home page, where you can find the latest
198 "level [<nick>]" prints the level of the given person (or your own
199 level if you don't give any parameter).
201 "shitlist [<nick>!<pattern>]" (alias "sl") prints the shit-list, or
202 the shits matched by a given pattern, or the shits that match a nick.
204 LEVEL 2 & 3 FUNCTIONS :
206 "alert" (alias "a") will put the channel in +m, shit the site who
207 flooded the more during the last seconds, will kick all the nick on
208 this site, and then will put the channel -m. This command is VERY
209 usefull against clone bots.
211 "antifloodoff <duration>" (alias "ao") will make suppress the
212 anti-flood system for the given duration. This feature is interesting
213 when the bot lagged because of network troubles.
215 "deban { list of patterns }" (alias "db") remove from the ban-list all
216 the entries who match one of the pattern
218 "filterkick <nick>!<pattern> [<comment>]" (alias "fk") will kick all
219 the people matching the pattern, or on the same site as the given nick
221 "home" sends back to the home channel
223 "join <#channel>" makes the bot leave the current channel and join
226 "op [{ nicks list }]" makes the bot give you the +o if no list is
227 given, and give the +o to the given nicks if there is a list
229 "pruneban <number>" (alias "pb") check the ban-list and keeps only the
232 "punshit { <pattern> list }" (alias "pus") removes all the pattern
233 that matches <pattern> from the shit-list (so "punshit *" will clear
236 "shit <nick>!<pattern> [<duration> [<comment>]]" (alias "s") adds a
237 pattern in the shit-list for a given duration. Each time a person
238 matching this pattern enters the channel, he will be banned & kicked
239 (with the given comment). If the parameter is a nickname, the bot will
240 compute a nick!user@host pattern by itself (matching all the person
241 with the same login, on the same site). The duration is the string
242 like #d#h#m#s where the # are integer numbers. For example, 2d4h means
245 "shithost <nick> <duration> <comment>" (alias "sh") adds a pattern
246 that matches all the person from the <nick>'s host. Usefull for
247 providers'people who can easily change their login in the login@host
248 but have to hangup to change the modem/machine name.
250 "shitsite <nick> <duration> <comment>" (alias "ss") adds a pattern
251 that matches all the person from the <nick>'s site.
253 "synch" makes the bot give the +o to all the people in the channel
254 with a level greater than 2 (usefull when you want to re-synchronize a
255 channel after hacks/splits, etc.)
257 "unshit { <nick>!<pattern> list }" (alias "us") removes patterns from
258 the shit-list, or all the pattern who match a given user.
262 "save [<file>]" saves the configuration file
264 "load [<file>]" loads the configuration file
266 "reset" kills the connection, randoms the nickname, reconnects, and
269 "friend <pattern> <level> [<passwd>]" adds someone in the friend list
270 with the given level and passwd if specified
272 "clone [<nick>]" starts a new session with the given nick or a random
277 "server <hostname> [<port>]" set the server name and the port number
280 "controlchar <char>" set the control character
282 "opdelay <delay in s>" set the delay before +o when level 2 enter the
285 "debandelay <delay in s>" set the delay before -b in case of +b by
290 If you have the password abcdef, to use a command with your level, you
291 just have to add &abcdef before any command. For example,
293 /msg TropBot &abcdef op
295 will make the bot op you.
299 With a DCC CHAT connection to tropbot, you can send all the commands
300 you use to send with /msg or with the control character in public. The
301 bot will send you back the answers throught the DCC CHAT too.
303 You gain two new commands, which can be used only in DCC CHAT :
305 "users" (alias "u") that gives you the nick!user@host of all the
306 people connected to the bot with DCC CHAT at the same time.
308 "talk <msg>" (alias "t") that send a message to all the people
309 connected with DCC CHAT.
311 -------------------------------------------------------------------------------
312 VI - CONCLUSION/BUGS ----------------------------------------------------------
313 -------------------------------------------------------------------------------
315 A bot is a complex program. This one, even if it's not very long has
316 to deal with many buffers and strings operations. Such kind of program
317 can't be 100% safe. I hope current version is stable, but I fear some
318 buggs are still creeping somewhere.
320 -------------------------------------------------------------------------------
321 - AUTHOR ----------------------------------------------------------------------
322 -------------------------------------------------------------------------------
326 E-mail : <francois.fleuret@inria.fr>.
327 IRCNICK : THX-1138 (EFNet, eureopean part, #france channel)
329 I really DON'T appreciate questions about compilation, and I HATE
330 questions whose answers are in this file. I appreciate suggestions and
337 78330 Fontenay le Fleury, FRANCE
339 -------------------------------------------------------------------------------
340 - ACKNOWLEDGEMENT -------------------------------------------------------------
341 -------------------------------------------------------------------------------
343 Linux, GCC, Emacs and XFree86 people ... I love you men ! :-)
345 Jim Frost <jimf@world.std.com> for http://world.std.com/~jimf/sockets.html
347 -------------------------------------------------------------------------------
projects / tropbot.git / blob