The Allegra Info-Bot

[robot]

 

Introduction

Allegra is an IRC info-bot (an information "robot", or software agent) created for the #Ada channel on the Freenode IRC network. This document describes the program itself, including how to build, install, and maintain it. Another document exists describing how to use the bot once it is running, and yet another discussing the code itself.

Allegra was intended primarily to serve the needs of the #Ada channel, and is not presented as a general-purpose info-bot, although her code is freely available and may be employed by others to whatever extent they find it useful. For a general-purpose IRC bot, try blootbot, infobot, dagny, eggdrop, or any one of a zillion others.

 

Licensing

Allegra's code is covered under the GNAT Modified General Public License.

 

Requirements

The code for the bot currently running on #Ada was built and runs in the following environment:

It depends on two Ada support libraries:

In turn, Postgres-Ada depends on libpq (currently provided by the Debian packages libpq-dev and libpq5, both currently at version 8.4.4-1+b1), and once running, the bot expects a PostgreSQL server to be available (package postgresql, current version 8.4.4-1).

The code uses some GNAT-specific packages, GNAT.Regpat most heavily, so porting it to another Ada compiler would be a bit of work, although the GNAT run-time library code is open-source, so in a pinch that could be used.

We're unaware of any "tight" version requirements, so other versions of the above software will likely work. If you discover any other dependencies not listed here, please report them on #Ada.

 

Building, Installation, and Configuration

 

Building

Building is quite straightforward (at least on our system!):

make

If all goes well, this creates the binary, "allegra", which may be installed anywhere you wish. It has no hard-coded dependencies on external files; it fetches all of its configuration from the "allegra" database on the PostgreSQL server, which is assumed to be running on the same host. To use a server on a different host, the "Host" argument to the "Connect" call in config.adb would need to be set to the hostname where the server is running. Possibly, this might be made more configurable in a future release, like being taken from a command-line option.

Some notable aspects of the makefile:

 

Installation

As mentioned above, the allegra binary may be placed in any location. It uses a PostgreSQL database for all configuration data. To set up the database, follow these steps:

  1. Once you have the binary built, you need to initialize the database used by the bot. The PostgreSQL utility to create the empty database initially is "createdb", and might be used like so:

    createdb allegra "Database for Allegra info-bot"

    If you wish to use a different database name, you will need to change the value of the constant "Allegra_DB" in config.ads; again, this is a good candidate for a command-line option in future.
  2. Once you have created the database, run:

    support/init-config

    from the Allegra install directory, to create the necessary tables and populate the configuration tables with their default values.
  3. No default values are provided for these tables: You will need to provide your own values for these tables. One simple way to do this is via the PostgreSQL utility "psql", using shell commands like so: You may insert as many of each sort of message as you wish. The bot will select randomly from among the ones found in the tables. Adding entries to the usrlevels table gives users who match the usermask that access level for executing bot commands. We recommended that you:
    1. Add your own usermask immediately, with bot operator access (level 10).
    2. Be careful in giving out bot operator access to anybody else. Be sure you trust them implicitly, although most of the damage they might do can be corrected by adjusting the database directly using psql. However, without a backup, you can't recover deleted factoids!
  4. The factoid and statistics tables are filled and maintained by the bot, either automatically or via bot commands, so no special action need be taken for those at installation time.
 

Configuration

The default configuration values are found in the support/init-config script, in the section with the "INSERT INTO config" statements. The current configuration items are:

Item Name Usage
armpath Pathname of the RM index file to be used for index lookups via the "find" bot command. Set to null to disable the "find" command.
channel The IRC channel the bot should join, without the leading "#", which is added automatically, eg. "mychan". May be overridden via a command-line parameter.
helppath Pathname of the bot's help-message file.
host Network name of the host running the IRC server to which you wish to connect, eg. "irc.freenode.net". May be overridden via a command-line parameter.
lastsize Size in lines of the buffer used for the "last" bot command. This sets the max number of lines the bot remembers, and thus that may be recalled using "last".
loglevel Verbosity level for the bot log. Legal values are:
  • none -- lowest, no messages logged
  • err -- error messages
  • warn -- warning and error messages
  • info -- informational, warning, and error messages
  • dbg -- highest, enable all message output
logpath Pathname of file to use for log messages, eg. "local.log". May be overridden via a command-line parameter.
nick The IRC nickname the bot should use, eg. "Momzer". May be overridden via a command-line parameter.
nickpass For IRC networks (like Freenode) which run NickServ, this is the password the bot should use for it. You must register the bot's nick yourself, set the password, then put that password value into the database.
port Numeric port number to use for the IRC connection, eg. "9996". May be overridden via a command-line parameter.
quips Numeric probability that the bot will print a quip when it sees its nick used in channel traffic, as a decimal fraction. Set to 0.0 to disable quips, 1.0 to always print quips, or somewhere in between for occasional ones.
realname The value the bot should use for the IRC "realname" field when registering with the server, eg. "My Allegra Clone".
shorthand A short string (usually just one character) which may be used in channel messages instead of the bot's nick, to cause the bot to treat them as commands. For example, "Allegra: quote" is treated as a bot command, but if the shorthand string is "!", then "!quote" has the same effect.
shorturl The network address of the URL shortener server the bot uses to shorten long URLs. If this changes, you'll probably have to update the code that accesses it, too, to conform to the new site's requirements.
username The value the bot should use for the IRC "username" field when registering with the server, eg. "allegra". Roughly equivalent to a Unix user ID.

You can change the configuration values either by editing the support/init-config script before running it, or at any time after installation by psql shell commands like these:

Note that the bot only reads the configuration values at startup, so if you change them while it is running, you'll need to stop it (via the "quit" bot command) and re-start it. Hey, we said it wasn't a general-purpose bot!

 

Running

To use the configured settings for IRC server, port, nickname, channel, and logfile pathname, simply run the bot binary with no arguments:

/path/to/allegra

Normally, we run it backgrounded and nohup'd, like so (under a Bourne-like shell, at least):

nohup /path/to/allegra >/path/to/startup-errors.log 2>&1 &

The first time or two, check the stderr output (shown above as "/path/to/startup-errors.log") to see if any serious errors occurred during startup. After the bot is started, it logs errors in its configured log file.

To override any of the above-mentioned five configuration values, use one or more of these positional command-line parameters:

allegra irc-host irc-port nick channel logpath

Since they are positional, you must specifify them in the order given above, and to specify, for example, an alternate IRC channel to join, you must also specify the irc-host, irc-port, and nick parameters too. Their meanings:

For testing your own setup and installation of this code, we highly recommend pircd, a Perl IRC server. It's easy to configure and run, and it's what we used when developing Allegra. We run pircd on the development machine, then use an allegra command like this, to avoid impacting the one that's running live on Freenode:

./allegra myhost 6667 Allegra testchan local.log &

Then we log onto the same server with an IRC client (xchat is a good one) and beat hell out of, er, test the new bot version from there.

 

Maintenance

The bot requires very little upkeep, just a botsnack now and again, and careful cultivation of a useful factoid database. Some maintenance tasks to consider:



Mail About Allegra

Robot image derived from "Robot Joe" rendering by the extremely talented Simon Abrams of Brooklyn, New York.

Last modified: Thu 8 Jul 2010 00:12:22 MST