Eggdrop is a scriptable IRC bot written in Tcl. It sits in one or more channels and can be extended with Tcl scripts to do more or less anything: logging, channel protection, games, relaying, custom commands. Most of the IRC bots running on ShadowShells are eggdrops.

1. Request a port, if you want the party line reachable

Eggdrop has a telnet-based admin interface called the party line, reached by connecting to a port the bot listens on. If you want to reach the party line from outside the shell — rather than only from a local telnet localhost on the box itself — you need a port, and on ShadowShells incoming ports are assigned by the system rather than chosen by you. Request one from the Ports section of the dashboard, and configure the bot to listen on exactly that port (see listen, below). A port you pick yourself will not be reachable from outside.

2. Build eggdrop

The easy way

ss-build-eggdrop

This fetches the eggdrop source, configures and compiles it, and installs it into ~/eggdrop.

The manual way

git clone https://github.com/eggheads/eggdrop.git
cd eggdrop
./configure
make config
make
make install DEST=$HOME/eggdrop

make config generates the module configuration before the real build (use make iconfig instead if you want to be asked interactively about optional modules). Eggdrop needs tcl-dev to compile, which is already installed, along with build-essential.

3. Configure eggdrop.conf

Copy the sample eggdrop.conf that ships with the source into your install directory and edit it. The settings that matter to get running:

set nick "mybot"
set altnick "mybot_"
set username "mybot"
set realname "eggdrop bot"
set servers {
  irc.example.org:6667
}
listen <port> all
set owner "yourhandle"

• set nick / set altnick — the bot's nickname, and a fallback if the first is taken
• set username / set realname — the identd username and the realname field shown in /whois
• set servers — the IRC network and port the bot connects to
• listen <port> all — where the party line listens. This is where your assigned port from step 1 goes; replace <port> with the number the dashboard gave you
• set owner — your handle, which gets full control of the bot from the party line

The bot's userfile, which tracks who has access and at what level, is created automatically the first time it runs. You don't need to create it by hand.

4. First start

The first time you start the bot, use -m so it creates its userfile:

cd ~/eggdrop
./eggdrop -m eggdrop.conf

Then connect to the party line to add yourself as owner:

telnet localhost <port>

At the prompt, type NEW to create an account, choose a handle matching what you put in set owner, and set a password. Once that handle exists, it has full owner access to the bot.

For subsequent starts, drop the -m:

./eggdrop eggdrop.conf

5. Run it under screen or tmux

Like any other long-running program on ShadowShells, start it inside a screen or tmux session so it survives disconnect:

screen -S eggdrop
./eggdrop eggdrop.conf

Detach with Ctrl-A then D. It now runs as a background process and counts against your plan's background process limit — see irssi with screen or tmux for the detaching and reattaching mechanics.

Rules for bots

The Acceptable Use Policy covers bot behaviour explicitly: flooding a network, spamming, or otherwise abusing an IRC network from a ShadowShells bot is treated as a violation by your account, not just the bot. Misconfigured or misbehaving third-party Tcl scripts count too — you're responsible for what your bot does.

Troubleshooting

Bot isn't connecting

Check the log first (below). Common causes: a wrong server address or port in set servers, the network rejecting your bot's nick or ident, or an outgoing connection being blocked somewhere between the box and the network.

Checking the log

Eggdrop logs to a file under its own directory, typically ~/eggdrop/logs/. Tail it while the bot is starting up to see connection attempts and errors as they happen.

Party line not reachable

Confirm the port in your listen line matches the port the dashboard assigned you, and confirm the bot process is actually running (screen -r eggdrop).