Features

What?

LumberJack is an IRC Logbot, paired with a web application for browsing and searching through logs.

It is written in Python (for the logger), and PHP & JavaScript (for the client).

A sample implementation is pointed at the channel #sfucsss, on irc.freenode.net. View it here.

Why?

A lot of companies and projects use IRC chat for internal team communication. It's a great way to connect a team semi-synchronously. The only trouble is that an individual team member only has logs of the conversation for when he's around. Clever folks just leave their IRC client logged in all of the time, and log into that whenever necessary — but I'd argue that that's a bit of a pain. Sometimes, teams need a way to archive and search through IRC logs.

Who?

I'm Curtis Lassam. You're on my website.

Download

The best only way to get Lumberjack is from a SVN checkout. A real gamebreaker of a bug has been found in LumberJack 1.1, so until I get a new release out, the SubVersion version is the bestest version.

You can do this by running:

svn co http://svn.lassam.net/pierc

You can download LumberJack here:

  LumberJack_1.1.zip

Lumberjack 1.1 adds a much needed combination of stability patch and auto-termination in the case of long-term failure.

  LumberJack_1.0.zip

Instructions

Requirements

LumberJack requires that you have the following...

  • A web server, capable of running PHP5 applications, with MySQL installed.
  • A computer with a stable connection to the internet, running Python, with Python-MySQL installed.

Step 1: Make Sure A Database Is There

On your webserver, create a MySQL database for use with LumberJack, and a user/password combination that can access the DB. 

$ mysql -u adminusername -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 5340 to server version: 3.23.54
 
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 
mysql> CREATE DATABASE lumberjack;
Query OK, 1 row affected (0.00 sec)
 
mysql> GRANT ALL PRIVILEGES ON lumberjack.* TO "lumberjack_user"@"hostname"
	-> IDENTIFIED BY "lumberjack_password";
Query OK, 0 rows affected (0.00 sec)
  
mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.01 sec)

mysql> EXIT
Bye
$

If your webserver is not going to be the same computer as the one running the logger, the database will need to be configured to allow remote login.

Step 2: Start Logging

The bot folder in the download contains all of the code necessary to run the log bot. Unpack it into a directory.

Install Python, and the mysql-python libraries. Note that, on Ubuntu (and other Debian based OSes), this requires a simple apt-get install python-mysql.

To configure the bot, copy irc_config.txt.example to irc_config.txt, and mysql_config.txt.example to mysql_config.txt 

me@puter: ~/bot/$ cp irc_config.txt.example irc_config.txt
me@puter: ~/bot/$ cp mysql_config.txt.example mysql_config.txt

Set the variables in irc_config to correspond to the channel that you want to log.

Set the variables in mysql_config to correspond to the database that you're logging to.

To install the tables in the database, run the command: 

me@puter: ~/bot/$ python LumberJack_Database.py

To run the logger, run: 

me@puter: ~/bot/$ python LumberJack.py

Notably, if you're running LumberJack on a remote server, you might consider sending output to a file, disabling 'hangup', and nice-ing it. 

me@remote: ~/bot/$ nohup nice LumberJack.py &

Step 3: Run the Client

The web folder in the download contains all of the code necessary to run the client.

Plunk the directory's contents down in a Apache server, one that's running PHP and PHP-MySQL.

To configure the client, copy config.php.example to config.php

me@puter: ~/bot/$ cp config.php.example config.php

Then, set the database details and default channel to mirror the bot's settings.

You should be GOOD TO GO! Try navigating to the client from the web!

What if I have problems?

Well, as of right now, you can e-mail them to me (curtis@lassam.net), and I'll try to figure them out, or ridicule you.

The Future

Here are some things to be addressed in future versions of LumberJack:

  • The Logger, Database, & JSON service all support logging of multiple channels, but the front-end provides no method to view anything but the default channel.
  • Things work very strangely (and often not at all) in Google Chrome.
  • With a MySQL database full of IRC data, stats gathering should be a breeze.
  • The ability to store & sync IRC preferences across multiple clients.
  • The ability to directly prompt the logbot to provide you, privately, with n lines of backscroll.
  • The development of another Bot, for feed, SVN, and GIT integration.
  • The ability to hide potentially embarassing or insecure chunks of information on request.
  • The ability to selectively ignore users from the client. (With this data saved in a cookie)
  • Stability. More of it.

License

LumberJack is released under a BSD license. Do whatever you want with it.

Copyright (c) 2009, Curtis Lassam

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Curtis Lassam nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY CURTIS LASSAM ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CURTIS LASSAM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.