]>
Commit | Line | Data |
---|---|---|
17f85155 | 1 | Modular Python3 IRC bot |
7c7fddd2 | 2 | =========================== |
a28e2ae9 | 3 | |
7c7fddd2 J |
4 | Getting started |
5 | --------------- | |
a28e2ae9 | 6 | - `cp bot.config.example bot.config` |
7 | - `vim bot.config` | |
6b4ba0b6 JR |
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);` | |
eb2e74a8 | 19 | - `./run` |
a28e2ae9 | 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 | ||
92da6dea | 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`) |
a28e2ae9 | 26 | |
17f85155 JR |
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. | |
a28e2ae9 | 29 | |
30 | Some modules require additional supporting materials, which can be found in `modules/contrib/`. | |
31 | ||
7c7fddd2 | 32 | |
a28e2ae9 | 33 | Module API |
76dfe9af | 34 | ---------- |
a28e2ae9 | 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. | |
db12799b JR |
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 | ||
e2035cb8 JR |
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 = !`) | |
db12799b JR |
53 | |
54 | ||
55 | Online Help | |
56 | ----------- | |
e2035cb8 | 57 | A command listing, with most (but not all) of the standard modules, is available at [https://jfr.im/help/](https://jfr.im/help/). |
db12799b | 58 | |
38182eb9 | 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>` |
db12799b JR |
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 | ||
e2035cb8 | 66 | (With `nofakelag = 1`, `!SHOWCOMMANDS` will spam the user with the whole list of commands.) |
38182eb9 | 67 | |
db12799b JR |
68 | |
69 | Support | |
70 | ------- | |
fd8ff629 | 71 | If you have any questions, issues, fixes, etc. message DimeCadmium on irc.1459.io |