pegasus/tclscripts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README

Browse Source 
Previous README was incomplete. Rewrote it to cover installation,
configuration, ban mask types, all public and private commands,
automatic ban tracking behaviour and language support.
This commit is contained in:
Teh PeGaSuS
2026-03-03 13:13:44 +01:00
parent 75c522d1c3
commit 6e910e2aea
1 changed files with 104 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Chanban/README.md
+104 -87
View File
@@ -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 \<nick> | Permanently ban a user |
| tban | !tban \<nick> | Temporarily ban a user |
| kick | !kick \<nick> | Kick a user from channel |
| unban | !unban \<mask> | Remove a ban by mask |
| banlist | !banlist | Get link to current ban list |
| opcmds | !opcmds | List available commands |
| 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)
| Command | Syntax | Description |
|---------|--------|-------------|
| ban | /msg botnick ban <#chan> \<nick> | Permanently ban a user |
| tban | /msg botnick tban <#chan> \<nick> | Temporarily ban a user |
| kick | /msg botnick kick <#chan> \<nick> | Kick a user from channel |
| unban | /msg botnick unban <#chan> \<mask> | 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> <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 |
```
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.
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.