Eggdrop

https://docs.eggheads.org
Admin
Eggdrop is a free, open-source IRC bot designed to manage IRC channels and automate tasks. It is...
Tokens:165,533
Snippets:1,642
Trust Score:9.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: Install Eggdrop to /home/user/otherdir

Source: https://docs.eggheads.org/install/install.html

Example of installing Eggdrop to a custom directory using the DEST variable.

```bash
make install DEST=/home/user/otherdir

```

--------------------------------

### Install a Python package in the .venv

Source: https://docs.eggheads.org/using/python.html

Activates the virtual environment and installs the requests package as an example.

```bash
cd eggdrop && source .venv/bin/activate && pip install requests

```

--------------------------------

### Example: Make LamestBot.conf executable

Source: https://docs.eggheads.org/install/install.html

Example of making a config file executable.

```bash
chmod u+x LamestBot.conf

```

--------------------------------

### Listen port example with control

Source: https://docs.eggheads.org/using/tcl-commands.html

Example of setting up a listen port and the callback that places the new connection under control. The listen:grab proc immediately calls control with the new index.

```tcl
listen 6687 script listen:grab

proc listen:grab {newidx} {
  control $newidx listen:control
}

```

--------------------------------

### Logfile configuration examples

Source: https://docs.eggheads.org/tutorials/setup.html

Examples of logfile lines for bot and channel logs, including specifying a directory for log files.

```tcl
logfile mcobxs * "botnick.log"
```

```tcl
logfile jkp #donkeys "#donkeys.log"
```

```tcl
logfile jkp #horses "#horses.log"
```

```tcl
logfile jkp #donkeys "logs/#donkeys.log"
```

--------------------------------

### Install Eggdrop with make install

Source: https://docs.eggheads.org/install/install.html

Installs Eggdrop into the default directory ~/eggdrop. Run from the Eggdrop directory after configuration and compilation.

```bash
make install

```

--------------------------------

### PUBM bind examples for channel message matching

Source: https://docs.eggheads.org/using/tcl-commands.html

These three bind commands show how to use the PUBM bind to listen for messages on a channel. The first listens on #eggdrop for lines starting with "Hello"; the second listens on any channel for lines starting with "Hello"; the third listens on any channel for a line that contains only "!command". The mask is matched against the channel name followed by the text and can contain wildcards.

```tcl
bind pubm * "#eggdrop Hello*" myProc
```

```tcl
bind pubm * "% Hello*" myProc
```

```tcl
bind pubm * "% !command" myProc
```

--------------------------------

### Run Eggdrop with config file

Source: https://docs.eggheads.org/tutorials/setup.html

Start Eggdrop with the -m flag and a configuration file (e.g., eggdrop-basic.conf or eggdrop.conf).

```bash
./eggdrop -m <config file>
```

--------------------------------

### Install OpenSSL and libssl-dev

Source: https://docs.eggheads.org/tutorials/setup.html

Install OpenSSL and its development library to enable SSL/TLS protection for Eggdrop.

```bash
sudo apt-get install openssl libssl-dev

```

--------------------------------

### Start Eggdrop with -m to create user file

Source: https://docs.eggheads.org/install/install.html

Starts the bot with the -m option to create a user file. Replace LamestBot.conf with your config file name.

```bash
./eggdrop -m LamestBot.conf

```

--------------------------------

### Install Eggdrop to a custom directory with make install DEST

Source: https://docs.eggheads.org/install/install.html

Installs Eggdrop to a specified directory. Use a full path for correct installation.

```bash
make install DEST=<directory>

```

--------------------------------

### Crontab autostart with options

Source: https://docs.eggheads.org/install/readme.html

Crontab example with options: checks every 5 minutes and does not send an email when the bot is restarted.

```bash
./scripts/autobotchk <Eggdrop config file> -noemail -5
```

--------------------------------

### Eggdrop telnet listening message example

Source: https://docs.eggheads.org/tutorials/firststeps.html

Example output from the bot's startup display showing the IP and port for telnet connections. If 0.0.0.0 is shown, the bot listens on all available IPs.

```text
Listening for telnet connections on 2.4.6.9:3183 (all).

```

--------------------------------

### Hub bot listen configuration

Source: https://docs.eggheads.org/tutorials/userfilesharing.html

Example listen configuration for the hub bot, listening on ports +3333 and +4444 for all connections. This is used in the hub bot setup steps.

```text
listen +3333/+4444 all

```

--------------------------------

### Install Tcl and dev packages

Source: https://docs.eggheads.org/tutorials/setup.html

Install Tcl and its development packages on Debian-based systems using apt-get.

```bash
sudo apt-get install tcl tcl-dev

```

--------------------------------

### Set up modules with make config

Source: https://docs.eggheads.org/tutorials/setup.html

Sets up which modules are to be compiled. For a more efficient installation, you can use 'make iconfig' to select modules, but if unsure, use 'make config'.

```bash
make config
```

```bash
make iconfig
```

--------------------------------

### logfile command examples

Source: https://docs.eggheads.org/using/core.html

This setting tells the bot what should be logged, from where, and to which file. The examples show logging to a global logfile and a channel-specific logfile. The flags used are m (private msgs, notices and ctcps to the bot), c (commands), o (misc info, errors, etc), j (joins, parts, quits, and netsplits on the channel), p (public text on the channel), and k (kicks, bans, and mode changes on the channel).

```tcl
logfile mco * "logs/eggdrop.log"
logfile jpk #lamest "logs/lamest.log"
```

--------------------------------

### isupport get [key]

Source: https://docs.eggheads.org/using/tcl-commands.html

Retrieves ISUPPORT settings from the server.

```APIDOC
## isupport get [key]

### Description
- isupport get: Returns a flat key/value list (dict) of settings. - isupport get <key>: Returns the setting's value as a string. Throws an error if the key is not set.

### Module
server

### Parameters
- **key** (string) - Optional - The key to retrieve.

### Returns
- **string or dict** - If key given, returns the value as a string; otherwise returns a dict of all settings.
```

--------------------------------

### server add command examples

Source: https://docs.eggheads.org/tutorials/setup.html

Shows the format for adding multiple servers to the Eggdrop config, including plain, password-protected, IPv6, and SSL connections. Use this to specify fallback servers in case the first is unreachable.

```tcl
server add you.need.to.change.this:6667
server add another.example.com:7000:password
server add [2001:db8:618:5c0:263::]:6669:password
server add ssl.example.net:+6697

```

--------------------------------

### Eggdrop command-line syntax

Source: https://docs.eggheads.org/install/readme.html

Shows the general command-line syntax for starting Eggdrop. The config-file argument is required unless using options that don't need it.

```bash
./eggdrop [options] [config-file]
```

--------------------------------

### manifest.json example for autoscripts package

Source: https://docs.eggheads.org/using/autoscripts.html

Required manifest.json for every autoscripts package. Contains metadata (schema, name, version, description) and user-configurable settings. Note the source example omits a comma after the long_description value, which would make the JSON invalid as shown.

```json
{
  "schema": 1,
  "name": "woobie",
  "version_major": 1,
  "version_minor": 0,
  "description": "An example script to help developers write autoscript packages",
  "long_description": "This is an example script to help understand the autoscript system. Yeah, it doesn't really do anything, but that's besides the point. It could, and that should be enough for anyone"
  "config": {
    "loaded": 0,
    "udef": {
       "myflag": {
          "type": "bool",
          "default": 0,
          "description": "This is an example flag"
       }
    }
  }
}
```

--------------------------------

### Install systemd job with autobotchk -systemd and manage with systemctl --user

Source: https://docs.eggheads.org/tutorials/firststeps.html

Install a systemd job for Eggdrop with autobotchk -systemd, then manage the service with systemctl --user. The reload command executes the Eggdrop '.rehash' command, not '.reload'. Use disable to prevent auto-start and enable to re-enable it.

```bash
./scripts/autobotchk yourEggdropConfigNameHere.conf -systemd

```

```bash
systemctl --user start <botname>.service

```

```bash
systemctl --user stop <botname>.service

```

```bash
systemctl --user reload <botname>.service

```

```bash
systemctl --user disable <botname>.service

```

```bash
systemctl --user enable <botname>.service

```

--------------------------------

### Module start function woobie_start

Source: https://docs.eggheads.org/tutorials/module.html

Called when Eggdrop loads the module. Registers the module and checks for a dependency on Eggdrop 1.8.0 or later.

```c
char *woobie_start(Function *global_funcs)
{
  global = global_funcs;

  /* Register the module. */
  module_register(MODULE_NAME, woobie_table, 2, 1);
  /*                                            ^--- minor module version
   *                                         ^------ major module version
   *                           ^-------------------- module function table
   *              ^--------------------------------- module name
   */

  if (!module_depend(MODULE_NAME, "eggdrop", 108, 0)) {
    module_undepend(MODULE_NAME);
    return "This module requires Eggdrop 1.8.0 or later.";
  }


```

--------------------------------

### NEED bind example: bind need - "% op" needop and bind need - "*" needall

Source: https://docs.eggheads.org/using/tcl-commands.html

Example for the NEED bind. The first line binds the mask "% op" to the proc needop, handling only the op need type. The second line binds the wildcard mask "*" to needall, handling all need types. The '<' characters are part of the source's inline comments.

```tcl
bind need - "% op" needop < handles only need op
bind need - "*" needall   < handles all needs

```

--------------------------------

### Configuration Section - Variables

Source: https://docs.eggheads.org/tutorials/firstscript.html

The configuration section of the GreetScript.tcl example. It defines two variables: pmsg (0 for public, 1 for private) and greetmsg (the greeting message). This section is meant to be edited by users.

```tcl
### Config Section ###
# How would you like the bot to gree users?
# 0 - via public message to channel
# 1 - via private message
set pmsg 0
# What message would you like to send to users when they join?
set greetmsg "Hi! Welcome to the channel!"
### DO NOT EDIT BELOW HERE UNLESS YOU KNOW WHAT YOU ARE DOING! ###

```

--------------------------------

### Start Eggdrop with activated venv

Source: https://docs.eggheads.org/using/python.html

Must be run every time to set the necessary environment variables for proper functionality.

```bash
cd eggdrop && source .venv/bin/activate && ./eggdrop

```

--------------------------------

### Eggdrop startup message for userfile creation mode

Source: https://docs.eggheads.org/tutorials/firststeps.html

Shown when the bot starts in userfile creation mode. It instructs the user to telnet and enter 'NEW' as nickname or use IRC /msg BotNick hello to become the master.

```text
STARTING BOT IN USERFILE CREATION MODE.
Telnet to the bot and enter 'NEW' as your nickname.
OR go to IRC and type:  /msg BotNick hello
This will make the bot recognize you as the master.

```

--------------------------------

### Old server configuration syntax (set servers)

Source: https://docs.eggheads.org/install/upgrading.html

Shows the deprecated 'set servers' syntax used in Eggdrop 1.8 and earlier. Replace this with the 'server add' command as shown in the next example.

```tcl
set servers {
  my.server.com:6667
}
```

--------------------------------

### Make config file executable with chmod u+x

Source: https://docs.eggheads.org/install/install.html

Makes the config file executable so it can be used as a shell script to start the bot. The top line of the script must contain the correct path to the Eggdrop executable.

```bash
chmod u+x <my-config-file-name>

```

--------------------------------

### Set server list with ports and passwords

Source: https://docs.eggheads.org/modules/mod/server.html

Defines the bot's server list. The bot starts at the first server and cycles through on disconnect. Format: server[:port[:password]]. Prefix port with '+' for SSL.

```tcl
set servers {
  you.need.to.change.this:6667
  another.example.com:7000:password
  [2001:db8:618:5c0:263::]:6669:password
  ssl.example.net:+6697
}

```

--------------------------------

### Registering a C callback for DCC bind (cmd_boot example)

Source: https://docs.eggheads.org/modules/internals.html

Shows how to define a C function (cmd_boot) and register it with add_builtins using a cmd_t table. The function signature matches the arguments passed by builtin_dcc: user, idx, and parameter string.

```c
/* We know the return value is ignored because the return value of F
 * in builtin_dcc is ignored, so it can be void, but for other binds
 * it could be something else and used in the C handler for the bind.
 */
void cmd_boot(struct userrec *u, int idx, char *par) { /* snip */ }

cmd_t *mycmds = {
  {"boot", "t", (IntFunc) cmd_boot, NULL /* automatic name: *dcc:boot */},
  {NULL, NULL, NULL, NULL}
};
add_builtins(H_dcc, mycmds);

```

--------------------------------

### Install Eggdrop with make install

Source: https://docs.eggheads.org/tutorials/setup.html

Installs Eggdrop into a directory named 'botdir' in your home directory. 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'.

```bash
make install DEST=~/botdir
```

```bash
make install DEST=/home/cooldude/botdir
```

```bash
pwd
```

--------------------------------

### Generate systemd autostart job

Source: https://docs.eggheads.org/install/readme.html

Generates a systemd job that starts Eggdrop at boot and restarts it if it crashes. Run from the Eggdrop install directory.

```bash
./scripts/autobotchk <Eggdrop config file> -systemd
```

--------------------------------

### Leaf bot listen configuration

Source: https://docs.eggheads.org/tutorials/userfilesharing.html

Example listen configuration for the leaf bot, listening on ports +5555 and +6666 for all connections. This is used in the leaf bot setup steps.

```text
listen +5555/+6666 all

```

--------------------------------

### Make config

Source: https://docs.eggheads.org/tutorials/setup.html

Run make config to set up the build configuration.

```bash
make config
```

--------------------------------

### boot <user@bot> [reason]

Source: https://docs.eggheads.org/using/tcl-commands.html

Boots a user from the partyline.

```APIDOC
## boot <user@bot> [reason]

### Description
Boots a user from the partyline.

### Returns
nothing

### Module
core
```

--------------------------------

### GreetScript.tcl - Full Example

Source: https://docs.eggheads.org/tutorials/firstscript.html

A complete Eggdrop Tcl script that greets users when they join a channel. It includes a configuration section with two settings (pmsg and greetmsg) and a bind join handler. The script sends a greeting either publicly to the channel or privately to the user, depending on the pmsg setting.

```tcl
# GreetScript.tcl
# Version: 1.0
# Author: Geo <geo@eggheads.org>
#
# Description:
# A simple script that greets users as they join a channel
#
### Config Section ###
# How would you like the bot to gree users?
# 0 - via public message to channel
# 1 - via private message
set pmsg 0
# What message would you like to send to users when they join?
set greetmsg "Hi! Welcome to the channel!"
### DO NOT EDIT BELOW HERE UNLESS YOU KNOW WHAT YOU ARE DOING! ###

bind join - * greet

proc greet {nick uhost hand chan} {
  global pmsg
  global greetmsg
  if {$pmsg} {
    putserv "PRIVMSG $nick :$greetmsg"
  } else {
    putserv "PRIVMSG $chan :$greetmsg"
  }
}

putlog "greetscript.tcl v1.0 by Geo"

```

--------------------------------

### Delete installation directory

Source: https://docs.eggheads.org/tutorials/setup.html

Safely deletes the installation directory 'eggdrop-1.10.2' that was created previously. Some people may keep it for future installations without recompiling.

```bash
cd ~
rm -rf eggdrop-1.10.2
```

--------------------------------

### Change to Eggdrop install directory

Source: https://docs.eggheads.org/tutorials/setup.html

Change to the ~/eggdrop directory where Eggdrop was installed.

```bash
cd ~/eggdrop
```

--------------------------------

### Create GREET_BINDS list and append join binds

Source: https://docs.eggheads.org/tutorials/pythonscript.html

Creates the GREET_BINDS list and appends two join binds. The second bind requires the 'o' flag to trigger. Arguments are separated with commas.

```python
GREET_BINDS = list()
GREET_BINDS.append(bind("join", "*", "*", joinGreetUser))
# Again, arguments are separated with a comma. This bind requires the 'o' flag to be triggered.
GREET_BINDS.append(bind("join", "o", "*", joinGreetOp))

```

--------------------------------

### starttls <idx>

Source: https://docs.eggheads.org/using/tcl-commands.html

Establishes a secure (using TLS) connection over idx. The TLS connection should be first negotiated over the plaintext link, or using other means. Both parties must switch to TLS simultaneously. This command is available on TLS-enabled bots only. Returns nothing.

```APIDOC
## starttls <idx>

### Description
Establishes a secure (using TLS) connection over idx. The TLS connection should be first negotiated over the plaintext link, or using other means. Both parties must switch to TLS simultaneously. This command is available on TLS-enabled bots only.

### Method
Tcl Command

### Parameters
- **idx** (integer) - Required - The connection index to establish TLS on.

### Returns
Nothing.

### Module
core
```

--------------------------------

### Install OpenSSL and libssl-dev

Source: https://docs.eggheads.org/tutorials/tlssetup.html

Install OpenSSL and its development headers on Debian/Ubuntu. Both packages are required for TLS support in Eggdrop.

```bash
apt-get install openssl libssl-dev

```

--------------------------------

### Set up an SSL port with plus sign

Source: https://docs.eggheads.org/using/core.html

Prepend a plus sign to the port number to set up an SSL port.

```tcl
listen +5555 all
```

--------------------------------

### Generate SSL certificates for custom install directory

Source: https://docs.eggheads.org/install/install.html

Generates SSL certificates when Eggdrop was installed to a different directory. Use the DEST variable to specify the directory.

```bash
make sslcert DEST=<directory>

```

--------------------------------

### File and directory settings: userfile, pidfile, help-path, text-path, motd, telnet-banner, userfile-perm, mod-path

Source: https://docs.eggheads.org/using/core.html

Configuration directives for Eggdrop file and directory paths. userfile specifies the userfile filename. pidfile specifies the pid file; if not set, pid.(botnet-nick) is used. help-path and text-path specify directories for help and text files. motd and telnet-banner specify files for messages. userfile-perm sets permissions for user, channel, and notes files (default 0600). mod-path specifies the module directory.

```tcl
set userfile "LamestBot.user"
```

```tcl
set pidfile "pid.LamestBot"
```

```tcl
set help-path "help/"
```

```tcl
set text-path "text/"
```

```tcl
set motd "text/motd"
```

```tcl
set telnet-banner "text/banner"
```

```tcl
set userfile-perm 0600
```

```tcl
set mod-path "modules/"
```

--------------------------------

### Set hourly-updates to 15

Source: https://docs.eggheads.org/using/core.html

Example: saves userfile 15 minutes past every hour.

```tcl
set hourly-updates 15
```

--------------------------------

### starttls

Source: https://docs.eggheads.org/using/tcl-commands.html

Switches an active connection to SSL. The script must first inform the other side of the connection that it wants to switch to SSL.

```APIDOC
## starttls

### Description
Switches an active connection to SSL. This can be used after a connection is already established. The script must first inform the other side of the connection that it wants to switch to SSL; the method is application specific.

### Method
Command

### Endpoint
starttls <idx>

### Parameters
- **idx** (integer) - Required - The DCC connection index to switch to SSL.

### Behavior
- The connection must be active.
- The script must coordinate the SSL switch with the remote side.
```

--------------------------------

### Botnet diagram after initial setup

Source: https://docs.eggheads.org/using/botnet.html

Diagram of the two-bot botnet with Lamestbot as hub and Lameshare as a leaf.

```text
Lamestbot
  `-+Lameshare

```

--------------------------------

### Configure Eggdrop build

Source: https://docs.eggheads.org/tutorials/setup.html

Run the configure script to prepare the build.

```bash
./configure
```

--------------------------------

### Install crontab job with autobotchk and verify with crontab -l

Source: https://docs.eggheads.org/tutorials/firststeps.html

Run autobotchk to install a crontab job that restarts Eggdrop every ten minutes. Verify the entry with crontab -l; the default entry runs the generated botchk script every ten minutes. If autobotchk is run from the scripts directory, specify the config file location with the -dir option.

```bash
./scripts/autobotchk yourEggdropConfigNameHere.conf

```

```bash
crontab -l

```

```cron
0,10,20,30,40,50 * * * * /home/user/bot/scripts/YourEggdrop.botchk 2>&1

```

--------------------------------

### Add a User with .+user

Source: https://docs.eggheads.org/tutorials/firststeps.html

Adds a user to the bot. Replace <handle> with the desired handle for the user.

```text
.+user <handle>

```

--------------------------------

### Set userfile and chanfile using variables

Source: https://docs.eggheads.org/using/tricks.html

Uses Tcl variables to set the 'userfile' and 'chanfile' config options to 'yourbot.user' and 'yourbot.chan'. This works because the config file is a normal Tcl file.

```tcl
set myvar "yourbot"
set userfile "$myvar.user"
set chanfile "$myvar.chan"

```

--------------------------------

### Set default-flags to hp

Source: https://docs.eggheads.org/using/core.html

Flags that all new users get by default. See '.help whois' for flag descriptions.

```tcl
set default-flags "hp"
```

--------------------------------

### Non-interactive SSL certificate generation with make sslsilent

Source: https://docs.eggheads.org/install/install.html

Generates a key and certificate non-interactively, useful for scripts installing Eggdrop.

```bash
make sslsilent

```

--------------------------------

### Connect to the bot using OpenSSL s_client

Source: https://docs.eggheads.org/using/tls.html

Use this command to connect to your bot from the command line using the key and certificate generated in the previous step. Replace host and sslport with your bot's address and TLS port.

```bash
openssl s_client -cert my.crt -key my.key -connect host:sslport

```

--------------------------------

### Basic Eggdrop Python script: greet users on join

Source: https://docs.eggheads.org/tutorials/pythonscript.html

Complete example script that greets users on join. It imports bind and putmsg, defines two handler functions, unbinds any previous binds on reload, and registers new join binds. Requires Eggdrop with the Python module and the .python commands enabled for loading via .pysource.

```python
from eggdrop import bind
from eggdrop.tcl import putmsg

def joinGreetUser(nick, host, handle, channel, **kwargs):
  putmsg(channel, f"Hello {nick}, welcome to {channel}")

def joinGreetOp(nick, host, handle, channel, **kwargs):
  putmsg(channel, f"{nick} is an operator on this channel!")

if 'GREET_BINDS' in globals():
  for greetbind in GREET_BINDS:
    greetbind.unbind()
  del GREET_BINDS

GREET_BINDS = list()
GREET_BINDS.append(bind("join", "*", "*", joinGreetUser))
GREET_BINDS.append(bind("join", "o", "*", joinGreetOp))

print('Loaded greet.py')

```

--------------------------------

### Declare global function tables

Source: https://docs.eggheads.org/tutorials/module.html

Declares the global function pointers and exports the start function. This is required for the module to function.

```c
#undef global
static Function *global = NULL, *server_funcs = NULL;
EXPORT_SCOPE char *woobie_start();

```

--------------------------------

### Set dcc-flood-thr to 3

Source: https://docs.eggheads.org/using/core.html

Number of lines from a user on the partyline within 1 second before they are considered flooding and get booted.

```tcl
set dcc-flood-thr 3
```

--------------------------------

### unames

Source: https://docs.eggheads.org/using/tcl-commands.html

Returns the current operating system the bot is using.

```APIDOC
## unames

### Description
Returns the current operating system the bot is using.

### Module
core

### Returns
Operating system string.
```

--------------------------------

### Get TLS certificate fingerprint

Source: https://docs.eggheads.org/tutorials/firststeps.html

Computes the SHA-1 fingerprint of the TLS certificate. The output is used to add the certificate to NickServ.

```bash
openssl x509 -in eggdrop.crt -outform der | sha1sum -b | cut -d' ' -f1
```
Tokens:
Raw