itte/docs

Itte Documentation

Requirements

• Lua 5.x
• luasocket
• 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]