tclscripts/Chanban/README.md

Channel Management

An Eggdrop script for IRC channel management. Provides ops with commands to ban, kick, voice, and manage the bot's internal ban list, with support for automatic ban tracking and multiple languages.

---

Requirements

• Eggdrop 1.8+
• Tcl 8.5+
• msgcat package (included in Tcl's standard library)

---

Installation

1. Copy cmgmt.tcl to your Eggdrop scripts/ directory.
2. Copy the cmgmt_langs/ directory to your Eggdrop scripts/ directory.
3. Add the following line to your Eggdrop configuration file:

source scripts/cmgmt.tcl

4. Rehash or restart your bot.

---

Configuration

All configuration is done at the top of cmgmt.tcl.

Variable	Default	Description
locale	en	Language to use. Must match a file in cmgmt_langs/ (e.g. en, pt_PT, it_IT)
trigger	@	Prefix for public commands
tBanDuration	30	Duration of temporary bans, in minutes
upCommand	curl -s -F file=@- https://x0.at/	Command used to upload the ban list. Must read from stdin
banMask	2	Ban mask type (see mask types below)
protectMasks	*!*@services.ptirc.org	Masks that can never be banned or kicked
noAddNicks	ChanServ NickServ ChanBot	Nicks to ignore when auto-adding bans
noAddMasks	*!*@services.ptirc.org	Masks to ignore when auto-adding bans

Ban Mask Types

Value	Mask format
0	*!user@host
1	*!*user@host
2	*!*@host
3	*!*user@*.host
4	*!*@*.host
5	nick!user@host
6	nick!*user@host
7	nick!*@host
8	nick!*user@*.host
9	nick!*@*.host

---

Commands

All commands require the user to have the o (op) flag on the channel. Commands are available both publicly in the channel (prefixed with the trigger) and privately via /msg to the bot.

Public Commands (in channel)

Command	Description
@ban <nick>	Bans a user from the channel and adds the mask to the bot's ban list
@tban <nick>	Temporarily bans a user for the duration set in tBanDuration
@kick <nick>	Kicks a user from the channel
@voice <nick>	Gives voice (+v) to a user
@devoice <nick>	Removes voice (-v) from a user
@unban <mask>	Removes a ban mask from the channel and the bot's ban list
@banlist	Uploads the bot's ban list for the channel and posts a link
@autoadd <on/off/status>	Enables, disables, or checks the status of automatic ban adding
@opcmds	Lists all available commands

Private Commands (via /msg)

The syntax is the same but requires the channel to be specified as the first argument.

Command	Description
ban <#chan> <nick>	Bans a user from the specified channel
tban <#chan> <nick>	Temporarily bans a user from the specified channel
kick <#chan> <nick>	Kicks a user from the specified channel
voice <#chan> <nick>	Gives voice to a user in the specified channel
devoice <#chan> <nick>	Removes voice from a user in the specified channel
unban <#chan> <mask>	Removes a ban mask from the specified channel
banlist <#chan>	Uploads and sends the ban list for the specified channel
autoadd <#chan> <on/off/status>	Manages automatic ban adding for the specified channel
opcmds <#chan>	Lists all available commands

---

Automatic Ban Tracking

When enabled, the bot automatically mirrors IRC bans (+b modes) into its internal ban list, and removes them when they are unset (-b). This keeps the bot's ban list in sync with the channel's ban list regardless of who sets the bans.

• Bans matching protectMasks or noAddMasks are never added and will be immediately removed if set.
• Bans matching any host belonging to a user with the m, n, or o flag are protected and will be immediately removed.
• Extended bans (masks starting with ~) are tracked separately as EXTBAN entries and marked as sticky.
• Auto-tracking is per-channel and is toggled with @autoadd on/off.
• Op notices (NOTICE @#channel) are sent when bans are automatically added or removed.

---

Language Support

The script uses Tcl's msgcat package for internationalisation. Language files are stored in scripts/cmgmt_langs/ and named by locale (e.g. en.msg, pt_PT.msg, it_IT.msg).

To change the language, set the locale variable in the configuration section to the desired locale code.

Available Languages

Code	Language
en	English
pt	Portuguese (European)
it	Italian

To add a new language, copy en.msg, rename it to the desired locale code, and translate the strings. The %s placeholders must be kept in the same order as described in the comments above each entry.

---

Notes

• The bot will not ban, kick, or devoice users with the o flag or users matching protectMasks.
• If someone tries to use a ban/kick command on the bot itself, the bot will kick them instead.
• The ban list upload requires an external command that reads from stdin. The default uses x0.at. This can be changed via the upCommand variable.
• Extended bans are tracked but not managed by the bot's ban/unban commands — they are handled solely through IRC mode changes.