Gentoo Wiki



Base Install

  1. What is Gentoo?
  2. About
  3. Preparation
  4. Partitioning
  5. Configuring
  6. Stage Progression
  7. Kernel
  8. Bootloader
  9. Test
  10. Converting from or to a non-Gentoo distribution
  11. Troubleshooting
  12. Maintaining


Base Extras



Other Articles



About BitlBee

BitlBee is an IRC instant messaging gateway. It communicates with the end-user via the IRC protocol whilst interacting with popular chat networks such as AIM and ICQ (both via OSCAR), Windows Live (MSN), Yahoo! and XMPP/Jabber (including Google Talk). The users' buddies appear as normal IRC users in a channel and conversations use the private message facility of IRC. This page deals with setting up an own BitlBee server but there are many servers available for public use.


Firstly you need to set the USE variable according to those protocols you want to use.

ipv6   IPv6 support
jabber XMPP/Jabber (including Google Talk)
oscar  AIM and ICQ
ssl    SSL (necessary if using Google Talk)
msn    Windows Live (MSN)

Having changed the USE variable, you can install BitlBee by simply executing: emerge -av bitlbee

BitlBee should now be installed properly. You can start BitlBee with:

/etc/init.d/bitlbeed start

In order to start the BitlBee service automatically on system start, enter:

rc-update add bitlbeed default



After you've installed the BitlBee gateway server, you'll need to connect to it. You can use any IRC client to connect to your BitlBee server. This is done via the "connect" command. In this example we are using the irssi IRC client. Start your IRC client and enter:

/connect <address>

If you're connecting to your local machine for this service you can use



/connect localhost

When everything has worked fine, you should be getting the BitlBee MOTD.

BitlBee has a control channel called &bitlbee. Two users will always be there, you (called by the nickname you are using) and the system user, root. The following commands must to be entered in this channel.

Register an account

Once you're connected to your (or a public) server, you'll need to register your account:

register <password>

You need register yourself so that all your settings can be saved on the BitlBee server. Be sure to remember your password. The next time you connect to the BitlBee server you will need to identify yourself, so that you will be logged in to all the instant messaging services automatically.

identify <password>

Mange your accounts

Adding accounts

After you've registered your account on your new server you need to add your accounts. Adding an account is basically done by:

  account add command: account add <protocol> <username> <password> [<server>].

Having added all the accounts you want to connect to, you need to go online:

 account on

If you only want to set specific accounts online, get the account listing first

account list

and then go only online with those accounts according to their ID. If you want to bring up all accounts, you can leave out the ID.

account on [<ID>]

To delete an account do the following:

account del <ID>


account add jabber <handle@server.tld> <password>


Oscar is the protocol used by AIM and ICQ. For AOL Instant Messenger, the server name is

account add oscar <screen name> <password>

For ICQ it is

account add oscar <UIN> <password>

'account add' is deprecated. Use 'account set' instead.


account add yahoo <screen name> <password>


account add msn <screen name> <password>

Google Talk

As Google Talk (gTalk) uses XMPP, we need to add a Jabber-account.

account add jabber <username> <password>

Try to bring up the account:

account on [<ID>]

If you're getting an error like this one, try to use instead of as domain:

"JABBER( - Login error: Error 403: Unknown error"

This only affects Google-Accounts registered from European countries. If it is the case, it's best to delete this account first and re-add it:

account del ID
account add jabber <username> <password>

If you are still unable to connect, try changing the port to 5222. For some reason some people must connect on 5223 while others have to connect on 5222.

Connecting to Jabber chat rooms

join_chat <account number> <room>@<server> <room name> <username>

Managing your buddy list

For most protocols BitlBee receives the contact list automatically from the IM server and all users should appear according to their status. BitlBee makes the nick names IRC-compatible. If you have more than one person who would have the same name, the second one will have an underscore attached. In those cases, it might be better to change the nickname. Therefore you can use "rename":

rename <old nickname> <new nickname>

Deleting buddies is done by:

remove <nickname>

To print your buddy list, you can either use




The only difference is, that blist also prints the status.

To get the status of a buddy, use:

/whois <username>

Messaging a buddy

You can only message contacts that are on your contact list unless it's a group chat.

If you prefer chatting in separate windows, use the /msg or /query command. It will behave like you're being private messaging someone in IRC. If you want to have messages automatically come up in private messages rather than in the &bitlbee channel, use the set private command

set private true

To change it back, use:

set private false

To open a new chat window, use:

/query <nickname>


/msg <nickname> <message>


Re-connect automatically

If you're connection to your accounts often breaks, you should enable "auto_reconnect":

set auto_reconnect true

Display name changes

If you want to get notified when your buddies change their nicknames, enable "display_namechanges":

set display_namechanges true

Enable typing notice

If you want to get notified when a buddy types a message to you, enable "typing_notice":

set typing_notice true

Disabling status updates

This will hide all status updates:

/ignore &bitlbee MODES

Stripping off HTML

If you want to strip off any HTML, use:

set strip_html true

Change an account's password

If you need to change an account's password, use:

set password <ID> <password>

Change the charset

It's best if you use the same charset for all your applications. BitlBee's default charset is ISO-8859-1. To change it to UTF-8, do:

set charset utf8 

Automatically (re-)connect

If your connection often crashes, BitlBee can automatically re-connect by using:

set auto_reconnect true

If you want BitlBee to log in automatically after having authenticated, use:

set auto_connect true

Save the settings

If you think, everything is configured properly, you can now save your settings. If you don't save, everything is lost when using BitlBee the next time. To save your configuration, use:


If you often change the configuration of BitlBee, the "save on quit"-option might be interesting for you:

set save_on_quit true

If you're using BitlBee the next time, you need to identify yourself. This will load all the settings and accounts. Use:

identify <password>


If you want to configure BitlBee manually, open up /etc/bitlbee/bitlbee.conf in your favorite editor. /etc/bitlbee/motd.txt contains the message that appears when connecting to your BitlBee server (MOTD - Message of the day).

Backup and migrate settings and accounts


Ensure you have backed up the following two directories:


If you want to migrate your data, you need to stop BitlBee (/etc/init.d/bitlbeed stop) and replace these two directories. Probably BitlBee will say something like this when trying to bring all accounts up:

No accounts known. Use `account add' to add one.

This can be solved by setting the correct owner and group of /var/lib/bitlbee/:

chown -R bitlbee:nogroup /var/lib/bitlbee/

Then you just have to restart BitlBee and you're done.

See also

Retrieved from ""

Last modified: Tue, 14 Oct 2008 12:13:00 +0000 Hits: 2,704