You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Pierre-Louis Bonicoli 1df884545f
Add a man page for the bipgenconfig script
3 months ago
samples Fix minor issues in bip sample configuration file 3 months ago
scripts new release: ensure NEWS file is up to date 3 months ago
src Fix spelling errors found by Lintian 3 months ago
systemd Add man pages in Documentation key of systemd unit 3 months ago
tests Fix test automake file to link openssl. 3 years ago
.clang-format Add .clang-format file. 3 years ago
.gitignore More files in .gitignore 3 years ago
AUTHORS Fix UTF-8 in all files 14 years ago
BUGS Cleanup BUGS and TODO. 14 years ago
COPYING Fix UTF-8 in all files 14 years ago
ChangeLog Update version and ChangeLog for bip-0.9.2 release. 3 months ago
INSTALL Update INSTALL file which refers to README 2 years ago
Makefile.am Make the tests subdirectory optional. 3 years ago
NEWS Synchronize NEWS file & NEWS from project 3 months ago
README '-Wall -Werror' automake switches are used by default 3 years ago
TODO Allow to set oidentd path 5 years ago
bip.1 bip manpage: mention -s switch in SYNOPSIS section 4 years ago
bip.conf.5 Fix spelling errors found by Lintian 3 months ago
bipgenconfig.1 Add a man page for the bipgenconfig script 3 months ago
bipmkpw.1 bipmkpw man page: mention bip man page 4 years ago
configure.ac Add -git to version string. 3 months ago

README

This is the BIP IRC Proxy README.

Bip can be used in two different ways:
- Old school bnc user style: easy and straightforward.
- Unix service style with and init.d scripts and the logs in /var/log

This small README file explains the usage "Old school" with which :
- you do not need the root privileges.
- gives easy access to the logs to the owner of the shell.

Table of contents :

I. Installation
II. Configuration
A. Manual configuration
B. Automated configuration
III. Running bip
IV. Using bip
A. Connecting your client(s)
B. Backlog and flood control
C. Multiple users and ident issues



I. INSTALLATION

Install bip on the machine that will be running bip (which is likely to be
your personnal or shared server) either compiling the package or using your
distro's package. Then create a configuration file.

Choose your distribution package if available. If not, build bip the
old-fashioned way. You will need make, gcc, lex, yacc, automake,
autoconf-archive and optionally libssl-dev to build bip.

Just issue:

From bip-X.Y.Z.tar.gz package:
# ./configure && make

From repository:
# autoreconf -i
# ./configure --enable-maintainer-mode && make

If openssl and its developement files are installed, bip should build with
SSL support. After a successful build the bip binary can be found in
./src/bip.

By default, "-Werror" is used. If you encounter warnings, you could try:
# CFLAGS="-Wno-error" ./configure && make


II. CONFIGURATION

First of all, create your bip configuration an log directory:

# mkdir -p ~/.bip/logs

There are two ways to create your bip configuration :
- edit the sample bip.conf file to match your needs
- use the bipgenconfig script to easily generate a configuration

If you want to connect to bip using an SSL client, you'll need to create
a certificate / key pair (in a bip.pem file) to allow bip to serve SSL
sockets.

A. MANUAL CONFIGURATION

If you are using a distribution package, the bip.conf sample configuration
file is likely to be shipped in /usr/share/doc/bip/examples/bip.conf.gz or
something similar.

If not, you'll find sample configuration file in the source package's
`samples' subdirectory.

Put the uncompressed configuration file in your ~/.bip directory (its
path should be ~/.bip/bip.conf), and edit it, most importantly the "user"
section that contains information about you and the servers you will want
to connect to. The "name" field in the "user" section is your login to
connect to bip.
The "name" field of the "connection" subsections are the server identifier
for when you connect to bip.

The "password" field is a hash of the password you will use to connect to
bip. To generate a hash value from a password, use bipmkpw, program which
comes in the bip package and source.

If you've set client_side_ssl to true, you'll need to generate a bip.pem
file containing a certificate / key pair. In order to do so, you can use
the third party `openssl' binary :

# openssl req -new -x509 -days 365 -nodes -out bip.pem -keyout bip.pem

You can then remove the passphrase with :

# openssl x509 -subject -dates -fingerprint -noout -in bip.pem

B. AUTOMATED CONFIGURATION

You can also use the bipgenconfig script to generate a new configuration.
This script will also help you generate the SSL certificate / key pair
needed for clients to connect to BIP through SSL.

This script can be found either in the source package's `scripts'
directory or shipped with your distribution's package.

Using the script is very simple, and it will generate a configuration
file but won't overwrite any existing configuration.

It will ask you the path to the bipmkpw binary, to automatically hash the
passwords you'll provide. Please make sure to enter the correct path to
the binary or you might observe unexpected behaviour.

You'll need to move the generated configuration from bip.conf.autogen to
bip.conf and the generated PEM file from bip.pem.autogen to bip.pem (or
whatever path you've configured in bip.conf).


III. RUNNING BIP

Once all this is configured, start bip as your regular user:

# ./src/bip

If you have installed bip in your path (or if you are using you
distribution's package), simply use:

# bip

Once bip starts, it connects to the different servers your defined in
all "user"'s "connection" blocks.


IV. USING BIP

A. CONNECTING YOUR CLIENT(S)

Then you want to use your regular irc client and connect to bip. Point
your client to the machine bip is running and set the proper port number
(defined in your bip.conf). You should then configure the client to use a
specific irc server password constructed this way:

user:password:connection

The user is the name field of the "user" section, the password is the
password (*not* the hash) corresponding to the "password" field of the
same user section (which is the hash generated with bipmkpw) and the
connection is the "name" field of the "connection" subsection. This is
how bip authenticates you and puts your client to the correct network.

Using the default (or sample file) configuration, logs are in ~/.bip/logs/

B. BACKLOG AND FLOOD CONTROL

Bip has a backlogging system which will send back parts of the last logs
upon client connection. Depending on your configuration, that may mean a
*lot* of data sent back to your client.

Users' messages will be replayed as if they were being sent at the moment
your client connects to bip, and if not disabled, system messages will
appear as coming from the "-bip" user.

Considering that, you may want to disable your client's anti-flood system,
totally or not, depending on it's flexibility.
Since bip doesn't replay CTCP messages, you can safely let your client's
anti-flood system manage them.

[Xchat]
If you're using Xchat, you can "disable" it by issuing these commands :
/set flood_msg_num = 1000
/set flood_msg_time = 10
In fact you'll tell xchat to activate its anti-flood system when you're
receiving more than 1000 messages in less than 10 seconds.

If you forgot to set these, private messages may not appear in separate
tabs as usual. If so, simply issue a :
/set gui_auto_open_dialog on

C. MULTIPLE USERS AND IDENT ISSUES

When you host many connections to the same IRC network, you might have
more connections than allowed by the network from one host.

Depending on the network and the services it runs, session limits may be
enforced either matching only your ip address/hostname, or matching the
username/ident part too.

To avoid being killed for session limit exceeded, you should define a
default_username in each user {}; block. A user without default_username
would appear as ~bip@yourhost if bip is the system user running bip. With
a default_username set to "myuser", he would appear as ~myuser@yourhost,
which may be sufficient for most networks.

If the network you're on is a bit more demanding, you can set up an
oidentd server on your host, and enable oidentd spoofing support
('write_oidentd = true;' option in bip configuration file). Let's
say bip is the system user running bip, you should add to
your /etc/oidentd.conf :

user "bip" {
default {
allow spoof_all
allow spoof_privport
allow spoof
}
}

Then reload oidentd and make sure that ~bip is accessible (+rx) by the
user running oidentd (which means most of the time ~bip should be world
readable and browsable +rx).

If you already have a ~bip/.oidentd.conf file, don't worry, bip'll only
add its entries without deleting any of the contents of the file.
This step should remove the "~" character from the username/ident part of
your ircmask, and thus satisfy some networks.

If the network is still killing you for session limit exceeded, you'll
have to contact it's admins and ask them for an exception on your host or
ip address.


Happy ircing!

-- Arnaud Cornet <nohar@t1r.net> and Loïc Gomez <opensource@kyoshiro.org>