mirror of https://github.com/nealey/irc-bot
105 lines
3.5 KiB
Plaintext
105 lines
3.5 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.
|
|
|
|
This framework gives you plenty of opportunity to shoot yourself in the foot.
|
|
If you're not a seasoned programmer, please stick to a language like Python or
|
|
Lua for your handler. Leave the arcane trivia of proper Bourne Shell quoting
|
|
rules to the seasoned experts who've learned the hard way how to do it.
|
|
|
|
|
|
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.
|
|
|
|
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 IRC line 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 text of this message, 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.
|
|
|
|
|
|
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 the
|
|
code I provide to prevent you from really hurting yourself, all I can do is
|
|
warn you.
|
|
|
|
|
|
|
|
Author
|
|
======
|
|
|
|
Neale Pickett <neale@woozle.org>
|
|
|
|
|
|
|