Eggdrop Documentation: Eggdrop core

Eggdrop core

This is an exhaustive list of all the Tcl commands added by eggdrop. All of the normal Tcl built-in commands are still there, of course. But you can also use these to manipulate features of the bot. Please see the module files for TCL commands relating to each module.

NOTICE: This list is accurate for the v1.6 series of eggdrop!

Scripts which were written for earlier versions will probably not work without modification. Some, however can be made to work using the compat.tcl distributed with eggdrop.

Contents

Configuration settings

Executable path

Basic settings

Log files

Files and directories

Botnet, dcc and network

Console

Common stuff

Modules

Scripts

Output commands

User record manipulation Commands

DCC commands

Miscellaneous commands

Global variables

Command extension

Return values

Matching characters

1. Configuration settings

Lines in bold are the lines that need to be included in the eggdrop config file if you want to use the share module.
Lines in bold italics are optional and only required if you wish to change the default behaviour for that particular feature.

1a. Executable path

The first line in eggdrop configuration file should contain a full qualified path to eggdrop executable. It has to be implemented in the way the example shows to make the config file work as a shell script

Example:

#! /path/to/eggdrop

1b. Basic settings

You can change the basic eggdrop appearence and behaviour in this section.

set username "lamest"

This setting defines the username the bot uses.

Note that this setting works only if no ident daemon is running on the machine your bot is on.

set admin "Lamer <email: lamer@lamest.lame.org>"

This setting defines which contact person should be shown in .status, /msg help and other places. You really should include this info.

set network "SomeIrcNetwork"

This setting is used only for info to share with others on your botnet.

set timezone "EST"

This setting defines the timezone is your bot in. It's used for internal routines as well as for logfile timestamping or scripting purposes. The timezone string specifies the name of the timezone and must be three or more alphabetic characters.

ex. Central European Time(UTC+1) could be "CET"

set offset "5"

offset specifies the time value to be added to the local time to get Coordinated Universal Time (UTC aka GMT). The offset is positive if the local timezone is west of the Prime Meridian and negative if it is east. The value(hours) must be between 0 and 24

ex. if the timezone is UTC+1 the offset is -1

set env(TZ) "$timezone $offset" (disabled by default)

If you dont want to use the timezone setting for scripting purpose only but instead everywhere possible then use this setting.

addlang "english"

If you want to have your eggdrop messages displayed in another language change the below command to match your preferences. An alternative would be to set the environment variabel EGG_LANG to that value.

1c. Log files

Eggdrop is capable of logging various stuff, from channel chatter to commands people use on the bot or file transfers.

Logfiles are kept normaly for 24 hours. Afterwards they'll be renamed to "(logfilename).yesterday". After 48 hours they'll get overwritten by the logfile of the next day.

set max-logs 5

maximum number of logfiles to allow - this can be increased if needed

(don't decrease this)

set max-logsize 0

maximum size of your logfiles, set this to 0 to disable. This value is in KiloBytes, so '550' would mean cycle logs when it reaches the size of 550 KiloBytes.

Note that this only works if you have keep-all-logs 0

set quick-logs 0

Defaultly eggdrop writes every 5 minutes its logfiles to disk. You can change this behaviour by turning this setting to 1. Eggdrop will write and check the logfiles for size every minute.

Note that this setting might increase the cpu usage of your bot (on the other hand it will decrease your mem usage)

logfile <logflags> <channel> "logs/logfile"

This setting actually tells the bot what should be loged from where in which file.

The most common log file flags are:

m private msgs/ctcps to the bot
k kicks, bans, mode changes on the channel
j joins, parts, netsplits on the channel
p public chatter on the channel
s server connects/disconnects/notices
b information about bot linking and userfile sharing
c commands people use (via msg or dcc)
x file transfers and file-area commands
r (if use-console-r enabled) EVERYTHING sent to the bot by the server
o other: misc info, errors -- IMPORTANT STUFF
w wallops: msgs between IRCops (be sure to set the bot +w in init-server)

There are others, but you probably shouldnt log them, it'd be rather unethical ;). There are also five user-defined levels ('1'..'5') which are used by Tcl scripts.

Each logfile belongs to a certain channel. Events of type 'k', 'j', and 'p' are logged to whatever channel they happened on. Most other events are currently logged to every channel. You can make a logfile belong to all channels by assigning it to channel "*".

Examples:

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

In 'eggdrop.log' put private msgs/ctcps, commands, misc info, and errors from any channel
In 'lame.log' put joins, parts, kicks, bans, public chatter and mode changes from #lamest

set log-time 1

Use this feature to timestamp entries in the log file.

Valid settings are 0 and 1.

set keep-all-logs 0

If you want to keep your logfiles forever turn this setting on. All logfiles will get suffix ".[day, 2 digits][month, 3 letters][year, 4 digits]" Note that your quota might get full by this, so check your logfiles often and download them.

Valid settings are 0 and 1.

set switch-logfiles-at 300

You can specify in this setting, when eggdrop should switch the logfiles and started fresh.

You have to use military time in here. 300 is default and describes 00:00.

Note that a leading 0 will make Tcl think this is an octal value, something you probably don't want.

set quiet-save 0

Those nasty "Writing user file..." and "Writing channel file ..." messages wont be logged anymore if this option is enabled.

Valid settings are 0 and 1.

1d. Files and directories

set userfile "LamestBot.user"

Specify here how your userfile should be called

set sort-users 0

If you want your userfile to be sorted on save, turn this feature on.

Note that this takes a bit more cpu

Valid settings are 0 and 1.

set help-path "help/"

Specify here where eggdrop should look for help files. Don't modify this setting until you know what you're doing!

set temp-path "/tmp"

Set here a place to store temporarily files

set motd "text/motd"

The MOTD (motto of the day) is displayed when people dcc chat or telnet to the bot.

Look into doc/settings.motd or type '.help set motd' in DCC CHAT or telnet connection for options.

set telnet-banner "text/banner"

This banner will be displayed on telnet connections

set userfile-perm 0600
Specifies what permissions the user, channel and notes (if notes module is loaded) files should be set to.

The octal values are the same as for the chmod system command.

To remind you:
           u  g  o           u  g  o           u  g  o
     0600  rw-------   0400  r--------   0200  -w-------    u - user
     0660  rw-rw----   0440  r--r-----   0220  -w--w----    g - group
     0666  rw-rw-rw-   0444  r--r--r--   0222  -w--w--w-    o - others
Note that the default 0600 is the most secure one and should only be changed if you need your files for shell scripting or other external applications.
set mod-path "modules/"

This path specifies the path were eggdrop should look for its modules

1e. Botnet, dcc and network

Settings in this section should be unimportant fur you until you deal with botnets (multiple eggdrops conected together to maximize efficency). You should read doc/BOTNET before modifying these settings.

set botnet-nick "LlamaBot" (disabled by default)

If you want to use a differnt nickname on the botnet than you use on IRC (i.e. if you're in an untrusted botnet) set it here.

listen <port> <mode>

The listen command opens a telnet port by which you or other bots can interact with the eggdrop by telneting in.

Valid ports are (as long as you aren't root) >1024.

Valid modes are 'all', 'bots' and 'users'. You can assign special ports for users and bots, or one for all.

Examples:

listen 3333 bots
listen 4444 users

or:

listen 3333 all

There are more options for the listen command in doc/tcl-commands.doc

Note, if you are running more than one bot on the same machine, you will want to space the telnet ports at LEAST 5 apart... 10 is even better.

set remote-boots 2

This setting defines if people can boot users on the eggdrop from other bots in your botnet.

Valid settings are:

0 - allow *no* outside boots
1 - allow boots from sharebots
2 - allow any boots

set share-unlinks 1

This setting prohibits eggdrop to unlink from share bots if an remote bots tells so.

set telnet-flood 5:60

Define here how many telnet connection attempt in how many seconds from the same host constitute a flood.

Attempts:Seconds

set paranoid-telnet-flood 1

If you telnet-flood to apply even to +f users, set this setting to 1

Valid settings are 0 and 1.

set open-telnets 0

If you want people allow to telnet in and type 'NEW' to become a new user, set this to 1. This is similar to 'hello'

Valid settings are 0 and 1.

set protect-telnet 0

This setting will drop telnet connections not matching a known host. It greatly improves protection from IRCOPs, but makes it impossible for NOIRC bots to add hosts or have NEW as a valid login.

Valid settings are 0 and 1.

set stealth-telnets 0

If you don't want eggdrop to identify itself on a telnet connection, set this setting to 1. Eggdrop will display its nickname instead.

Valid settings are 0 and 1.

set use-telnet-banner 0

If you want eggdrop to display a banner when telneting in set this setting to 1. The telnet banner is set by 'telnet-banner'.

set dcc-sanitycheck 1

This setting will make the bot ignore DCC chat requests which appear to have bogus information on the grounds that the user may have been trying to make the bot connect to somewhere that will get it into trouble, or that the user has a broken client (like mIRC tends to do), in which case the connect wouldn't work anyway. It's suggested that you turn this on.

Valid settings are 0 and 1.

set quiet-reject 1

If set to 1, the bot will squelch the error message when rejecting a DCC CHAT or SEND.

Normally eggdrop tells the DCC user that the CHAT or SEND has been rejected because they don't have access, but sometimes IRC server operators detect bots that way.

set max-dcc 50

Set here the maximum number of dcc connections you will allow - you can increase this later, but never decrease it.

set require-p 0

Define here if +o user still need the +p flag to dcc the bot.

Valid settings are 0 and 1.

set dcc-flood-thr 3

Specify here the number of lines from a user on the partyline (dcc, telnet) before they are considered to be flooding (and therefore get booted)

set resolve-timeout 15

Set here the amount of seconds before giving up on hostname/address lookup. (you might want to increase this if you are on a slow network).

set ident-timeout 5

Set a timeout in seconds how long to wait on ident-lookups.

set connect-timeout 15

This settings defines a timeout in seconds how long the bot should wait for a dcc chat, telnet, relay, etc connection.

set my-hostname "virtual.host.com"

set my-ip "99.99.0.0"

If you're using virtual hosting (your machine has more than 1 IP), you may want to specify the particular IP to bind to. You can specify either by hostname or by IP. You may also want to set the hostname here if eggdrop has trouble detecting it when it starts up.

set firewall "host:port"

Set this to your socks host if your eggdrop sits behind a firewall

Example:

set firewall "proxy:178"

If you use a Sun "telnet passthru" firewall, use this setting:

Example:

set firewall "!sun-barr.ebay:3666"

set nat-ip "127.0.0.1"

If you have a NAT firewall (you box has an IP in one of the following ranges: 192.168.0.0-192.168.255.255, 172.16.0.0-172.31.255.255, 10.0.0.0-10.255.255.255 and your firewall transparently changes your address to a unique address for your box.) or you have IP masquerading between you and the rest of the world, and /dcc chat,/ctcp chat or userfile shareing aren't working. Enter your outside IP here.

Do not enter anything for my-ip or my-hostname if you use this setting.

set reserved-portrange 2010:2020

If you want all your dcc file transfers bound to a particular portrange, either because your behind a firewall, or for other security reasons, set it here.

set dcc-portrange 1024:65535

This setting is so that people can't send fake ports to your bot when they try to dcc it. irc clients should never use a port below 1024 and well 65535 is the highest port possible. this setting is used for telnet too.

set dupwait-timeout 5

If your eggdrop rejects bots that actually have already disconnected from another hub, but the disconnect information has not yet spread over the botnet due to lag, use this setting.

The bot will wait dupwait-timeout seconds before it checks again and then finally reject the bot.

1f. Console

set console "mkcobxs"

This is the default console mode. It uses the same event flags as the log files do.

Note that the console channel is automatically set to your "primary" channel (the one you defined first in config file)

Masters can change their console channel and modes with the '.console' command

1g. Common stuff

set ignore-time 15

Set the time in minutes how long temporary ignores should last

set hourly-updates 00

Define here what eggdrop calls 'hourly'. All calls to it, including such things as note notifying or userfile saving are affected by this.

Example:

set hourly-updates 15

Bot will save 15 minutes past every hour its userfile

set owner "MrLame, MrsLame"

Put all permanent owner into this variable.

set default-flags "hp"

Enter all flags that new users should get as a default.

set whois-fields "url birthday"

Enter all user-defined fields that should be displayed in a '.whois' This will only be shown if the user has one of these xtra fields.

You might prefer to comment this out and use the userinfo1.0.tcl script which provides commands for changing all of these.

set die-on-sighup 0

Enable this setting if you want your eggdrop on receiving a SIGHUP. Otherwise eggdrop will just rehash.

Valid settings are 0 and 1.

set die-on-sigterm 0

Enable this setting if you want your eggdrop on receiving a SIGTERM. Otherwise eggdrop will just save its userfile.

Valid settings are 0 and 1.

set must-be-owner 0

If you enable this setting, only permanent owners (owner setting) will be able to use .tcl and .set moreover if you want only let permanent owners use .dump, then set it to 2 Valid settings are 0, 1 and 2

set enable-simul 1

Enable this setting, if you want to enable the 'dccsimul' tcl command

Valid settings are 0 and 1.

set allow-dk-cmds 1

Enable this setting, if you want +d & +k users to use commands bound as -|-

Valid settings are 0 and 1.

1h. Modules

After the core settings you should start loading any modules you need. Modules are loaded by the command "loadmodule module". Eggdrop looks for modules in the directory you specified by the module-path setting in the path section.

Documentation and a list of all modules can be found in doc/modules directory

Please note, that for different configurations different modules are needed.

Channel security bot

This bot needs channel, console, dns, irc and if you like ctcp module loaded. More is not needed and makes the bot slower.

Public bot

A public bot should have all modules available loaded since they provide all functions for everybody.

Secure filesys bot

This bot needs all normal irc operating modules but not notes, seen, ctcp or share module.

Limbo bot

A limbo bot (bot serves as a botnet hub outside irc) just needs channels, console, dns and maybe notes or share module loaded. Of course blowfish needs to be loaded here, too.

1i. Scripts

Script section should be placed at the end of the config file. All modules should be loaded and their variables should be set at this point.

source scripts/script.tcl

This line loads script.tcl in the scripts directory of your eggdrop. All script should be put there, although you can place them where you like as long as you can supply a fully qualified path to them.

Some commonly loaded scripts are alltools.tcl and action.fix.tcl.

The aproperiate source lines are:

source scripts/alltools.tcl
source scripts/action.fix.tcl

2. Output commands

putlog <text>

sends text to the log for any channel, marked as 'misc' (o);

returns: nothing

putcmdlog <text>

sends text to the log for any channel, marked as 'command' (c);

returns: nothing

putxferlog <text>

sends text to the log for any channel, marked as 'file-area' (x)

returns: nothing

putloglev <level(s)> <channel> <text>

sends text to the log, tagged with all of the valid levels given (use "*" to indicate all log levels)

returns: nothing

dumpfile <nick> <filename>

dumps out a file from the help/text directory to a user on IRC via msg (one line per msg); the user has no flags, so the flag bindings won't work within the file.

3. User record manipulation commands

countusers

returns: number of users in the bot's database

validuser <handle>

returns: "1" if a user by that name exists; '0' otherwise

finduser <nick!user@host>

finds the user record which most closely matches the given user@host

returns: the handle found, or "*" if none

userlist [flags]

returns: a list of the handles of users on the bot. You can use the new flag matching system here.

Example:

[global]{&/|}[chan]{&/|}[bot]
matches the flags relevantly, (chan matches vs anywhere), & specifies an and match, | specifies or, only the first of these is relevant, the default is or.

passwdok <handle> <pass>

checks the password given against the user's password -- if the user has not set a password, will always return "1"; check against the password "" (a blank string) to find out if a user has no password set

returns: "1" if password matches for that user; "0" if not

getuser <handle> <entry-type> [extra info]

This is a generic interface to the new generic userfile support, it return info specific to each entry-type.

Valid entry types are:

BOTFL

returns the current bot-specific flags for the user (if it's a bot :)

BOTADDR

(another bot-only thing :) returns a list containing the bots address, the bots telnet port, and it's relay port.

HOSTS

returns a list of the host for the user

LASTON

returns a list containing the unixtime last seen, and the last seen place.

LASTON #channel

returns the time last seen on the channel or 0 if no info

INFO

returns the user's global info line

COMMENT

returns the master-visible only comment for the user

EMAIL

returns the users email address

URL

returns the users url address

XTRA

returns xtra info, use the form:
getuser <handle> XTRA <key>
to receive data set for a certain key

setuser <handle> <entry-type> [extra info]

This is the counterpart of getuser, it lets you set the various values extra ones not supported about:

PASS

use this to set a users password (no 3rd arg will clear it)

HOSTS

for setting hosts, no extra info = clear, otherwise *1* hostmask is added

LASTON

sets global laston time, will also set laston time for any channel the user has a chanrec for (if it matches) to prevent setting a channel time from ALSO setting the global time use LASTON time #channel *

XTRA

in the form:
setuser <handle> XTRA <key> <data>
sets up to 500 bytes of data per key (use no data to clear)

chnick <old-handle> <new-handle>

changes a user's handle

returns: "1" on success; "0" if the handle is already used, the handle is invalid, or the user can't be found

chattr <handle> [changes [channel]]

changes the attributes for a user record, if you include any -- changes are of the form "+f", "-o", "+dk", "-o+d", etc; if a channel is specified, the channel-specific flags for that channel are altered you can now use the +o|-o #channel format here too.

returns: new flags for the user (if you made no changes, returns current flags); if a channel was specified, the channel-specific flags for that channel are returned -- returns "*" if that user does not exist

matchattr <handle> <flags> [channel]

returns: "1" if the specified user has the matching flags. (using the new matching system)

adduser <handle> <hostmask>

creates a new user entry with the handle and hostmask given (with no password, and the default flags)

returns: "1" if successful, "0" if it already existed

deluser <handle>

attempts to erase a user record with that handle

returns: "1" if successful, "0" if no such user exists

delhost <handle> <hostmask>

deletes a hostmask from a user's hostmask list

returns: "1" on success, "0" if that hostmask wasn't in the list or the user does not exist

newignore <hostmask> <creator> <comment> [lifetime]

adds an entry to the ignore list; creator is given credit for the ignore; lifetime is how many minutes until the ignore expires and is removed; if lifetime is not specified, ignore-time (usually 60) is used; setting the lifetime to 0 makes it a permanent ignore

returns: nothing

killignore <hostmask>

removes an entry from the ignore list

returns: "1" if successful, "0" otherwise

ignorelist

returns: list of ignores; each entry is itself a list, containing: hostmask, comment, expiration timestamp, time added, and creator (the three timestamps are in unixtime format)

isignore <hostmask>

returns: "1" if the ignore is in the list, "0" otherwise

save

writes the userfile to disk

returns: nothing

reload

loads the userfile from disk (replacing whatever's in memory)

returns: nothing

backup

makes a simple backup of the userfile that's on disk

returns: nothing

getting-users

returns: "1" if the bot is currently downloading a userfile from a sharebot (and hence, user records are about to drastically change), "0" if not

4. DCC commands

putdcc <idx> <text>

sends text to the dcc user indicated

returns: nothing

dccbroadcast <message>

sends your message to everyone on the party line on the bot net, in the form "*** <message>" for local users, and "*** [Bot] <message>" for users on other bots

dccputchan <channel> <message>

sends your message to everyone on a certain channel on the bot net, in a form exactly like dccbroadcast does -- valid channels are 0 thru 99999

returns: nothing

restart

restarts the bot

returns: nothing

rehash

rehashes the bot

returns: nothing

dccsimul <idx> <text...>

simulates text typed in by the dcc user specified -- note that in v0.9, this only simulated commands; now a command must be preceded by a '.' to be simulated

returns: nothing

hand2idx <handle>

returns: the idx (a number greater than or equal to zero) for the user given, if she is on the party line in chat mode (even if she is currently on a channel or in chat off), the file area, or in the control of a script; "-1" otherwise -- if the user is on multiple times, the oldest idx is returned

idx2hand <idx>

returns: handle of the user with that idx

valididx <idx>

returns: "1" if the idx currently exists; "0" if not

botlist

returns: a list of bots currently on the botnet; each item in the list will be a sublist with four elements: bot, uplink, version, sharing status.

bot : the bot's nickname
uptlink : who the bot is connected through
version : its currentnumeric version
sharing : a "+" if the bot is sharing, "-" otherwise

islinked <bot>

returns: "1" if thebot is currently linked, "0" otherwise

getchan <idx>

returns: the current party line channel for a user on the party line -- "0" indicates he's on the group party line, "-1" means he has chat off, and a value from 1 to 99999 is a private channel

setchan <idx> <channel>

sets a party line user's channel rather suddenly (the party line user is not notified that she is now on a new channel); a channel name can be used (provided it exists.

returns: nothing

console <idx> [channel] [console-modes]

changes a dcc user's consolemode, either to an absolute mode (like "mpj") or just adding/removing flags (like "+pj" or "-moc" or "+mp-c"); the user's console channel view can be changed also (as long as the new channel is defined in the bot)

returns: a list containing the user's (new) channel view, and (new) console mode, or nothing if that user isn't currently in dcc chat

echo <idx> [status]

turns a user's echo on or off; the status has to be a 1 or 0

returns: new value of echo for that user (or the current value, if status was omitted)

killdcc <idx>

kills a party-line or file area connection, rather abruptly

returns: nothing

dccused

returns: number of dcc connections currently in use

dcclist

returns: list of active dcc connections that are in the chat area, the file area, or a script; each item in the list will be a sublist with four elements: idx, nickname, hostname, and type; type will be "chat", "files", "bot", "file_receiving", "file_sending", "file_send_pending", or "script" (or "socket" for connections that haven't been put under 'control' yet) or any new dcc type that gets added.

getdccidle <idx>

returns: number of seconds the dcc chat/file system/script user has been idle

getdccaway <idx>

returns: away message for a dcc chat user (or "" if the user is not set away)

setdccaway <idx> <message>

sets a party line user's away message and marks them away; if set to "", the user is marked un-away

returns: nothing

connect <host> <port>

makes an outgoing connection attempt and creates a dcc entry for it; a 'control' command should be used immediately after a successful 'connect' so no input is lost

returns: idx of the new connection

listen <port> <type> [options] [flag]

opens a listening port to accept incoming telnets; type must be one of "bots", "all", "users", "script", or "off":

listen <port> bots [mask]

accepts connections from bots only; the optional mask is used to identify permitted bot names; if the mask begins with '@' it is interpreted to be a mask of permitted hosts to accept connections from

returns: port #

listen <port> users [mask]

accepts connections from users only (no bots); the optional mask is used to identify permitted nicknames; if the mask begins with '@' it is interpreted to be a mask of permitted hosts to accept connections from

returns: port #

listen <port> all [mask]

accepts connections from anyone; the optional mask is used to identify permitted nicknames/botnames; if the mask begins with '@' it is interpreted to be a mask of permitted hosts to accept connections from

returns: port #

listen <port> script <proc> [flag]

accepts connections which are immediately routed to a proc; the proc is called with one parameter: the idx of the new connection flag may currently only be 'pub', which makes the bot allow anyone to connect.

returns: port #

listen <port> off

stop listening at a port

returns: nothing

dccdumpfile <idx> <filename>

dumps out a file from the text directory to a dcc chat user; the flag matching that's used everywhere else works here too

link [via-bot] <bot>

attempts to link to another bot directly (or, if you give a via-bot, it tells the via-bot to try

returns: "1" if it looks okay and it will try; "0" if not

unlink <bot>

attempts to remove a bot from the botnet

returns: "1" if it will try or has passed the request on; "0" if not

encrypt <key> <string>

returns: encrypted string (using blowfish), encoded into ascii using base-64 so it can be sent over the botnet

decrypt <key> <encrypted-base64-string>

returns: decrypted string (using blowfish)

encpass <password>

returns: encrypted string (using blowfish)

md5 <string>

returns: the 128 bits MD5 "message-digest" of the specified string.

5. Miscellaneous commands

bind <type> <attr(s)> <command-name> [proc-name]

adds a new keyword command to the bot; valid types are listed below; the <attr(s)> are the flags that a user must have to trigger this command; the <command-name> for each type is listed below; <proc-name> is the name of the Tcl procedure to call for this command (see below for the format of the procedure call); if the proc-name is omitted, no binding is added -- instead, the current binding is returned (if it's stackable, a list of the current bindings is returned) yes, you can use the new flag binding method here too, and this is where it becomes truely phearful since you may never need to check attr's inside functions again...imagine:

bind pub -o&+o command command_proc

returns: name of the command that was added, or (if proc-name was omitted), a list of the current bindings for this command

unbind <type> <attr(s)> <command-name> <proc-name>

removes a previously-made binding

returns: name of the command that was removed

logfile [<modes> <channel> <filename>]

creates a new logfile, which will log the modes given for the channel listed -- or, if no logfile is specified, just returns a list of logfiles; "*" can be used to mean all channels; you can also change the modes and channel of an existing logfile with this command -- entering a blank mode and channel makes the bot stop logging there

returns: filename of logfile created, or (if no logfile is specified) a list of logfiles like: "{mco * eggdrop.log} {jp #lame lame.log}"

maskhost <nick!user@host>

returns: hostmask for the string given ("n!u@1.2.3.4" -> "*!u@1.2.3.*", "n!u@lame.com" -> "*!u@lame.com", "n!u@a.b.edu" -> "*!u@*.b.edu")

unixtime

returns: a long integer which is the current time according to unix

strftime <formatstring> [time]

returns: a formatted string of time using standard strftime format, uses the value of time, or now if no time specified

ctime <unixtime>

returns: a string of the date/time represented by the unix time given (i.e. "Fri Aug 3 11:34:55 1973")

myip

returns: a long number representing the bot's IP address, as it might appear in (for example) a DCC request

rand <limit>

returns: a random integer between 0 and limit-1

die [reason]

causes the bot to log a fatal error and exit completely; if no reason is given, "EXIT" is used

unames

returns: the current operating system the bot is using.

6. Global variables

(All config-file variables are global too, but these variables are set by the bot.)

version

current bot version (ie: "1.1.2+pl1 1010201 pl1"); first item is the text version, second item is a numerical version, and any following items are the names of patches that have been added

numversion

current numeric bot version (ie: "1010201")

Numerical version is "MMNNRRPP" where:

MM is the major release number
NN is the minor release number
RR is the sub-release number
PP is the patch level for that sub-release

uptime

unixtime value for when the bot was started

lastbind

The last command binding which triggered. This allows you to identify which command triggered a tcl routine.

7. Command extension

You can use the 'bind' command to attach Tcl procedures to certain events. For example, you can write a Tcl procedure that gets called every time a user says "danger" on the channel. The following is a list of the types of bindings, and how they work. Under each binding type is the format of the bind command, the list of arguments sent to the Tcl proc, and an explanation.

Some bindings are marked as "stackable". That means that you can bind multiple commands to the same trigger. Normally, for example, a binding of "bind msg - stop msg_stop" (which makes a msg-command "stop" call the Tcl proc "msg_stop") will overwrite any previous binding you had for the msg-command "stop". With stackable bindings, like 'msgm' for example, you can bind to the same command or mask again and again. When the binding is triggered, ALL the Tcl procs that are bound to it will be called, one after another.

To remove a binding, use "unbind". For example, to remove that binding for the msg-command "stop", use "unbind msg - stop msg_stop".

There are more bindings which are enabled from the loading of specific modules, see the specific module information pages to see which module provides which bindings.

DCC

bind dcc <flags> <command> <proc>
proc-name <handle> <idx> <args>

used for commands from a dcc chat on the party line; as in MSG, the command is the first word and everything else is the argument string; the idx is valid until the user disconnects; after that it may be reused, so be careful about storing an idx for long periods of time

BOT

bind bot <flags> <command> <proc>
proc-name <from-bot> <command> <args>

triggered by a message coming from another bot in the botnet; works similar to a DCC binding; the first word is the command and the rest becomes the argument string; flags are ignored

CHON (stackable)

bind chon <flags> <mask> <proc>
proc-name <handle> <idx>

when someone first enters the "party-line" area of the bot via dcc chat or telnet, this is triggered before they are connected to a chat channel (so yes, you can change the channel in a 'chon' proc); mask matches against handle; this is NOT triggered when someone returns from the file area, etc

CHOF (stackable)

bind chof <flags> <mask> <proc>
proc-name <handle> <idx>

triggered when someone leaves the party line to disconnect from the bot; mask matches against the handle; note that the connection may have already been dropped by the user, so don't send output to that idx

CHAT (stackable)

bind chat <flags> <mask> <proc>
proc-name <nick> <channel#> <text>

when someone says something on the botnet, it invokes this binding; flags is ignored; nick could be a user on this bot (i.e. "DronePup") or on another bot (i.e. "Eden@Wilde"); the mask is checked against the text

LINK (stackable)

bind link <flags> <mask> <proc>
proc-name <botname> <via>

triggered when a bot links into the botnet; botname is the name of the bot that just linked in; via is the bot it linked through; the mask is checked against the bot that linked; flags is ignored

DISC (stackable)

bind disc <flags> <mask> <proc>
proc-name <botname>

triggered when a bot disconnects from the botnet for whatever reason; just like the link bind, flags are ignored; mask is checked against the nickname of the bot that left

FILT (stackable)

bind filt <flags> <mask> <proc>
proc-name <idx> <text>

DCC party line and file system users have their text sent through filt before being processed; if the proc a blank string, the text is considered parsed; otherwise the bot will use the text returned from the proc and continue parsing that

ACT (stackable)

bind act <flags> <mask> <proc>
proc-name <nick> <channel#> <action>

when someone does an action on the botnet, it invokes this binding; flags is ignored; the mask is checked against the text of the action (this is very similar to the CHAT binding)

BCST (stackable)

bind chat <flags> <mask> <proc>
proc-name <bot> <channel#> <text>

when a bot says something on the botnet, it invokes this binding; flags is ignored; the mask is checked against the text

CHJN (stackable)

bind chat <flags> <mask> <proc>
proc-name <bot> <nick> <channel#> <flag><sock> <from>

when someone joins a botnet channel, it invokes this binding; flags is ignored; the mask is checked against the text

CHPT (stackable)

bind chat <flags> <mask> <proc>
proc-name <bot> <nick> <sock> <chan>

when someone parts a botnet channel, it invokes this binding; flags is ignored; the mask is checked against the channel

TIME (stackable)

bind time - <mask> <proc>
proc-name <min> <hour> <day> <month> <year>

allows you to schedule procedure calls at certain times, mask matches 5 space seperated integers of the form: "min hour day month year"

AWAY (stackable)

bind away - <mask> <proc>
proc-name <bot> <idx> <msg>

triggers when a user goes away or comes back on the botnet (msg == "" when returning)

LOAD (stackable)

bind load - <mask> <proc>
proc-name <module>

triggers when a module is loaded.

UNLD (stackable)

bind unld - <mask> <proc>
proc-name <module>

triggers when a module is unloaded.

NKCH (stackable)

bind nkch - <mask> <proc>
proc-name <oldnick> <newnick>

triggered whenever a local users nick is changed (in the userfile)

EVNT (stackable)

bind evnt - <type> <proc>
proc-name <type>

triggered whenever one of these events happens. valid events are:

sighup

called on a kill -HUP <pid>

sigterm

called on a kill -TERM <pid>

sigill

called on a kill -ILL <pid>

sigquit

called on a kill -QUIT <pid>

save

called when the userfile is saved

rehash

called just after a rehash

prerehash

called just before a rehash

logfile

called when the logs are switched daily

8. Return values

Several bindings pay attention to the value you return from the proc (using "return $value"). Usually they expect a 0 or 1, and failing to return any value is interpreted as a 0.

Here's a list of the bindings that use the return value from procs they trigger, these bindings are mostly enabled from the loading of specific modules, see the specific module information pages to see which module provides which bindings.

MSG

Return 1 to make the command get logged like so:
(nick!user@host) !handle! command

DCC

Return 1 to make the command get logged like so:
#handle# command

FIL

Return 1 to make the command get logged like so:
#handle# files: command

PUB

Return 1 to make the command get logged like so:
<<nick>> !handle! command

CTCP

Return 1 to ask the bot not to process the CTCP command on its own. Otherwise it would send its own response to the CTCP (possibly an error message if it doesn't know how to deal with it).

FILT

Return 1 to indicate the text has been processed, and the bot should just ignore it. Otherwise it will treat the text like any other.

FLUD

Return 1 to ask the bot not to take action on the flood. Otherwise it will do its normal punishment.

RAW

Return 1 to ask the bot not to process the server text. This can affect the bot's performance (by causing it to miss things that it would normally act on) -- you have been warned.

WALL

Return 1 to make the command get logged liked so:
!nick! msg

9. Matching characters

Many of the bindings allow match characters in the arguments. Here are the four special characters:

? matches any single character
* matches 0 or more characters of any type
% matches 0 or more non-space characters (can be used to match a single word)
~ matches 1 or more space characters (can be used for whitespace between words)

� 1997 Robey Pointer
� 1999,2000 Eggheads