/[cvs]/eggdrop1.8/README
ViewVC logotype

Contents of /eggdrop1.8/README

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.5 - (show annotations) (download)
Mon Nov 1 23:00:10 2010 UTC (8 years, 6 months ago) by pseudo
Branch: MAIN
CVS Tags: HEAD
Branch point for: gettext
Changes since 1.4: +2 -6 lines
Minor docfixes

1 $Id: README,v 1.4 2010/10/25 15:56:36 pseudo Exp $
2
3 Readme
4 Last revised: Nov 01, 2010
5 _________________________________________________________________
6
7 Readme
8
9
10 Please at least SKIM this document before asking questions. In fact, READ IT
11 if you've never successfully set up an Eggdrop bot before. PLEASE! READ IT!
12
13 Contents
14
15 0. Important notice
16 1. What is Eggdrop?
17 2. How do I get Eggdrop?
18 2a. How to get the latest version of Eggdrop via CVS
19 3. Quick startup
20 4. Upgrading
21 4a. Upgrading from a pre-1.3 version to 1.8
22 4b. Upgrading from an older 1.3/1.4/1.5/1.6 version to a newer one
23 5. Command line
24 6. Frequently Asked Questions
25 6a. What do I do if I get the error "User file not found"?
26 6b. What the Heck is Tcl?
27 6c. My bot dies and the last entry in the logfile is "Received terminate
28 signal". What does that mean and can I prevent it?
29 6d. Someone else set up a bot I don't like. Are there any backdoors I
30 can use to take their bot down?
31 6e. What are modules?
32 6f. Can I compile Eggdrop without dynamic modules?
33 6g1. Do I still need to "loadmodule" modules?
34 6g. Where can I get a pre-compiled Eggdrop for my computer?
35 6h. I get "Makefile:3 : invalid operator" or some such thing when I
36 try to "make".
37 6i. When I "tclsh scripts/weed <userfile> c" It barfs chunks at me
38 and dies.
39 6j. I get "ld-elf.so.1: Shared object "libtcl80.so.1" not found" or
40 "eggdrop: error in loading shared libraries / libtcl8.1.so: cannot
41 open shared object file: No such file or directory" when I try to
42 start my bot.
43 6k. I get a whole pile of "unresolved symbol 'Tcl_AppendResult'" (or
44 some other symbol) when I try to load a module.
45 7. Setting up a crontab
46 7a. Setting up a crontab using autobotchk
47 8. Boring legal stuff
48 9. Mailing list
49 10. Documentation
50 11. Obtaining help
51
52 _________________________________________________________________
53
54
55 (0) NOTICE
56
57 Please read this file carefully before trying to set up Eggdrop. Also,
58 make SURE that you select your +n (owner) users wisely! They have 100%
59 access to your bot and account! ONLY GIVE THIS POWER TO SOMEONE YOU
60 TRUST COMPLETELY!!
61
62
63 (1) WHAT IS EGGDROP?
64
65 Eggdrop is the World's most popular Internet Relay Chat (IRC) bot; it is
66 freely distributable under the GNU General Public License (GPL). Eggdrop
67 is a feature rich program designed to be easily used and expanded upon by
68 both novice and advanced IRC users on a variety of hardware and software
69 platforms.
70
71 An IRC bot is a program that sits on an IRC channel and performs automated
72 tasks while looking just like a normal user on the channel. Some of these
73 functions include protecting the channel from abuse, allowing privileged
74 users to gain op or voice status, logging channel events, providing
75 information, hosting games, etc.
76
77 One of the features that makes Eggdrop stand out from other bots is module
78 and Tcl scripting support. With scripts and modules, you can make the bot
79 perform almost any task you want. They can do anything from preventing
80 floods to greeting users and banning advertisers from channels.
81
82 You can also link multiple Eggdrop bots together to form a botnet. This
83 can allow bots to op each other securely, control floods efficiently, and
84 even link channels across multiple IRC networks. It also allows the
85 Eggdrops share user lists, ban lists, exempt/invite lists, and ignore
86 lists with other bots if userfile sharing is enabled. This allows users
87 to have the same access on every bot on your botnet. It also allows the
88 bots to distribute tasks such as opping and banning users. See doc/BOTNET
89 for information on setting up a botnet.
90
91 Eggdrop is always being improved and adjusted because there are bugs to
92 be fixed and features to be added (if the users demand them, and they make
93 actually sense). In fact, it existed for several years as v0.7 - v0.9
94 before finally going 1.0. This version of Eggdrop is part of the 1.8 tree.
95 A valiant effort has been made to chase down and destroy bugs.
96
97 This README file contains information about how to get Eggdrop, command
98 line options for Eggdrop, what you may need to do when upgrading from
99 older versions, a list of frequently asked questions, how to set up a
100 crontab, some boring legal stuff, info about the mailing list (a great
101 place to ask questions, and a good place to report bugs, too), some basics
102 about CVS usage, and some channels where you might get help with Eggdrop.
103
104
105 (2) HOW TO GET EGGDROP
106
107 Before you can compile Eggdrop, you need to have Tcl installed on your
108 system. Most systems should have Tcl on them by now -- you can check by
109 trying the command "tclsh". If it works, you will be given a "%" prompt,
110 and you can type "exit" to exit the program. This means Tcl is installed
111 on your system. If tclsh doesn't load, then Tcl probably isn't on your
112 system, and you will need to install it. The best ftp site for Tcl is
113 ftp://tcl.activestate.com/pub/tcl/.
114
115 Currently, the 1.8 tree of Eggdrop is developed at eggheads.org. You can
116 get the latest version of Eggdrop from the following url:
117
118 http://geteggdrop.com/
119
120 You might try www.eggheads.org for help and information.
121
122
123 (2a) CVS USAGE
124
125 You can obtain the VERY LATEST version of Eggdrop, that is still under
126 development, by using CVS. CVS means 'Concurrent Versions System' and is
127 a tool for developers to always keep source code up to date. Try 'man cvs'
128 on your shell for more information about CVS.
129
130 This is intended only for users that know a good bit about Eggdrop. Be
131 aware that the versions of Eggdrop that you get via CVS are still being
132 developed, and may be buggy. The Eggheads Development Team will in NO WAY
133 take any responsibility for whatever might happen to you or your shell if
134 you use a CVS version of Eggdrop.
135
136 To obtain Eggdrop over CVS, do as follows:
137
138 1. Log into your shell.
139
140 2. Type: 'export
141 CVSROOT=:pserver:anonymous@cvs.eggheads.org:/usr/local/cvsroot'.
142
143 3. Type 'cvs login'.
144
145 4. Press <enter> when prompted for a password.
146
147 5. In your home dir, type 'cvs checkout eggdrop1.8'
148
149 6. In ~/eggdrop1.8, you should have a copy of the latest CVS version
150 of Eggdrop.
151
152 Notes:
153
154 o You can 'cvs logout', but you don't need to.
155
156 o You don't need to go through this whole process every time. If you
157 want to get a CVS version of Eggdrop at a later time, you can just
158 'cd ~/eggdrop1.8' and type 'cvs update -CdAP'.
159
160 o If you experience errors when using 'export', you might be using tclsh
161 as a shell. If so, try using the command 'setenv' instead of 'export':
162
163 setenv CVSROOT :pserver:anonymous@cvs.eggheads.org:/usr/local/cvsroot
164
165
166 (3) QUICK STARTUP
167
168 Please see the 'INSTALL' file AFTER you finish reading this file.
169
170
171 (4) UPGRADING
172
173
174 (4a) UPGRADING FROM A PRE-1.3 VERSION TO 1.8
175
176 #### BACK UP YOUR USERFILE ####
177
178 We can't stress this enough. If you are upgrading and you have even a
179 slight possibility of downgrading again later, you will HAVE to back up
180 your userfile, or you will lose it. v1.3 of Eggdrop radically changed a
181 lot of things.
182
183 There are many major changes between v0.9, v1.0, v1.1 and v1.8, so PAY
184 ATTENTION to this part if you have a v0.9, 1.0 or 1.1 bot currently. If
185 you're just starting out, you can skip this section.
186
187 If you run share bots, you will need to upgrade them all at the same time
188 because of the new userfile format. Older bots will be able to link in,
189 but will not get or send a userfile. MAKE A NEW CONFIG FILE from the
190 example; there are some radical changes.
191
192 If you are upgrading from 0.9/1.0 to 1.8, just redo the whole thing.
193 Absolutely everything has changed, including the userfile and config file
194 formats.
195
196 If you are upgrading from 1.1/1.2 to 1.8, you will likely want to redo
197 the config file, as much as changed. BACK UP! You will need to run 'tclsh
198 scripts/weed/<userfile> c' to convert your userfile from v3 (1.1/1.2) to
199 v4 (1.3/1.4/1.5/1.6/1.8).
200
201
202 (4b) UPGRADING FROM AN OLDER 1.3/1.4/1.5/1.6 VERSION TO A NEWER 1.8 VERSION
203
204 If you followed the 'INSTALL' file and did a 'make install' (or 'make
205 install DEST="path"') after 'make', this will be pretty easy. Just upload
206 the new eggdrop1.8.x.tar.gz file to your home dir on your shell, gunzip
207 and untar it, and type 'cd ~/eggdrop1.8.x'. Next, type './configure',
208 'make config' or 'make iconfig', then 'make'. Then, kill the bot ('.die'
209 on the party line), and 'make install' to the same directory your bot
210 is currently in. After that, you can just restart your bot. You may wish
211 to delete the old Eggdrop executable and modules as well, especially if
212 you have limited disk space.
213
214 You should read through the new eggdrop.conf file for all of the new
215 options in Eggdrop 1.8.x. You can copy and paste any of these settings
216 into you current conf file if you do not want to use the default settings.
217
218
219 (5) COMMAND LINE
220
221 Eggdrop has some command-line options -- not many, because most things
222 should be defined through the config file. However, sometimes you may
223 want to start up the bot in a different mode, and the command-line
224 options let you do that. Basically, the command line for Eggdrop is:
225
226 % eggdrop [options] [config-file]
227
228 The options available are:
229
230 -n: Don't background. Normally, Eggdrop will move itself into the
231 background when you start it up, meaning you'll get another shell
232 prompt, and you can do other things while the bot is running. With
233 -n, you won't return to the shell prompt until the bot exits (which
234 won't normally happen until it's killed). By default, -n will send
235 all log entries to the console.
236
237 -nt: Don't background, use terminal. This is just like -n, except that
238 instead of seeing log entries, your console will simulate a DCC
239 chat with the bot.
240
241 -nc: Don't background, show channel info. This is just like -n, except
242 that instead of seeing log entries, every 10 seconds your screen
243 will clear and you will see the current channel status, sort of
244 like "top".
245
246 -m: Create userfile. If you don't have a userfile, this will make Eggdrop
247 create one and give owner status to the first person that introduces
248 himself or herself to it. You'll need to do this when you first set
249 up your bot.
250
251 -h: Show help.
252
253 -v: Show version info, then quit.
254
255 Most people never use any of the options except -m, and you usually only
256 need to use that once.
257
258
259 (6) FREQUENTLY ASKED QUESTIONS (or "Why doesn't this thing work?")
260
261 6a. WHAT DO I DO IF I GET THE ERROR "USER FILE NOT FOUND"?
262
263 1. Run Eggdrop with the "-m" option (i.e. "eggdrop -m eggdrop.conf").
264
265 2. Go to IRC and send "hello" to your bot (i.e. "/msg mybot hello").
266
267 3. You will become an owner on your bot. You can leave the bot running
268 (nobody else will become an owner if they say "hello"), but in the
269 future, don't use the "-m" option when running the bot.
270
271 6b. WHAT THE HECK IS Tcl?
272
273 Tcl is a scripting language written by John Ousterhout. It's much better
274 than most "built-in" script languages (like the one in ircII) and is
275 meant to be linked with anything needing a scripting language, so I
276 linked it with Eggdrop. The file "tcl-commands.doc" in the doc directory
277 contains a list of additional Tcl commands provided by Eggdrop. There
278 are also several example scripts in the scripts/ directory, and one in
279 the doc directory called first_script.txt. Hundreds of scripts floating
280 around on the ftp/web sites if you like working by example (which is
281 typically the best way).
282
283 6c. MY BOT DIES, AND THE LAST ENTRY IN THE LOGFILE IS "RECEIVED TERMINATE
284 SIGNAL". WHAT DOES THAT MEAN, AND CAN I PREVENT IT?
285
286 There's nothing you can do to prevent it. It means the system
287 administrator is killing the Eggdrop process. Most of the time, it's an
288 automatic thing that happens when the system is being rebooted, so it's
289 harmless. If you have a crontab running, the bot will get restarted when
290 the system is back online. Occasionally, the system administrator will
291 kill the bot manually. For example, if he/she doesn't want bots running
292 on the system.
293
294 6d. SOMEONE ELSE SET UP A BOT I DON'T LIKE. ARE THERE ANY BACKDOORS I CAN
295 USE TO TAKE THEIR BOT DOWN?
296
297 No, there have never been any backdoors and there never will be, so
298 please stop asking. Every once in a while, someone finds a way to
299 exploit a bug in Eggdrop, but we fix these bugs as soon as we find out
300 about them. If you want to bring down someone else's bot, you will not
301 have my/our help.
302
303 6e. WHAT ARE MODULES?
304
305 Modules are a way of adding extra features to the bot, much like Tcl
306 scripts, without requiring the bot to be recompiled. See doc/MODULES
307 for more information.
308
309 6f. CAN I COMPILE EGGDROP WITHOUT DYNAMIC MODULES?
310
311 Yes, you can. If the configure script detects that your system CAN'T
312 run modules, it will setup 'make' to link the modules in statically
313 for you. You can choose this option yourself by using 'make static'.
314 You can also try to compile dynamic modules on a static-only system
315 by using 'make eggdrop'.
316
317 6f1. DO I STILL NEED TO 'loadmodule' MODULES?
318
319 YES, when you compile statically, all the modules are linked into the
320 main executable. HOWEVER, they are not enabled until you use loadmodule
321 to enable them, hence you get nearly the same functionality with static
322 modules as with dynamic modules.
323
324 6g. WHERE CAN I GET A PRE-COMPILED EGGDROP FOR MY COMPUTER?
325
326 It is HIGHLY recommended AGAINST using pre-compiled Eggdrops from
327 un-trusted sources. Eggdrop has been a regular target for hacking and
328 crashing. Distribution of pre-compiled (binary) versions of Eggdrop are
329 the easiest way for hackers to provide you with the easiest (and most
330 dangerous) way of gaining access to, not only your bot, but to your
331 computer account directly. Don't advertise your pre-compiled Eggdrop
332 binary sites on the Eggdrop list either. =P
333
334 6h. I GET 'Makefile:3 :invalid operator' OR SOME-SUCH-THING WHEN I TRY
335 TO 'make'.
336
337 Try 'gmake'.
338
339 6i. WHEN I 'tclsh scripts/weed <userfile> c' IT BARFS CHUNKS AT ME AND
340 DIES. :(
341
342 Upgrade your Tcl. You are probably using Tcl 7.5 or earlier. Some of the
343 commands in weed require Tcl7.6 to run, so either upgrade it or remove
344 the offending lines from you userfile manually (those starting with '.'
345 generally) and accept the loss of that data.
346
347 6j. I GET "ld-elf.so.1: Shared object "libtcl80.so.1" not found" or
348 "eggdrop: error in loading shared libraries libtcl8.1.so: \
349 cannot open shared object file: No such file or directory" WHEN I TRY
350 TO START MY BOT.
351
352 './configure' is looking in the wrong place for Tcl; it looks like it
353 compiled with one version of Tcl and tries to load another. Maybe your
354 sysadmin upgraded Tcl and didn't tell you. In that case, you should just
355 need to recompile your bot.
356
357 Maybe, when upgrading, he didn't clean the old version of Tcl and
358 './configure' is looking for the files in the wrong places, or trying
359 to use different versions of tcl.h and libtcl*. Smack your admin and
360 have him install Tcl properly. ;)
361
362 You can also try:
363
364 ./configure --with-tcllib=<path-to-tcl-lib>
365 --with-tclinc=<path-to-tcl-inc>
366
367 This will tell configure where to look for the Tcl files.
368
369 Try looking for libtcl by:
370
371 ls /usr/lib/libtcl*
372 ls /usr/local/lib/libtcl*
373
374 Try looking for tcl.h by:
375
376 ls /usr/include/tcl.h
377 ls /usr/local/include/tcl.h
378
379 If everything else fails, try to install Tcl to your home dir ;)
380 (Suggested by dw@Undernet, dw@lixom.nu)
381
382 6k. I GET A WHOLE PILE OF "Unresolved symbol 'Tcl_AppendResult'" (OR SOME
383 OTHER SYMBOL) WHEN I TRY TO LOAD A MODULES.
384
385 POSSIBILITY A: See section 6j.
386
387 POSSIBILITY B:
388
389 Some of the standard libraries have been compiled for static linking
390 only on your machine, you have 3 options:
391
392 1. If it's your own machine, recompile Tcl using dynamic linking by
393 using './configure --enable-shared' when you configure Tcl (not
394 the bot) and then remake, and reinstall.
395
396 2. If it's not your machine, you may have to resort to 'make static'
397 and 'make install DEST="path"' to make and install your bot.
398
399 3. If you are of a more aggressive sense of mind, go beat the
400 stuffing out of your admin for having lame static libraries. :)
401
402
403 (7) SETTING UP A CRONTAB
404
405 Eggdrop has become more stable with time, thanks mostly to people
406 reporting bug details and helping find places where it crashes. However,
407 there are still a -few- places where things aren't perfect. Few, if any,
408 things in life are.
409
410 Also, most systems go down from time to time. These things cause your bot
411 to disappear from IRC, and you have to restart it.
412
413 Eggdrop comes with a shell script called 'botchk' that will help keep the
414 bot online. It will make the machine check every ten minutes to make sure
415 your bot is still running. To use it, you have to add a line to your
416 crontab. First, edit 'botchk' and change the directory and command line
417 parameters so that it will be able to start up your bot. Then, add this
418 line to your crontab:
419
420 0,10,20,30,40,50 * * * * /home/mydir/botchk
421
422 If you don't want to get e-mails from cron, use this:
423
424 0,10,20,30,40,50 * * * * /home/mydir/botchk >/dev/null 2>&1
425
426 Naturally, you need to change the path to the correct path for botchk. If
427 you've never used crontab before, here is a simple way to add that line:
428
429 1. Create a new file called 'mycron' and put the above line into it.
430
431 2. From your shell prompt, type '% crontab mycron'.
432
433 That will create a new crontab entry for you with a line that runs botchk
434 every ten minutes. Botchk will then restart the bot when necessary (and
435 send you email informing you).
436
437
438 (7a) SETTING UP A CRONTAB USING AUTOBOTCHK
439
440 Included with your Eggdrop is an Eggdrop utility called 'autobotchk'.
441 Using autobotchk is probably the fastest way of creating your botchk and
442 crontabbing it with just a few required steps:
443
444 1. Type 'cp scripts/autobotchk ..'.
445
446 2. Type './autobotchk <Eggdrop config file>'.
447
448 This will hopefully crontab your bot using the default setup. If you want
449 a list of autobotchk options, type './autobotchk'. An example with options
450 would be:
451
452 ./autobotchk <Eggdrop config file> -noemail -5
453
454 This would setup crontab to run the botchk every 5 minutes and also to
455 not send you e-mail saying that it restarted your bot.
456
457
458 (8) BORING LEGAL STUFF
459
460 The Eggdrop bot is Copyright (C) by Robey Pointer. As of January, 1997,
461 Eggdrop is distributed according to the GNU General Public License. There
462 should be a copy of this license in the file 'COPYING'. If not, write to
463 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
464
465 As of Eggdrop 1.3.28, all changes made by the Eggheads Development Team to
466 the Eggdrop source code and any related files are Copyright (C) by Eggheads
467 Development Team. The source code will still be distributed according to
468 the GNU General Public License as Robey Pointer did in the past.
469
470 Releases previous to 1.0m were made using a different licensing scheme.
471 You may, at your option, use the GNU General Public License on those
472 versions (instead of the license packaged with them) with my blessing.
473 For any versions bearing a copyright date of 1997 or later, you have
474 no choice -- you must use the GNU General Public License.
475
476 The files "match.c", "net.c", and "blowfish.c" are exempt from the above
477 restrictions. "match.c" is original code by Chris Fuller (email:
478 crf@cfox.bchs.uh.edu) and has been placed by him into the public domain.
479 "net.c" is by me, and I [Robey Pointer] also choose to place it in the
480 public domain. "blowfish.c" is by various sources and is in the public
481 domain as well. All 3 files contain useful functions that could easily
482 be ported to other applications.
483
484 Tcl is by John Ousterhout and is in no way affiliated with Eggdrop. It
485 likely has its own set of copyrights and whatnots.
486
487 There is no warranty, implied or whatever. You use this software at your
488 own risk, no matter what purpose you put it to.
489
490
491 (9) MAILING LIST
492
493 There are currently a couple of mailing lists about Eggdrop.
494 eggheads@eggheads.org is the one relevant for posts about Eggdrop 1.4 and
495 up (suggestions, help, etc).
496
497 To subscribe to the eggheads mailing list, send e-mail to
498 eggheads-request@eggheads.org. In the body of the message, put "subscribe
499 eggheads". You can also go to the following url:
500
501 http://lists.eggheads.org/mailman/listinfo/eggheads
502
503 ### DO NOT SEND ROBEY EMAIL ABOUT EGGDROP! ###
504
505 Robey is no longer developing the Eggdrop code, so don't bother e-mailing
506 him. If you have a serious problem, email the eggheads mailing list and
507 it will get to the coders.
508
509 Please, before posting to this list, see what things are like. When you do
510 post, read over your post for readability, spelling, and grammar mistakes.
511 Obviously, we're all human (or are we?) and we all make mistakes (heck,
512 look at this document! ;).
513
514 Open discussion and debate is integral to change and progress. Don't flame
515 others over mere form (grammar and spelling), or even substantive issues
516 for that matter. Please read and follow the mailing list rules.
517
518 The eggheads@eggheads.org mailing list is not dedicated to those all too
519 common questions we have all seen on other lists... For example:
520
521 o "Why does my bot say this: Please edit your config file."
522 o "How do I telnet my bot?"
523 o "Where do I get Eggdrop for windows??????"
524
525 Technical questions, your thoughts or suggestions on new features being
526 added to Eggdrop, things that should be removed or fixed, amazing problems
527 that even stump the guru's, etc. are what we want to see here.
528
529 Bug reports should be sent to bugs@eggheads.org. Please read and fill out
530 the BUG-REPORT file in the doc directory.
531
532 DO NOT SEND HTML E-MAILS TO ANY OF THE EGGHEADS.ORG MAILING LISTS. ANYONE
533 CAUGHT SENDING HTML E-MAILS TO ONE OF THESE LISTS WILL BE REMOVED
534 IMMEDIATELY!
535
536
537 (10) DOCUMENTATION
538
539 We're trying to keep the documentation up to date. If you feel that
540 anything is missing here or that anything should be added, etc, please
541 e-mail bugs@eggheads.org about it. Thank you.
542
543
544 (11) OBTAINING HELP
545
546 You can obtain help with Eggdrop in the following IRC channels:
547
548 Undernet - #eggdrop (official channel)
549 EFnet - #egghelp
550 IRCnet - #eggdrop
551 DALnet - #eggdrop
552 FreeNode - #eggdrop, #egghelp
553 QuakeNet - #eggdrop.support
554
555 If you plan to ask questions in any of the above channels, you should be
556 familiar with and follow IRC etiquette.
557
558 o Don't type using CAPITAL letters, colors, or bold.
559
560 o Don't use "!" and "?" excessively.
561
562 o Don't /msg people without their permission.
563
564 o Don't repeat or paste large amounts of text to the channel.
565
566 If there are any other serious Eggdrop related channels that should be
567 added to the above list, please let us know.
568
569 ________________________________________________________________________
570
571 Copyright (C) 1997 Robey Pointer
572 Copyright (C) 1999 - 2010 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23