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