source: doc/README @ 1999fe5

Last change on this file since 1999fe5 was 1999fe5, checked in by dequis <dx@…>, at 2016-12-26T00:18:55Z

Misc documentation updates

  • Remove a bunch of mentions of yahoo
  • Remove 'smileys' topic from help index
  • Add 'identify_methods' help topic
  • Mention new commands like 'chat list' or 'plugins'
  • Property mode set to 100644
File size: 6.3 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
11RUN MODES
12=========
13
14--- (Fork)Daemon mode
15
16These days ForkDaemon mode is the recommended way of running BitlBee. The
17difference between Daemon and ForkDaemon mode is that in the latter, a
18separate process is spawned for every user. This costs a little bit more
19memory, but means that if one user hits a bug in the code, not all other
20users get disconnected with him/her.
21
22To use BitlBee in any daemon mode, just start it with the right flags or
23enable it in bitlbee.conf (see the RunMode option). You probably want to
24write an init script to start BitlBee automatically after a reboot. (This
25is where you realise using a package from your distro would've been a better
26idea. :-P)
27
28Please do make sure that the user BitlBee runs as (not root, please!) is
29able to read from and write to the /var/lib/bitlbee directory to save your
30settings!
31
32--- inetd installation (more or less deprecated)
33
34After installation you have to set up inetd (you got that one running,
35right? If not, just take a look at utils/bitlbeed.c) to start BitlBee. You
36need to add BitlBee to inetd.conf, like this:
37
386667 stream tcp nowait nobody /usr/sbin/tcpd /usr/local/sbin/bitlbee
39
40Creating a special BitlBee user and running BitlBee with that UID (instead
41of just 'nobody') might be a good idea.
42
43*BSD/Darwin/OSX NOTE: Most *BSD inetds are more scrict than the one that
44comes with Linux systems. Possibly all non-Linux inetds are like this. They
45don't allow you to specify a port number in the inetd.conf entry, instead
46you have to put a service name there (one that is also mentioned in
47/etc/services). So if there's no line in /services for 6667/tcp (or whatever
48you choose), add it and use that name in the inetd.conf entry.
49
50-- xinetd installation (equally deprecated)
51
52Most machines use xinetd instead of inetd these days. If your machine runs
53xinetd, you can copy the bitlbee.xinetd file from the doc/ directory to your
54xinetd.d/ directory. Most likely you'll have to change a thing or two before
55it'll work.
56
57After configuring your (x)inetd, send the daemon a SIGHUP and things should
58work. If not, see your syslogs, since both daemons will complain there when
59something's wrong.
60
61Also, don't forget to create the configuration directory (/var/lib/bitlbee/
62by default) and chown it to the UID BitlBee is running as. Make sure this
63directory is read-/writable by this user only.
64
65
66DEPENDENCIES
67============
68
69BitlBee's only real dependency is GLib. This is available on virtually every
70platform. Any recent version of GLib (2.4 or higher) will work.
71
72Off-the-Record encryption support can be included if libotr is available on
73your machine. Pass --otr=1 to configure to build it into BitlBee, or
74--otr=plugin to build it as a separate loadable plugin (mostly meant for
75distro packages).
76
77These days, many IM protocols use SSL/TLS connections (for authentication
78or for the whole session). BitlBee can use several SSL libraries for this:
79GnuTLS, NSS (which comes with Mozilla) and OpenSSL. OpenSSL is not GPL-
80compatible in some situations, so using GnuTLS is preferred. However,
81especially on *BSD, OpenSSL can be considered part of the operating system,
82which eliminates the GPL incompatibility.
83
84The incompatibility is also the reason why the SSL library detection code
85doesn't attempt to use OpenSSL. If you want to use OpenSSL, you have to
86force configure to use it using the --ssl=openssl parameter. For more
87information about this problem, see the URL's configure will write to stdout
88when you attempt to use OpenSSL.
89
90
91PORTABILITY ISSUES
92==================
93
94The configure script is may not work very well with some non-bash shells (but
95dash is supported), so if you experience problems, make sure you use bash to
96run the script. Same for the Makefile, it only works well with GNU make. (gmake
97on most BSD systems)
98
99If someone can tell us how to write Makefiles that work with both/all
100versions of make, we'd love to hear it, but it seems this just isn't
101possible.
102
103
104USAGE
105=====
106
107Not much to say here, it's all documented elsewhere already. Just connect to
108the new BitlBee IRC server and the bot (root) will tell you what to do.
109
110
111BACKGROUNDS
112===========
113
114We are both console lovers. But it is annoying to have a few tty's open with
115chat things in them. IRC, ICQ, MSN, AIM, Jabber... For X there is Gaim, which
116supports many chatprotocols. Why wasn't there such a thing for the console?
117
118The idea to port Gaim was easily thought of, of course. But we liked our IRC
119clients. And we used it the most, so we used it best. Importing it into the
120IRC client was a nice idea. But what if someone liked a different client.
121Then (s)he had to duplicate our work.
122
123That's a shame, we thought. Doing work twice is pointless. So when Wilmer
124got the ingenious thought in his mind while farming, to create an IRC to
125other chatnetworks gateway, we were both so excited, that we started working
126on it almost immediately. And the result is BitlBee.
127
128
129WEBSITE
130=======
131
132You can find new releases of BitlBee at:
133http://www.bitlbee.org/
134
135The bug tracking system:
136http://bugs.bitlbee.org/
137
138Our version control system is Bazaar. Our repository is at:
139http://code.bitlbee.org/
140
141More documentation on the Wiki:
142http://wiki.bitlbee.org/
143
144
145A NOTE ON PASSWORD ENCRYPTION
146=============================
147
148BitlBee currently uses salted MD5 and RC4 to store the passwords. This means
149that people who somehow get their hands on your configuration files can't
150easily extract your passwords from them anymore.
151
152However, once you log into the BitlBee server and send your password, an
153intruder with tcpdump can still read your passwords. This can't really be
154avoided, of course. So if you run a public server, it's most important that you
155don't give root access to people who like to play with tcpdump.
156
157LEGAL
158=====
159
160BitlBee is distributed under the GPL (GNU General Public License). See the
161file COPYING for this license.
162
163
164        BitlBee - An IRC to other chat networks gateway
165                  <http://www.bitlbee.org/>
166        Copyright (C) 2002-2010  Wilmer van der Gaast <wilmer@gaast.net>
167                                 and others
Note: See TracBrowser for help on using the repository browser.