Welcome to Eggdrop!

Setting up an Eggdrop

[ The Short Short Version | Getting the Eggdrop Source | Installation | Configuration | Starting the Eggdrop ]

Note: This page was taken from the famed egghelp.org website, which is sadly no longer maintained. We (Eggheads) have attempted to update it where required, but most of these words are from slennox, one of the greatest Eggdrop supporters ever. We maintain it here now out of loving respect and with the hope that it will continue to be useful.

The Short Short Version

If you're experienced with the Unix shell environment and don't think you need to read all the stuff on this page, follow this quick guide to installing Eggdrop (otherwise, proceed straight to Getting the Eggdrop Source):

1) Download eggdrop1.8-latest.tar.gz from the eggheads ftp.
Telnet and FTP to the shell.
Upload eggdrop1.8-latest.tar.gz via FTP.
In telnet type tar zxvf eggdrop1.8-latest.tar.gz
Type cd eggdrop1.8.4
Type ./configure
7) Type make config (compiles all modules) or make iconfig (allows you to select the modules to compile).
8) Type make
Type make install DEST=/home/name/botdir
Switch to the botdir and edit the sample config file eggdrop.conf, then rename it to something appropriate (e.g. botnick.conf).
Type ./eggdrop -m <config file>

Note: Eggdrop requires Tcl to compile. If the server does not have Tcl installed, you will need to download and install it.

Getting the Eggdrop Source

There are many different versions of Eggdrop available for download from various FTP sites, but the current version under development is the 1.8 series. It is the most complete, feature-rich and functional version of Eggdrop. If you're just starting out with Eggdrop, you should use the most recent version of 1.8.

The previous version of Eggdrop, still widely used, is the 1.6 series. This was in development for some time (during which it was known as the 1.5 series), so it was quite refined and stable by the time 1.6.0 was released. The last release of 1.6 was 1.6.21.

The Eggdrop2 bot was a substantial rewrite of Eggdrop in the C++ language and with an even more modular structure. However, it was considered to be quite buggy, and its developers eventually abandoned Eggdrop altogether as users stuck with the 1.3 series, which was further developed by a new team. Most 1.4/1.5/1.6 series versions are actually newer than Eggdrop2, and Eggdrop2 should not be confused with the upcoming 2.0 series currently in development.

Download locations

Eggdrop is distributed primarily on FTP servers in tarball format (with the .tar.gz filename extension), with the version number in the filename. The Eggdrop 1.4.5 source, for example, would be named eggdrop1.4.5.tar.gz.

The Eggheads downloads page contains the latest versions of Eggdrop.

ftp.eggheads.org/pub/eggdrop/ is the official site for all releases of Eggdrop 1.3, 1.4, 1.6 and 1.8.

You can download these directly to your shell using the shell's FTP client as described here, but I recommend you download Eggdrop to your system (then upload it to the shell) so that you have a local copy of the config file, documentation, etc. to refer to when needed (you can use 7-Zip to unzip the .tar.gz file on your system). Note that if you download Eggdrop with an old version of Internet Explorer or Netscape, the filename may be corrupted into something like eggdrop1_4_5_tar.tar once it's downloaded. If that happens, make sure you change it back to eggdrop1.4.5.tar.gz.


Installing Eggdrop is a relatively simple process provided your shell has the required tools for successful compilation. On most commercial shell accounts which allow Eggdrop bots you won't have any problems with installation, but on some private boxes or a shell on your ISP you may experience errors during compilation.

Below is a step by step guide to the installation process. These instructions apply to 1.8 bots. It assumes you will be installing eggdrop-1.8.4.tar.gz, so just change the numbers if you are installing another version (in the 1.8 series, that is - installation of 1.4 and older versions varies slightly from 1.8).

1) Put the Eggdrop source on your shell using one of the specified download locations, either by downloading the eggdrop-1.8.4.tar.gz file to your system then uploading it to the shell via FTP (recommended), or downloading it directly to the shell using the shell's FTP client. You don't need to put the .tar.gz file in its own directory (it'll be done automatically in the next step).

2) Telnet to the shell (if you haven't already), and type tar zxvf eggdrop-1.8.4.tar.gz (if this doesn't work, try gunzip eggdrop-1.8.4.tar.gz then tar xvf eggdrop-1.8.4.tar). This will extract the Eggdrop source into its installation directory, named 'eggdrop-1.8.4'.

3) Type cd eggdrop-1.8.4 to switch to the directory the Eggdrop source was extracted to.

4) Type ./configure (that's a period followed by a slash followed by the word 'configure').  This makes sure the shell has all the right tools for compiling Eggdrop, and helps Eggdrop figure out how to compile on the shell.

5) When configure is done, type make config. This sets up which modules are to be compiled. For a more efficient installation, you can use make iconfig to select the modules to compile, but if you're not sure just use make config.

6) Type make. This compiles the Eggdrop. The process takes around two minutes or less on fast systems, longer on slow systems.

7) Type make install DEST=~/botdir. This will install Eggdrop into a directory named 'botdir'. You can change 'botdir' to anything you like.

Note that in some cases you may need to specify the full path, e.g. make install DEST=/home/cooldude/botdir - using the ~ character in make install won't always work. You can get the full path by typing pwd.

8) Switch to the root of your directory using cd ~ then type chmod 700 (where is the directory you installed the bot to). This is important to keep the contents your bot directory hidden from prying eyes.

9) You can safely delete the installation directory named 'eggdrop-1.8.4' (to do this, type cd ~ then rm -rf eggdrop-1.8.4) that was created previously, although some people may find it handy to keep that directory for performing additional or future installations of the same version without recompiling.

That's it! Eggdrop is now installed into its own directory on the shell. It's time to edit the configuration files to make Eggdrop work the way you want it to.


There are two files you will need to edit before you can start up your Eggdrop - the configuration file and (optionally) the botchk file. You can find the example configuration file in the directory you extracted the Eggdrop source to, under the name 'eggdrop.conf', and the 'botchk' file can be found in the /scripts subdirectory. If you downloaded Eggdrop to your system, you can unzip the tarball (.tar.gz) file to its own directory using 7-Zip or a similar program, and view the example config file, botchk file, and all the documentation files locally. You can use Notepad to edit these files, although it's sometimes desirable to use an editor that supports the Unix file format such as EditPlus.

Editing the config file

Previous versions of the 1.6 series of Eggdrop came with eggdrop.simple.conf, eggdrop.advanced.conf, and eggdrop.complete.conf, with the simple one being the best sample configuration file for new users. This has been changed, and there a quick-start, but incomplete, eggdrop-basic.conf; and the fully commented complete sample config eggdrop.conf. While this makes things simpler for developers and helpers, the complete config is over 1000 lines long and can be overwhelming for people new to Eggdrop. If you want to take full advantage of all Eggdrop has to offer, you will eventually need to spend the extra time it takes to go through and understand many of the options in the complete config file anyway.

You should first rename the sample config file to something other than "eggdrop.conf". Giving it the name of the bot's nick (e.g. NiceBot.conf) is quite common. In the config file, you set up the IRC servers you want the bot to use, the channels you want the bot to be in, and set Eggdrop's options to suit your needs. Eggdrop has many options to configure, and editing the configuration file can take some time. I recommend you go over the entire config file to ensure the bot will be configured properly for your needs. All of the options in the config file have written explanations - be sure to read them carefully. Some of them can be a little bit vague, though.

If you're editing the config file on your system (usually a better idea than editing it on the shell as that can be rather cumbersome) you'll need to upload it to your bot's directory when you're done.

Below I elaborate on and make some recommendations for many of the settings, but it is not a complete list of settings. You'll probably notice many of the options are commented out (i.e. preceded by the # (hash) character) - a commented out setting can either mean the setting is not used or it's set to the default setting. You can uncomment the setting by removing the hash. Many of the options can be set to either 0 or 1 - 0 typically means the option is disabled, while 1 means enabled.

Note that if you're using a version of Eggdrop older than 1.3.27, some of the settings below may not apply -- if it's not in the complete sample config that comes with your version of Eggdrop, then the setting is not supported. If you're editing the eggdrop-basic.conf rather than the complete config file, you can skip the descriptions below as they mainly cover many of the more complex options not available in eggdrop-basic.conf.

set username: if your shell runs identd (most do), then you should set this to your account login name.

set my-hostname and set my-ip: you'll need to set one of these if you want your bot to use a vhost. The my-hostname setting is the vhost, e.g. linux.niceshells.net, while my-ip is the IP address of the vhost, e.g. 206.343.63.217. You don't need to set both of these, but I recommend you do so as it can help if the shell is having problems with DNS. Setting these can also help solve userfile transfer problems.

logfile: keeping logs is a good idea. Generally, you should have one log for bot stuff, and one log for each of your channels. For bot stuff, add the line logfile mcobxs * "botnick.log" to the config. For channels, add logfile jkp #donkeys "#donkeys.log", logfile jkp #horses "#horses.log", etc. Make sure you remove the sample logfile lines for the channel #lamest. If you'd like to put your logfiles in their own directory, specify the directory in the log name (e.g. logfile jkp #donkeys "logs/#donkeys.log" to write the logfiles in the /logs directory).

set sort-users: by default, userfile entries are sorted in the order each user is added, from first to last. Setting this to 1 will make the userlist sort itself based on user flags. Both sorting methods can be just as useful as the other - I recommend leaving this set to 0 to start with.

listen 3333 all: you will almost certainly want to change this, as 3333 will probably be in use if there are other Eggdrops running on the machine. Generally, you can choose any port from 1024 to 65535, but the 49152-65535 range is best as these are the private/dynamic ports least likely to be reserved by other processes. You can choose not to have a port by commenting this line out, but that will prevent any telnet connections to the bot (you won't be able to use the bot as a hub, won't be able to telnet to the bot yourself, and the bot won't respond to /ctcp botnick CHAT requests).

set protect-telnet: setting this to 1 is strongly recommended for security reasons.

set require-p: this is a useful feature allowing you to give party line access on a user-specific basis. I recommend setting it to 1.

set stealth-telnets: when you telnet to your bot, it will usually display the bot's nickname and version information. You probably don't want people seeing this info if they do a port scan on the bot's shell. Setting this to 1 will prevent the bot from displaying its nickname and version when someone telnets to it.

set dcc-flood-thr: this setting determines the number of lines per second you can send to the party line before being booted. It can be a pain in the butt when you want to paste multiple lines on the party line, so you may want to increase this to something like 5 or 10.

set hourly-updates: it's a good idea to change this from the default setting of 00, since lots of other bots are already using 00 and putting a lot of stress on the shell at that time. Choose something that isn't a multiple of 10 (e.g. 03, 37, and 56 are examples of good settings).

set notify-newusers: set this to the nick you will have on the bot. This setting isn't really used if you have learn-users switched off.

set owner: you should only put one person in this list - yourself. Set it to the nick you will have on the bot. Do NOT leave it set to the default "MrLame, MrsLame".

set default-flags: these are the flags automatically given to a user when they introduce themselves to the bot (if learn-users is on) or when they're added using .adduser. If you don't want the user to be given any flags initially, set this to "" or "-".

set remote-boots: the default setting of 2 can result in annoying boots from the party line (which is kind of like being kicked from an IRC channel). You should probably set this to 0 or 1.

unbind dcc n tcl *dcc:tcl and unbind dcc n set *dcc:set: these lines unbind the .tcl and .set commands. It's a good idea to leave these lines alone, as the .tcl and .set commands can be a security risk since they provide access to your shell account through the bot. These commands are only really useful if you plan on writing Tcl scripts.

set must-be-owner: if you have the .tcl and .set commands enabled, you should definitely set this to 1. In 1.3.26 and later, you can set it to 2 for even better security.

set chanfile: the chanfile allows you to store 'dynamic' channels so that the bot rejoins the channel if restarted. Dynamic channels are those you make the bot join using the .+chan command - they aren't defined in the config file. The chanfile is good if you frequently add/remove channels from the bot, but can be a pain if you only like to add/remove channels using the config file since settings stored in the chanfile with overwrite those set in the config. You can choose not to use a chanfile by setting it to "".

channel add: this is the command you use to add channels to the bot. There are lots of options for this command. Channels are added in the following format:

channel add #donkeys {

channel set #donkeys +option -option

channel add #horses {

channel set #horses +option -option

All the different options and channels settings are shown in the examples in the config file. Make sure you remove the example entries for #lamest and #botcentral.

set nick: this is what you use to specify your bot's nickname. I recommend against using [ ] { } \ character's in the bot's nick, since these can cause problems with some Tcl scripts, but if you'd like to use them, you'll need to precede each of those characters with a backslash in the setting, e.g. if you wanted your bot to have the nick [NiceBot], use set nick "\[NiceBot\]".

set altnick: if you want to use [ ] { } \ characters in the bot's alternate nick, follow the backslash rule described previously.

set servers: you should specify multiple servers in this list, in case the bot is unable to connect to the first server. The format for this list is shown below.

set servers {

Wherever possible, you should use a port other than 6667 (connect to the server and type /motd to see a list of available ports). You should use servers that allow bots (some shells have rules enforcing this), but unless your shell's policy says otherwise you may also wish to use non-bot servers as a backup in case your IRC network has very few bot servers your bot is able to connect to (but place the servers that allow bots at the top of the list).

set use-ison: leave this set to 1, as setting it to 0 will make your bot use the 'trace' command and may get your bot k:lined (banned) from a server.

set strict-host: if this is set to 0, Eggdrop will ignore the tilde in idents starting with ~. Setting it to 1 is a little more secure, but it can be a pain when it comes to user hostmask management. If you're not sure how you should set this, just leave it set to 0.

set server-cycle-wait: by default, Eggdrop waits 60 seconds between connection attempts to servers. This is quite a long time, but it is necessary to prevent 'throttling' on Undernet servers (if a server gets too many connection attempts from a particular host within a short period of time, it will block all connections from that host until there's been a break in connection attempts). If you use Undernet and you're sharing a shell with lots of other bot users, leave this set to 60. Otherwise, it's a good idea to decrease this to something like 20.

set trigger-on-ignore: setting this to 1 diminishes the usefulness of Eggdrop's ignore feature. I recommend you leave it set to 0.

set bounce-bans: setting this to 1 makes the bot remove any bans set by a server.

set bounce-modes: setting this to 1 makes the bot remove any modes set by a server.

set learn-users: this is an important setting that determines how users will be added to your Eggdrop. If set to 1, people can add themselves to the bot by sending 'hello' to it (the user will be added with the flags set in default-flags). If set to 0, users cannot add themselves - a master or owner must add them using the .adduser command.

unbind msg - hello *msg:hello and bind msg - myword *msg:hello: these allow you to change the 'hello' command to something different. Change myword to the name you the hello command you want. If you have learn-users set to 0, this command is only used for when you first introduce yourself to the bot.

unbind msg - ident *msg:ident and unbind msg - addhost *msg:addhost: these lines unbind the ident and addhost commands. You will almost certainly want to rebind the ident command, either by commenting out the unbind line (this will enable the default 'ident' msg command) or by binding it to a new command. It's a good idea to change the command for extra security. To bind it to another command, let's say 'horse', you would add the line bind msg - horse *msg:ident.

set dcc-block: although the example config file recommends you set this to 0 (turbo-dcc), this may cause DCC transfers to abort prematurely. If you'll be using DCC transfers a lot, set this to 1024.

loadmodule uptime: read my uptime module description for a better idea of what this module is for.

Finally, be sure to remove the 'die' commands from the config (there are two of them 'hidden' in various places), or the bot won't start. Once you've finished editing the config file, make sure you rename it to something other than
"eggdrop.conf" if you haven't already. Then, if you edited the config file locally, upload the config file to the directory you installed the bot.

Editing the botchk file

The botchk script and crontab are used to automatically restart the bot if the shell it's on reboots or if the bot process is killed for some other reason. You can find the botchk file in the scripts directory (in the directory you installed the bot to). Newer versions of Eggdrop (from 1.3.24i) have a script included that automatically configures botchk and crontab for you. In telnet, simply switch to the scripts directory and type chmod 700 autobotchk then ./autobotchk -dir /home/botdir -noemail, where /home/botdir is the directory you installed the bot to and is the name you chose for your config file.

Otherwise, you can edit the botchk file and insert the required crontab entry manually. There are only four things you need to set in the botchk file, all of which are pretty self explanatory. Once you've edited the botchk file, you need to add an entry to your crontab. Here's the best method:

1) Your crontab line should look like:

0,10,20,30,40,50 * * * * /home/botdir/scripts/botchk >/dev/null 2>&1

This will run the botchk script every 10 minutes, which checks that the bot is running and restarts it if it isn't. You just need to change the /home/botdir part to the correct path to the bot on your shell (type pwd to show this). Type the line in Notepad or some place where you can highlight and copy it from.

2) Type crontab -e. This should bring up the vi editor (it will appear as a bunch of lines starting with the ~ character), but may open up the pico editor instead.

3) For vi, do the following - hit ctrl-L, hit i, paste the crontab line you created earlier, hit Esc, type :wq! then hit Enter (if you make a mistake doing this, just hit Esc and start over). For pico - paste the crontab line you created earlier, hit ctrl-X, hit Y when prompted to save, hit Enter when prompted for a filename.

You can view your current crontab entries by typing crontab -l. To clear your crontab, use crontab -r (may be crontab -d on some shells).

Starting the Eggdrop

Phew! Now that you've compiled, installed, and configured Eggdrop, it's time to start it up. Switch to the directory to which you installed the bot, cross your fingers, and type ./eggdrop -m <config> (where <config> is the name you gave to the config file). Eggdrop should start up, and the bot should appear on IRC within a few minutes. The -m option creates a new userfile for your bot. In future, you will only need to type ./eggdrop <config> to start the bot.

Once your bot is on IRC, it's important that you promptly introduce yourself to the bot. Msg it the 'hello' command you specified in the config file, e.g. /msg <botnick> hello. This will make you the bot's owner. Once that's done, you need to set a password using /msg <botnick> pass <password>. You can then DCC chat to the bot.

Now that your Eggdrop is on IRC and you've introduced yourself as owner, it's time to learn how to use your Eggdrop.

No show?

If your bot didn't appear on IRC, you should log in to the shell and view or download the bot's logfile (as set in the config file—the default is "logs/eggdrop.log"). Note that logfile entries are not written to disk immediately unless quick-logs is enabled, so you may have to wait a few minutes before the logfile appears, or contains messages that indicate why your bot isn't showing up.

If you're still unsure what the problem is, try asking in #eggdrop on Freenode, and be sure to include any relevant errors from the logfile.