bip/bip.conf.5

.TH BIP.CONF 5 "2 January 2022"

.SH NAME

bip.conf \- Configuration file for BIP IRC Proxy

.SH SYNOPSIS

.PP
~/.bip/bip.conf

.SH DESCRIPTION

A BIP configuration file consists of a list of variable affectations or
sections. It contains the global options, networks definitions, users
configuration, users connections declarations. Each section is described in
this manpage.

The
.BR bip.conf
skeleton should be something like this :

.EX
option1 = value;
option2 = value;
 ...

network {
    net_opt = value;
    ...
    server { ... };
    server { ... };
};
 ...

user {
    user_opt = value;
    ...
    connection {
        conn_opt = value;
        ...
        channel { ... };
    };
    connection {
        conn_opt = value;
        ...
        channel { ... };
        channel { ... };
        ...
    };
};
.EE

.SH SYNTAX RULES

The syntax is quite simple :
.RS
.IP \(bu 4
everything after the \fB#\fP character is ignored (comments)
.IP \(bu 4
each variable affectation must be finished with a \fB;\fP
.IP \(bu 4
each section { } must be finished with a \fB;\fP
.RE

If you use vim you will probably want to use vim with the provided
\fBbip.vim\fP syntax file to avoid common syntax and lexical mistakes. You can
also find an example configuration file along with BIP.

By default, \fBbipdir\fR is the \fI$HOME/.bip\fR directory and the parent
directory for client certificate, configuration, logs, pid, oidentd. If
environment variable \fB$HOME\fP doesn't exist, \fB-s\fP parameter must be
used.

.SH GLOBAL OPTIONS

.TP
\fBclient_side_ssl\fP (default: \fBfalse\fP)
When true, clients will need to connect to BIP using SSL.
You'll also need to generate a SSL cert/key pair in \fIbipdir/bip.pem\fR
(usually \fI~/.bip/bip.pem\fR or \fI/var/lib/bip/bip.pem\fR) or \fBclient_side_ssl_pem\fP if
defined.

.TP
\fBclient_side_ssl_pem\fP (default: \fI<bipdir>/bip.pem\fR)
Set this to the full path of the cert/key pair bip should use to accept clients
SSL connections.

.TP
\fBclient_side_ciphers\fP
OpenSSL cipher lists used for clients SSL connections. If not set, OpenSSL
default ciphers will be used.

.TP
\fBclient_side_dh_param\fP DH parameters filename\fP (default: \fI<bipdir>/dh.pem\fR)
Used for clients SSL connections, Supply at least 2048-bit parameters.

.TP
\fBssl_default_ciphers\fP
OpenSSL cipher lists used for server connections. If not set, OpenSSL default
ciphers will be used.

.TP
\fBip\fP (default: \fB0.0.0.0\fP)
Listening IP address. This is the IP address bip will listen for incoming
client connections.

.TP
\fBlog\fP (default: \fBtrue\fP)
When true, the log system is enabled. Else, BIP will not write a single log
file. Backlog is then stored into memory.

.TP
\fBlog_system\fP (default: \fBtrue\fP)
When true, system messages such as connection errors are logged. Else, BIP will
not write system logs.

.TP
\fBlog_format\fP (default: \fB%u/%n/%Y-%m/%c.%d.log\fP)
Determines the log filename depending on :
.br
\- %u username (name in \fBuser\fP { }; section)
.br
\- %n network name (name in \fBconnection\fP { }; section)
.br
\- %c channel name
.br
\- %Y 4 digits year
.br
\- %m 2 digits month
.br
\- %d 2 digits day

.TP
\fBlog_level\fP (default: \fB1\fP)
Specify the verbosity of BIP from 0 (fatal errors) to 6 (huge debug output)

.TP
\fBlog_root\fP (default: \fI<bipdir>/logs\fR
Main log directory. Sub-directories and files will be created from there
depending on \fBlog_format\fP.

.TP
\fBlog_sync_interval\fP (default: \fB5\fP)
Defines the delay between each logfiles sync to the disk. Must be a non null
positive integer.

.TP
\fBreconn_timer\fP (default: \fB30\fP)
Defines the initial delay (in seconds) before a reconnection attempt.
The delay increases with the number of attempts:
delay = reconn_timer * number of attempts

.TP
\fBpid_file\fP (default: \fI<bipdir>/bip.pid\fR)
Defines the file where BIP's pid will be stored. BIP checks if this file exists
and if the pid is still alive upon startup. If true, BIP refuses to start.

.TP
\fBwrite_oidentd\fP (default: \fIfalse\fR)
Must be set to true to overwrite oidentd configs.

.TP
\fBoidentd_file\fP (default: \fI<bipdir>/.oidentd.conf\fR)
oidentd configuration file (if oidentd enabled).

.TP
\fBport\fP (default: \fB7778\fP)
The port on which BIP should listen for clients.

.SH NETWORK SECTION

This section allows you to declare a network for use in the connection
sections. It may appear more than once in the configuration file.

.TP
\fBssl\fP (default: \fBfalse\fP)
If true, BIP will connect to this network using SSL only. You cannot mix
SSL servers and non-SSL servers in the same \fBnetwork\fP section. This is by choice,
we believe it's a bad idea.

.TP
\fBssl_ciphers\fP (override global \fBssl_default_ciphers\fP)
OpenSSL cipher lists used for this network.

.TP
\fBname\fP
It's the network name used in the \fBconnection\fP section. Please note that
this value is not used in \fBlog_format\fP, since it uses the variable
\fBname\fP from the \fBconnection\fP section.

.SH SERVER SUB-SECTION

BIP will cycle through the server sections list when reconnecting to a network.
It may appear more than once in a network section.

.TP
\fBhost\fP
The server's hostname or IP address.

.TP
\fBport\fP (default: \fB6667\fP)
The server port to connect to.

.SH USER SECTION

This section allows you to define the users allowed to connect to BIP and their
options. It may appear more than once in the configuration file.

.TP
\fBadmin\fP (default: \fBfalse\fP)
If a user has admin set to true, he'll become a bip administrator, which allows
him for example to reload bip from IRC or to see the user configuration.

.TP
\fBbacklog\fP (default: \fBtrue\fP)
Enable or disable the whole backlog system, which allows clients to see a
log replay upon connection.

.TP
\fBbacklog_always\fP (default: \fBfalse\fP)
If true, clients will always receive \fBbacklog_lines\fP log lines, even if
they were already sent before. That means :
If \fBbacklog_always\fP is false, backlog will be reset whenever there
is no more client connected to a network. Else backlog will not be reset.
This option should of course not be enabled if \fBbacklog_lines\fP is 0 !
If you still want to do so, don't forget to \fB/BIP BLRESET\fP sometimes.

.TP
\fBbacklog_lines\fP (default: \fB0\fP)
If set to 0, BIP will replay all the logs since last client disconnect. Else,
it'll replay exactly \fBbacklog_lines\fP lines on each channel and privates.
Be aware that BIP will replay \fBbacklog_lines\fP lines of all privates, even
if there are more. For example if Coyote told you 12 lines and then RoadRunner
6, you'll only have a replay of the 6 RoadRunner's lines and the last 4 of
Coyote's.

.TP
\fBbacklog_timestamp\fP (default: \fBtime\fP)
\fBnone\fP disables timestamps in backlogged lines, \fBtime\fP or
\fBdatetime\fP allow one to select the timestamp format in backlogged lines.

.TP
\fBbacklog_no_timestamp\fP (default: \fBfalse\fP)
This parameter is deprecated, use \fBbacklog_timestamp\fP instead.
.I false
implies
.I backlog_timestamp = "none"
and
.I true
implies
.I backlog_timestamp = "time"
\&.

.TP
\fBbacklog_reset_on_talk\fP (default: \fBfalse\fP)
When true, backlog will be reset upon client talk (channel/private message or
action). It means that next time you log to your bip session, the backlogging
will start at the time right after your last words on that specific channel or
query.

.TP
\fBbacklog_reset_connection\fP (default: \fBfalse\fP)
When true, backlog_reset_on_talk option above is changed in that the whole
network backlog is reset when you talk in the network.

.TP
\fBbacklog_msg_only\fP (default: \fBfalse\fP)
When true, bip will backlog only channel/private messages/notices. No topic
change, nick change, user quit/part/join will be backlogged upon connection.

.TP
\fBbip_use_notice\fP (default: \fBfalse\fP)
If \fBbip_use_notice\fP is true, bip's notifications to the clients will be
send as notices instead of private messages. For example, this setting applies
to disconnection notifications or \fB/BIP\fP command replies.

.TP
\fBdefault_nick\fP
The default nick option for each \fBconnection\fP section where no \fBnick\fP
is defined. See \fBCONNECTION SECTION\fP for more details.

.TP
\fBdefault_realname\fP
The default realname option for each \fBconnection\fP section where no
\fBrealname\fP is defined. See \fBCONNECTION SECTION\fP for more details.

.TP
\fBdefault_user\fP
The default user option for each \fBconnection\fP section where no \fBuser\fP
is defined. See \fBCONNECTION SECTION\fP for more details.

.TP
\fBname\fP
The username. It'll be used to authenticate to bip and in \fBlog_format\fP.

.TP
\fBpassword\fP
The password. It \fBMUST\fP be generated with \fBbipmkpw\fP or it'll not work.

.TP
\fBssl_check_mode\fP (default: \fBnone\fP)
Tells whether BIP should check the server SSL certificate and against what.
Can be \fBnone\fP for no check at all, \fBca\fP to check if the cert is signed
by a Certificate Authority in repository, or \fBbasic\fP to check if cert
exists in repository. The repository is defined by \fBssl_check_store\fP.  This
allows a "ssh-like" private key generation scheme. Note that in basic mode:
.br
 - expired certificates that are in the store are considered valid.
.br
 - CA-signed certificates are considered valid even if not in store.

.TP
\fBssl_check_store\fP (default: \fBnot set\fP)
This repository is browsed by BIP when a SSL certificate or CA check is needed.
In ssl_check_mode \fBbasic\fP it must be a file, to which certificates you
choose to trust will be appended. In ssl_check_mode \fBca\fP it may be a
single file containing one or more trusted certificates concatenated together
between BEGIN CERTIFICATE and END CERTIFICATE lines, a directory containing
individual certificates in PEM format which has been processed by \fBc_rehash\fP,
or unset, in which case bip will attempt to use the default certificate store of
the OpenSSL it is built against.

.TP
\fBssl_client_certfile\fP (default: \fBnot set\fP)
Some networks (OFTC at least) allow you to authenticate to nickserv services
using a client side certificate. Make this variable point to the .pem file to
use this feature.

.SH CONNECTION SUB-SECTION

Each \fBconnection\fP section associates a user to the networks he wants to connect
to. Thus, it must be declared in the \fBUser\fP sections, and can be used more than
once.

.TP
\fBaway_nick\fP (default: \fBnot set\fP)
If set, and if there are no more client attached, BIP will change nickname to
this \fBaway_nick\fP. Your nickname will be restored upon client connect.

.TP
\fBno_client_away_msg\fP (default: \fBnot set\fP)
This options allows you to set an away message. This away message will be set
when the last client disconnects, and removed when a client connects.

.TP
\fBfollow_nick\fP (default: \fBfalse\fP)
If set to true, when you change nick, BIP stores the new nickname as the new
default nickname value. Thus, if you are disconnected from the server, BIP will
restore the correct nickname.

.TP
\fBautojoin_on_kick\fP (default: \fBtrue\fP)
If set to false bip will not attempt to re-join a channel from which you were
kicked.

.TP
\fBignore_first_nick\fP (default: \fBfalse\fP)
If set to true, BIP will ignore the nickname sent by the client upon connect.
Further nickname changes will be processed as usual.

.TP
\fBignore_server_capab\fP (default: \fBtrue\fP)
By default bip ignores when a server advertises the CAPAB feature. Servers that
support this can prefix each line with a "+" or a "-" depending if a user is
registered or not. xchat checks if a server has the CAPAB feature and enables
it.
If you have two clients connected to a bip connection, one that supports this
mode and one that does not, you see the plus and the minuses on each line in
the client that does not support CAPAB. To avoid that, when a server advertises
CAPAB bip simply removes it. You can set this option to false to keep using
CAPAB (if you only use clients that support it for instance).

.TP
\fBnetwork\fP
The network name. See the \fBNETWORK SECTION\fP.

.TP
\fBlog\fP (override global log)
When \fBtrue\fP, the file logs are enabled for this connection.
When \fBfalse\fP, no log file is written, logs are kept in memory.

.TP
\fBnick\fP
BIP will send that string as your nickname upon connect. If not specified
and if \fBdefault_nickname\fP is specified in the \fBuser\fP section, BIP will
use that default nickname string.

.TP
\fBon_connect_send\fP
You can specify this field more than once. BIP will send the text as is to the
server. It'd be useful for a greet on connect or to send your NickServ password.

.TP
\fBpassword\fP
This is the IRC server password, which is sent upon connection to the IRC server
only.

.TP
\fBrealname\fP
BIP will send that string as the realname part (description in whois result)
upon connect. If not specified and if \fBdefault_realname\fP is specified in
the \fBuser\fP section, BIP will use that default realname string.

.TP
\fBsasl_mechanism\fP
Tells BIP to use specified SASL mechanism. Currently supported: PLAIN, EXTERNAL.
PLAIN mechanism requires \fBsasl_username\fP and \fBsasl_password\fP and is the
default if these are set.

.TP
\fBsasl_username\fP
This connection's username to pass on using SASL authentication.

.TP
\fBsasl_password\fP
This connection's password to pass on using SASL authentication.

.TP
\fBsource_port\fP
If specified, tells BIP to connect from this port to the IRC server.

.TP
\fBssl_check_mode\fP (default: \fBthe user's option\fP)
See \fBssl_check_mode\fP option in \fBUser\fP section.

.TP
\fBuser\fP
BIP will send that string as the user part (usually between ! and @ in a whois
result) upon connect. It's also used by the oidentd support (if enabled). If
not specified and if \fBdefault_user\fP is specified in the \fBuser\fP section,
BIP will use that default user string.

.TP
\fBvhost\fP
If specified, BIP will use \fBvhost\fP as the IP address to bind to when
connecting to the IRC server. It'll allow you to use a specific IP address
for this network when you have more than one. This options is totally useless
to people who only have one IP address.

.SH CHANNEL SUB-SUB-SECTION

This section defines the list of channels to join for a user on a particular
network. It is to be found in the \fBconnection\fP sections and appear more than once
in a \fBconnection\fP section.

.TP
\fBname\fP
The channel name (#bip, &bip, ...).

.TP
\fBkey\fP
The channel key if needed.

.TP
\fBbacklog\fP (default: \fBtrue\fP)
Enable or disable backlogging of this particular channel.
Setting this to true will NOT enable the backlog system, see the \fBuser\fP
section.

.SH IRC CLIENT CONFIGURATION
.P
On your IRC client, setup as many IRC servers as connections defined in your
\fBconnection\fP section.
.P
Host and port must match values defined in \fBip\fP and \fBport\fP global
option. The password must be \fIusername:password:connectionname\fR where:

.RS
.IP \(bu 4
username is the \fIname\fR defined in the \fIuser\fR section;
.IP \(bu 4
password is the clear text value of the \fIpassword\fR corresponding to the
hashed password defined in the \fIuser\fR section;
.IP \(bu 4
connectionname is the \fIname\fR defined in \fIconnection\fR sub-section.
.RE

.SH SEE ALSO

.BR bip (1),
.BR bipmkpw (1)

.SH AUTHOR

bip authors:
.br
Arnaud 'nohar' Cornet
.br
Loïc 'Kyoshiro' Gomez

Thanks to jj, YS and lafouine, for hanging around while we were coding.
.br
Crypto shamelessly taken from Christophe 'sexy' Devine.
.br
This man page is written by Loïc 'Kyoshiro' Gomez.