search

joodicator / PageBot

A general-purpose IRC robot.
GNU Lesser General Public License v3.0
2 stars 0 forks source link

readme

PageBot

A general-purpose, modular, extensible IRC robot written in Python 2. Includes numerous plugins for various different purposes.

Contents

  1. Dependencies
  2. Contributing
  3. License
  4. Installation and Usage
  5. Overview of Files
  6. Main Configuration File
  7. Core Modules
  8. Support Modules
  9. Available Plugins
    1. Admin Tools
      • aop - give channel op status to users.
      • chanserv - keep ChanServ out of channels.
      • debug - print debugging information to the console.
      • flood - defend against flooding attacks.
      • invite - join channels when invited.
    2. User Tools
      • convert - convert between units of measurement.
      • dice - simulate dice rolling, etc.
      • kakasi - transliterate Japanese characters.
      • mirror - copy impermanent URLs for posterity.
      • qdbs - show updates from QdbS quote databases.
      • seen - tell when users were last seen.
      • tell - leave public messages for users.
      • url - show information about URLs.
    3. Game Tools
      • dominions - show updates from Dominions 4: Thrones of Ascension.
      • dungeonworld - assist with running Dungeon World sessions.
      • minecraft - connect channels to Minecraft servers.
      • terraria - connect channels to Terraria servers.
    4. Other Plugins

Dependencies

Required

Optional

Contributing

Bug reports and feature requests may be submitted to this repository using the issue tracker, and are more than welcome. Pull requests fixing bugs are welcome, and pull requests adding or changing features will be duly considered.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Installation and Usage

  1. Clone this repository, or download an archive of the code and extract it, into an empty directory.
  2. Copy conf/templates/bot.py to conf/bot.py and edit it to configure the basic parameters of the bot. See Main Configuration File.
  3. As needed for any plugins loaded, copy additional files from conf/templates/ into conf/ and edit them. The plugins listed in Core Modules should usually be present at the beginning of this list, in the same order.
  4. If the bot should identify to NickServ, create conf/nickserv.py with the relevant information. If you wish to be able to issue admin-only commands to the bot, add yourself to conf/admins.txt and/or set a password in conf/auth_password.txt and then use the !identify command.
  5. Run main, and the bot will connect to the configured IRC server and print a log of sent and received IRC messages to stdout. The bot currently has no built-in daemon mode, but it can be left running in the background using a terminal multiplexer such as GNU screen. To restart the bot, issue Ctrl+C once and wait or twice to terminate it. It may also be caused to restart using the admin command !restart, or with a particular quit message using !quit MESSAGE.
  6. There are at least three ways to cause the bot to join IRC channels:
    1. Configure the channels statically in conf/bot.py, and they will be automatically joined.
    2. If the invite plugin is loaded: configure the channels dynamically (while the bot is running) using the IRC INVITE and KICK commands to cause it to join or leave channels. You must usually be a channel operator to do this. This will be remembered when the bot is restarted.
    3. If you are a bot administrator, use the !join and !part commands in a channel or by private message. These settings will not be remembered when the bot is restarted.
  7. While the bot is running, if you are an administrator, modules can be dynamically installed, uninstalled and reloaded from disk using the !load, !unload, !reload and !hard-reload commands.

Overview of Files

Main Configuration File

This file is located at conf/bot.py and configures the core features of the bot. It is a Python 2.7 source file which may bind the following names at the top level:

Name Type Description
server str The hostname of the IRC server to which to connect.
port int The port number to which to connect. Usually 6667. Plain IRC connections must be accepted on this port, as PageBot does not (currently) support SSL.
nick str The nickname for the bot to use on IRC.
user str The username for the bot to use on IRC.
name str The "real name" for the bot to use on IRC.
host str The bot's own hostname reported to the IRC server. In practice, this is usually ignored by the server, and can be anything.
channels list of str The channels to join automatically after connecting.
plugins list of str The plugins to load automatically.
timeout Number The number of seconds of latency after which the connection will time out and restart.
bang_cmd True or False If False, bot commands must be prefixed by NICK:, where NICK is the bot's nick. This is useful if there are multiple bots present which may respond to commands of the form !COMMAND.
flood_limits list of (Number,Number) Each list item (lines, seconds) enforces a serverbound flood protection rule preventing the bot from sending more than lines IRC messages in any period of seconds seconds. This is useful to prevent the bot from being disconnected by an IRC server's flood protection mechanisms. In practice, IRC servers often have multiple such mechanisms, hence the need for multiple rules.

If any of these are not specified, the default values in main.py or ameliabot/amelia.py (in that order) are used.

Core Modules

These plugins implement the basic functionality of PageBot beyond that provided by the code of ameliabot, and should usually be present in the plugins section of conf/bot.py and loaded at all times, in order for the bot to work properly. Additionally, the user may wish to edit some of the configuration files listed here to use certain features.

runtime

Actively performs miscellaneous tasks essential to the bot and other modules.

message

Manages basic IRC message events from xirclib and provides the !help command.

nickserv

Communicates with the network service known as NickServ on most IRC networks.

auth

Provides authentication of bot administrators. Requires identity to be separately installed for certain features.

control

Provides admin commands for control of the bot's basic functions.

channel

Manages state information relating to IRC channels. Also defines the concept of a quiet channel: a channel is quiet if it is listed in the corresponding configuration file, or if it has mode +m active. Several plugins modify their behaviour to suppress frivolous messages to quiet channels.

Support Modules

These plugins do not by themselves implement functionality useful to the user, but are required by some other plugins. Unless otherwise noted, they do not need to be explicitly installed, as they will be automatically loaded by the plugins that depend on them. However, many of them do have configuration files that may need to be edited by the user.

Infrastructure

bridge

Allows groups of channels - each of which is either an IRC channel or a special type of channel external to the IRC network, provided by a module such as minecraft - to be bridged together, such that any message sent to one will also be relayed to the others by the bot. Also causes certain commands to work in the aforementioned non-IRC channels.

chan_link

Allows pairs of channels to be linked together, so that messages from one channel are relayed to the other. This is the same functionality provided by bridge, except that: it only affects IRC channels, and as such uses a somewhat different format for displaying messages; it allows finer control over the nature of the channel links; and it allows links to be created dynamically by admin commands or programmatically by other plugins. A channel link is mutual if messages are relayed in both directions; otherwise, they are only relayed from one channel to another. A channel link is persistent if it is saved in the state file so that it is re-established when the bot is restarted.

limit

Implements per-user flood protection for user commands and other actions causing processor or network usage, to curtail denial-of-service attacks against the bot. When a user exceeds the limits defined in limit.py, they are ignored for a period of time and given a notification of this.

modal

Allows different plugins to share access to limited resources associated with IRC channels, such as the right to respond to a command whose name is the same for two different plugins. Access is mediated based on a centrally managed mode determining which plugin has access at any given time. See comments in modal.py for more information.

External API Access

imgur

Provides programmatic access to Imgur's API.

pastebin

Provides programmatic access to Pastebin's API.

youtube

Provides programmatic access to YouTube's API. Requires google-api-python-client to be separately installed in the same Python distribution used to run the bot.

Other Modules

identity

Manages sets of credentials used to recognise particular IRC users.

phantomjs

Provides common utilities for running web pages using PhantomJS via Selenium. The selenium Python package and the PhantomJS operating system package must both be present in order for this module to be useful.

util

Provides various miscellaneous classes and functions shared by many different modules.

Available Plugins

Admin Tools

aop

Automatically ops other users. When the bot has mode +o in a channel, this module allows the bot to automatically give +o to other users when they join the channel, when they issue !update, and when the bot joins the channel. This plugin automatically loads identity.

chanserv

Communicates with the network services known as ChanServ on most IRC networks. Currently, this is only useful for automatically evicting ChanServ from desired channels, but more features may be added in the future.

debug

Displays on the console extended information about the internals of the bot's operation. When loaded, shows most untwisted events passing through the bot's primary Mode instance, and possibly also those passing through auxiliary Mode instances created by plugins. Events which occur so frequently as to make the console unreadable are suppressed.

flood

Employs heuristic measurements to detect when a user is maliciously flooding a channel with repetitive messages, either alone or in concert with other users. This is especially useful against automated spam-bot attacks. When such behaviour is detected, the bot will ban and kick the offending user or perform some other action according to its configuration.

invite

Causes the bot to join channels when invited, and indefinitely remembers INVITEd and KICKed channels.

User Tools

convert

Converts quantities between different measurement units.

dice

Simulates dice rolls and other random choices. Uses Python 2's standard random number generator, which in turn uses either an internal pseduo-random number generation algorithm or a source of entropy provided by the operating system.

Multiple dice rolls or choices may be made in the same !roll invocation by writing them one after the other, possibly separated by other text, which will be repeated in the result. Moreover, the two types of random sampling may be mixed together, and lists of choices may be nested within each other. See !help roll for more information and additional features.

kakasi

Shows the Hepburn romanisation of Japanese text. Where there is more than one possible reading of a sequence of kanji, the alternatives are shown within braces. Any messages detected to contain a majority of Japanese text will be automatically transliterated. Requires KAKASI and in particular the shared library libkakasi.so to be present on the system.

mirror

Automatically copies resources from URLs known to expire after a short time, for posterity. When such a URL is posted in a channel, the bot will copy it to a permanent location and provide a link to the copy. Currently, this consists of copying PNG, GIF or JPEG images hosted on 4chan to Imgur, but more schemes may be added in future. This plugin requires the imgur module to be configured with a valid client_id.

qdbs

Notifies channels and users of new entries posted to a QdbS quote database. This plugin automatically loads the identity module. Requires BeautifulSoup 4 and html5lib.

seen

Tells when users were last seen by the bot in a channel.

tell

Allows users to leave public messages for each other in channels. This is similar to the service provided by MemoServ on many IRC networks, but can be useful when MemoServ is not available, or when the recipient may not be logged in to a NickServ account or may not notice that they have a memo.

If the user issuing !tell or !untell is a bot administrator, the arguments of the command may be prefixed with the name of a channel so that it affects that channel rather than any current channel. Additionally, the commands !tell, !untell, !tell?, !tell+, !tell-, !tell-clear, !tell-undo and !tell-redo may equivalently be written as !page, !unpage, !page?, !page+, !page-, !page-clear, !page-undo and !page-redo, respectively.

url

Shows information about URLs mentioned in the channel. The title, file size and MIME type are shown, if available. For links to images, the "best guess" provided by Google's reverse image search is also shown. If the imgur module is configured with a valid client ID, additional information is shown for Imgur URLs. If the youtube module is configured with a valid API key, additional information is shown for YouTube videos. Requires BeautifulSoup 4 and html5lib.

Up to 5 additional !url invocations, introduced by ! as usual, may be included on the same line as the first !url command. This can be useful to view the titles of several recently mentioned URLs at once.

Game Tools

dominions

Displays updates from Dominions 4: Thrones of Ascension multiplayer servers. The game must be hosted using Dominion's TCP server, with the --statuspage option used to generate an HTML document accessible to the bot by HTTP or in the local file system. The bot will periodically read this document to discover updates in the game's status. See this document for more information about the command-line options of Dominions 4. Requires BeautifulSoup 4 and html5lib.

The commands !dom+, !dom- and !dom? have the special property that they may be followed by a new command (introduced with the ! character as usual) on the same line, for convenience when issuing multiple commands at once.

dungeonworld

Assists with running games of Dungeon World on IRC. Supplements the functionality of the dice plugin, which should be separately installed. Requires the pastebin module to be configured with a valid developer key.

minecraft

Relays messages between Minecraft servers and other channels. The plugin connects to Minecraft servers via pipeserve and mcchat2, both of which must be installed and run separately. The bridge plugin must also be separately installed, and configured to connect Minecraft servers to other channels.

terraria

Relays messages between Terraria servers and other channels. The bridge plugin must also be separately installed, and configured to connect Terraria servers to other channels.

Other Plugins

bum

Occasionally repeats people's messages, with one word replaced with "bum". Suppressed in quiet channels. Inspired by https://github.com/ollien/buttbot.

chess

Allows two-player games of chess to be played on IRC using a textual interface. This is done by connecting to this chess engine through a socket created by pipeserve, both of which must be installed and run separately.

hue

Whenever onamatapoeic laughter is detected in the channel, the bot joins in. Suppressed in quiet channels.

quora

Posts questions from Quora at random intervals in configured channels.

upoopia

Allows two-player games of Upoopia to be played on IRC using a textual interface. Because of the imperfect information each player is supposed to receive, this is implemented with each player residing in separate IRC channel where private information is sent by the bot, with any other public messages being relayed between the two channels (using the chan_link module). The bot must be present in both channels, as may spectators, but a player should never join their opponent's channel while a game is being played.