source: doc/README @ 8e9e2b7

Last change on this file since 8e9e2b7 was 8e9e2b7, checked in by Wilmer van der Gaast <wilmer@…>, at 2010-10-03T02:45:26Z

Merging mainline, which includes a huge msnp13 merge.

Not 100% sure about the OpenSSL merge, should double check that but I'm
currently offline.

  • Property mode set to 100644
File size: 7.9 KB
Line 
1INSTALLATION
2============
3
4If you installed BitlBee from a .deb or .rpm you probably don't have to do
5anything anymore for installation. Just skip this section.
6
7If you want to compile BitlBee yourself, that's fine. Just run ./configure
8to set up the build system. If configure succeeds, run make to build BitlBee.
9make install will move all the files to the right places.
10
11--- (Fork)Daemon mode
12
13These days ForkDaemon mode is the recommended way of running BitlBee. The
14difference between Daemon and ForkDaemon mode is that in the latter, a
15separate process is spawned for every user. This costs a little bit more
16memory, but means that if one user hits a bug in the code, not all other
17users get disconnected with him/her.
18
19To use BitlBee in any daemon mode, just start it with the right flags or
20enable it in bitlbee.conf (see the RunMode option). You probably want to
21write an init script to start BitlBee automatically after a reboot. (This
22is where you realise using a package from your distro would've been a better
23idea. :-P)
24
25Please do make sure that the user BitlBee runs as (not root, please!) is
26able to read from and write to the /var/lib/bitlbee directory to save your
27settings!
28
29--- inetd installation (more or less deprecated)
30
31After installation you have to set up inetd (you got that one running,
32right? If not, just take a look at utils/bitlbeed.c) to start BitlBee. You
33need to add BitlBee to inetd.conf, like this:
34
356667 stream tcp nowait nobody /usr/sbin/tcpd /usr/local/sbin/bitlbee
36
37Creating a special BitlBee user and running BitlBee with that UID (instead
38of just 'nobody') might be a good idea.
39
40*BSD/Darwin/OSX NOTE: Most *BSD inetds are more scrict than the one that
41comes with Linux systems. Possibly all non-Linux inetds are like this. They
42don't allow you to specify a port number in the inetd.conf entry, instead
43you have to put a service name there (one that is also mentioned in
44/etc/services). So if there's no line in /services for 6667/tcp (or whatever
45you choose), add it and use that name in the inetd.conf entry.
46
47-- xinetd installation (equally deprecated)
48
49Most machines use xinetd instead of inetd these days. If your machine runs
50xinetd, you can copy the bitlbee.xinetd file from the doc/ directory to your
51xinetd.d/ directory. Most likely you'll have to change a thing or two before
52it'll work.
53
54After configuring your (x)inetd, send the daemon a SIGHUP and things should
55work. If not, see your syslogs, since both daemons will complain there when
56something's wrong.
57
58Also, don't forget to create the configuration directory (/var/lib/bitlbee/
59by default) and chown it to the UID BitlBee is running as. Make sure this
60directory is read-/writable by this user only.
61
62
63DEPENDENCIES
64============
65
66BitlBee's only real dependency is GLib. This is available on virtually every
67platform. Any recent version of GLib (2.4 or higher) will work.
68
69Off-the-Record encryption support will be included by default if the
70configure script finds libotr in one of the usual places. You can pass
71--otr=1 or --otr=0 to force it on or off, respectively.
72
73These days, many IM protocols use SSL/TLS connections (for authentication
74or for the whole session). BitlBee can use several SSL libraries for this:
75GnuTLS, NSS (which comes with Mozilla) and OpenSSL. OpenSSL is not GPL-
76compatible in some situations, so using GnuTLS is preferred. However,
77especially on *BSD, OpenSSL can be considered part of the operating system,
78which eliminates the GPL incompatibility.
79
80The incompatibility is also the reason why the SSL library detection code
81doesn't attempt to use OpenSSL. If you want to use OpenSSL, you have to
82force configure to use it using the --ssl=openssl parameter. For more
83information about this problem, see the URL's configure will write to stdout
84when you attempt to use OpenSSL.
85
86
87PORTABILITY ISSUES
88==================
89
90Cygwin NOTE: You'll need a glib installation to run BitlBee. However, Cygwin
91doesn't provide a glib package. You can download a binary tar.gz from:
92<http://my.dreamwiz.com/jbdoll/>. When you installed it, BitlBee should work
93fine. You'll probably like bitlbeed or xinetd to get it running on the
94network.
95
96On some non-Linux systems the program still suffers from some random bugs.
97Please do report them, we might be able to fix them if they're not too
98mysterious.
99
100Also, the configure script is known to not work very well with non-Bash
101shells, so if you experience problems, make sure you use bash to run the
102script. Same for the Makefile, it only works well with GNU make. (gmake on
103most BSD systems)
104
105If someone can tell us how to write Makefiles that work with both/all
106versions of make, we'd love to hear it, but it seems this just isn't
107possible.
108
109
110USAGE
111=====
112
113Not much to say here, it's all documented elsewhere already. Just connect to
114the new BitlBee IRC server and the bot (root) will tell you what to do.
115
116
117BACKGROUNDS
118===========
119
120We are both console lovers. But it is annoying to have a few tty's open with
121chat things in them. IRC, ICQ, MSN, AIM, Jabber... For X there is Gaim, which
122supports many chatprotocols. Why wasn't there such a thing for the console?
123
124The idea to port Gaim was easily thought of, of course. But we liked our IRC
125clients. And we used it the most, so we used it best. Importing it into the
126IRC client was a nice idea. But what if someone liked a different client.
127Then (s)he had to duplicate our work.
128
129That's a shame, we thought. Doing work twice is pointless. So when Wilmer
130got the ingenious thought in his mind while farming, to create an IRC to
131other chatnetworks gateway, we were both so excited, that we started working
132on it almost immediately. And the result is BitlBee.
133
134
135WEBSITE
136=======
137
138You can find new releases of BitlBee at:
139http://www.bitlbee.org/
140
141The bug tracking system:
142http://bugs.bitlbee.org/
143
144Our version control system is Bazaar. Our repository is at:
145http://code.bitlbee.org/
146
147More documentation on the Wiki:
148http://wiki.bitlbee.org/
149
150
151A NOTE ON PASSWORD ENCRYPTION
152=============================
153
154There used to be a note here about the simple obfuscation method used to
155make the passwords in the configuration files unreadable. However, BitlBee
156now uses a better format (and real encryption (salted MD5 and RC4)) to store
157the passwords. This means that people who somehow get their hands on your
158configuration files can't easily extract your passwords from them anymore.
159
160However, once you log into the BitlBee server and send your password, an
161intruder with tcpdump can still read your passwords. This can't really be
162avoided, of course. The new format is a lot more reliable (because it can't
163be cracked with just very basic crypto analysis anymore), but you still have
164to be careful. The main extra protection offered by the new format is that
165the files can only be cracked with some help from the user (by sending the
166password at login time).
167
168So if you run a public server, it's most important that you don't give root
169access to people who like to play with tcpdump. Also, it's a good idea to
170delete all *.nicks/*.accounts files as soon as BitlBee converted them to the
171new format (which happens as soon as the user logs in, it can't be done
172automatically because it needs the password for that account). You won't
173need them anymore (unless you want to switch back to an older BitlBee
174version) and they only make it easier for others to crack your passwords.
175
176
177LEGAL
178=====
179
180BitlBee is distributed under the GPL (GNU General Public License). See the
181file COPYING for this license.
182
183The MD5 algorithm code is licensed under the Aladdin license. This license
184can be found in the files, to which this applies. The SHA1 algorithm code
185is licensed under the Mozilla Public License, see http://www.mozilla.org/MPL/
186for details.
187
188The Yahoo! library used by BitlBee is libyahoo2 <http://libyahoo2.sf.net/>,
189also licensed under the GPL.
190
191
192        BitlBee - An IRC to other chat networks gateway
193                  <http://www.bitlbee.org/>
194        Copyright (C) 2002-2010  Wilmer van der Gaast <wilmer@gaast.net>
195                                 and others
Note: See TracBrowser for help on using the repository browser.