mirror of https://github.com/nealey/irc-bot
124 lines
4.1 KiB
Plaintext
124 lines
4.1 KiB
Plaintext
bot
|
|
===
|
|
|
|
This is a simple C program to assist writing an IRC bot in whatever
|
|
language(s) you choose. It is based on the Unix principle that one
|
|
program should do one thing.
|
|
|
|
|
|
Getting Started Quickly
|
|
=======================
|
|
|
|
The example handler script, called `newmont`, will get you started right
|
|
away. It will set its nickname to `newmont`, join the channel
|
|
`#newmont`, and respond to any channel message containing the substring
|
|
"strawberry".
|
|
|
|
Start it like so:
|
|
|
|
tcpclient YOUR.IRC.SERVER 6667 ./bot contrib/newmont
|
|
|
|
|
|
What's Going On
|
|
===============
|
|
|
|
There are three pieces involved.
|
|
|
|
|
|
tcpclient
|
|
---------
|
|
|
|
`tcpclient' is a program that connects to a TCP port, sets file
|
|
descriptors 6 and 7 to be the input and output channels to that
|
|
connection, and hands off control to whatever program you specify (in
|
|
the example above, the `./bot` program with argument `./newmont`).
|
|
There also exist a `udpclient`, `sslclient`, and probably others. The
|
|
advantage to this method is that your network client doesn't have to
|
|
care about the transport mechanism: TCP, UDP, TCP6, SSL, or whatever
|
|
else.
|
|
|
|
Other programs which work this way include `socat` and BSD `netcat`.
|
|
Use whatever you prefer.
|
|
|
|
|
|
bot
|
|
---
|
|
|
|
`bot` reads one line at a time from fd6 (or 0 as a fallback), parses it
|
|
up, forks, sets some environment variables, and runs the "handler"
|
|
program provided as the first argument. Whatever that program prints to
|
|
stdout is sent back to the server, verbatim. As a convenience, it
|
|
automatically responds to PING messages from the server. It can also
|
|
rate-limit messages to the server, so your bot doesn't flood itself off
|
|
IRC. Lastly, it can monitor a directory and send the contents of any
|
|
new file to the server, deleting the file after. This allows you to
|
|
write to IRC from a cron job, git post-update hook, or whatever else you
|
|
dream up.
|
|
|
|
`bot` sets the following environment variables:
|
|
|
|
prefix you probably don't care about this
|
|
command IRC command or numeric
|
|
sender nickname to send "private" replies to this message
|
|
forum nickname to send "public" replies to this message
|
|
text command text, like what's sent to the channel
|
|
|
|
Any additional parameters of the message, like with the MODE command,
|
|
are passed in as arguments to the handler.
|
|
|
|
|
|
handler
|
|
-------
|
|
|
|
The handler is launched once for each incoming message. It should
|
|
decide what to do based on the environment variables and argv, possibly
|
|
writing something to stdout, and then it should exit.
|
|
|
|
Handlers are launched in parallel to each other. IRC is an asynchronous
|
|
protocol, and while messages do tend to arrive in a particular order,
|
|
don't count on it, especially with this framework.
|
|
|
|
`newmont` is a very simple handler script to reply to any PRIVMSG with
|
|
the substring "strawberry", in the (public) forum it was sent.
|
|
|
|
I don't provide any cool handler frameworks because I want you to enjoy
|
|
designing your own. It's not difficult, you can use any language you
|
|
want, and you don't even need to restart anything to apply your changes,
|
|
since a new handler is launched for each message.
|
|
|
|
|
|
factoids
|
|
========
|
|
|
|
A program to maintain a low-overhead, read-optimized database file, which
|
|
can store multiple values for each key. This was written to help develop
|
|
infobots, but can also be used for any other key/value store needed.
|
|
|
|
The `infobot.py` program in `contrib/` has a simple infobot implementation.
|
|
|
|
|
|
Caution
|
|
=======
|
|
|
|
Your handler is getting input provided by a potentially malicious
|
|
adversary. If you're not careful, you could create a remote exploit: a
|
|
path through your handler script that allows anyone on IRC to do
|
|
whatever they want on your local computer.
|
|
|
|
You can write handlers in bourne shell: it's really easy. It's equally
|
|
as easy to accidentally allow remote control. There's nothing I can do
|
|
in my code I provide to prevent you from creating a remote exploit, all
|
|
I can do is warn you.
|
|
|
|
If you're not confident in your mastery of bourne shell quoting rules,
|
|
you should build off of the provided lua example, which will make it
|
|
much more difficult to accidentally create an exploit. Or create a new
|
|
handler in Python, Ruby, etc.
|
|
|
|
|
|
Author
|
|
======
|
|
|
|
Neale Pickett <neale@woozle.org>
|
|
|