####################################################################### # Introduction # ####################################################################### IRCBNX Chatterbot is a moderation IRC bot based on the original Battle.net text gateway bot BNX Chatterbot. Like the original, it features a rule-based response system, an access system, and several moderation features. ####################################################################### # Installing # ####################################################################### If a precompiled version is available for your operating system, either extract the archive where it best suits you, or copy the executable, response.txt, and bot.ini to the desired location. ####################################################################### # Usage # ####################################################################### Once installed and configured, simply run "ircbnx" from the command line. NOTE: It will NOT produce output, but it should be working properly. Be sure to check "bot.log" for additional information. IRCBNX also has some command line flags: Usage: ircbnx [-hv] [-c config.ini] -h - Produces the above usage. -v - Queries the version of IRCBNX. -c - Specify a different configuration file (by default it's bot.ini). ####################################################################### # Configuration # ####################################################################### For simplicity and flexibility, the configuration file format is INI. Every IRCBNX config file must have a "global" section and a "profiles" key specifying a comma delimited list of bot configurations to examine. The log file may also be optionally specified with the "logfile" key. For example: [global] profiles=bot1,bot2 logfile=bot.log In this example, two bots, "bot1" and "bot2" are to be examined. Each bot profile listed in "profiles" references a section with the following configurations enabled - Whether the configuration is to be loaded or not (use 0 or 1). server - The hostname or IP address of the IRC server. port - The service or port number to use. nickname - The nickname to use. username - The username to use when registering the connection. realname - The real name to use when registering the connection. homechannels - A comma delimited list of channels to join. nickserv - The nickserv service name (if any). nickservpassword - The password to identify with the nickserv (if any). shitlist - The shit list file to use. seenlist - The seen list file to use. accesslist - The access list file to use. responserules - The response rules file to use. For example: [bot1] server=some.irc.network.com port=6667 nickname=enslay username=nslay realname=Nathan Lay homechannels=#ircbnx,#freebsd This example corresponds to the configuration of bot profile "bot1" as mentioned above. ####################################################################### # Access List Format # ####################################################################### The access list format is a line oriented list with <hostmask> <access level> <password> on each line. For example: ; This is a comment nslay!*@*.myisp.net 100 passwd enslay!*@*.theirisp.net 90 giraffe In this example, the first line allows anyone with nickname nslay and subdomains of myisp.net to authenticate with password "passwd". The second line allows anyone with nickname enslay and subdomains of theirisp.net to authenticate with password "giraffe". Access levels range from 0-100 where 100 is the bot owner. The granularity of control this sceheme offers is probably inappropriate but was copied from the original Battle.net BNX implementation. See section "Commands" for commands and their required access levels. Passwords are one word (i.e. no white space). Any additional words specified are ignored. Comments are limited. A line MUST begin with ';' to be considered a comment. Any other use is an error. ####################################################################### # Shit List Format # ####################################################################### The shit list format is a line oriented list with <hostmask> on each line. For example: ; This is a comment *!*@*.badisp.net *!*@*.anotherisp.net When the bot has channel operator status, it will ban anyone with subdomains of badisp.net and anotherisp.net automatically. Comments are limited. A line MUST begin with ';' to be considered a comment. Any other use is an error. ####################################################################### # Response Rule Format # ####################################################################### Response rules are groupings of regular expressions and possible responses. The format is as follows ; This is a comment P <rule1> P <rule2> ; Matching either of these rules produces one of these three responses R <response1> R <response2> R <response3> For example: P \bwho +are +you\b R Who I am is not important... P \bwhat\b.*\bare\b.*\byou\b P \bare\b.*\byou\b.*\bbot\b R I'm a BNX Chatterbot v1.0 In this example, anyone who asks it, "who are you?" will be met with the one possible response, "Who I am is not important..." If anyone asks it either, "What are you?" or, "Are you a bot?" will be met with the one possible response, "I'm a BNX Chatterbot v1.0" Comments are limited. A line MUST begin with ';' to be considered a comment. Any other use is an error. ####################################################################### # Commands # ####################################################################### Commands will be grouped and documented by minimum required access level. All commands are issued by directly messaging the bot. You must "login" to the bot prior to issuing commands, see "login" under "Level 0". *** Level 100 *** shutdown - Have all bots quit and exit. reconnect - Have the bot reconnect to the server. userlist - Display the access list. useradd <hostmask> <accesslevel> <password> - Add a new user to command the bot. userdel <hostmask> - Delete user from the access list. nick <newnick> - Chane the bot's nickname. *** Level 90 *** op <channel> <nick> - Give operator status to a user. deop <channel> <nick> - Remove operator status from a user. *** Level 75 *** chatter - Enable chattering. The bot will produce automated responses. This clears the squelch list. shutup - Disable chattering. The bot will no longer produce automated responses. join <channel> - Have the bot join a new home channel. part <channel> - Have the bot part from a channel. rejoin <channel> - Have the bot rejoin a channel. squelch <hostmask> - Ignore all users matching a hostmask. Users can still command the bot but it will not produce automated or CTCP responses. ignore <hostmask> - Same as squelch. unsquelch <hostmask> - No longer ignore users matching the given hostmask. shitadd <hostmask> - Add a hostmask to ban on sight. shitdel <hostmask> - Remove a hostmask from the shitlist. shitlist - List all shit listed hostmasks. *** Level 60 *** kick <channel> <nick> [<reason>] - Have the bot kick a user from a channel it has operator status in. ban <channel> <nick|hostmask> [<reason>] - Have the bot set mode +b on a given hostmask. If a nick is provided, it will search the channel for the hostmask. unban <channel> <hostmask> - Set mode -b on a given hostmask. splatterkick <channel> <nick> - Ban a user with one of twelve humorous sequences. voteban <channel> <nick> - Hold a 30 second vote on whether to ban a user. *** Level 0 *** login <password> - Login to the bot to issue commands. logout - Logout of the bot. No commands can be issued until you "login" again. say <target> <message> - Have the bot send a message to a user(s) or channel(s). The message may use "/me" or "/action" where - Have the bot tell you its current channels. who <channel> - Have the bot tell you the users in a channel it is currently in. seen <nickname> - Have the bot tell you where and when it last saw a user with nickname <nickname>. lastseen <channel> [<days>] - Have the bot tell you all users last seen in in a channel in the past day. If <days> is specified, the past <days> days. ####################################################################### # Miscellaneous # ####################################################################### IRCBNX exhibits some of the following additional behaviors: - It will shitlist users who kick it from a channel. - It will progressively warn, kick, and ban users flooding the channel it has ops in. - It will automatically logout users after 10 minutes of inactivity. - It will produce responses either when whispered or addressed in the channel (i.e. using its nickname in a message). - It will say "Hi!" when a second user joins the channel. - It will produce automated responses when there are only two users in the channel (including itself) regardless of being addressed. - It will ignore users who tell it to shut up (or variants of shutup). - It will ban users who address it with messages including "f**k" in the channel. - It will refuse to voteban itself. - It will ignore users who try to abuse its automated responses. - It will periodically try to join channels it was kicked or banned from. ####################################################################### # Building from Source # ####################################################################### To build IRCBNX from source, you will need CMake, a C++ compiler, and the following dependencies: - PCRE (required for Windows, optional for Unix-like systems) http://pcre.org/ - libevent2 http://libevent.org First extract the IRCBNX source somewhere. Next create a separate directory elsewhere. This will be the build directory. Run CMake and configure the source and build directories. More specifically On Windows: - Run cmake-gui (Look in Start Menu) and proceed from there. On Unix-like systems: - From a terminal, change directory to the build directory and then run: ccmake /path/to/source/directory In both cases, "configure" and then specify whether you want to enable PCRE (recommended), the location of the libevent headers and libraries, and the location of the PCRE headers and libraries. Next "generate" to generate the build system. Visual Studio: - Open the solution in the build directory you created and proceed. Unix-like systems: - Run make(1). IRCBNX is known to build in the following environments: FreeBSD 10.0: - Clang 3.3 FreeBSD 9.1: - GCC 4.2 - Clang 3.1 CentOS 6.3: - GCC 4.4.6 Windows 7: - MingW64 4.5.3 - Visual Studio 2010 - Visual Studio 2012