diff --git a/Chanban/README.md b/Chanban/README.md index 70ae03b..48528ed 100644 --- a/Chanban/README.md +++ b/Chanban/README.md @@ -1,113 +1,130 @@ -# Channel Management TCL Script for Eggdrop +# Channel Management -## Description -A comprehensive channel management script for Eggdrop bots that provides both public and private commands for banning, temporary banning, kicking, unbanning, and viewing ban lists. +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. -## Features -- Public commands using configurable trigger (!ban, !tban, !kick, !unban, !banlist, !opcmds) -- Private message commands (ban, tban, kick, unban, banlist, opcmds) -- Permanent and temporary bans with configurable duration -- Automatic banmask generation with multiple mask types -- Special handling for uid/sid hosts -- Anti-abuse protection (cannot ban/kick the bot itself) -- Ban list uploads to a configurable file hosting service -- Clean channel output (banlist sent via upload link) -- Proper access control using Eggdrop flags -- Efficient mode queueing with pushmode +--- ## Requirements -- Eggdrop 1.6.x or higher -- curl command-line tool (for ban list uploads) + +- Eggdrop 1.8+ +- Tcl 8.5+ +- `msgcat` package (included in Tcl's standard library) + +--- ## Installation -1. Copy the script to your Eggdrop scripts directory -2. Add the following line to your Eggdrop config file: - source scripts/chanmanagement.tcl -3. Rehash or restart your Eggdrop + +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 variables are at the top of the script: -| Variable | Description | Default | -|----------|-------------|---------| -| trigger | Command trigger character | "!" | -| banReason | Reason for permanent bans | "User has been banned from the channel." | -| tBanReason | Reason for temporary bans | "User has been temporarily banned from the channel." | -| kickReason | Reason for kicks | "Your behaviour is not conducive to the desired environment." | -| revengeKick | Message when someone tries to ban/kick the bot | "Very funny... NOT" | -| tBanDuration | Temporary ban duration in minutes | "30" | -| upCommand | Command used to upload the ban list | "curl -s -F file=@- https://x0.at/" | -| banMask | Banmask type (0-9) | "2" | +All configuration is done at the top of `cmgmt.tcl`. -### Banmask Types -- 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 +| 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 | Syntax | Description | -|---------|--------|-------------| -| ban | !ban \ | Permanently ban a user | -| tban | !tban \ | Temporarily ban a user | -| kick | !kick \ | Kick a user from channel | -| unban | !unban \ | Remove a ban by mask | -| banlist | !banlist | Get link to current ban list | -| opcmds | !opcmds | List available commands | + +| Command | Description | +|---|---| +| `@ban ` | Bans a user from the channel and adds the mask to the bot's ban list | +| `@tban ` | Temporarily bans a user for the duration set in `tBanDuration` | +| `@kick ` | Kicks a user from the channel | +| `@voice ` | Gives voice (+v) to a user | +| `@devoice ` | Removes voice (-v) from a user | +| `@unban ` | 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 ` | Enables, disables, or checks the status of automatic ban adding | +| `@opcmds` | Lists all available commands | ### Private Commands (via /msg) -| Command | Syntax | Description | -|---------|--------|-------------| -| ban | /msg botnick ban <#chan> \ | Permanently ban a user | -| tban | /msg botnick tban <#chan> \ | Temporarily ban a user | -| kick | /msg botnick kick <#chan> \ | Kick a user from channel | -| unban | /msg botnick unban <#chan> \ | Remove a ban by mask | -| banlist | /msg botnick banlist <#chan> | Get link to current ban list | -| opcmds | /msg botnick opcmds <#chan> | List available commands | -## Access Control -Users need either: -- Global +o flag, OR -- Channel +o flag on the specific channel +The syntax is the same but requires the channel to be specified as the first argument. -## Customizing the Upload Service -The upload command is controlled by the `upCommand` configuration variable. The ban list file is piped into the command via stdin, so your command must read from stdin. The default uses x0.at: +| Command | Description | +|---|---| +| `ban <#chan> ` | Bans a user from the specified channel | +| `tban <#chan> ` | Temporarily bans a user from the specified channel | +| `kick <#chan> ` | Kicks a user from the specified channel | +| `voice <#chan> ` | Gives voice to a user in the specified channel | +| `devoice <#chan> ` | Removes voice from a user in the specified channel | +| `unban <#chan> ` | Removes a ban mask from the specified channel | +| `banlist <#chan>` | Uploads and sends the ban list for the specified channel | +| `autoadd <#chan> ` | Manages automatic ban adding for the specified channel | +| `opcmds <#chan>` | Lists all available commands | -``` -variable upCommand "curl -s -F file=@- https://x0.at/" -``` +--- -To use a different service, replace the value with any command that reads from stdin and returns a URL: +## Automatic Ban Tracking -``` -# For termbin.com -variable upCommand "nc termbin.com 9999" +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. -# For your own pastebin -variable upCommand "curl -s -F file=@- https://your-pastebin.com/upload" -``` +- 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. -## Important Notes -- Do not modify code below the configuration section unless you understand TCL -- The script includes protection against banning/kicking the bot itself -- Temporary bans use Eggdrop's internal ban expiration -- Ban lists are uploaded as text files and a link is returned to the user +--- -## Troubleshooting -- "Failed to upload ban list": Check that curl is installed and the upload service is accessible -- Commands not working: Verify the user has appropriate flags (o|o) -- Bot not responding: Ensure the script is loaded and binds are active +## Language Support -## License -This script is provided as-is. Use at your own risk. The author is not responsible for any midnight visitations resulting from improper modification of the code. +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`). -## Author -Your friendly neighborhood script writer who will definitely not touch you at night if you follow the instructions. \ No newline at end of file +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](https://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. \ No newline at end of file