]>
Commit | Line | Data |
---|---|---|
1 | Modular Python3 IRC bot | |
2 | =========================== | |
3 | ||
4 | Getting started | |
5 | --------------- | |
6 | - `cp bot.config.example bot.config` | |
7 | - `vim bot.config` | |
8 | - Create a MySQL database, i.e. `CREATE DATABASE foo; GRANT ALL ON foo.* TO ...` | |
9 | - `mysql <dump.sql` | |
10 | - Add your auth (main NickServ nick/account name on other networks) in the database as owner: `INSERT INTO users VALUES ('YourAuth', 100);` | |
11 | - `./run` | |
12 | ||
13 | Install croncheck.sh in your crontab, if desired. | |
14 | `* * * * * /path/to/erebus/croncheck.sh` | |
15 | To suppress croncheck.sh from restarting the bot without removing from crontab, `touch dontstart` | |
16 | ||
17 | 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`) | |
18 | ||
19 | The bot targets Python 3 only. It has some time ago switched to being primarily tested on Python 3. | |
20 | Python 2 support is presumed to have slowly eroded due to a lack of testing. It probably won't work. | |
21 | ||
22 | Some modules require additional supporting materials, which can be found in `modules/contrib/`. | |
23 | ||
24 | ||
25 | Module API | |
26 | ---------- | |
27 | 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. | |
28 | ||
29 | 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. | |
30 | ||
31 | ||
32 | Buffering | |
33 | --------- | |
34 | 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. | |
35 | ||
36 | 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. | |
37 | ||
38 | ||
39 | Using the bot | |
40 | ------------- | |
41 | Commands can be triggered by: | |
42 | - Messaging the bot (`/msg Erebus whoami`) | |
43 | - Prefixing the command with the bot's name and a colon (`/msg #channel Erebus: whoami`) | |
44 | - Or prefixing the command with the trigger character set in bot.config (`/msg #channel !whoami` if `[erebus] trigger = !`) | |
45 | ||
46 | ||
47 | Online Help | |
48 | ----------- | |
49 | A command listing, with most (but not all) of the standard modules, is available at [https://jfr.im/help/](https://jfr.im/help/). | |
50 | ||
51 | So long as you don't prohibit loading of the help module with `[autoloads] help = 0`, command info will be available with `!HELP <command>` | |
52 | ||
53 | 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: | |
54 | 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. | |
55 | 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 | |
56 | 1. Run `!GENHELP` whenever you change which modules (or commands) are available, or else just set `[help] autogen = 1`. | |
57 | ||
58 | (With `nofakelag = 1`, `!SHOWCOMMANDS` will spam the user with the whole list of commands.) | |
59 | ||
60 | ||
61 | Support | |
62 | ------- | |
63 | If you have any questions, issues, fixes, etc. message DimeCadmium on irc.quakenet.org |