168 lines
5.5 KiB
Markdown
168 lines
5.5 KiB
Markdown
# Itte Documentation
|
|
|
|
|
|
## Requirements
|
|
|
|
- [Lua 5.x](https://www.lua.org/)
|
|
- [luasocket](https://w3.impa.br/~diego/software/luasocket/)
|
|
- [luasec](https://github.com/brunoos/luasec)
|
|
|
|
|
|
## Installation
|
|
|
|
- Install Lua and other dependencies. Example:
|
|
|
|
- Debian/Ubuntu-based distributions: `apt-get install lua-socket lua-sec`
|
|
|
|
- Alpine Linux: `apk add lua-socket lua-sec`
|
|
|
|
- Copy the `itte*.lua` files to the project directory.
|
|
|
|
|
|
## Usage
|
|
|
|
- Create two config files, or copy the sample files from `examples/` to the
|
|
same directory level as the `itte*.lua` files. Replace instances of
|
|
`[prefix]` hereafter with the name of your choice without spaces or special
|
|
characters, e.g. the project name.
|
|
|
|
- `[prefix].servers.lua`: list servers and global admins here.
|
|
|
|
- `[prefix].config.lua`: add bot settings and handlers here.
|
|
|
|
- There are two variables in `*.servers.lua`:
|
|
|
|
- `itte_servers` (required): add a server to `itte_server` following the
|
|
example configurations.
|
|
|
|
- `itte_admins` (optional): this is a table of global admins who can access
|
|
bot-wide handlers like connecting servers. If left undefined, global
|
|
admin-only handlers will not be run. In some cases this may be desirable to
|
|
reduce incidents of bot tampering.
|
|
|
|
- There are two optional variables in `*.config.lua`:
|
|
|
|
- `itte_config`: customise bot settings, such as the default response and
|
|
error messages shown to users.
|
|
|
|
- `itte_handlers`: most bots listen for some pre-defined code words (often
|
|
known as "commands") and respond by calling a handler, or function to
|
|
handle the request accordingly. Handlers for scheduled tasks can also be
|
|
added.
|
|
|
|
The module will refer to the keywords as codes to distinguish them
|
|
from IRC commands sent to the server like `JOIN` or `PART`. Name the
|
|
handler after the code word that will be used to trigger the function and
|
|
add it to `itte_handlers` so it can be automatically picked up by the
|
|
module. For example, if the code users will type is `!hello` (where `!` is
|
|
a prefix to mark it as a bot code), name the function
|
|
`itte_handlers.hello()`. Handler names cannot start with numbers or special
|
|
characters.
|
|
|
|
- Initialise the module in a project file named `[prefix].lua` and add the
|
|
following to the file:
|
|
|
|
```
|
|
-- Import the module
|
|
local itte = require("itte")
|
|
|
|
-- Set the prefix for the module to find the config files
|
|
-- The prefix is the name preceding `.servers.lua` and `.config.lua`
|
|
itte.confs.prefix = "[prefix]"
|
|
|
|
-- Call the run function
|
|
itte.run()
|
|
```
|
|
|
|
- Start the bot: `lua ./[prefix].lua`
|
|
|
|
|
|
## Built-in service codes
|
|
|
|
The module includes a number of built-in codes that bots can respond to. The
|
|
full list can be viewed on IRC by issuing the code `!help` in a private
|
|
message with a bot or in a channel where the bot is present. Admin users will
|
|
also see admin-only codes to manage a bot.
|
|
|
|
Global admin-only codes:
|
|
|
|
- `connect [server] [user] [password]`: connect to server listed in the server
|
|
config, where `[server]` is the name given in the servers table (or use
|
|
`servers` to get the names).
|
|
|
|
- `quit [server] [user] [password]`: disconnect from a server. The bot process
|
|
will automatically exit if it is not connected to any server.
|
|
|
|
- `reload [user] [password]`: reload the bot config.
|
|
|
|
- `servers [user] [password]`: list known/active servers from the config.
|
|
|
|
Server admin-only codes:
|
|
|
|
- `channels [password]`: list known channels from the server config.
|
|
|
|
- `join [channel] [password]`: join channel(s), e.g. `!join #bots #programming
|
|
password`.
|
|
|
|
- `part [channel] [passowrd]`: leave channel(s), e.g. `!part #bots password`.
|
|
|
|
Codes accessible by all users:
|
|
|
|
- `help`: list available service codes.
|
|
|
|
- `ping`: send a pong message.
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
The `examples/` directory has a few demo bots to show how to use the module.
|
|
|
|
- *hellobot*: a "hello world" example that greets users in several different
|
|
languages when they type `!hello`. The source files include more information
|
|
about available configuration settings.
|
|
|
|
- *ramenkan*: a bot that serves ramen. It has some custom config settings and
|
|
scheduled tasks.
|
|
|
|
- *hachi* and *gordon*: bots inspired by tracery text expansion. Loads files
|
|
("foils") containing selection tables and creates handlers to return
|
|
responses, one service code per foil.
|
|
|
|
|
|
## Running a bot as a background process
|
|
|
|
There are multiple ways to have a bot run in the background.
|
|
|
|
### nohup
|
|
|
|
Using the `nohup` command is quick and simple, though it does not support
|
|
restarting if the bot exits due to a network issue.
|
|
|
|
To run the bot and discard any output by redirecting it to `/dev/null`:
|
|
`nohup lua /path/to/[prefix].lua >/dev/null 2>&1 &`
|
|
|
|
### Init scripts, e.g. systemd
|
|
|
|
Startup scripts enable services to start automatically and relaunch in the
|
|
event of an unexpected exit (unless expressly stopped through an init system
|
|
command). The instructions below describe setting up and running a [systemd]
|
|
service for a bot under a non-privileged user.
|
|
|
|
- Create a systemd directory for the user running the bot if it does not
|
|
already exist: `mkdir -p /home/[user]/.config/systemd/user`
|
|
|
|
- Copy the sample `*.service` to the user systemd directory and rename the file
|
|
to `[prefix].service`. Edit the service description, `WorkingDirectory` and
|
|
`ExecStart` values as needed. Use full paths for the `WorkingDirectory` and
|
|
location of the Lua executable, or the service file will not work.
|
|
|
|
- Start and enable the service:
|
|
|
|
```
|
|
systemctl --user start [prefix]
|
|
systemctl --user enable [prefix]
|
|
```
|
|
|
|
[systemd]: https://www.freedesktop.org/software/systemd/man/systemd.service.html
|