doc/index.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <html>
   3   <head>
   4     <title>Bobot++ - an IRC bot</title>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1>Bobot++ - an IRC bot</h1>
   9
  10     <p>First, if you don't know what is a bot or if you don't know what
  11       is IRC, you're at the wrong place, sorry :-)</p>
  12
  13     <h2>Introduction</h2>
  14
  15     <p>The <em>bobot++</em> is an IRC bot written in C++. This is the
  16       evolution of the <em><a
  17           href="http://www.via.ecp.fr/~hugo/bobot.html">bobot</a></em>
  18       that I wrote in C with <a
  19         href="http://www.via.ecp.fr/~hugo/">Bartman</a>.</p>
  20
  21     <p>The <em>bobot</em> was a powerful bot, but it was limited to an
  22       unique channel, and an unique bot per process. The
  23       <em>bobot++</em> is designed to support as many channels as you
  24       want (in the limit of 20 channels, but this limit is set by the
  25       servers). Moreover, it will support multithreading easily (all
  26       the objects are thread-safe).</p>
  27
  28     <p>Here is a non comprehensive list of the <em>bobot++</em>'s
  29       features:</p>
  30
  31     <ul>
  32       <li>No backdoor: there is no backdoors in the
  33         <em>bobot++</em>. You are free to believe me or not, but
  34         unlike many other bots, this one has no backdoor. Note that
  35         there is an hidden command, but this command is not designed to
  36         take control of the bot,</li>
  37       <li>Multichannel: A <em>bobot++</em> can join as many channels
  38         as you want,</li>
  39       <li>Flood control: It will ignore people flooding it,</li>
  40       <li>Output rate control and priority handling: The
  41         <em>bobot++</em> will send its commands to the server at the
  42         highest possible rate (ie as fast as possible without making
  43         an ``excess flood''). The most important commands (MODE's,
  44         etc.) are sent first,</li>
  45       <li>Time dependant commands: you can ban people for a fixed
  46         amount of time. This is really useful in order not to fill the
  47         banlist, [NOT YET FINISHED]</li>
  48       <li>Complex online help system: each user can have the list of
  49         the commands he can execute. Each command has its description
  50         in the help system,</li>
  51       <li>Four user levels (user, trusted user, friend and master),
  52         three different protections (no kick, no ban and no deop) and
  53         possible auto-op. Note that trusted user is created to permit
  54         the use of wildcards on dangerous commands such as
  55         <tt>kick</tt>, or <tt>ban</tt>,</li>
  56       <li>Support for combined join and channel op of 2.9 servers on
  57         IRCNet (this feature will be suppressed from the servers, but
  58         it may remain useful...),</li>
  59       <li>Logging of commands and events,</li>
  60       <li>``Intelligent'' ban and deban,</li>
  61       <li>Password protection on accounts, expiration dates on user
  62         accounts,</li>
  63       <li>Anti-spoof: one can not acquire operator priviledges spoofing
  64         the bot</li>
  65     </ul>
  66
  67     <h2>Downloading the bobot++</h2>
  68
  69     <p>You can get the latest version of the bobot++ from this site
  70       <em>only</em>. Here is the current version:</p>
  71
  72     <p><a href="bobot++.1.0.tgz">Download the 1.0 version</a></p>
  73     <p><a href="bobot++.1.2.tgz">Download the 1.2 version</a></p>
  74     <p><a href="bobot++.1.4.tgz">Download the 1.4 version</a></p>
  75
  76     <p>Note that revision numbers 1.1 and 1.3 were development
  77       versions only.</p>
  78
  79     <h2>Change log</h2>
  80
  81     <p>Changes since version 1.2:</p>
  82
  83     <ul>
  84       <li>Fixed a memory leak in the <tt>UserList::load()</tt>
  85         function.</li>
  86       <li>Added antispoofing code (the bot pings before
  87         auto-opping)</li>
  88       <li>Added password protection of user accounts.</li>
  89       <li>Added expiration on user accounts</li>
  90     </ul>
  91
  92     <h2>Compiling the bobot++</h2>
  93
  94     <p>Compiling the <em>bobot++</em> is rather simple. You will only
  95       need an Un*x-like system and a C++ compiler supporting the
  96       Standard Template Library (STL).</p>
  97
  98     <p>The <em>bobot++</em> compiles fine under the following
  99       operating systems:</p>
 100
 101     <ul>
 102       <li>Linux 2.0.x and g++ version 2.7.2.3,</li>
 103       <li>HP-UX version 9.x and 10.x and g++ version 2.7.2,</li>
 104       <li>SunOS 4.1 and g++.</li>
 105     </ul>
 106
 107     <p>It should compile easily on many other POSIX compliant
 108       systems.</p>
 109
 110     <p>First, you will have to edit the <tt>Makefile</tt> if your C++
 111       compiler is not g++. Change the line:</p>
 112
 113     <pre>CXX=g++</pre>
 114
 115     <p>With some Un*ces, you will have to link the program with some
 116       extra libraries. Change the line:</p>
 117
 118     <pre>LIBS=</pre>
 119
 120     <p>For example, you will need this line with Solaris:</p>
 121
 122     <pre>LIBS=-lsocket -lnsl</pre>
 123
 124     <p>Then you should be ready to compile the program. Type
 125       <tt>make</tt> at the prompt. If you get an error, please try and
 126       fix it before emailing me...</p>
 127
 128     <p>Now, you should have a executable file named <tt>bobot++</tt>
 129       in the directory. This is it! We will have to configure the bot,
 130       now...</p>
 131
 132     <h2>Configuring the bobot++</h2>
 133
 134     <h4>General configuration</h4>
 135
 136     <p>Edit the example file <tt>bot.conf</tt> to suit your needs. The
 137       comments in the file should be self explanatory...</p>
 138
 139     <p>Here is an example:</p>
 140
 141     <pre>nick = Bobot
 142 username = bot
 143 cmdchar = !
 144 userlist = bot.users
 145 logfile = log
 146 server = irc.eurecom.fr
 147 server = irc.emn.fr
 148 server = irc.enst.fr
 149 server = salambo.enserb.u-bordeaux.fr
 150 channel = #test1
 151 channel = #test2 key</pre>
 152
 153     <p>The bot will be named <em>Bobot</em>, more precisely
 154       <em>Bobot!bot@your.machine.com</em>. Its command char will be
 155       '!'. It will find its user list in the file <tt>bot.users</tt>,
 156       and it will have three servers in its server list. The log will
 157       be written to the file <tt>log</tt>. It will join two channels:
 158       #test1 and #test2 with <tt>key</tt> as the channel key
 159       (remember, the +k mode for channels...).</p>
 160
 161     <p>If you omit one of these configuration options, a default value
 162       will be used.</p>
 163
 164     <p>Comments begin with ``#'' (at the first column only), and here
 165       is the meaning of all configuration options. Note that there are
 166       synonyms.</p>
 167
 168     <table border="1">
 169       <tr>
 170         <th>Syntax</th>
 171         <th>Default value</th>
 172         <th>Meaning</th>
 173       </tr>
 174       <tr>
 175         <td>NICK=&lt;nickname&gt;<br>
 176           NICKNAME=&lt;nickname&gt;</td>
 177         <td>Bobot</td>
 178         <td>This is the nickname of the bot</td>
 179       </tr>
 180       <tr>
 181         <td>USERNAME=&lt;username&gt;</td>
 182         <td>bot</td>
 183         <td>The username of the bot, if there is no <tt>identd</tt> daemon</td>
 184       </tr>
 185       <tr>
 186         <td>IRCNAME=&lt;ircname&gt;<br>
 187         REALNAME=&lt;ircname&gt;</td>
 188         <td>I'm a bobot++!</td>
 189         <td>The ircname of the bot</td>
 190       </tr>
 191       <tr>
 192         <td>CMDCHAR=&lt;command&nbsp;char&gt;<br>
 193         COMMAND=&lt;command char&gt;</td>
 194         <td>!</td>
 195         <td>The command char of the bot</td>
 196       </tr>
 197       <tr>
 198         <td>USERLIST=&lt;file&nbsp;name&gt;</td>
 199         <td>bot.users</td>
 200         <td>The userlist file</td>
 201       </tr>
 202       <tr>
 203         <td>LOGFILE=&lt;file&nbsp;name&gt;</td>
 204         <td>log</td>
 205         <td>The log file (may be set to <tt>/dev/null</tt> if you do
 206           not want to log...</td>
 207       </tr>
 208       <tr>
 209         <td>SERVER=&lt;server&nbsp;name&gt;&nbsp;[&lt;port&gt;&nbsp;[&lt;password&gt;]]</td>
 210         <td>None</td>
 211         <td>The server the bot will try to connect to, on the port
 212           specified, and optionally with a password. You can put any
 213           number of SERVER lines</td>
 214       </tr>
 215       <tr>
 216         <td>CHANNEL=&lt;channel&nbsp;name&gt;&nbsp;[&lt;channel&nbsp;key&gt;]</td>
 217         <td>None</td>
 218         <td>The channel the bot will join on startup. You can put any
 219           number of CHANNEL lines</td>
 220       </tr>
 221     </table>
 222
 223     <h4>You are the master of the bot</h4>
 224
 225     <p>Yes! But the bot does not know who you are yet. Edit the file
 226       <tt>bot.users</tt> (or whatever your userlist file is) and put
 227       in a line like this one:</p>
 228
 229     <pre>&lt;your adress&gt;:#*:4:0:0:-1:*NONE*</pre>
 230
 231     <p>where &lt;your adress&gt; is composed with your IRC address. It
 232       should be something like that:</p>
 233
 234     <pre>*!*username@*.domain.com</pre>
 235
 236     <p>if you connect on IRC from <tt>machine.domaine.com</tt>, with
 237       <tt>username</tt> as login.</p>
 238
 239     <p>For me, this is <tt>*!*bernard@*.cma.fr</tt>.</p>
 240
 241     <p>Now, you can run the bot:</p>
 242
 243     <pre>./bobot++</pre>
 244
 245     <p>Note that there are certain command line options that you can
 246       see with:</p>
 247
 248     <pre>./bobot++ -h</pre>
 249
 250     <h2>Using the <em>bobot++</em></h2>
 251
 252     <h4>Adding people on the userlist</h4>
 253
 254     <p>Of course, you will want to add people on the userlist, as well
 255       as other bots. The <tt>adduser</tt> command is for you, then!
 256       Its syntax is:</p>
 257
 258     <pre>!adduser &lt;nick&gt;|&lt;mask&gt; &lt;channel&nbsp;mask&gt; &lt;level&gt; &lt;prot&gt; &lt;aop&gt;</pre>
 259
 260     <p>Note that ``!'' is the command char of the bot, and it may be
 261       different according to the configuration you chose.<br>
 262       The meaning of the different options is rather simple:</p>
 263
 264     <table border="1">
 265       <tr>
 266         <td align="center">&lt;nick&gt;</td>
 267         <td>The nickname of the person to add. The bot will generate a
 268           mask matching this person. If the mask is not accurate
 269           enough, you should use...</td>
 270       </tr>
 271       <tr>
 272         <td align="center">&lt;mask&gt;</td>
 273         <td>...to select the mask you really want. I remind you that
 274           the mask is a regular expression designed to match
 275           <em>nick!username@hostname</em></td>
 276       </tr>
 277       <tr>
 278         <td align="center">&lt;channel&nbsp;mask&gt</td>
 279         <td>This is a mask representing channels where this account is
 280           available. You can put ``*'' for every channels, ``#*'' for
 281           every non-local channels, etc.</td>
 282       </tr>
 283       <tr>
 284         <td align="center">&lt;level&gt;</td>
 285         <td><table width="100%" border="1">
 286             <tr>
 287               <td>0</td>
 288               <td>No level - Impossible to execute commands. This is
 289                 for bots, for example.</td>
 290             </tr>
 291             <tr>
 292               <td>1</td>
 293               <td>User level - Will be able to execute many of the
 294                 commands, but will not be able to use masks on kicks
 295                 and on bans.</td>
 296             </tr>
 297             <tr>
 298               <td>2</td>
 299               <td>Trusted user level - Exactly the same commands as
 300                 the ``User'' level, except that the user will be able
 301                 to use masks on bans and kicks.</td>
 302             </tr>
 303             <tr>
 304               <td>3</td>
 305               <td>Friend level - Can do everything on the bot, except
 306                 stopping it. Be careful of who your friends are :-)</td>
 307             </tr>
 308             <tr>
 309               <td>4</td>
 310               <td>Master level - Can do everything on the bot.</td>
 311             </tr>
 312           </table>
 313         </td>
 314       </tr>
 315       <tr>
 316         <td align="center">&lt;protection&gt;</td>
 317         <td><table width="100%" border="1">
 318             <tr>
 319               <td>0</td>
 320               <td>No protection - for nearly everybody.</td>
 321             </tr>
 322             <tr>
 323               <td>1</td>
 324               <td>No ban - it will be impossible to ban the user,
 325                 directly or indirectly.</td>
 326             </tr>
 327             <tr>
 328               <td>2</td>
 329               <td>No kick - if the user is kicked, there will be a
 330                 revenge.</td>
 331             </tr>
 332             <tr>
 333               <td>3</td>
 334               <td>No deop - The bot will insure that the user can not
 335                 be deopped. Useful for bots.</td>
 336             </tr>
 337           </table>
 338         </td>
 339       </tr>
 340       <tr>
 341         <td align="center">&lt;aop&gt;</td>
 342         <td><table width="100%" border="1">
 343             <tr>
 344               <td>0</td>
 345               <td>No auto-op on join.</td>
 346             </tr>
 347             <tr>
 348               <td>1</td>
 349               <td>Auto-op on join. For bots, and optionnaly other
 350                 users. It depends on the policy of your channel.</td>
 351             </tr>
 352           </table>
 353         </td>
 354       </tr>
 355     </table>
 356
 357     <p>Here are two examples:</p>
 358
 359     <pre>!adduser eb #* 2 1 0
 360 !adduser *!*test@138.195.*.* #test 0 3 1
 361 !save</pre>
 362
 363     <p>We first add ``eb'' (me!) to the userlist, for every non-local
 364       channel, at level 2 (trusted user), with no-ban protection and
 365       no auto-op.</p>
 366
 367     <p>Then we add every user matching ``*!*test@138.195.*.*'' to the
 368       userlist for channel ``#test'', with level 0 (no level),
 369       protection 3 (no-deop) and auto-op on join. It is probably
 370       another bot.</p>
 371
 372     <p>Finally, we save the changes to the userlist. Note that this is
 373       not mandatory, since the userlist is saved when the bot
 374       <tt>!die</tt>s, but if the bot is killed or if there is a bug
 375       (yes, there <em>are</em> bugs :-), all your changes would not
 376       have been saved.</p>
 377
 378     <h4>Issuing a command (like for example a kick)</h4>
 379
 380     <p>The <em>bobot++</em> supports two types of commands: those who
 381       affect a channel (kick, ban, topic...) and those who don't.</p>
 382
 383     <p>For commands which need a channel name, the channel name can be
 384       optionnaly put after the name of the command. This is mandatory
 385       if the command is made directly to the bot, with a private
 386       message.</p>
 387
 388     <p>Suppose the bot is on two channels, <tt>#test1</tt> and
 389       <tt>#test2</tt>. You are on channel <tt>#test1</tt>. Here is the
 390       behavior of the bot:</p>
 391
 392     <table border="1">
 393       <tr>
 394         <td><tt>#test1&gt; !kick foo reason</tt></td>
 395         <td>This will kick <em>foo</em> out of channel
 396           <tt>#test1</tt>.</td>
 397       </tr>
 398       <tr>
 399         <td><tt>#test1&gt; !kick #test1 foo reason</tt></td>
 400         <td>This will also kick <em>foo</em> out of channel
 401           <tt>#test1</tt>.</td>
 402       </tr>
 403       <tr>
 404         <td><tt>#test1&gt; !kick #test2 foo reason</tt></td>
 405         <td>This will kick <em>foo</em> out of channel
 406           <tt>#test2</tt>.</td>
 407       </tr>
 408       <tr>
 409         <td><tt>-&gt; *bot* !kick #test1 foo reason</tt></td>
 410         <td>This will kick <em>foo</em> out of channel
 411           <tt>#test1</tt>.</td>
 412       </tr>
 413       <tr>
 414         <td><tt>-&gt; *bot* !kick #test2 foo reason</tt></td>
 415         <td>This will kick <em>foo</em> out of channel
 416           <tt>#test2</tt>.</td>
 417       </tr>
 418       <tr>
 419         <td><tt>-&gt; *bot* !kick foo reason</tt></td>
 420         <td>This will <em>not</em> work. The bot has no way to know to
 421           which channel this command applies to.
 422       </tr>
 423     </table>
 424
 425     <p>Is this clear enough? This is rather compelling, I know, but I
 426       have not found a better way to do this.</p>
 427
 428     <h4>Spying the bot</h4>
 429
 430     <p>I hate people that kick others <em>via</em> the bots, and using
 431       a private message to the bot. There is no good way to really
 432       know what others do. Furthermore, some private messages can be
 433       sent to the bot and this can be funny. That is why I made a
 434       command to spy bot's private messages.</p>
 435
 436     <p>There is a ``spylist'' on the bot that every user can read with
 437       the command <tt>!spylist</tt>. To be added to the spylist, you
 438       should use the <tt>!spymessage</tt> command. To be removed, this
 439       is the <tt>!rspymessage</tt> command.</p>
 440
 441     <p>Note that password control on the bot is not yet implemented,
 442       so there is no danger of knowing the password of other people. I
 443       will improve the spylist later in order not to be able to see
 444       others' password.</p>
 445
 446     <h4>Intelligent ban and deban</h4>
 447
 448     <p>Note what happens if you try:</p>
 449
 450     <pre>!ban *.a.a
 451 !ban *.b.a
 452 !ban *.c.a
 453 !ban *.d.a</pre>
 454
 455     <p>Then</p>
 456
 457     <pre>!ban *.a</pre>
 458
 459     <p>Fine, isn't it? If we didn't do that, the server would not
 460       accept the last ban. Try also <tt>!deban *</tt> (use it when the
 461       banlist is full!).</p>
 462
 463     <h4>Getting help on other commands</h4>
 464
 465     <p>The <tt>!help</tt> command without arguments will give you all
 466       the commands you can issue. For a master, this will give
 467       you (this may change in the future):</p>
 468
 469     <pre>-Bobot- Available topics for you are:
 470 -Bobot- ACTION ADDUSER ADDSERVER BAN CHANNELS CYCLE DEBAN DELSERVER DEOP
 471         DIE HELP INVITE JOIN KICK KICKBAN LOCK NAMES NEXTSERVER NICK
 472         NSLOOKUP OP PART RECONNECT RSPYMESSAGE SAVE SAY SERVER SERVERLIST
 473         SPYLIST SPYMESSAGE TOPIC UNLOCK USERLIST WHO WHOIS
 474 -Bobot- Use HELP &lt;command&gt; for help about &lt;command&gt;</pre>
 475
 476     <p>If you want help about the <tt>!kick</tt> command, use
 477       <tt>!help kick</tt>:</p>
 478
 479     <pre>-Bobot- Help for KICK:
 480 -Bobot- KICK [&lt;channel&gt;] &lt;mask&gt;|&lt;nick&gt; [&lt;reason&gt;]
 481 -Bobot- Kicks &lt;mask&gt; or &lt;nick&gt; out of &lt;channel&gt;, because of &lt;reason&gt;.
 482 -Bobot- You need to be a trusted user to use a &lt;mask&gt;.
 483 -Bobot- End of help.</pre>
 484
 485     <p>Then you have the tools to explore the <em>bobot++</em> in
 486       details. Good luck!</p>
 487
 488     <h2>Bugs, questions, etc.</h2>
 489
 490     <p>If you find a bug or a strange behaviour of the bot, please try
 491       to reproduce it, and then send me a mail describing the problem
 492       <em>in details</em>.</p>
 493
 494     <p>If you have suggestions about new features, please tell
 495       me. If you added features yourself, send me your patch!</p>
 496
 497     <p>Note that I will not answer to configuration or compilation
 498       problems...</p>
 499
 500     <h2>Plans for the future</h2>
 501
 502     <p>Here is what I plan to add to the <em>bobot++</em>:</p>
 503
 504     <ul>
 505       <li>Scripting support with Guile, the GNU Scheme
 506         interpreter;</li>
 507       <li>Bot control via telnet, or a java applet;</li>
 508       <li>DCC Send and Get (we will be able to use the bot as a
 509         file server);</li>
 510       <li>Shitlist, like on the <em>bobot</em>;</li>
 511       <li>Dynamic settings;</li>
 512       <li>Other ideas?</li>
 513     </ul>
 514
 515     <h2>Why use Guile?</h2>
 516
 517     <p>Guile is the GNU Scheme interpreter. In a future release of the
 518       <em>bobot++</em>, I plan to add scripting support using this
 519       interpreter.</p>
 520
 521     <p>So, why did I chose Guile, instead of Tcl or Python?</p>
 522
 523     <p>One of the main features of Guile is that it will be easy to
 524       extend the interpreter in order to translate Python, Tcl or
 525       Perl to Scheme code. So, you will have the choice of the
 526       language! If you prefer Python instead of Perl or Tcl, use
 527       Python. If you prefer CTax (a language similar to C), all right!
 528       I hope that religious wars opposing those languages will soon be
 529       over...</p>
 530
 531     <p>Moreover, as Guile is GNU code, it is <em>really</em> a free
 532       software, and will keep this status.</p>
 533
 534     <p>Finally, it is an excellent product, so why shouldn't we use
 535       it?</p>
 536
 537
 538     <hr>
 539     <address><a href="mailto:bernard@isia.cma.fr">Etienne
 540         BERNARD</a></address>
 541
 542     <!-- Created: Fri Mar  6 18:45:32 CET 1998 -->
 543     <!-- hhmts start -->
 544 Last modified: Sat Mar 21 13:32:54 CET 1998
 545 <!-- hhmts end -->
 546   </body>
 547 </html>