                       _
  ___   __ _  __ _  __| |_ __  ___  _ __
 / _ \ / _` |/ _` |/ _` | '__|/ _ \| '_ \
|  __/| (_| | (_| | (_| | |  | (_) | |_) |
 \___| \__, |\__, |\__,_|_|   \___/| .__/
       |___/ |___/                 |_|     v0.9p

Please at least SKIM this document before asking questions.


(1) WHAT IS EGGDROP?

    Eggdrop is an IRC bot, written in C.  If you don't know what IRC is,
    this is probably not whatever you're looking for!  Eggdrop, being a
    bot, sits on a channel and takes protective measures: to keep the
    channel from being taken over (in the few ways that anything CAN),
    to recognize banished users or sites and reject them, to recognize
    priveledged users and let them gain ops, etc.

    One of the more unique features of eggdrop is its "party line",
    accessable via DCC chat, which allows you to talk to other people
    lag-free.  Consider it a multi-way DCC chat, or a miniature IRC
    (complete with channels).  You can link up with other bots and
    expand the party line until it actually becomes something very much
    like IRC, in fact.  

    Eggdrop is still being worked on, and is considered "unfinished".
    At this point, what that really means is that the author hasn't done
    quite everything that he set out to do yet -- but he's getting pretty
    close.  A valiant effort has been made to chase down and destroy bugs.
    It is definitely nowhere near as buggy as the ircII client.  Crashes
    should be rare and surprising (but aren't they always?).

    This README file contains information about how to get eggdrop, how to
    quickly compile the bot, what you may need to do when upgrading from 
    older versions, a list of frequently asked questions about compiling,
    how to set up a crontab, some boring legal stuff, info about the mailing
    list (a great place to ask questions), and a complaint/explanation about
    the lack of documentation.


(2) HOW TO GET EGGDROP

    The eggdrop code is available via anonymous FTP at:
       ftp://robot.asimov.net/pub/eggdrop/eggdrop0.9p.tar.gz
       ftp://ftp.lightning.net/pub/eggdrop/eggdrop0.9p.tar.gz

    There is also a web page that is updated pretty frequently, and
    always has links to the latest few versions, as well as to botnets
    and other sources of info:
       http://www.lightning.net/~robey/eggdrop.html

    An EGGDROP TCL SCRIPT LIBRARY has been started up at the ftp site on
    godzilla.npl.com, so that's probably a good place to look for Tcl
    scripts, or upload your own favorites.


(3) QUICK STARTUP

    NOTE: As of v0.9p, I'm trying out the GNU autoconf stuff.  (I finally
          managed to read most of their contorted documentation.)  So pay
          close attention here because the whole process of compiling the
          bot has changed (and become much easier, I think).

    1. Type './configure' from the eggdrop directory.  That script will
       determine how your system is set up, and figure out how to compile
       eggdrop (I hope).  If it can find Tcl, it will automatically tell
       the Makefile to try compiling using Tcl (which is almost required
       these days).

    2. Edit 'src/eggdrop.h' to your liking if you're the hacker type.
       (THIS STEP IS OPTIONAL.)

    3. Type 'make' from the eggdrop directory.  If you want your bot to run
       from it's own directory (highly recommended), type 'putegg <dir>' to
       copy the main files there.

    4. Edit 'lamestbot' (a sample script) and rename it to something you can
       remember (like "mybot").  Move it to your bot's directory.
       (If you didn't compile with Tcl, you must use 'egg.config.dist'
       instead of 'lamestbot'.)

    5. Start the bot with the "-m" option to create a user file, ie
       'eggdrop -m lamestbot'.

    6. When starting the bot in the future, drop the "-m".  If you compiled
       with Tcl and have edited your bot script correctly, you can type:
         chmod u+x <my-bot-script-name>
       and from then on, you will be able to run your bot directly from the
       script.  So you can just type "lamestbot" from your shell prompt to
       start up your bot.  For this to work, the top line of your script MUST
       contain the correct path to eggdrop.

    7. It's advisable to run your bot via crontab so that it will automatic-
       ally restart if the machine goes down or (heaven forfend) the bot
       should crash.  Look at the file 'botchk' for a great start with cron-
       tabbing the bot.


(4) UPGRADING

    from 0.9g:
    If you use share-bots, upgrade them all of them simultaneously -- user
    records for other bots are no longer swapped, so a non-upgraded bot will
    either lose or create duplicate bot entries.

    from 0.9i:
    Until all the bots on a bot-net upgrade to 0.9i, the '.whom' and remote
    '.who' commands will look screwy, or may not even work at all.

    from 0.9j:
    The party line supports multiple channels now, so it is to your advantage
    to upgrade all the bots on a bot-net at around the same time.

    from 0.9l:
    Scripts which used "bind sign" may not work correctly without editing
    (there is a new parameter to procedures of this type).

    from 0.9n:
    If you compile with the new OWNER ability (and this is now the default),
    be sure you have at least ONE person listed in the 'owner' variable, ie:
       set owner "MrLame"
    so that someone will be given the new owner flag (+n) when the bot starts
    up.  If you start up and nobody has the +n flag, you can't do much.

    from 0.9o:
    A few Tcl commands have changed syntax so that they'll make more sense.
    Some scripts may need to be updated, especially any that used 'control',
    'dccsimul', 'getchan', 'putchan', or 'console'.  Those commands are now
    referenced by idx instead of handle, since someone can be on the party
    line several times with the same handle -- but their idx will be diff-
    erent each time.  This will probably break a lot of the weirder scripts,
    but in the long run it will make most scripts work better.


(5) FREQUENTLY ASKED QUESTIONS

    1. WHAT DO I DO IF I GET THE ERROR "USER FILE NOT FOUND"?

       (1) Run eggdrop with the "-m" option (ie, "eggdrop -m mybot").
       (2) Go to IRC and send "hello" to your bot (ie, "/msg mybot hello").
       (3) You will become a master on your bot.  You can leave the bot
           running (nobody else will become a master if they say "hello"),
           but in the future, don't use the "-m" option when running the bot.

    2. WHAT DO I DO IF I GET A WARNING WHILE COMPILING THAT SAYS "ATOL
       REDEFINED"?

       You must be using gcc.  Just ignore it, the redefinition of atol() is
       intentional, because on some crappy BSD/386 systems, atol() is broken.

    3. MY EGGDROP WON'T RUN; IT JUST SAYS "CAN'T FIND YOUR HOSTNAME!"

       Your machine is set up strangely, and eggdrop can't figure out its 
       network hostname.  You can get around this by setting an environment
       variable called HOSTNAME.  In sh or ksh:
         $ HOSTNAME=myhost.domain.edu
         $ export HOSTNAME
       In csh or tcsh:
         % setenv HOSTNAME myhost.domain.edu
       It should work after that.  You may want to bug your system admini-
       strator to set up her /etc/hosts file correctly, or add those above
       commands to your '.login' file (sh or ksh: '.profile').

    4. WHAT THE HECK IS TCL?

       Tcl is a scripting language written by John Ousterhout.  It's much 
       better than most "in-built" script langauges (like the one in ircII)
       and is meant to be linked with anything needing a script langauge.  
       So I linked it with eggdrop.  Most systems should have Tcl on them by
       now -- you can check by trying the command "tclsh".  If it works, you
       will be given a "%" prompt, and you can type "exit" to exit the
       program.  That means Tcl is on your system.  If tclsh doesn't load,
       then Tcl probably isn't on your system, and you will need to ftp it
       if you want to use the script language features of eggdrop.  The best
       ftp site is:
          ftp://ftp.cs.berkeley.edu/ucb/tcl
       The current version as of this writing is 7.4 and it works great.

       The file "tcl-commands.doc" in the eggdrop directory contains a list
       of the commands added to Tcl by eggdrop.  Another file, "lamestbot",
       is a script file meant to be executed from the command line.  It starts
       up an eggdrop bot called "LamestBot" which sits on channel #lamest.
       NOTE THAT IF YOU COMPILE WITH TCL, YOUR CONFIG FILE MUST LOOK LIKE 
       THIS, NOT LIKE "EGG.CONFIG.DIST".  The file "botkick" is a sample
       script file which implements a "kick" command via msg, and "samples"
       contains a few sample scripts.  There are gobs of eggdrop/Tcl scripts
       floating around (including a bunch on Snowbot) if you like working by
       example.

       Additional note: Tcl is included with most recent versions of Linux.
       YAY!

    5. I TRIED TO COMPILE AND IT'S COMPLAINING ABOUT A "TCL.H" FILE -- WHERE
       IS THAT?

       This shouldn't ever happen now.  If it still does, it means that the
       'configure' script thought you had Tcl, and you don't.  Please send
       me email if this happens to you.

    6. MY BOT SEEMS TO BE CREATING "ZOMBIE" PROCESSES ON THE SYSTEM. HELP!

       Some operating systems apparently don't properly signal eggdrop when
       processes die.  A kludge has been put into the bot to fix this, if
       necessary, by trying to search for zombies every so often.  Go into
       the file "eggdrop.h" and change the line:
         #undef HUNT_ZOMBIES
       to:
         #define HUNT_ZOMBIES
       This seems to fix the zombie problem on every system I've tried it on.

       Note: Having 1-3 zombie processes may be part of the bot's normal 
       operation.  When you have a tandem-bot on auto-connect, it may be 
       failing to connect, which can generate zombie processes.  The zombies
       are cleaned up, but then immediately regenerated by the auto-connect.

    7. COMPILE ERROR: SOMETHING ABOUT "WAITPID" OR "WAIT3"?

       You're trying to hunt for zombies on a non-posix compliant system.  I
       can't really help you any more. :)  Go back and #undef HUNT_ZOMBIES.

    8. MY USER LIST IS VERY LARGE.  HOW CAN I CUT IT DOWN?

       There is a Tcl script called "weed" distributed with eggdrop.  To use 
       it, type:
         tclsh weed
       It will give you a list of options for weeding out your userlist.  You
       can erase users who haven't been on the channel within a specified
       number of days, or erase any ops who haven't set a password yet, etc.
       Lots of options.

    9. MY BOT DIES AND THE LAST ENTRY IN THE LOGFILE IS "RECEIVED TERMINATE
       SIGNAL".  WHAT DOES THAT MEAN AND CAN I PREVENT IT?

       There's nothing you can do to prevent it.  It means the system admini-
       stator is killing the eggdrop process.  Most of the time, it's an
       automatic thing that happens when the system is being rebooted -- so
       it's harmless, and if you have a crontab running, the bot will get
       restarted when the system is back online.  Occassionally the system
       administrator will kill the bot manually -- for example, if he/she
       doesn't want bots running on the system.


(6) SETTING UP A CRONTAB

    Eggdrop has become more stable with time, thanks mostly to people detail-
    ing bugs to me and helping me find places where it crashes.  However, I'm
    sure there are still a few places where things aren't perfect -- that's
    how life works.  Also, most systems go down from time to time.  These 
    things cause your bot to disappear from IRC, and you have to restart it.

    I have included a csh script called 'botchk' which will help keep the bot
    online.  It will make the machine check every ten minutes to make sure
    your bot is still running.  To use it, you have to add a line to your
    crontab.  First, edit 'botchk' and change the directory and command line
    parameters so that it will be able to start up your bot.  Then, add this
    line to your crontab:

    0,10,20,30,40,50 * * * *   /home/mydir/botchk

    Naturally, you need to change the path to the correct path for botchk.  If
    you've never used crontab before, here is a simple way to add that line:
    Create a new file called 'mycron' and put the above line into it.  Then,
    from your shell prompt, type
      % crontab mycron
    That will create a new crontab entry for you, with a line that runs botchk
    every ten minutes.  Botchk will then restart the bot when necessary (and
    send you email informing you).


(7) BORING LEGAL STUFF

    The eggdrop bot is copyright (c) by Robey Pointer.  You, the user, have
    permission to use it as long as the copyright notices remain in place.
    You may modify the code for your own purposes in any way you choose;
    however, you may not distribute the code, except in its original form,
    or as modifications to the original code ("patches").  (This is because,
    even though I'm sure there are a lot of better coders out there, I don't
    want code to be spread around with my name on it when it isn't by me and
    could possibly have backdoors or strange bugs.)

    The files "match.c" and "net.c" are exempt from the above restrictions.
    "match.c" is original code by Chris Fuller <crf@cfox.bchs.uh.edu> and
    has been placed by him into the public domain.  "net.c" is by me and I
    also choose to place it in the public domain.  Both files contain useful
    functions that could easily be ported to other applications -- the other
    parts of the bot generally don't.

    Tcl is by John Ousterhout and is in no way affiliated with eggdrop,
    and has its own set of copyrights and whatnots, I'm sure.

    The 'configure' script was compiled using GNU autoconf, and follows the
    weird legalities of the world of GNU.  Basically I think you can copy
    it wherever.

    There is no warranty, implied or whatever.  You use this software at
    your own risk, no matter what purpose you put it to.  You didn't pay
    for it, so don't expect magic.


(8) MAILING LIST

    The mailing list has returned.  To subscribe, send email to:
       eggdrop-request@holli.com
    In the body of the message, put "subscribe eggdrop".  My address at
    multiverse.com no longer works, so don't bother to send any more email
    there.  I cancelled my account because they're incompetent.

    I tend to get a lot of mail about this thing, so please don't flood
    my mailbox.  However if you have something urgent and private to tell
    me, I can be reached at
       robey@lightning.net

    The mailing list is generally the best place to ask questions, though.
    There are a lot of people on there who have used the bot for a year or
    more, and know almost as much about the bot as I do.  (Some of them
    probably know more...)


(9) DOCUMENTATION

    I've been trying hard to keep the online documentation (in the help/
    directory) fairly up-to-date.  It should be complete now; you can browse
    through there for some handy tips.  Please let me know if you find any
    help files that are incorrect or confusing!

    I know that a unified documentation would REALLY BE HELPFUL.  All I can
    say is...  I've been pretty busy with classwork (I go to school) and I
    haven't even had much time to keep updating the bot.  But I AM working
    on it, bit by bit.  Stage one was finishing the online docs.  Now I'm
    slowly adding bits to the unified documentation.

    I have two sections written so far, one on linking bots together into
    a botnet, and another on sharing userfiles with linked bots.  You can
    find them in "botnet.doc" right now.  Comments and suggestions would
    be welcome!


This is the end.  Wow.  Someone actually read this far.
