source: doc/README @ 8d6c4b1

Last change on this file since 8d6c4b1 was bad4a586, checked in by Wilmer van der Gaast <wilmer@…>, at 2005-12-04T02:38:18Z

README additions

  • Property mode set to 100644
File size: 7.5 KB
RevLine 
[b7d3cc34]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
[42bdeec]11--- inetd installation
12
[b7d3cc34]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
[42bdeec]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
[b7d3cc34]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 (including 1.x versions) will work.
50
51These days, MSN Messenger clients have to connect to the MS Passport servers
52through HTTPS. BitlBee can use serveral SSL libraries for this: GnuTLS, NSS
53(which comes with Mozilla) and OpenSSL. OpenSSL is not GPL-compatible in some
54situations, so using GnuTLS or NSS is preferred. However, especially on *BSD,
55OpenSSL can be considered part of the operating system, which eliminates the
56GPL incompatibility.
57
58The incompatibility is also the reason why the SSL library detection code
59doesn't attempt to use OpenSSL. If you want to use OpenSSL, you have to
60force configure to use it using the --ssl=openssl parameter. For more
61information about this problem, see the URL's configure will write to stdout
62when you attempt to use OpenSSL.
63
64
65PORTABILITY ISSUES
66==================
67
68Cygwin NOTE: You'll need a glib installation to run BitlBee. However, Cygwin
69doesn't provide a glib package. You can download a binary tar.gz from:
70<http://my.dreamwiz.com/jbdoll/>. When you installed it, BitlBee should work
71fine. You'll probably like bitlbeed or xinetd to get it running on the
72network.
73
74On some non-Linux systems the program still suffers from some random bugs.
75Please do report them, we might be able to fix them if they're not too
76mysterious.
77
[42bdeec]78Also, the configure script is known to not work very well with non-Bash
79shells, so if you experience problems, make sure you use bash to run the
80script. Same for the Makefile, it only works well with GNU make. (gmake on
81most BSD systems)
82
83If someone can tell us how to write Makefiles that work with both/all
84versions of make, we'd love to hear it, but it seems this just isn't
85possible.
86
[b7d3cc34]87
88RUNNING ON SERVERS WITH MANY USERS
89==================================
90
91BitlBee is not yet bug-free. Sometimes a bug causes the program to get into
92an infinite loop. Something you really don't want on a public server,
93especially when that machine is also used for other (mission-critical) things.
94For now we can't do much about it. We haven't seen that happen for a long
95time already on our own machines, but some people still manage to get
96themselves in nasty situations we haven't seen before.
97
98For now the best we can offer against this problem is bitlbeed, which allows
99you to setrlimit() the child processes to use no more than a specified
100number of CPU seconds. Not the best solution (not really a solution anyway),
101but certainly trashing one busy daemon process is better than trashing your
102whole machine.
103
104We don't believe adding a limit for bitlbee to /etc/security/limits.conf will
105work, because that file is only read by PAM (ie just for real login users,
106not daemons).
107
108See utils/bitlbeed.c for more information about the program.
109
[bad4a586]110Just a little note: Now that we reach version 1.0, this shouldn't be that
111much of an issue anymore. However, on a public server, especially if you
112also use it for other things, it can't hurt to protect yourself against
113possible problems.
[b7d3cc34]114
115
116USAGE
117=====
118
119Not much to say here, it's all documented elsewhere already. Just connect to
120the new BitlBee IRC server and the bot (root) will tell you what to do.
121
122
123BACKGROUNDS
124===========
125
126We are both console lovers. But it is annoying to have a few tty's open with
127chat things in them. IRC, ICQ, MSN, AIM, Jabber... For X there is Gaim, which
128supports many chatprotocols. Why wasn't there such a thing for the console?
129
130The idea to port Gaim was easily thought of, of course. But we liked our IRC
131clients. And we used it the most, so we used it best. Importing it into the
132IRC client was a nice idea. But what if someone liked a different client.
133Then (s)he had to duplicate our work.
134
135That's a shame, we thought. Doing work twice is pointless. So when Wilmer
136got the ingenious thought in his mind while farming, to create an IRC to
137other chatnetworks gateway, we were both so excited, that we started working
138on it almost immediately. And the result is BitlBee.
139
140
141WEBSITE
142=======
143
144You can find new releases of BitlBee at:
145http://www.bitlbee.org/
146
[bad4a586]147The bug tracking system:
148http://bugs.bitlbee.org/
149
150Our version control system is Bazaar-NG. Our repository is at:
151http://code.bitlbee.org/
152
[b7d3cc34]153
154A NOTE ON ENCRYPTION
155====================
156
157BitlBee stores the accounts and settings (not your contact list though) in
158some sort of encrypted/obfuscated format.
159
160*** THIS IS NOT A SAFE FORMAT! ***
161
162You should still make sure the rights to the configuration directory and
163files are set so that only root and the BitlBee user can read/write them.
164
165This format is not to prevent malicicous users from running with your
166passwords, but to prevent accidental glimpses of the administrators to cause
167any harm. You have no choice but to trust root though.
168
169
170LEGAL
171=====
172
173BitlBee is distributed under the GPL (GNU General Public License). See the
174file COPYING for this license.
175
176Unfortunately some parts of the Gaim Jabber plugin (most notably the XML
177code) were licensed under the MPL (Mozilla Public License) version 1.1. We
178could not relicense this code under the GPL. As such it is still licensed
179under the MPL. The parts of the code to which this applies are marked as
180such.
181
182The MPL is provided in the file MPL-1.1.txt. This license is not GPL
183compatible. It is however a free software license.
184
185Another part (the md5 algorithm) is licensed under the Aladdin license.
186This license can be found in the files, to which this applies.
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/>
[bad4a586]194        Copyright (C) 2002-2005  Wilmer van der Gaast <wilmer@gaast.net>
[b7d3cc34]195                                 and others
Note: See TracBrowser for help on using the repository browser.