# BitlBee User Guide

### Jelmer Vernooij

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

# Chapter 1. Installation

## Downloading the package

The latest BitlBee release is always available from http://www.lintux.cx/bitlbee.html. Download the package with your favorite program and unpack it: tar xvfz BitlBee-0.71.tar.gz

## Compiling

BitlBee's build system has to be configured before compiling. The `configure` script will do this for you. Just run it, it'll set up with nice and hopefully well-working defaults. If you want to change some settings, just try ./configure --help and see what you can do.

Some variables that might be of interest to the normal user:

- config - The place where BitlBee will save settings for all the users. `/var/bitlbee/` is the default value.

- tcpd - If you enable this one, you can specify what hosts should be allowed to use your BitlBee by editting `/etc/hosts.deny` and/or `/etc/hosts.deny`.

After running `configure`, you should run make. After that, run make install as root.

## Configuration

By default, BitlBee runs as the user nobody. You might want to run it as a seperate user (some computers run named or apache as nobody).

Since BitlBee uses inetd, you should add the following line to `/etc/inetd.conf`:

    127.0.0.1:6667    stream  tcp     nowait _bitlbee /usr/local/sbin/bitlbee bitlbee

Inetd has to be restarted after changing the configuration. kill -HUP `cat /var/run/inetd.pid` should do the job.

You should create a directory where BitlBee can store it's data files. This should be the directory named after the value 'CONFIG' in Makefile.settings. The default is `/var/bitlbee`, which can be created with the command mkdir -p /var/bitlbee. This directory has to be owned by the user that runs bitlbee. To make 'nobody' owner of this directory, run chown nobody /var/bitlbee. Because things like passwords are saved in this directory, it's probably a good idea to make this directory owner-read-/writable only.

Note from port-maintainer: already done

# Chapter 2. Usage

## Connecting to the server

Since BitlBee acts just like any other irc daemon, you can connect to it with your favorite irc client. Launch it and connect to localhost port 6667 (or whatever host/port you are running bitlbee on).

## The #bitlbee control channel

Once you are connected to the BitlBee server, you should 'join' #bitlbee on that server. This channel acts like the 'buddy list' you have on the various other chat networks.

The user 'root' always hangs around in #bitlbee and acts as your interface to bitlbee. All commands you give on #bitlbee are 'answered' by root.

## Commands

BitlBee can be configured by giving 'commands' in the #bitlbee channel. 'root' responds to these commands.

### help

Syntax: help

Gives a list of commands bitlbee supports with syntax. You can get an up-to-date list of available commands using the help commands command. This information is usually more up-to-date than the information in this file.

### login

Syntax: login <protocol> <username> <password> [<server>]

Logs in to the given server with the specified protocol, username and password. Specifying the server is optional and principally only necessary when using oscar.

Example:

    00:10 < ctrlsoft> login jabber ctrlsoft@jabber.org secret
    00:10 < root> JABBER - Logging in: Connecting
    00:10 < root> JABBER - Logging in: Connected
    00:10 < root> JABBER - Logging in: Requesting Authentication Method
    00:10 < root> JABBER - Logging in: Authenticating
    00:10 < root> JABBER - Logged in

### slist

Syntax: slist

Gives a list of all active connections to servers

Example:

    00:09 < ctrlsoft> slist
    00:09 < root>  0. MSN, jelmervernooij@hotmail.com
    00:09 < root>  1. OSCAR, 30761007 on login.icq.com
    00:09 < root>  2. OSCAR, JelmerVernooij on login.oscar.aol.com
    00:09 < root>  3. JABBER, ctrlsoft@jabber.org
    00:09 < root> End of connection list

### logout

Syntax: logout <connection-number>

Log out of the specified connection number's network. The correct connection number can be retrieved by running the slist command.

Example:

    00:11 < ctrlsoft> logout 3
    00:11 -!- gryp [gryp@jabber.jabber.org] has quit [Leaving...]
    00:11 < root> JABBER - Logged out

### add

Syntax: add <connection> <handle>

Adds the given buddy at the specified connection to your buddy list. The connection number can be retrieved with the slist command.

Example:

    00:15 < ctrlsoft> add 3 gryp@jabber.org
    00:15 -!- gryp (gryp@jabber.org) [gryp@jabber.jabber.org] has joined #bitlbee

### remove

Syntax: remove <nick>

Removes the specified nick from your buddy list.

Example:

    00:14 < ctrlsoft> remove gryp
    00:14 -!- gryp [gryp@jabber.jabber.org] has quit [Leaving...]

### block

Syntax: block [<nick<|<connection> <handle>]

Puts the specified user on your ignore list. Either specify the users' nick when you have him/her in your contact list or a connection number and a user handle. The connection number can be retrieved with the slist command.

### allow

Syntax: allow [<nick<|<connection> <handle>]

Reverse of block. Unignores the specified user or user handle on specified connection. Connection number can be retrieved using the slist command.

### set

Syntax: set [<variable>] [<value>]

Without any arguments, this command lists all the set variables. You can also specify a single argument, a variable name, to get that variable's value. To change this value, specify the new value as the second argument.

### save

Syntax: save

This command saves all your nicks and accounts immediately. Handy if you have the autosave functionality disabled, or if you don't trust the program's stability... ;-)

## Settings

BitlBee can be configured by using the set command. The available settings are discussed in this section.

### private

Type: boolean

Default: False

If value is true, messages from users will appear in seperate query windows. If false, messages from users will appear in #bitlbee.

### save_on_quit

Type: boolean

Default: True

If enabled causes bitlbee to save all current settings and account details when user disconnects.

### html

Type: string

Default: nostrip

Determines what bitlbee should do with HTML in messages. If set to nostrip, HTML in messages will not be touched. If set to strip, all html will be stripped from messages.

### debug

Type: boolean

Default: False

Some debugging messages can be sent to the control channel if you wish. They're probably not really useful for you, unless you're doing some development on BitlBee.

## Talking to people

You can talk to by starting a query with them. In most irc clients, this can be done with either /msg <nick> <text> or /query <nick>.

To keep the number of open query windows limited, you can also talk to people in the control channel, like <nick>: <text>.

# Chapter 3. Support

## BitlBee is beta software

Although BitlBee has quite some functionality it is still beta. That means it can crash at any time, corrupt your data or whatever. Don't use it in any production environment and don't rely on it.

## Support channels

### The World Wide Web

http://www.lintux.cx/bitlbee.html is the homepage of bitlbee and contains the most recent news on bitlbee and the latest releases.

### IRC

BitlBee is discussed on #bitlbee on the OFTC IRC network(server: irc.oftc.net).

### Mailinglists

BitlBee doesn't have any mailinglists (yet).