bip.conf - Configuration file for BIP IRC Proxy
~/.bip/bip.conf
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
bip.conf skeleton should be something like this :
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 { ... };
...
};
};
The syntax is quite simple :
- •
- everything after the # character is ignored
(comments)
- •
- each variable affectation must be finished with a
;
- •
- each section { } must be finished with a ;
If you use vim you will probably want to use vim with the provided
bip.vim syntax file to avoid common syntax and lexical mistakes. You
can also find an example configuration file along with BIP.
By default,
bipdir is the
$HOME/.bip directory and the parent
directory for client certificate, configuration, logs, pid, oidentd. If
environment variable
$HOME doesn't exist,
-s parameter must be
used.
-
client_side_ssl (default: false)
- When true, clients will need to connect to BIP using SSL.
You'll also need to generate a SSL cert/key pair in bipdir/bip.pem
(usually ~/.bip/bip.pem or /var/lib/bip/bip.pem) or
client_side_ssl_pem if defined.
-
client_side_ssl_pem (default:
<bipdir>/bip.pem)
- Set this to the full path of the cert/key pair bip should
use to accept clients SSL connections.
- client_side_ciphers
- OpenSSL cipher lists used for clients SSL connections. If
not set, OpenSSL default ciphers will be used.
-
client_side_dh_param DH parameters filename
(default: <bipdir>/dh.pem)
- Used for clients SSL connections, Supply at least 2048-bit
parameters.
- ssl_default_ciphers
- OpenSSL cipher lists used for server connections. If not
set, OpenSSL default ciphers will be used.
-
ip (default: 0.0.0.0)
- Listening IP address. This is the IP address bip will
listen for incoming client connections.
-
log (default: true)
- When true, the log system is enabled. Else, BIP will not
write a single log file. Backlog is then stored into memory.
-
log_system (default: true)
- When true, system messages such as connection errors are
logged. Else, BIP will not write system logs.
-
log_format (default:
%u/%n/%Y-%m/%c.%d.log)
- Determines the log filename depending on :
- %u username (name in user { }; section)
- %n network name (name in connection { }; section)
- %c channel name
- %Y 4 digits year
- %m 2 digits month
- %d 2 digits day
-
log_level (default: 1)
- Specify the verbosity of BIP from 0 (fatal errors) to 6
(huge debug output)
-
log_root (default: <bipdir>/logs
- Main log directory. Sub-directories and files will be
created from there depending on log_format.
-
log_sync_interval (default: 5)
- Defines the delay between each logfiles sync to the disk.
Must be a non null positive integer.
-
reconn_timer (default: 120)
- Defines the initial delay (in seconds) before a
reconnection attempt. The delay increases with the number of attempts:
delay = reconn_timer * number of attempts
-
pid_file (default:
<bipdir>/bip.pid)
- 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.
-
write_oidentd (default: false)
- Must be set to true to overwrite oidentd configs.
-
oidentd_file (default:
<bipdir>/.oidentd.conf)
- oidentd configuration file (if oidentd enabled).
-
port (default: 7778)
- The port on which BIP should listen for clients.
This section allows you to declare a network for use in the connection sections.
It may appear more than once in the configuration file.
-
ssl (default: false)
- If true, BIP will connect to this network using SSL only.
You cannot mix SSL servers and non-SSL servers in the same network
section. This is by choice, we believe it's a bad idea.
-
ssl_ciphers (override global
ssl_default_ciphers)
- OpenSSL cipher lists used for this network.
- name
- It's the network name used in the connection
section. Please note that this value is not used in log_format,
since it uses the variable name from the connection section.
BIP will cycle through the server sections list when reconnecting to a network.
It may appear more than once in a network section.
- host
- The server's hostname or IP address.
-
port (default: 6667)
- The server port to connect to.
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.
-
admin (default: false)
- 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.
-
backlog (default: true)
- Enable or disable the whole backlog system, which allows
clients to see a log replay upon connection.
-
backlog_always (default: false)
- If true, clients will always receive backlog_lines
log lines, even if they were already sent before. That means : If
backlog_always 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 backlog_lines is 0 ! If
you still want to do so, don't forget to /BIP BLRESET sometimes.
-
backlog_lines (default: 10)
- If set to 0, BIP will replay all the logs since last client
disconnect. Else, it'll replay exactly backlog_lines lines on each
channel and privates. Be aware that BIP will replay backlog_lines
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.
-
backlog_timestamp (default: time)
-
none disables timestamps in backlogged lines,
time or datetime allow one to select the timestamp format in
backlogged lines.
-
backlog_no_timestamp (default: false)
- This parameter is deprecated, use backlog_timestamp
instead. false implies backlog_timestamp = none and
true implies backlog_timestamp = time .
-
backlog_reset_on_talk (default: false)
- 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.
-
backlog_reset_connection (default:
false)
- When true, backlog_reset_on_talk option above is changed in
that the whole network backlog is reset when you talk in the network.
-
backlog_msg_only (default: false)
- When true, bip will backlog only channel/private
messages/notices. No topic change, nick change, user quit/part/join will
be backlogged upon connection.
-
bip_use_notice (default: false)
- If bip_use_notice 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
/BIP command replies.
- default_nick
- The default nick option for each connection section
where no nick is defined. See CONNECTION SECTION for more
details.
- default_realname
- The default realname option for each connection
section where no realname is defined. See CONNECTION SECTION
for more details.
- default_user
- The default user option for each connection section
where no user is defined. See CONNECTION SECTION for more
details.
- name
- The username. It'll be used to authenticate to bip and in
log_format.
- password
- The password. It MUST be generated with
bipmkpw or it'll not work.
-
ssl_check_mode (default: none)
- Tells whether BIP should check the server SSL certificate
and against what. Can be none for no check at all, ca to
check if the cert is signed by a Certificate Authority in repository, or
basic to check if cert exists in repository. The repository is
defined by ssl_check_store. This allows a "ssh-like"
private key generation scheme. Note that in basic mode:
- expired certificates that are in the store are considered valid.
- CA-signed certificates are considered valid even if not in store.
-
ssl_check_store (default: not set)
- This repository is browsed by BIP when a SSL certificate or
CA check is needed. In ssl_check_mode basic it must be a file, to
which certificates you choose to trust will be appended. In ssl_check_mode
ca 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 c_rehash, or unset, in which
case bip will attempt to use the default certificate store of the OpenSSL
it is built against.
-
ssl_client_certfile (default: not set)
- 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.
Each
connection section associates a user to the networks he wants to
connect to. Thus, it must be declared in the
User sections, and can be
used more than once.
-
away_nick (default: not set)
- If set, and if there are no more client attached, BIP will
change nickname to this away_nick. Your nickname will be restored
upon client connect.
-
no_client_away_msg (default: not set)
- 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.
-
follow_nick (default: false)
- 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.
-
autojoin_on_kick (default: true)
- If set to false bip will not attempt to re-join a channel
from which you were kicked.
-
ignore_first_nick (default: false)
- If set to true, BIP will ignore the nickname sent by the
client upon connect. Further nickname changes will be processed as usual.
-
ignore_server_capab (default: true)
- 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).
- network
- The network name. See the NETWORK SECTION.
-
log (override global log)
- When true, the file logs are enabled for this
connection. When false, no log file is written, logs are kept in
memory.
- nick
- BIP will send that string as your nickname upon connect. If
not specified and if default_nickname is specified in the
user section, BIP will use that default nickname string.
- on_connect_send
- 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.
- password
- This is the IRC server password, which is sent upon
connection to the IRC server only.
- realname
- BIP will send that string as the realname part (description
in whois result) upon connect. If not specified and if
default_realname is specified in the user section, BIP will
use that default realname string.
- sasl_mechanism
- Tells BIP to use specified SASL mechanism. Currently
supported: PLAIN, EXTERNAL. PLAIN mechanism requires sasl_username
and sasl_password and is the default if these are set.
- sasl_username
- This connection's username to pass on using SASL
authentication.
- sasl_password
- This connection's password to pass on using SASL
authentication.
- source_port
- If specified, tells BIP to connect from this port to the
IRC server.
-
ssl_check_mode (default: the user's
option)
- See ssl_check_mode option in User section.
- user
- 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 default_user is
specified in the user section, BIP will use that default user
string.
- vhost
- If specified, BIP will use vhost 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.
This section defines the list of channels to join for a user on a particular
network. It is to be found in the
connection sections and appear more
than once in a
connection section.
- name
- The channel name (#bip, &bip, ...).
- key
- The channel key if needed.
-
backlog (default: true)
- Enable or disable backlogging of this particular channel.
Setting this to true will NOT enable the backlog system, see the
user section.
On your IRC client, setup as many IRC servers as connections defined in your
connection section.
Host and port must match values defined in
ip and
port global
option. The password must be
username:password:connectionname where:
- •
- username is the name defined in the user
section;
- •
- password is the clear text value of the password
corresponding to the hashed password defined in the user
section;
- •
- connectionname is the name defined in
connection sub-section.
bip(1),
bipmkpw(1)
bip authors:
Arnaud 'nohar' Cornet
Loïc 'Kyoshiro' Gomez
Thanks to jj, YS and lafouine, for hanging around while we were coding.
Crypto shamelessly taken from Christophe 'sexy' Devine.
This man page is written by Loïc 'Kyoshiro' Gomez.