source: doc/README @ 42fc5b6

Last change on this file since 42fc5b6 was de8e584, checked in by Wilmer van der Gaast <wilmer@…>, at 2008-05-24T19:57:47Z

Daemon mode is not an experiment anymore, it's running on testing.bitlbee.org
for two weeks already with >30 active connections and not a single crash.

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