1This is the BIP IRC Proxy README. 2 3Bip can be used in two different ways: 4- Old school bnc user style: easy and straightforward. 5- Unix service style with and init.d scripts and the logs in /var/log 6 7This small README file explains the usage "Old school" with which : 8 - you do not need the root privileges. 9 - gives easy access to the logs to the owner of the shell. 10 11Table of contents : 12 13 I. Installation 14 II. Configuration 15 A. Manual configuration 16 B. Automated configuration 17 III. Running bip 18 IV. Using bip 19 A. Connecting your client(s) 20 B. Backlog and flood control 21 C. Multiple users and ident issues 22 23 24 25I. INSTALLATION 26 27 Install bip on the machine that will be running bip (which is likely to be 28 your personnal or shared server) either compiling the package or using your 29 distro's package. Then create a configuration file. 30 31 Choose your distribution package if available. If not, build bip the 32 old-fashioned way. You will need make, gcc, lex, yacc, automake, 33 autoconf-archive and optionally libssl-dev to build bip. 34 35 Just issue: 36 37 From bip-X.Y.Z.tar.gz package: 38 # ./configure && make 39 40 From repository: 41 # autoreconf -i 42 # ./configure --enable-maintainer-mode && make 43 44 If openssl and its developement files are installed, bip should build with 45 SSL support. After a successful build the bip binary can be found in 46 ./src/bip. 47 48 By default, "-Werror" is used. If you encounter warnings, you could try: 49 # CFLAGS="-Wno-error" ./configure && make 50 51 52II. CONFIGURATION 53 54 First of all, create your bip configuration an log directory: 55 56 # mkdir -p ~/.bip/logs 57 58 There are two ways to create your bip configuration : 59 - edit the sample bip.conf file to match your needs 60 - use the bipgenconfig script to easily generate a configuration 61 62 If you want to connect to bip using an SSL client, you'll need to create 63 a certificate / key pair (in a bip.pem file) to allow bip to serve SSL 64 sockets. 65 66 A. MANUAL CONFIGURATION 67 68 If you are using a distribution package, the bip.conf sample configuration 69 file is likely to be shipped in /usr/share/doc/bip/examples/bip.conf.gz or 70 something similar. 71 72 If not, you'll find sample configuration file in the source package's 73 `samples' subdirectory. 74 75 Put the uncompressed configuration file in your ~/.bip directory (its 76 path should be ~/.bip/bip.conf), and edit it, most importantly the "user" 77 section that contains information about you and the servers you will want 78 to connect to. The "name" field in the "user" section is your login to 79 connect to bip. 80 The "name" field of the "connection" subsections are the server identifier 81 for when you connect to bip. 82 83 The "password" field is a hash of the password you will use to connect to 84 bip. To generate a hash value from a password, use bipmkpw, program which 85 comes in the bip package and source. 86 87 If you've set client_side_ssl to true, you'll need to generate a bip.pem 88 file containing a certificate / key pair. In order to do so, you can use 89 the third party `openssl' binary : 90 91 # openssl req -new -x509 -days 365 -nodes -out bip.pem -keyout bip.pem 92 93 You can then remove the passphrase with : 94 95 # openssl x509 -subject -dates -fingerprint -noout -in bip.pem 96 97 B. AUTOMATED CONFIGURATION 98 99 You can also use the bipgenconfig script to generate a new configuration. 100 This script will also help you generate the SSL certificate / key pair 101 needed for clients to connect to BIP through SSL. 102 103 This script can be found either in the source package's `scripts' 104 directory or shipped with your distribution's package. 105 106 Using the script is very simple, and it will generate a configuration 107 file but won't overwrite any existing configuration. 108 109 It will ask you the path to the bipmkpw binary, to automatically hash the 110 passwords you'll provide. Please make sure to enter the correct path to 111 the binary or you might observe unexpected behaviour. 112 113 You'll need to move the generated configuration from bip.conf.autogen to 114 bip.conf and the generated PEM file from bip.pem.autogen to bip.pem (or 115 whatever path you've configured in bip.conf). 116 117 118III. RUNNING BIP 119 120 Once all this is configured, start bip as your regular user: 121 122 # ./src/bip 123 124 If you have installed bip in your path (or if you are using you 125 distribution's package), simply use: 126 127 # bip 128 129 Once bip starts, it connects to the different servers your defined in 130 all "user"'s "connection" blocks. 131 132 133IV. USING BIP 134 135 A. CONNECTING YOUR CLIENT(S) 136 137 Then you want to use your regular irc client and connect to bip. Point 138 your client to the machine bip is running and set the proper port number 139 (defined in your bip.conf). You should then configure the client to use a 140 specific irc server password constructed this way: 141 142 user:password:connection 143 144 The user is the name field of the "user" section, the password is the 145 password (*not* the hash) corresponding to the "password" field of the 146 same user section (which is the hash generated with bipmkpw) and the 147 connection is the "name" field of the "connection" subsection. This is 148 how bip authenticates you and puts your client to the correct network. 149 150 Using the default (or sample file) configuration, logs are in ~/.bip/logs/ 151 152 B. BACKLOG AND FLOOD CONTROL 153 154 Bip has a backlogging system which will send back parts of the last logs 155 upon client connection. Depending on your configuration, that may mean a 156 *lot* of data sent back to your client. 157 158 Users' messages will be replayed as if they were being sent at the moment 159 your client connects to bip, and if not disabled, system messages will 160 appear as coming from the "-bip" user. 161 162 Considering that, you may want to disable your client's anti-flood system, 163 totally or not, depending on it's flexibility. 164 Since bip doesn't replay CTCP messages, you can safely let your client's 165 anti-flood system manage them. 166 167 [Xchat] 168 If you're using Xchat, you can "disable" it by issuing these commands : 169 /set flood_msg_num = 1000 170 /set flood_msg_time = 10 171 In fact you'll tell xchat to activate its anti-flood system when you're 172 receiving more than 1000 messages in less than 10 seconds. 173 174 If you forgot to set these, private messages may not appear in separate 175 tabs as usual. If so, simply issue a : 176 /set gui_auto_open_dialog on 177 178 C. MULTIPLE USERS AND IDENT ISSUES 179 180 When you host many connections to the same IRC network, you might have 181 more connections than allowed by the network from one host. 182 183 Depending on the network and the services it runs, session limits may be 184 enforced either matching only your ip address/hostname, or matching the 185 username/ident part too. 186 187 To avoid being killed for session limit exceeded, you should define a 188 default_username in each user {}; block. A user without default_username 189 would appear as ~bip@yourhost if bip is the system user running bip. With 190 a default_username set to "myuser", he would appear as ~myuser@yourhost, 191 which may be sufficient for most networks. 192 193 If the network you're on is a bit more demanding, you can set up an 194 oidentd server on your host, and enable oidentd spoofing support 195 ('write_oidentd = true;' option in bip configuration file). Let's 196 say bip is the system user running bip, you should add to 197 your /etc/oidentd.conf : 198 199 user "bip" { 200 default { 201 allow spoof_all 202 allow spoof_privport 203 allow spoof 204 } 205 } 206 207 Then reload oidentd and make sure that ~bip is accessible (+rx) by the 208 user running oidentd (which means most of the time ~bip should be world 209 readable and browsable +rx). 210 211 If you already have a ~bip/.oidentd.conf file, don't worry, bip'll only 212 add its entries without deleting any of the contents of the file. 213 This step should remove the "~" character from the username/ident part of 214 your ircmask, and thus satisfy some networks. 215 216 If the network is still killing you for session limit exceeded, you'll 217 have to contact it's admins and ask them for an exception on your host or 218 ip address. 219 220 221 Happy ircing! 222 223-- Arnaud Cornet <nohar@t1r.net> and Loïc Gomez <opensource@kyoshiro.org> 224 225