source: doc/README @ acf26c3

INSTALLATION
============

If you installed BitlBee from a .deb or .rpm you probably don't have to do
anything anymore for installation. Just skip this section.

If you want to compile BitlBee yourself, that's fine. Just run ./configure
to set up the build system. If configure succeeds, run make to build BitlBee.
make install will move all the files to the right places.

RUN MODES
=========

--- (Fork)Daemon mode

These days ForkDaemon mode is the recommended way of running BitlBee. The
difference between Daemon and ForkDaemon mode is that in the latter, a
separate process is spawned for every user. This costs a little bit more
memory, but means that if one user hits a bug in the code, not all other
users get disconnected with him/her.

To use BitlBee in any daemon mode, just start it with the right flags or
enable it in bitlbee.conf (see the RunMode option). You probably want to
write an init script to start BitlBee automatically after a reboot. (This
is where you realise using a package from your distro would've been a better
idea. :-P)

Please do make sure that the user BitlBee runs as (not root, please!) is
able to read from and write to the /var/lib/bitlbee directory to save your
settings!

--- inetd installation (more or less deprecated)

After installation you have to set up inetd (you got that one running,
right? If not, just take a look at utils/bitlbeed.c) to start BitlBee. You
need to add BitlBee to inetd.conf, like this:

6667 stream tcp nowait nobody /usr/sbin/tcpd /usr/local/sbin/bitlbee

Creating a special BitlBee user and running BitlBee with that UID (instead
of just 'nobody') might be a good idea.

*BSD/Darwin/OSX NOTE: Most *BSD inetds are more strict than the one that
comes with Linux systems. Possibly all non-Linux inetds are like this. They
don't allow you to specify a port number in the inetd.conf entry, instead
you have to put a service name there (one that is also mentioned in
/etc/services). So if there's no line in /services for 6667/tcp (or whatever
you choose), add it and use that name in the inetd.conf entry.

-- xinetd installation (equally deprecated)

Most machines use xinetd instead of inetd these days. If your machine runs
xinetd, you can copy the bitlbee.xinetd file from the doc/ directory to your
xinetd.d/ directory. Most likely you'll have to change a thing or two before
it'll work.

After configuring your (x)inetd, send the daemon a SIGHUP and things should
work. If not, see your syslogs, since both daemons will complain there when
something's wrong.

Also, don't forget to create the configuration directory (/var/lib/bitlbee/
by default) and chown it to the UID BitlBee is running as. Make sure this
directory is read-/writable by this user only.


DEPENDENCIES
============

BitlBee's only real dependency is GLib. This is available on virtually every
platform. Any recent version of GLib (2.4 or higher) will work.

Off-the-Record encryption support can be included if libotr is available on
your machine. Pass --otr=1 to configure to build it into BitlBee, or
--otr=plugin to build it as a separate loadable plugin (mostly meant for
distro packages).

These days, many IM protocols use SSL/TLS connections (for authentication
or for the whole session). BitlBee can use several SSL libraries for this:
GnuTLS, NSS (which comes with Mozilla) and OpenSSL. OpenSSL is not GPL-
compatible in some situations, so using GnuTLS is preferred. However,
especially on *BSD, OpenSSL can be considered part of the operating system,
which eliminates the GPL incompatibility.

The incompatibility is also the reason why the SSL library detection code
doesn't attempt to use OpenSSL. If you want to use OpenSSL, you have to
force configure to use it using the --ssl=openssl parameter. For more
information about this problem, see the URL's configure will write to stdout
when you attempt to use OpenSSL.


PORTABILITY ISSUES
==================

The configure script is may not work very well with some non-bash shells (but
dash is supported), so if you experience problems, make sure you use bash to
run the script. Same for the Makefile, it only works well with GNU make. (gmake
on most BSD systems)

If someone can tell us how to write Makefiles that work with both/all
versions of make, we'd love to hear it, but it seems this just isn't
possible.


USAGE
=====

Not much to say here, it's all documented elsewhere already. Just connect to
the new BitlBee IRC server and the bot (root) will tell you what to do.


BACKGROUNDS
===========

We are both console lovers. But it is annoying to have a few tty's open with
chat things in them. IRC, ICQ, MSN, AIM, Jabber... For X there is Gaim, which
supports many chatprotocols. Why wasn't there such a thing for the console?

The idea to port Gaim was easily thought of, of course. But we liked our IRC
clients. And we used it the most, so we used it best. Importing it into the
IRC client was a nice idea. But what if someone liked a different client.
Then (s)he had to duplicate our work.

That's a shame, we thought. Doing work twice is pointless. So when Wilmer
got the ingenious thought in his mind while farming, to create an IRC to
other chatnetworks gateway, we were both so excited, that we started working
on it almost immediately. And the result is BitlBee.

In the years after, Gaim was renamed to Pidgin, BitlBee got libpurple support
allowing to use Pidgin plugins and the support for the old chatprotocols ICQ,
MSN and AIM was finally removed from BitlBee.


WEBSITE
=======

You can find new releases of BitlBee at:
https://www.bitlbee.org/

The bug tracking system:
https://bugs.bitlbee.org/

Our version control system is Git. Our repository is at:
https://github.com/bitlbee/bitlbee

More documentation on the Wiki:
https://wiki.bitlbee.org/


A NOTE ON PASSWORD ENCRYPTION
=============================

BitlBee currently uses salted MD5 and RC4 to store the passwords. This means
that people who somehow get their hands on your configuration files can't
easily extract your passwords from them anymore.

However, once you log into the BitlBee server and send your password, an
intruder with tcpdump can still read your passwords. This can't really be
avoided, of course. So if you run a public server, it's most important that you
don't give root access to people who like to play with tcpdump.

LEGAL
=====

BitlBee is distributed under the GPL (GNU General Public License). See the
file COPYING for this license.


        BitlBee - An IRC to other chat networks gateway 
                  <https://www.bitlbee.org/>
        Copyright (C) 2002-2010  Wilmer van der Gaast <wilmer@gaast.net>
                                 and others