source: doc/README @ 3ffc53e

Last change on this file since 3ffc53e was 3ffc53e, checked in by Sven Moritz Hallberg <sm@…>, at 2008-02-12T00:25:41Z

add a blurb about OTR to the README

  • Property mode set to 100644
File size: 8.2 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
45DEPENDENCIES
46============
47
48BitlBee's only real dependency is GLib. This is available on virtually every
49platform. Any recent version of GLib (2.4 or higher) will work.
50
51Off-the-Record encryption support will be included by default if the
52configure script finds libotr in one of the usual places. You can pass
53--otr=1 or --otr=0 to force it on or off, respectively.
54
55These days, MSN Messenger clients have to connect to the MS Passport servers
56through HTTPS. BitlBee can use several SSL libraries for this: GnuTLS, NSS
57(which comes with Mozilla) and OpenSSL. OpenSSL is not GPL-compatible in some
58situations, so using GnuTLS or NSS is preferred. However, especially on *BSD,
59OpenSSL can be considered part of the operating system, which eliminates the
60GPL incompatibility.
61
62The incompatibility is also the reason why the SSL library detection code
63doesn't attempt to use OpenSSL. If you want to use OpenSSL, you have to
64force configure to use it using the --ssl=openssl parameter. For more
65information about this problem, see the URL's configure will write to stdout
66when you attempt to use OpenSSL.
67
68
69PORTABILITY ISSUES
70==================
71
72Cygwin NOTE: You'll need a glib installation to run BitlBee. However, Cygwin
73doesn't provide a glib package. You can download a binary tar.gz from:
74<http://my.dreamwiz.com/jbdoll/>. When you installed it, BitlBee should work
75fine. You'll probably like bitlbeed or xinetd to get it running on the
76network.
77
78On some non-Linux systems the program still suffers from some random bugs.
79Please do report them, we might be able to fix them if they're not too
80mysterious.
81
82Also, the configure script is known to not work very well with non-Bash
83shells, so if you experience problems, make sure you use bash to run the
84script. Same for the Makefile, it only works well with GNU make. (gmake on
85most BSD systems)
86
87If someone can tell us how to write Makefiles that work with both/all
88versions of make, we'd love to hear it, but it seems this just isn't
89possible.
90
91
92RUNNING ON SERVERS WITH MANY USERS
93==================================
94
95BitlBee is not yet bug-free. Sometimes a bug causes the program to get into
96an infinite loop. Something you really don't want on a public server,
97especially when that machine is also used for other (mission-critical) things.
98For now we can't do much about it. We haven't seen that happen for a long
99time already on our own machines, but some people still manage to get
100themselves in nasty situations we haven't seen before.
101
102For now the best we can offer against this problem is bitlbeed, which allows
103you to setrlimit() the child processes to use no more than a specified
104number of CPU seconds. Not the best solution (not really a solution anyway),
105but certainly trashing one busy daemon process is better than trashing your
106whole machine.
107
108We don't believe adding a limit for bitlbee to /etc/security/limits.conf will
109work, because that file is only read by PAM (ie just for real login users,
110not daemons).
111
112See utils/bitlbeed.c for more information about the program.
113
114Just a little note: Now that we reach version 1.0, this shouldn't be that
115much of an issue anymore. However, on a public server, especially if you
116also use it for other things, it can't hurt to protect yourself against
117possible problems.
118
119
120USAGE
121=====
122
123Not much to say here, it's all documented elsewhere already. Just connect to
124the new BitlBee IRC server and the bot (root) will tell you what to do.
125
126
127BACKGROUNDS
128===========
129
130We are both console lovers. But it is annoying to have a few tty's open with
131chat things in them. IRC, ICQ, MSN, AIM, Jabber... For X there is Gaim, which
132supports many chatprotocols. Why wasn't there such a thing for the console?
133
134The idea to port Gaim was easily thought of, of course. But we liked our IRC
135clients. And we used it the most, so we used it best. Importing it into the
136IRC client was a nice idea. But what if someone liked a different client.
137Then (s)he had to duplicate our work.
138
139That's a shame, we thought. Doing work twice is pointless. So when Wilmer
140got the ingenious thought in his mind while farming, to create an IRC to
141other chatnetworks gateway, we were both so excited, that we started working
142on it almost immediately. And the result is BitlBee.
143
144
145WEBSITE
146=======
147
148You can find new releases of BitlBee at:
149http://www.bitlbee.org/
150
151The bug tracking system:
152http://bugs.bitlbee.org/
153
154Our version control system is Bazaar-NG. Our repository is at:
155http://code.bitlbee.org/
156
157
158A NOTE ON PASSWORD ENCRYPTION
159=============================
160
161There used to be a note here about the simple obfuscation method used to
162make the passwords in the configuration files unreadable. However, BitlBee
163now uses a better format (and real encryption (salted MD5 and RC4)) to store
164the passwords. This means that people who somehow get their hands on your
165configuration files can't easily extract your passwords from them anymore.
166
167However, once you log into the BitlBee server and send your password, an
168intruder with tcpdump can still read your passwords. This can't really be
169avoided, of course. The new format is a lot more reliable (because it can't
170be cracked with just very basic crypto analysis anymore), but you still have
171to be careful. The main extra protection offered by the new format is that
172the files can only be cracked with some help from the user (by sending the
173password at login time).
174
175So if you run a public server, it's most important that you don't give root
176access to people who like to play with tcpdump. Also, it's a good idea to
177delete all *.nicks/*.accounts files as soon as BitlBee converted them to the
178new format (which happens as soon as the user logs in, it can't be done
179automatically because it needs the password for that account). You won't
180need them anymore (unless you want to switch back to an older BitlBee
181version) and they only make it easier for others to crack your passwords.
182
183
184LEGAL
185=====
186
187BitlBee is distributed under the GPL (GNU General Public License). See the
188file COPYING for this license.
189
190The MD5 algorithm code is licensed under the Aladdin license. This license
191can be found in the files, to which this applies. The SHA1 algorithm code
192is licensed under the Mozilla Public License, see http://www.mozilla.org/MPL/
193for details.
194
195The Yahoo! library used by BitlBee is libyahoo2 <http://libyahoo2.sf.net/>,
196also licensed under the GPL.
197
198
199        BitlBee - An IRC to other chat networks gateway
200                  <http://www.bitlbee.org/>
201        Copyright (C) 2002-2007  Wilmer van der Gaast <wilmer@gaast.net>
202                                 and others
Note: See TracBrowser for help on using the repository browser.