-Modular {Python2,Python3} IRC bot
-=================================
+Modular Python3 IRC bot
+===========================
-Getting started:
+Getting started
+---------------
- `cp bot.config.example bot.config`
- `vim bot.config`
- Create a MySQL database, i.e. `CREATE DATABASE foo; GRANT ALL ON foo.* TO ...`
- `mysql <dump.sql`
-- `./run.sh`
+- Add your auth (main NickServ nick/account name on other networks) in the database as owner: `INSERT INTO users VALUES ('YourAuth', 100);`
+- `./run`
Install croncheck.sh in your crontab, if desired.
`* * * * * /path/to/erebus/croncheck.sh`
To suppress croncheck.sh from restarting the bot without removing from crontab, `touch dontstart`
-Output will be placed in `logfile`, which is rotated to `oldlogs/`. (I strongly recommend `rm oldlogs/*` as a weekly crontab entry.)
+Output will be placed in `logfile`, which is rotated to `oldlogs/`. (I strongly recommend `rm oldlogs/*` as a weekly crontab entry. `@weekly find /path/to/erebus/oldlogs/ -mtime +7 '!' -name .keep -delete`)
-The bot targets both Python 2 and 3. However, it is generally only actively tested on Python 2.
-If it's not working on Python 3 (or an included module isn't working on Python 3), please raise a bug.
+The bot targets Python 3 only. It has some time ago switched to being primarily tested on Python 3.
+Python 2 support is presumed to have slowly eroded due to a lack of testing. It probably won't work.
Some modules require additional supporting materials, which can be found in `modules/contrib/`.
-*****
+
Module API
----------
The module API has largely remained backwards-compatible and likely will remain so into the future. However, it is still currently unstable, primarily because it's only tested with the included modules. If you find a change was introduced which breaks something you relied on, please raise a bug.
There is currently no documentation as to... well, anything. A good starter template for a new module is `modules/eval.py`. `modules/control.py` uses a significant subset of the API features available. `modules/foo.py` is intended as a demonstration module, and documents some of the major features.
+
+
+Buffering
+---------
+The bot includes message buffering, with two different message queues (plus a "fast" message which sends immediately). This is to help prevent the bot from being flooded off the network by malicious users.
+
+Unfortunately this does mean that the bot can be overwhelmed and take quite a while to respond. As an admin, you can use the `!QCLEAR` command to clear the queues. If you control the IRC server, you can exempt the bot from flooding checks and then set `[erebus] nofakelag = 1` in the bot.config. This will turn off message buffering completely.
+
+
+Using the bot
+-------------
+Commands can be triggered by:
+- Messaging the bot (`/msg Erebus whoami`)
+- Prefixing the command with the bot's name and a colon (`/msg #channel Erebus: whoami`)
+- Or prefixing the command with the trigger character set in bot.config (`/msg #channel !whoami` if `[erebus] trigger = !`)
+
+
+Online Help
+-----------
+A command listing, with most (but not all) of the standard modules, is available at [https://jfr.im/help/](https://jfr.im/help/).
+
+So long as you don't prohibit loading of the help module with `[autoloads] help = 0`, command info will be available with `!HELP <command>`
+
+However, due to the message buffering mentioned above, there is no command listing available over IRC unless nofakelag is enabled. In order to generate a command listing, you must do the following:
+1. Set `[help] path` in the config file, if needed, to a path which exists and is available on the web. f.e. `[help] path = /home/jrunyon/public_html/help/%(#)d.txt`. Several values are available, for use with !GENHELP; they are the same as the prefix characters @#+- (see !HELP GENHELP). This determines the path to which !GENHELP will save output files.
+1. Set `[help] url` in the config file to a path where help can be found, f.e. `[help] url = https://jfr.im/help/%d.txt`. %d (or %s) will be replaced with the user's level. This determines the URL which is provided to users when they !SHOWCOMMANDS
+1. Run `!GENHELP` whenever you change which modules (or commands) are available, or else just set `[help] autogen = 1`.
+
+(With `nofakelag = 1`, `!SHOWCOMMANDS` will spam the user with the whole list of commands.)
+
+
+Support
+-------
+If you have any questions, issues, fixes, etc. message DimeCadmium on irc.1459.io
projects / erebus.git / blobdiff