Grufti is a project mainly written in C and SHELL, it's free.
Grufti, an IRC bot
Grufti1.0
by Steve Rider - [email protected] (and many others who continue to provide support and feedback)
Special thanks goes to Andreas Bieri ([email protected]) and Erin Heinemeyer ([email protected]) for giving me the continued inspiration to keep this project going! Lots of late nights at the Frontier babbling about code and ideas have contributed to many of the cool features that you see here. Erin came up with the idea of having a bot named Grufti way back in 1993, and we've all had a lot of fun with it ever since.
SOURCE Source code for Grufti can be found at http://grufti.com or ftp grufti.com:/pub/Grufti
Introduction
Documentation
Upgrading from a previous version
Compiling and installing grufti
Summary of features
The config.gb configuration file
Maintaining your bot
Responses
Changes
What Next?
This directory and its descendants contain the sources for Grufti, a service-oriented bot for the IRC network. The information here corresponds to version 1.0, the first public release of Grufti.
The best way to get started with Grufti is to become familiar with the directory structure, and the help file found in etc. Every command is documented there as well as major topics like Grufti accounts and how to configure responses. By browsing through the help file you'll be able to get an idea of the scope of Grufti and what kinds of things are possible.
This README file will try to explain some of the concepts Grufti relies on, a little more detail on bot organization, and how to compile and how to configure the bot.
If you are upgrading from a previous version of Grufti, you will need to do the following:
Grufti supports an install script, and if the install directory is given as one from a previous version, the script will rename certain files with the .old extension, and will not overwrite your vital bot files.
Once the compilation and installation has been achieved, you will need to edit config.gb. Since new changes may have been made to this file, it is to your advantage to start over with this new config.gb while looking at the changes you made in the old one. The old config will have been renamed to config.gb.old.
At this point, all your bot files should be intact, and the new version will be in place and ready to go.
This release contains everything you should need to run a Grufti under most major UNIX's. It even contains the source code for creating a CGI executable. This can be triggered from a web page to provide a web-interface for your bot. Setting it up will require you to edit webconfig.h. With web access enabled, users can edit responses, send, manage, and read Notes, check who's on any of the botted channels, view info on other Grufti users, setup their Grufti account, and more. It's cool, try it.
To run through the entire installation including machine configuration, compilation, and installation, type
make installThis will perform all 3 steps needed in a complete installation. If you want a little more control, or are planning on editing the Makefile before compiling, use "make config" to configure the bot, "make" to compile the source code and finally "make install" to install all components and create the necessary bot structure.
If all goes well, the bot will have been compiled and the install script will have created a directory ready to run your bot.
Change to the new bot directory and see section 6 to find out what you need to do to get your new bot up and running.
If you want to use the CGI for web page access, you will need to edit the webconfig.h file to establish the appropriate settings.
Build and install the cgi by typing
make install-cgiThis will compile the CGI and install it to the directory specified.
NOTE: If you make any changes to webconfig.h, you will need to recompile and reinstall both the main bot and the CGI.
To save space, you can type
make cleanto remove intermediate object files and executables.
Skip the next part if you are not interested in compiling optional modules into the bot.
A DEFINES line is provided in the Makefile to control what is compiled into the bot. The DEFINES values currently supported are
-DWEB_MODULE -DRAW_LOGGING
The define -DWEB_MODULE is defined by default. If you know that you will not be using the web area, you can undefine this to save some space. If you define or undefine anything in the Makefile, be sure to do "make clean", then "make" again.
Specify -DRAW_LOGGING if you plan on logging raw server and DCC interaction. Most likely you won't need this, and #define'ing it out helps a little on overhead.
Troubleshooting: If you CAN'T get the bot to compile, I can try and provide some help, although I don't have access to TOO many types of machines. Just give me a detailed listing of the errors you encountered during the compile, and what OS and machine type you're using. Most likely the errors will be in the configure script not operating properly (I still can't get configure to recognize gcc on bloody IRIX systems), or the source not using the config.h settings in the proper way.
The design goals that went into Grufti were that it use little CPU overhead, be highly usable, highly customizable, and provide a really nice looking user-interface. A lot of time was invested in making the bot as easy to use by normal IRC users as possible. It's really like a BBS and provide services more for the channel regulars than to maintain channel integrity like modes and such. Priority was really given to implementing as many useful features as possible but keeping it simple and easy to use.
Here are a few of the design points of interest:
Object-oriented design and data abstraction: Even though the code is still in c for portability reasons, a lot can be borrowed from c++ and its idea of objects. In Grufti 1.0, major components exist as objects such as Grufti, Server, Channel, Response, DCC, User, Command, and Codes. These objects know about the data they hold, and can make educated decisions depending on different states of the system. One object may query the Server object, for example, to determine how the bot is connected, what state the connection is in, etc.
Better searching algorithms: Unlike most bots, Grufti stores information on every user it sees across the channel. This database of users can be large. Grufti sees about 5,000 unique people per month on his current channel. Grufti 1.0 uses techniques like move-to-front algorithms to decrease run times for searching the lists. A good deal of cross-referencing is used which allow routines to find the information from the database directly, instead of resorting to expensive database lookups.
Statistics: Grufti 1.0 is designed from the ground up to keep track of lots of neat information about channel and server usage, and users. Average channel size, user usage time, top usage can all be monitored. A nightly report of daily statistics can be configured and sent to bot owners via Grufti Notices.
Better use of account identity: Instead of users existing as ever-changing hostmasks, users exist as 'accounts' on Grufti. IRC nicks can be added and deleted from the account and personal information can be set. 'Noteboxes' are central to an account, and users exist as one entity so that if you are on IRC and have been informed of new Notes, you will not be informed again if you connect with one of your other nicks.
Notes: One of the prime features of Grufti is the ability to send and receive Notes from other IRC users. Since Grufti accounts are setup in such a way that one user can have many alternate nicks, sending a quick Note to a user is just a matter of remembering any nick which belongs to their account. The Note 'read' and 'send' commands have been designed to make them simple to use. Many Grufti users rely on them, and find themselves checking their Grufti Notes as often as they check their email. With the latest release, users can have their Notes forwarded to an email address automatically! See help on 'setforward'
Customizable account information: Users with Grufti accounts can set a lot of personal information which can be viewed by other IRC users. This information includes email address, web address, location, finger info, plan info, and the nicks which they are known by on IRC. There are also 10 other slots, which can contain information of any type. Some people use them to display favorite music, hobbies, phone and pager numbers, and other unique, interesting things. The location field is unique in that it allows users to use a command to view all the users who live in a certain region, like Germany, or the SF bay area.
Secure method of password and verification: Grufti1.0 keeps track of verification in the DCC records. If the identification occurs via DCC, the session is considered 'secure' and a password will not have to be sent again until the DCC connection is disconnected. Grufti also requires passwords to gain access to accounts, and for receiving ops by the bot. This greatly improves security compared with the traditional method of verifying users by hostmask.
Tracking of users via USERHOST: This allows Grufti to watch users on IRC, not just on the channel. Users can then be informed of new Notes when joining IRC. The 'seen' command also makes use of this feature by indicating if the user can be found on IRC somewhere. The 'finger' command also makes use of this feature by displaying a list of users known to the bot that are currently online or connected via DCC or telnet, in much the same was as the unix 'finger' command.
Programmable response matching: Configuring a bot to say certain things on a channel defines its personality, and can make the bot a lot more fun to have around. A well-configured personality can make the bot enjoyable for years. The Grufti which sparked all of this has been around since 1993, and is well-known for his fun-loving personality! Grufti 1.0 allows responses to be matched using fall-through AND/OR logic, and allows for response exceptions, so that by specifying an except line of "this mortal coil" in the Coil response won't match Coil when someone asks the bot to sing This Mortal Coil. All this provides a powerful way to program responses. I have been amused more than once watching new people to the channel carry on a small discussion with the bot thinking it was a real person. Responses can also be programmed on the fly, and levels can be given to users which allow them to program responses into the bot as well.
These are just a few of the main features. I think you'll be pleased with all the little frills which have been added. This bot is designed to be useful, easy to use, look nice, and not be a nuisance, and I think it lives up!
At this point, your bot is probably compiled and waiting, and you're wondering what to do next.
Overrall bot configuration is done using the config.gb file. (If you don't like the name of this file, you can change it in grufti.h) This is where you will setup your bot's nick, the channels it will reside on, file locations, the servers it will use, and the many variables you can tweak to make the bot work exactly the way you want.
The config file is organized into the following main areas:
Bot identity Files and Locations Logs Channels Servers Command level redefinitions Response types
The nick, username, and realname entries in the 'Bot identity' area MUST be set. Everything else past that is optional, however, you probably don't want the bot sitting on #grufti for the rest of its life.
Go through the config file, and edit the appropriate lines as necessary. Config lines should be self-explanatory. As you learn more about the bot, you will understand more of what some of the configurations do. But for now, the parts you will need to focus on are in Channels, Servers, and Logs.
In the Channels area is where you will set up the channels on which your bot will reside. You can have the bot enforce channel modes on your channel, specify what the channel topic should be, and whether it should be enforced or not. Notice that even though the modes +k and +l (key and limit) are considered 'modes' on IRC, Grufti treats them separately since they have arguments. As a result, if you try to specify +k and +l in the 'mode' setting, they will be ignored. Use the 'key' and 'limit' settings to configure keys and limits. Look at the examples for #mychannel to see how channel modes can be set. Specifying 'force-' in front of any mode causes that mode to be enforced.
The Servers area is next, and you should set up your servers of preference. (Or any servers that will actually allow you and your bot). The servers will be loaded in the order they are listed in the configfile, so you should put the primary servers first in the list. While the bot is running, you will use the 'jump' command to jump between the servers in the list.
Finally, the Logs area, which is located before the Channels area (we need to setup the logs as fast as possible so we know where to log config errors) should be configured. The public logs for
to reflect the channel(s) on which your bot will reside.
So you've got your bot up and running, and you want to know what all you can do with this thing.
Running the bot for the first time with no userlist will prompt you to enter the username and password for your account. After this, the bot will go into the background and you will find him waiting on the channel(s) specified in the config.gb file. If you haven't configured the telnet port to something else, you can interact with the bot via telnet by telneting to the bot's hostname at port 9000. (telnet hostname 9000) This is the preferred way of doing a lot of interaction with the bot. You should also check out the gb_cmd.zip file, found in the files directory. It contains gb.c, which can be compiled to give you an executable that will interact directly with the running bot from the UNIX command line. This is very handy for doing bot interaction as well. This file must be edited to provide an interface for your bot. Once you edit gb.c, your users will be able to download it from the files directory with the command 'send', and it will allow them to access your bot. Right now its setup to access a nonexisting bot, and you will probably get the error "pipe broken" when trying to run it.
This version of Grufti uses the \n translation modifier in the help file which translates to the bot's nick, so it should be general enough for your bot. You should still run through it and update any web pages, etc specific to your bot. Remember, this is your bot, so you can have the help file say anything you want! If you don't like the main help screen, change it!
The following topics will help you in getting started. Help can
be found on any command listed here by typing 'help
Adding users and levels:
Users can be added to the bot in 2 ways. Either you can
wait for the user to register him or herself with the bot,
or you can add them with the 'adduser' command. Either way,
you can only setup levels for users who have accounts on the
bot. To view account information, use the 'finger' command.
More help is available on account personalization by typing
'help account'. Users can get information on registering
by simply DCC chatting the bot. (If the bot seems to be
ignoring DCC chat requests, tell folks to try /msg
You will want to do 'help levels' to see all the levels a
user can possibly have. Notice that your account is given
the +m level, for master. Adding and removing levels is
accomplished with the 'mode' command. You will become very
familiar with it.
The level +b should be given to any other bots on the
channel, including yours. It keeps bots from getting in
bot wars by not taking action against things bots do on
the channel.
The level +o allows users to get ops on the channel by using
the 'op' command, or whenever they use the 'pass' command.
The level +g has the bot greet the user whenever they join
the channel. Users can set their own greetings with the
'addgreet' and 'delgreet' commands. Greets can be displayed
with 'showgreets'.
The level +f and +p are self-explanatory. The level +l
allows users to program responses directly into the bot.
Only give people you trust this level! Bot personality is
a delicate thing.
The level +3 is not really yet defined. It's more of a
status symbol which can be used for mark long-time users
and those with high standings on the channel.
The level +t is for trusted users which are allowed
to do things like have the bot jump servers, leave and
rejoin the channel, hush, etc. Users with +t are general
administrators, but who probably don't have access to the
machine on which the bot runs.
The level +m specifies the user is a master. Users with
+m can do any command regardless of the levels required.
Generally, users besides you who have +m are those who have
direct access to the machine on which the bot is running.
They'll be the people who check to make sure the bot is
running and if not can restart him, etc.
Finally, the level +n allows users with that level to receive
Grufti Notices whenever certain things happen with the bot.
You should probably give yourself this level along with
other +m users who are actively administrating the bot,
since it will let you and them know what is going on with
your bot at all times. One of the Notices it sends is
whenever a user registers with the bot. There is an area
of config.gb which deals with Grufti Notices, and you can
setup which events trigger or don't trigger a Notice.
The best way to get started is to have as many users register
themselves with the bot right away, giving them levels as
they register.Overriding command level requirements: To change the levels required for any command, edit the config.gb file and look under the section "Command Function Level Redefinitions". The commands currently listed are only a few of the commands which can be reconfigured. Any Grufti command can be overridden simply by specifying the name of the command and the new levels it will require. You will need to shut down and restart the bot for any changes made to have effect. Eventually I'll have a 'rehash' command which will do just that.
Monitoring logs: If you haven't become familiar with the logs in the logs directory, you should do so. This is where all the logs you specified in the config file are written. You will find a lot of useful information in these logs, like why servers aren't connecting, any errors detected in the config.gb file, etc. It is a good idea to check these logs every so often to make sure that everything is running as expected, especially the error log. I give each one a quick run-through every day to look for anything out of the ordinary. Also, in the (hopefully) unlikely event that the bot CRASHES, you can find the line # and file the bot crashed at, information I'd be interested in knowing.
A handy unix utility for monitoring logs is the 'tail'
command. Use it in the form
tail -f <logfile>
to watch the latest changes to the file be written directly
to your screen.
Another way to monitor logs is by using the 'watchlog'
command.Shutting things down: The bot is programmed to intercept kill signals, and will shut down when receiving a QUIT, HUP, or TERM. The normal way of shutting down the bot is to use the 'die' command on the bot, or by running the executable with the switch -k. The switch -k actually sends the kill signal USR1 to the bot. The bot intercepts it, signs off IRC, writes all its files, and exits gracefully. This is called a Soft Kill. Notice that if the bot is still waiting to sign off IRC (it could take a while), you can use the -k switch again, which will tell the bot that you don't care if the IRC server has acknowledged its QUIT request, and the bot will write all files and exit immediately.
The only difference between the bot receiving a HUP, TERM,
or QUIT signal and a USR1 signal is that the bot doesn't
sign off IRC with the QUIT signals. The connection is just
closed, and the bot will show a Connection reset by peer,
or Read error when this happens instead of signing off with
a normal message. We do this to make sure the bot can get
the hell out of there fast and write all of its bot files
since a QUIT, HUP, or TERM signal is usually given right
before the machine goes down!
In the unlikely event that you want to have the bot shut down
WITHOUT writing the botfiles, you would use the switch -x,
called a Hard Kill. This is not recommended at all.
So, the typical way to shutdown the bot is by using the -k
switch after the executable, or via the 'DIE' command.Setting up the MOTD and the telnet banner: In the etc directory, you will find a file called motd, and one called banner. These should be customized for your bot.
Summary of master commands: The following commands are used to keep the bot running smoothly, like adding new servers to the server list, and viewing bot resources.
watchlog - Use this command to monitor logs directly from
a DCC chat or telnet connection.
mode - Use this command to change levels for a user.
adduser - Use this command to add a user to the bot.
deluser - Use this command to delete a user from the bot.
chpass - Change the password for a user. Useful when a
user forgets their password.
leave - Have the bot leave the channel for a specified
amount of time. Handy when trying to resynch a
channel. Note that the bot will automatically
cycle the channel if he finds himself the only
member on the channel and he doesn't have ops.
join - Have the bot rejoin a channel he has been asked
to leave.
hush - Have the bot 'hush up' on the channel for a
specified amount of time. Sometimes, a bot can
be annoying if it talks too much. This is how
you can keep people from getting overly upset :>
unhush - Have the bot return to normal operations.
jump - Use this command to connect the bot to a
different server in the serverlist. If no
server is specified, the bot will connect to the
next server in the list.
addserver - Add a server to the serverlist. Note that this
doesn't write it to config.gb.
delserver - Delete a server from the serverlist. Handy for
when a server becomes unreliable, but you don't
want to remove the server permanently.
servinfo - Display a listing of all configured servers.
If the -r switch is used disconnect reasons are
displayed.
configinfo - Displays the values of all internal variables.
setvar - Sets an internal variable. This is handy again
if you want to change a value temporarily.
meminfo - Display the total memory used by the bot.
cmdinfo - Dispays all commands and required levels. The
required levels for any command can be overridden
in config.gbConfiguring a bot to say certain things on a channel defines its personality, and can make the bot a lot more fun to have around. A well-configured personality can make the bot enjoyable for years. The Grufti which sparked all of this has been around since 1993, and is well-known for his fun-loving personality! Grufti 1.0 allows responses to be matched using fall-through AND/OR logic, and allows for response exceptions, so that by specifying an except line of "this mortal coil" in the Coil response won't match Coil when someone asks the bot to sing This Mortal Coil. All this provides a powerful way to program responses. I have been amused more than once watching new people to the channel carry on a small discussion with the bot thinking it was a real person. Responses can also be programmed on the fly, and levels can be given to users which allow them to program responses into the bot as well.
In the example response file given, there are currently 5 predefined response types. They are:
internal, lyrics, url, private, and publicThese types were configured in the 'Response Object Definitions' section of the config.gb file. These types group the responses under similar subjects. For example, the 'lyrics' type is setup to check all the lyrics responses whenever the word 'sing' and the bot's nick is found in public chatter. The 'private' type is setup to check all the private responses whenever the bot's nick is found in a message. The private types are useful when you want the bot to be the subject of a particular message (ie. "hi Grufti!"). The 'public' type on the other hand checks every message regardless of whether the bot's nick is in the message or not. Be careful which responses you enter under the public type, as all text is checked for matches. It could get real annoying if an everday word triggers one of your public responses.
A pretty decent example of configuring responses is given under the help topic 'response'. As a side note, it will probably be a LOT easier to edit the response file manually when you're first settings things up, since programming responses into the bot directory is cumbersome at best. Just make sure the bot is not running while you're editing the file, or you're likely to lose changes.
As of version 1.0.08b, the access users have to responses can be restricted to specific response types. There are two types of users who can edit responses. Those who have +l, and those who have +L. Look in the config file for more details. As an example, the default allows users with +l to access (edit) "lyrics" and "url" responses, while users with +L can access any type of response.
The main reason why response commands were implemented to edit responses in the first place was to give users who DIDN'T have access to the machine on which the bot was running the ability to program responses and lyrics into the bot, not as a convenient tool for adding responses yourself. Maybe someday I'll find an easier solution. But for now, this is acceptable. Besides, I have the web page all set up for editing responses which is even easier than editing by hand, and any user with +l can do it from the page!
You'll notice there is no 'reload' command. A reload command is very dangerous since reloading a bot file will wipe out any changes made to the internal databases. Being able to do this kind of goes against the design I had for Grufti, one of which was that the integrity of the bot be very stable, and that a high priority is given for keeping the datafiles intact.
By looking at how the example responses are set up, you should be able to figure out how responses are matched, and go from there.
From this point on I will be keeping track of all changes made to the bot, since this is the first real release. I hadn't really been doing changes before since there were gaping holes that I needed to fill, things I had wanted to do with the bot from the very beginning and have only now gotten to. I am pleased to say though that this release encompasses nearly every feature I wanted to see in a Grufti. There are only a few minor details I need to attend to, but all the major functionality is there. As I come up with more ideas, I will work my way up to the next major release of 1.1. In the meantime, expect to see intermediate releases which will be bugfixes, or small changes. I have no doubts that I can keep the bot files format the same, so that any version of Grufti will be compatible with bot files written by any other version.
Since this is a pre-README, I will no doubt incorporate popular questions and possibly a FAQ into the next release...
Bedtime!
Thanks for reading this far! Grufti has been a lot of fun to work on, and I hope you have just as much fun running yours as I do mine. Feel free to check out the REAL Grufti, who watches
Send me a line at [email protected]
Have fun!