![[robot]](robot2.jpg)
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.
Allegra's code is covered under the GNAT Modified General Public License.
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 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:
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:
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.support/init-config
from the Allegra install directory, to create the necessary tables and populate the configuration tables with their default values.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:
|
| 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!
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.
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:
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