bip.conf - Configuration file for BIP IRC Proxy
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.
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 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.