100 IRC Hacks - BitlBee
This is going to be a hack in the upcoming O'Reilly title 100 IRC Hacks. Since the contract I have with them says the copyrights stay with me, and since this might actually be quite a useful document to some people, I decided to put it on the site. You'll have to wait until June 2004 if you want to read this all (actually, a lot more than just this single hack!) on paper instead.
More than just IRC / BitlBee
You might feel very comfortable with IRC, but some others don't and prefer to stick with networks like ICQ or MSN. There is a way to get in touch with those people.
You don't have to install a separate program for chatting with ICQ/MSN/AIM people anymore. There is a program which allows you to talk to all these people through your IRC client. This program is called BitlBee. Fortunately, using this program is a lot easier than spelling its name correctly.
BitlBee simulates an IRC server with one channel. All your buddies will join the channel so you can talk to them. You can install BitlBee on your own machine, but if you don't want to, or if you just can't, you can also use someone else's BitlBee server.
This hack will tell you how to install and use BitlBee. If you don't want to install your own BitlBee, you can just skip that section.
Note: Many people wonder where the name BitlBee came from. Some even assumed it'd probably've had something to do with drugs. Although the authors are Dutch, which highens that last probability, BitlBee was just a name derived from "Little Bee". Some people also refer to it as 'The Bee'. Most important was for it to have a unique name, so finding it with Google would be easier.
Installation
BitlBee is available for a number of different platforms. The authors use it on Linux machines, but the program also works on several other Unix platforms. Even AmigaOS and Windows ports are available, though not supported by the authors. Support for some IM-protocols might be missing.
The easiest way to install BitlBee on your machine is probably through the packaging system. apt-get, emerge, or get it from your BSD ports tree. Most packages do all the hard work for you, so after installation you can skip the rest of this section and read more about how to use BitlBee.
If there is no package available for your platform, or if you just don't like packages, you can, of course, also install BitlBee from source. First, get the source from the site (http://www.bitlbee.org/).
Then, unpack the tarball, run the configure script, make (remember to use GNU make on BSD systems!) and make install. This will install all the program files on your machine.
Configure might complain about missing dependencies. At the time of writing, BitlBee needs recent versions of glib and GnuTLS to work completely. Of course, later versions of the program might have different dependencies.
BitlBee is not a daemon on its own, it depends on something like inetd to talk to your IRC client. Add a line like this to /etc/inetd.conf:
ircd stream tcp nowait nobody /usr/local/sbin/bitlbee bitlbee
And make inetd reload the configuration files. You can do this by sending the HUP signal to the inetd process, for example by running /etc/init.d/inetd reload
If you run xinetd, like most people do these days, you have to copy the doc/bitlbee.xinetd file from the BitlBee source directory to /etc/xinetd.d/ and send a HUP signal to xinetd.
Of course, if you installed BitlBee to a different location, you shouldn't forget to put the correct path in the (x)inetd file! Also, if you're already running an IRC server on your machine, you probably have to change the port number BitlBee listens on. Please read the (x)inetd documentation if you don't know how to do that.
Using BitlBee
If you installed BitlBee on your own machine, you can connect to it now. In most clients, all you have to do is type "/connect localhost". Or a different hostname, if your BitlBee is running on a different machine on your network.
If you decided not to install BitlBee but use an external BitlBee server, please visit the site (http://www.bitlbee.org/), go to the server list and pick a server close to you. Connect to this server with your IRC client, and read on.
When you connect to a BitlBee server, you're force-joined into a channel called #bitlbee. You receive a welcome message from a bot called "root" (some BitlBee packagers rename the root user to something else, you'll notice soon enough), which invites you to read the quickstart documentation. The quickstart might cover some things which are not (yet) in this article, so this is always a good idea.
Good, let's get started. It's a good idea to register your nickname as soon as possible. Not to protect your nickname (since BitlBee is not a real IRC server, you will never notice the other people on the server, everyone gets a different #bitlbee), just for your own ease. With your nickname registered, BitlBee will remember your settings, your account information, your buddy lists and everything else. To register your nickname, just say "register password" in the #bitlbee channel, where "password" is your password of choice.
When you come back later, say "identify password" and BitlBee will restore all your settings and connect to all your accounts. So, let's make a connection right now!
To manage your IM-connections, you can use the "account" command. First, add all your accounts using the "account add" command. This command requires at least three arguments: The protocol, your username/handle/screenname and your password. For some protocols, you also have to specify a servername. ICQ and AIM, for example, share the same protocol, they just use a different server. For the exact syntax of the "account add" command, just see the following list:
account add jabber user@server.com password account add msn user@domain.com password account add yahoo nickname password account add oscar 123456 password login.icq.com account add oscar aimuser password login.oscar.aol.com
After adding all your accounts, type "account on" and see how BitlBee connects to all the services you want. For most protocols (at the time of writing, all but ICQ), it will also download your buddy lists and you'll notice some people joining the #bitlbee channel. Only the people who are on-line will be visible in the channel. As soon as they go off-line, you'll see them quitting.
Of course you can also talk to your buddies. Talk to them in the channel like you normally do on IRC, or open a query. Of course the other person won't notice any difference, so do whatever you like. Remember that #bitlbee is a virtual channel. When you talk to foo here, only foo will get your message, not everyone in the channel.
If you don't get a buddy list (or if you just want to add more buddies), you can use the "add" command. Before you use this command, you should check what connection number to use. As you probably know, BitlBee supports multiple protocols and networks, and it allows you to be connected to more than one network at once. So when you add a buddy, BitlBee wants to know what buddy list you want to edit. You can get a list of all your connections using the "account list" command.
You will a get a list like this:
<wilmer> account list <root> 0. OSCAR, 267762 on login.icq.com (connected) <root> 1. JABBER, lintux@jabber.com/BitlBee (connected) <root> 2. MSN, lintux@lintux.cx <root> End of account list
As you can see here, only the first two accounts are connected. If I want to add a buddy to my MSN contact list, I have to enable that account first, using the "account on 2" command. Fortunately, I can add people to my other lists now. To add a contact, use the "add" command. This command requires two arguments: A connection number and a handle. If you want, you can also specify a nick the contact should get in BitlBee. If you omit this, BitlBee will generate a unique nick from the handle. See the following example:
<wilmer> add 0 32899265 paul <root> User `32899265' added to your contact list as `paul' -!- paul [32899265@login.icq.com] has joined #bitlbee -!- mode/#bitlbee [+v paul] by root
As you see, Paul immediately joins the channel and gets voice. This means he's on-line and not set as away. So when you don't see the person you add join the channel, he or she is probably just off-line.
And more than just talking
One last command you really have to know about is the "set" command. This command can be used to customize BitlBee in many ways. To get a list of available settings, type "set" without any arguments. To change a setting, give two arguments. First, specify the setting you want to change. Second, specify the new value for this setting. BitlBee will respond with a confirmation of your changed setting. If the setting doesn't seem to be changed, there was something wrong with what you were doing.
Also, most essential IRC commands like /away and /whois work with BitlBee. Many more root-commands are available too. Just type "help commands" to get a full list. You can get more information about a command using, for example, "help account".
There's not enough space in this book to explain everything about BitlBee. If you're interested and want more, it's probably a good idea to read the documentation. I suggest you to read the quickstart first. It tries to get the reader started with BitlBee as quickly as possible, just as this article, but discusses more features.
