|
NAMEslackjaw - Chat and utility bot for the Firstclass bulletin board system.
SYNOPSISThis software is for use with a FirstClass bulletin board system. For information on FirstClass, visit http://www.centrinity.com. Otherwise, Centrinity has nothing to do with slackjaw. FirstClass is a bulletin board system that wraps forums, file transfer, messaging, and chat all into one neat little package. It's ironic however, that a server based so much on communication has such wimpy chat features. slackjaw hopes to fill some of that void - adding IRC style topics, personalized greetings, idle timers, last seen timers, away messages, and logging to chat. slackjaw can also be used as a general respository for user email addresses, and users can be mailed from the chat. slackjaw can be laden with phrases to say on events, or can be configured to run silently. All configuration for the bot (after initial setup) is executed via a CGI script, which in itself is customizable, with multiple user login and access levels. The newest slackjaw can be downloaded from http://www.martini.nu/slack/
DESCRIPTIONslackjaw requires MySQL, either a web server (apache) OR Tcl/Tk, and Perl version 5.004 or better. The web server must be on the same machine as the bot. The mySQL server can be at any location. The needed perl components can all be retrieved from www.cpan.org. They were not included, in order to keep the archive small and tidy. slackjaw uses the following external modules:
DBI
DBD::Mysql
Net::Telnet
To install them, cd into each modules directory, and in order, type:
perl Makefile.pl
make
make test
make install
This software is ``find-something-cool-and-send-it-to-me-ware.'' Anything. Music, mannequins, cardboard cutouts of people, moose heads, beer, etc. Or, just mail me and tell me you are using it. :) Feel free to paw through the source, (perl), there is probably stuff that can be greatly improved upon. Please, don't forget to send me changes, you will get credit in the next version if I decide to include it. Don't pawn this off as yer own. Bad things will happen. I will froth at the mouth. You will have nightmares. Planes will crash. Karma. Karma. Karma.
Installation* MySQL setup To begin with, you need to be root to create a new MySQL database. If you don't have root access, ask the administrator of your machine to add a mysql database for you. Two things you should know how to do if you are root:
1. Make a new (empty) database.
2. Set up permissions for it, so you can access the DB from
the bot and the CGI script.
If you don't know how to do this stuff, http://www.devshed.com has some nice walkthroughs, along with the FAQ at http://www.mysql.org. It's too involved to explain here. Nothing else needs root access, you do everything else now as the user that you will run the bot as. You should have already untarred the slackjaw tarball, since you are reading this. Open the slackjaw script in your favorite editor, and edit the top variables to match your database connection. Save and close the script. Enter mysql, and switch to your database.
% mysql -u [username] -p [database name] The next step is to create the tables the bot uses. In the slackjaw directory, there is a dir called 'mysql_files'. These are table creation commands. The easiest way to create the tables is to read the whole file into mysql. Assuming you are using vi:
mysql> \e # Switch to editor mode.
:r /path/to/mysql_files/create_config_table.sql
# Read in the config table.
:x # Save the command to mysql.
mysql> ; # Commit the command. If everything worked correctly, you will see something like this.
Query OK, 0 rows affected (0.01 sec) Do this for the config table, the user table, and the phrases tables. When you are done, issue the show tables command to check. It should look like this: (don't worry if it's not in the same order.)
<mysql> show tables;
+---------------------------+
| Tables in [database name] |
+---------------------------+
| config |
| users |
| hello_phrases |
| join_phrases |
| inactive_phrases |
| general_phrases |
| emotion_phrases |
+---------------------------+
Exit from mysql, and load the bot.
% ./slackjaw You will see a load of diagnostic information hit your screen. Welcome to debug mode. :) * Setting up FirstClass Everything you see when you've just loaded the bot for the first time are simply defaults, and they most definitly won't work. The bot will exit with an error. Most importantly, the bot made a record in the config table, with it's default values. It also created a 'logs' directory, which will contain all the chat and web logs for the bot. Go to your FirstClass board. You will need administrator access. If you don't have it, an admin will have to lend you a hand.
Make an account for the bot.
Make a chat room on the bot's desktop.
Give the bot clui access.
Make sure the bot has access to the public chat, wherever it is.
Now would also be a very good time to login as the bot, via CLUI. Write down the number that is next to the chat on the bots desktop. That number will become the 'path to private chat' variable soon. Write down the numbers you have to hit to get to the public chat. Those will become the 'path to public chat' variable.
Home: 1 Conference.
* 1 MailBox
2 Conferences
3 private chat Chat
Type an item's name or number to open it.
Commands: Help,Logout,Scan.
>
Home:Conferences: 3 Conferences, 2 Folders.
* 1 Information
2 Feedback Folder
* 3 Graphics forum
4 Gateways
5 public chat Chat (Active)
6 Random stuff Folder
Type an item's name or number to open it, or EXIT to exit.
Commands: Help,Logout,Exit,Read,New,Home,Delete,Send,Reply,...
>
In the above example, the 'path' to the bot private chat (for testing and whatever else) would simply be 3. The 'path' to the public chat would be 2,5. * Bot configuration via the CGI Now that the default values have been placed in the database, and the bot has a valid FirstClass account, it's time to load up the CGI that came along with the bot. Move the entire 'web' directory to some web-accesible place. Open the slackjaw.cgi script in an editor, and once again, it's time to edit some variables. Everything in there is relatively self-explanitory. When done, save, close, and change the permissions on the CGI script. This is probably the single most important step - the CGI simply will NOT work if you leave this out. The owner of this CGI script should match the owner that the bot runs as, and the bot's directories were created under. The script must be setuid to this user.
% chmod 4755 slackjaw.cgi Time to fire up the web browser. Point it to wherever you stuck the web directory. You need to have cookies enabled. You'll see a prompt for a username, and password. Don't worry about it, since none exist yet. Just hit login. You should be prompted to enter a owner name, and password. The owner name should match exactly with what you have your FirstClass handle set to, establishing you as the owner. Owner has full access, can view others passwords, and edit/remove web admins. Hit the set button when you've chosen your password. You'll be prompted again with the login screen - this time it is locked down. Enter the username and password that you just set. Head straight to the 'config' button. Now comes the fun task of setting bot variables.
If you have a javascript enabled browser, you can also click on the variable names in the CGI for quick reference. * Final tidbits I recommend keeping the bot in debug mode for the time being, until you actually get it into a chat room. That way, you can easily kill it with cntl-c, and see exactly what it sees so you can squash problems as they happen. After the bot seems to be doing alright, turn off debug, and the bot will become a happy little daemon. Once you are done setting up the variables, hit the save changes button. Go back to your bot directory, and load the bot.
% ./slackjaw If it doesn't start and get into chat, double check your settings and repeat the CGI config --> load bot until you get it. At this point, you should have a bot sitting in your chat. Try some commands.
!help
!stats
!add-page [email address]
!page [user name]
!admins
!add-admin [admin name]
!set-topic [topic]
!topic
!greet [greeting]
!noisy
!reload
Check the logs, see if the bot is logging the chat. Play with the CGI, see how it all works in combination with the bot. Add some phrases to hello_phrases and general_phrases with the CGI. Go back to chat, and make sure the bot is in !noisy mode. Say the bot's name. Say ``hello.'' Wait for an hour without talking. See if the bot says a status. Everything should work as expected. If not, run back through the above steps. Have fun. :D I'd love to know if you found this useful. Mail me, report success.
% uname -a | mail -s "slackjaw success v3.8" slackjaw@martini.nu
Optional utilities* bot_utils.pl This script performs 2 functions - a quick way to send signals to the bot, and a way to monitor the bot and reload it if it dies.
Usage:
-a to send ALRM (speaking to chat)
-h to send HUP (reloads bot)
-q to send QUIT (reloads configuration)
-k to kill
Add a setting your your crontab. (Highly recommended) This will check to make sure the bot is running, and if it's not, will load/reload it at 30 min intervals. Make sure to change the path variable in the script, to point to the directory the bot is located in.
*/30 * * * * /path/to/bot/directory/bot-utils.pl * Tk interface tkslack is not part of the standard package, you will have to download it from http://www.martini.nu/slack if you wish to use it. tkslack is an alternative to the web CGI. It can do everything the CGI can, except for multiuser access. It is assumed that whoever is using tkslack is the owner of the bot, and therefore makes no attempt to mask passwords, log, or deal with user level access. tkslack uses the following external modules:
DBI
DBD::Mysql
Tk
To install them, cd into each modules directory, and in order, type:
perl Makefile.pl
make
make test
make install
Using a text editor, you will need to change the variables so the script can login to the mysql database. tkslack has been seen running on Windows (Activestate perl) machines, albeit with most of it's functionality disabled.
PluginsIf slackjaw doesn't do something that you would like him to, it's very easy to add your own commands to him via plugins. Check out plugins/echo for a good guide to begin creating your own. * Syntax for slackjaw plugin files A slackjaw plugin is nothing more than a perl subroutine, with one additional line of slackjaw specific code at the very top. Line 1 should always have this syntax.
#subroutine name : access (1/0) : logging (1/0) : help msg 'access' and 'logging' are toggles. 1 for on (admin) , 0 for off (public). Line 1 always must contain the above syntax, or the plugin will not load. All changes to plugin code require a bot reload. You can enable and disable them by moving them in or out of the 'plugins' directory and reloading. All plugs automatically have a few variables to play with.
$chatdood - who called the command
$plugarg - what they called the command with.
$t - the telnet object. See the example code.
All plugins need to be subroutines, and need to end with 1; Be careful in the use of variable and subroutine names, don't stomp over pre-existing ones. (Don't follow in my bad example... use 'my'!)
#echo:0:0:This plugin echos what you type to it.
# 'Echo' example plugin.
# Example in chat:
# User: !echo I am just testing.
# This plug would simply return
# slackjaw: User said "I am just testing."
sub echo {
if ($plugarg) {
$t->print(" $chatdood said \"$plugarg\"");
} else {
$t->print(" $chatdood didn't say anything at all.");
}
}
1;
AUTHORMahlon Smithslackjaw@martini.nu
BUGSFirstClass CLUI is not the most robust command line atmosphere in the world.
Without pauses in between commands, the first letter of chat output is
lost. As a crappy fix, If slackjaw hangs when connecting to your FC board - try shortening your default CLUI welcome to fit on a standard terminal screen. This file can normally be found on the administrator's desktop, in a folder called 'CLUI help'. The filename is '01 Welcome'. In an extremely busy chat, it is possible for commands to be ignored due to spoof protection. There are really far too many installation steps.
COPYRIGHTMahlon Smith, 2001. slackjaw is distributed under an artistic license - feel free to redistribute and modify to your liking - please let me know you found it useful. Do NOT include on any software collections for resale. |