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