Eggdrop Tcl Archive

Extended Description File

Mailbot - IRC messaging system

Frequently, IRC channels are used as a collaboration tool.
Due to the real-time nature of IRC, it is hard to keep up with events
when you are offline. The Mailbot script solves that problem.
It provides a unified messaging service in form of an interactive IRC bot.
Users are able to post to messages to channels, for other users to come
and read them later. As well, the script allows the users to send private
messages to each other. This is useful in cases where the recipient is not
online, yet a message be sent to him/her (just like offline messages
in ICQ).
The service is implemented as a TCL script for eggdrop.
It uses sqlite for the backend database storage, and AES for encryption.
It has extensive search capabilities.

::Sections::

   1. Example Scenario
   2. Installation
         1. Installation of the Prerequisites
         2. Installation of the TCL Script
         3. Configuring the Mailbot
   3. Working with Mailbot
         1. Initializing the Database
         2. User Authentication and Authorization
         3. Sending and Receiving Messages
         4. Searching Messages
         5. Adjusting Time Zone Settings
   4. Download
         1. Subversion
         2. Changelog
   5. References

::Example Scenario::

This scenario presents a typical usage pattern of the bot: users posting
messages, and other users reading them at a later time.
Suppose we have a channel #cooltalk, with 3 regulars: Bob, Alice and Jeff.
Users Bob joins channel #cooltalk, & posts an announcement using the bot:

    (in #cooltalk)
    <Bob> !mail add Hey guys! I will be away next week so please forward
          all your concerns about the project to Jeff.
    <MAILBOT> Message number 1 posted to channel #cooltalk.
     * Bob has left the channel 

At this point, the mail bot stores the message in the pool for channel
#cooltalk, so other users can read it.

Now, a bit later, Alice joins #cooltalk. She receives a private message
from the mail bot telling her that she has unread mail:

    (in private query with MAILBOT)
    <MAILBOT> You have unread mail.
    <Alice> !mail read
    <MAILBOT>   MESSAGES TO #cooltalk  
    <MAILBOT> 1. 26.10.2007 15:42:27 Bob: Hey guys! I will be away next
       week so please forward all your concerns about the project to Jeff.

Then, Jeff joins the channel and reads the same message.  He has a
personal question to Bob about the project. However, Bob is offline.
So, Jeff sends a private message to Bob using the mail bot
(in private query):

    (in private query with MAILBOT)
    <Jeff> !mail send Bob Listen Bob, there was a problem with the
           project. The database is corrupted.
    <MAILBOT> Private message number 7 sent to user Bob. 

Bob, an incurable IRC addict, joins IRC but wants to stay away from
#cooltalk so no one bothers him.
However, he can still interact with the mail bot:

    (in private query with MAILBOT)
    <Bob> !mail read
    <MAILBOT>   PRIVATE MESSAGES  
    <MAILBOT> 7. 28.10.2007 11:12:55 Jeff: Listen Bob, there was a
              problem with the project. The database is corrupted. 

::Installation::

The installation of the script involves the installation of the
prerequisites (tcllib, sqlite), the actual TCL script, as well as
tweaking the configuration files.
Installation of the Prerequisites

Mailbot requires the following prerequisites:
                           Tcllib and the SQLite TCL bindings.
Tcllib comes standard on recent Tcl installations.
Specifically, mailbot uses the aes, base64, and crc packages from tcllib.
So, if you do not want to bother install all of tcllib, you can just copy
the directories of those packages and include them in the eggdrop
configuration file for your bot (described in detail later).
The SQLite TCL bindings are required so the mailbot script can use sqlite
databases. The script has been coded against version 3 of sqlite.
Typically, the name of the bindings library is libtclsqlite3.so on UNIX,
and something like tclsqlite3_5_0.dll on Windows.
There is a commercial version of SQLite that allows databases to be
password protected. Such version is not needed for the mailbot, as it
implements its own encryption layer on top of the free version of sqlite
using tcllib's aes and base64 packages.
If you have trouble loading the sqlite bindings binaries into your bot,
and receive weird error messages like
   tclsqlite-3.5.1.so: undefined symbol: sqlite3StrICmp
then you should probably download the source code to sqlite, compile it
yourself, and use the libtclsqlite3.so.0.8.6 binary instead
(it should compile into the .libs directory in the sqlite source tree).
Installation of the TCL Script

This step describes how to install the actual mailbot TCL script into
your eggdrop bot.

   1. Unpack mailbot-1.01.tar.gz into eggdrop/scripts. This will create
      eggdrop/scripts/mailbot-1.01 that will contain the TCL files.
   2.

      Edit the eggdrop configuration file for your bot:
           include the sqlite module and the script:

      #
      # Load the sqlite TCL bindings module.
      # N.B. Read the 'Installation of Prerequisites' step above in
      #      detail, if you encounter errors when executing this line.
      #
      load libtclsqlite3.so

      #
      # Include the tcllib prerequisites.
      # If you have the Tcllib normally installed, you may replace
      # these with 'package require' lines instead, like so:
      #
      #   package require aes
      #   package require base64
      #   package require crc
      #
      # Though, source lines work just as well :P
      # Just be sure to adjust the paths to suit your system.
      #
      source tcllib1.10/aes/aes.tcl
      source tcllib1.10/base64/base64.tcl
      source tcllib1.10/crc/crc32.tcl

      #
      # Finally, include the mailbot script.
      # N.B. The scripts/ subdirectory is relative to your location
      #      of your eggdrop binary.
      #
      source scripts/mailbot-1.0/mailbot.tcl

::Configuring Mailbot::

   1.

      The mailbot package comes with two TCL files:
          - mailbot.tcl - the actual code,  and
          - mailbot-options.tcl - the configuration file for the script.
            It is included into mailbot.tcl by mailbot.tcl on line 13.
            It contains 2 variables that you should change
             - the path to the database file which will store all the
               messages, as well the top-level command that access the
               mailbot functionality.
               This is usually set to !mail or !news.

      ####################################################################
      # mailbot-options.tcl - options for mailbot.tcl
      ####################################################################

      #
      # Path to the database file
      #
      variable db_path "/home/comrade/eggdrop/mail.db"

      #
      # Public access command name
      #
      variable pub_cmdname "!mail"

   2. Copy blank.db to the database path that you specified above,
      and make the file writable.


This concludes the installation.

::Working with Mailbot::

This section deals with interacting with the mailbot script once it is
up and running on top of an eggdrop bot.

Initializing the Database

Upon running the bot, the mailbot script needs to be initialized by a
bot administrator (anyone with +m or +n flag on the bot).
This is done by messaging the bot in private:

    (in private query with MAILBOT)
    <BotAdmin> !mail init 0 bigapple.
    <MAILBOT> Database not initialized: checksums do not match.
              The correct checksum for bigapple is 243.
    <MAILBOT> NOTE: Initializing the database with the incorrect password
              can inflict irreparable damages. Please double-check the
              password or the checksum for typos.

    <BotAdmin> !mail init 243 bigapple.
    <MAILBOT> Database initialized. 

This step is necessary to keep the database password out of the
configuration file. If the password would be hardcoded anywhere in the
configuration or the script, anyone with shell access can find out the
password.
Note: this step has to be repeated every time the bot is
      rehashed or restarted.
The purpose of the checksum is to prevent typos.
If you would like to skip this step, and hardcode the database password
into the configuration file, you may add the following line to the
end of mailbot.tcl:

#
# Automatically initialize the database with the password 'bigapple'.
#

mail::initialize "bigapple"

Be aware of the security risks associated with doing so.

::User Authentication and Authorization::

The mailbot script uses the built-in eggdrop userbase to authenticate
users. The user's handle on the bot is used as the user's name when
posting messages.
A user's channel access is determined by the user's channel record on
the bot. Any user with a +v flag on the channel is allowed to
send/receive messages from that particular channel. However,
private messages can be sent/received by the user without any particular
channel access records.
Superusers are the users that are able to initialize the database.  Any
user with a +m or +n global flags on eggdrop is considered a superuser.

::Sending and Reading Messages::

To get help on sending, and reading messages, please invoke the help menu
from the bot directly by typing !mail help
(substitute !mail with your own command if you changed it).

::Searching Messages::

The mailbot script features extensive search capabilities with many ways
to filter the results. The search feature can be accessed through the
!mail search [filters] [keywords] command.
Keyword matching is case-insensitive.
The possible filters are:

1. -before:YYYY-MM-DD to search only messages before a specific date.
2. -after:YYYY-MM-DD to search only messages after and including a
    specific date.
3. -ago:num_days to search only messages from up to num_days ago.
4. -from:user to search only messages sent by the user user.
5. -to:channel to search only messages sent to the channel.
6. -any to make the filter match any one of the keywords from the list.
    if not specified, all keywords must be matched.


Examples:

 * !news search -before:2007-11-01 -after:2007-10-01 -from:leonidas
   this is sparta
      -> searches for all mail for the month of October 2007, sent by
         leonidas, and containing all of the keywords this, is and sparta
         (not necessarily in that order).
 * !news search -any color flavor
      -> searches for all mail containing either the keyword color,
         or the keyword flavor.
 * !news search -to:#cooltalk database
      -> searches for the mail sent to channel #cooltalk containing
         the keyword database.

::Adjusting Time Zone Settings::

You can adjust the local time zone with the
!mail timezone <+/- minutes> command.
The offsets are relative to the bot's local time (unfortunately, TCL does
not provide UTC time, so the offsets are guesswork unless you know where
the bot is). For example, if the bot displays times that are 1 hour ahead
of my time, I would simply type !mail timezone -60 to make the adjustment.
The offset is in granularity of minutes, which makes it compatible
with Venezuela.


Download:
mailbot-1.01.tar.gz (8 KB)

Older versions:
mailbot-1.0.tar.gz (8 KB)

The project is released under the BSD license.

Subversion:
The subversion repository for the project can be accessed here:
   http://mailbot.svn.sourceforge.net/viewvc/mailbot/.

Changelog:
The changelog can be also be accessed here:
   http://mailbot.svn.sourceforge.net/viewvc/mailbot/trunk/?view=log.

------------------------------------------------------------------------
r4 | comrade64 | 2007-11-01 01:31:59 -0400 (Thu, 01 Nov 2007) | 4 lines

version 1.01:
- fixed aes encryption oddity on some strings
- fixed bold irc string escaping on some strings

------------------------------------------------------------------------
r2 | comrade64 | 2007-11-01 01:29:32 -0400 (Thu, 01 Nov 2007) | 1 line

initial import of mailbot-1.0

::References::

* Mailbot SF.net Project Page - mailbot at sourceforge.
* Eggdrop - The official home of Eggdrop development and the Eggdev team.
* SQLite - The official homepage of SQLite, the embedded database engine.
* Tcllib - Core development home for the tcllib standardized Tcl library.