How to set Bitlbee (GTalk and Twitter) in Debian

BitlBee is an IRC gateway to other instant messaging networks which use different protocols (e.g: jabber, ICQ, AIM, MSN, etc)

From user point of view BitlBee acts as an IRC server which forwards your messages to other networks like Google Talk, Facebook, Twitter, Identica,
etc.

BitlBee official web page: http://www.biltbee.org

INSTALL BITLBEE (DEBIAN)

When writting this article current BitlBee version in Debian unstable was 3.0.5
This version allows us to authenticate using OAth.

$ aptitude show bitlbee

Package: bitlbee                         
Version: 3.0.5-1.1
Description: An IRC to other chat networks gateway (default version)

Install BitlBee IRC gateway:
$ sudo aptitude install bitlbee

If after configuring it we need to restart Bitlbee daemon
$ sudo service bitlbee restart

CONNECT TO BITLBEE SERVER

Once BitlBee server is running you only need an IRC client to connect to it:

E.g: I use ERC within emacs.

So connect using an IRC client program to localhost (or the address of the system you installed BitlBee on)


You will automatically join channel &bitlbee (control channel). There is also root user there.

*** You have joined channel &bitlbee  [12:29]
 *** localhost has changed mode for &bitlbee to +Ct
 *** Users on &bitlbee: @root @user 
 *** Topic for &bitlbee: Welcome to the control channel. Type help for help
    information.
 *** &bitlbee: topic set by root!root@localhost, 12:29:01 2012/09/02
<root> Welcome to the BitlBee gateway!
<root>  
<root> If you've never used BitlBee before, please do read the help
       information using the help command. Lots of FAQs are answered there.
<root> If you already have an account on this server, just use the identify
       command to identify yourself.
 *** &bitlbee modes: +Ct

NOTE: Channels starting with & are control channels.

REGISTER INTO BITLBEE SERVER

First step is registering your password:
ERC> register my_password


Next time you will access to the IRC server, you will be able to identify yourself using identify command:
<user> identify my_password

Once you are identified, you can access to your account settings.

BITLBEE EMBEDDED HELP

It is a good idea to read BitlBee embedded help.

<user> help

<root> These are the available help subjects:                                                                                  
<root>                                                                                                   
<root>  quickstart - A short introduction into BitlBee                                                                         
<root>  commands - All available commands and settings                                                                         
<root>  channels - About creating and customizing channels                                                                     
<root>  away - About setting away states                                                                                       
<root>  groupchats - How to work with groupchats on BitlBee                                                                    
<root>  nick_changes - Changing your nickname without losing any settings                                                      
<root>  smileys - A summary of some non-standard smileys you might find and                                                    
       fail to understand                                                                                                      
<root<                                                                                                                         
<root< You can read more about them with help <subject>

E.g:
<user> help quickstart

BITLBEE DEFAULT CONFIGURATION FILE

Global configuration file: /etc/bitlbee/bitlbee.conf

Editing that file you can configure the interface it listens to, daemon mode, etc.

MAKE BITLBEE SERVER ONLY ACCESSIBLE VIA LOCALHOST

Edit in global config file: /etc/bitlbee/bitlbee.conf

DaemonInterface = 127.0.0.1


After restarting BitlBee daemon you will only be able to connect from localhost interface.

ADD A GTALK ACCOUNT

I am going to add my gtalk account using OAuth authentication (using a web browser).

≤user> acc add jabber my_account@gmail.com

<root> Account successfully added with tag gtalk
<root> You can now use the /OPER command to enter the password
<root> Alternatively, enable OAuth if the account supports it: account gtalk
       set oauth on

Enable oauth authentication method:
<user> acc gtalk set oauth true
<user> acc gtalk on

<root> jabber - Logging in: Starting OAuth authentication

A private message will pop up:
It will show you a HTML URL address, you go there in a browser, to authenticate, then it will return you a string token.
Respond to that private message with that token and you will be authenticated.


After you successfully set your gtalk account, your buddy contact list will appear in &bitlbee channel.
Also if a strange one like: _1wfdzfoobarbazhbaia9@public.talk.google.com appears, it represents the contacts that
are in your Google plus circles but not in your Gtalk contact list.

If you want to rename that nick, in &bitlbee channel:
<user> rename old_nick new_nick

ADD A TWITTER ACCOUNT

We will use same OAuth authentication process as in Gtalk account.


<user> account add twitter BitlBee foo # We give a fake password "foo". BitlBee is not our user but it will work anyway.

<root> Account successfully added with tag twitter

OAth authentication process

A private message will pop up: show a HTML URL, go there to authenticate an write back the returned token.


A channel #twitter_bitlbee will be created, and you will receive your twits there.



Follow a new twitter user

To show your twitter account id:
<user> account list

...
  1 (twitter): twitter, BitlBee (connected)
...
 End of account list

It shows number 1 for the twitter account in my system, then:

<user> add 1 publico_es # 1 is the configured twitter account in my settings. Use account list to find it.


Remove a twitter user:

E.g: if you want to remove "foo_twitter_user"

in &bitlbee channel

<user> remove foo_twitter_user

IDENTI.CA

Same token process as before to authenticate using OAuth way:

&bitlbee channel:

<user> account add identica my_account

<root> Account successfully added with tag identica
<root> No need to enter a password for this account since it's using OAuth

<user> account on

<root> Trying to get all accounts connected...
<root> identica - Logging in: Connecting
 *** identica_my_account (identi.ca_my_account@identica) has joined channel
    &bitlbee
 *** localhost has changed mode for &bitlbee to +v identica_my_account
<root> identica - Logging in: Requesting OAuth request token
<root> identica - Logging in: Getting contact list
<root> identica - Logging in: Getting initial statuses
<root> identica - Logging in: Logged in

A new channel opens: #identi.ca_my_account@BitlBee

MANAGING ACCOUNTS

LIST ALL ACCOUNTS
<user> account list

<root>  0 (gtalk): jabber, my_user@gmail.com (connected)
<root>  1 (twitter): twitter, BitlBee (connected)
<root>  2 (identica): identica, my_user (connected)

SIGNING OFF FROM ONE ACCOUNT
<user> account 0 off

<root> jabber - Signing off..

SIGNING ON IN ONE ACCOUNT
<user> account 0 on

<root> jabber - Logging in: Connecting
<root> jabber - Logging in: Connected to server, logging in
<root> jabber - Logging in: Converting stream to TLS
<root> jabber - Logging in: Connected to server, logging in
<root> jabber - Logging in: Authentication finished
<root> jabber - Logging in: Server changed session resource string to
<root> jabber - Logging in: Authenticated, requesting buddy list
<root> jabber - Logging in: Logged in

SIGNING ON IN ALL ACCOUNTS AT ONCE

<user> account on


SIGNING OFF FROM ALL ACCOUNTS AT ONCE

<user> account off


SHOWS HELP FOR A COMMAND

E.g: show help for rename command:

<user> help rename

<root> Syntax: rename <oldnick> <newnick>
<root> Syntax: rename -del <oldnick>
<root>  
<root> Renick a user in your buddy list. Very useful, in fact just very
       important, if you got a lot of people with stupid account names (or
       hard ICQ numbers).
<root>  
<root> rename -del can be used to erase your manually set nickname for a
       contact and reset it to what was automatically generated.
<root>  
<root> Example:
<root> <itsme> rename itsme_ you
<root> * itsme_ is now known as you

LIST ALL CONFIGURED CHANNELS

This command gives you a list of all the channels you configured.

<user> channel list

<root>  0. &bitlbee, control channel (joined)
<root>  1. #twitter_bitlbee, chat channel (joined)
<root>  2. #identi.ca_my_account, chat channel (joined)
<root>  3. &offline, control channel (joined)
<root>  4. #foo, chat channel (joined)
<root> End of channel list

COPY BITLBEE INSTANCE INTO ANOTHER MACHINE.

If you want to install bitlbee into another machine and want to use same configuration,
you can simply copy /var/lib/bitlbee/your_name.xml into /var/lib/bitlbee in the new machine.


$ cp /var/lib/bitlbee/my_user.xml /path/to/other/machine # copy user config file into the other machine.

Watch out file permissions. Do not make them readable for everyone.
$ sudo chown bitlbee:bitlbee my_user.xml
$ sudo chmod 600 my_user.xml
$ sudo mv my_user.xml /var/lib/bitlbee

REFERENCE

http://www.bitlbee.org (Home page)
http://wiki.bitlbee.org (Wiki page)
http://www.bitlbee.org/main.php/extdoc.html (Documentation)
http://princessleia.com/bitlbee.php
http://quark.humbug.org.au/publications/internet/bitlbee.pdf
http://wiki.bitlbee.org/HowtoGtalk
http://wiki.bitlbee.org/HowtoTwitter

$ man bitlbee