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