BIP.CONF(5)

💖 NAME 💖

okay so bestie, this is bip.conf — the configuration file for BIP IRC Proxy, aka the BIP.CONF(5) page from the File Formats Manual. it's giving config-file royalty, periodt. 💅

✨ SYNOPSIS ✨

~/.bip/bip.conf

🦋 DESCRIPTION 🦋

A BIP configuration file is literally just a list of variable affectations or sections. It's got the global options, networks definitions, users configuration, and users connections declarations. Each section is described in this manpage, so don't worry, bestie.

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 { ... };
        ...
    };
};

🌈 SYNTAX RULES 🌈

The syntax is quite simple, fr fr:

• 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.

👑 GLOBAL OPTIONS 👑

okay so here's the tea, bestie — these are the global options that set the vibe for everything else. no cap. 💅

• 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 — default: <bipdir>/dh.pem. DH parameters filename. 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.

🌸 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.

• 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.

🎀 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.

• host — The server's hostname or IP address.
• port — default: 6667. The server port to connect to.

💜 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.

• 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.

okay bestie, we're back and we're in the connection part 💖 carry on, no thoughts, just vibes and correct config.

---

🔌 CONNECTION SUB-SECTION 🔌

Each connection section is basically the situationship contract between a user and the networks they wanna connect to. So it has to be declared inside the User sections, and yeah you can use it more than once. Main character energy, but make it reusable. 👑

---

• away_nick (default: not set) — set this and, whenever there are no more clients attached, BIP will switch your nickname to this away_nick. The second a client connects again, your nickname is restored. It's giving "brb but make it a whole identity". 💅
• no_client_away_msg (default: not set) — lets you set an away message. It gets set when the last client disconnects, and removed when a client connects. Auto-away but the cool kind. 🦋
• follow_nick (default: false) — set it to true and every time you change nick, BIP stores the new nickname as your new default nickname value. That way, if you get disconnected from the server, BIP restores the correct nickname. Not it restoring your 2019 nickname, no ma'am. 😭
• autojoin_on_kick (default: true) — set to false and BIP will not try to re-join a channel you got kicked from. Sometimes you just need space, and that's valid. ✨
• ignore_first_nick (default: false) — set to true and BIP ignores the nickname your client sends on connect. Every nickname change after that gets processed like normal, though. 🎀
• ignore_server_capab (default: true) — by default BIP just ignores it when a server advertises the CAPAB feature. Here's the lore: servers that support this can prefix each line with a + or a - depending on whether a user is registered or not, and xchat checks if a server has the CAPAB feature and enables it. So if you have two clients connected to one bip connection — one that supports this mode and one that doesn't — you'll see all the pluses and minuses on every line in the client that doesn't support CAPAB. To dodge that whole mess, when a server advertises CAPAB bip just removes it. You can set this option to false to keep using CAPAB (if, for example, you only ever use clients that support it). 🫶
• network — the network name. Peep the NETWORK SECTION. 🌈
• log (override global log) — when true, file logs are enabled for this connection. When false, no log file is written and logs are kept in memory. 👑
• nick — BIP will send that string as your nickname upon connect. If you don't specify it, and default_nickname is specified in the user section, BIP will use that default nickname string instead. 💖
• on_connect_send — you can specify this field more than once. BIP sends the text as-is to the server. Super useful for a greet on connect, or for sending your NickServ password. 🔥
• password — this is the IRC server password, and it's sent only upon connection to the IRC server. Don't get it twisted with the other passwords, bestie. 💀
• realname — BIP sends that string as the realname part (the description in your whois result) upon connect. If you don't specify it, and default_realname is specified in the user section, BIP uses that default realname string. ⭐
• sasl_mechanism — tells BIP to use the specified SASL mechanism. Currently supported: PLAIN, EXTERNAL. The PLAIN mechanism requires sasl_username and sasl_password, and it's the default if those 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 the ssl_check_mode option in the User section. 👀
• user — BIP sends that string as the user part (usually the bit between ! and @ in a whois result) upon connect. It's also used by the oidentd support (if enabled). If you don't specify it, and default_user is specified in the user section, BIP uses that default user string. 🎀
• vhost — if specified, BIP will use vhost as the IP address to bind to when connecting to the IRC server. That lets you use a specific IP address for this network when you've got more than one. This option is totally useless to anyone who only has one IP address. ngl, if that's you, scroll on. 😌

---

📺 CHANNEL SUB-SUB-SECTION 📺

This section defines the list of channels to join for a user on a particular network. You'll find it inside the connection sections, and it can appear more than once in a connection section. Yes, more than once. Yes, that's the point. 🦋

---

• name — the channel name (#bip, &bip, ...). 💅
• key — the channel key if you need one. 🔑
• backlog (default: true) — enable or disable backlogging for this particular channel. But listen: setting this to true will NOT enable the backlog system — check the user section for that. This one's just the per-channel switch, okay? Don't @ me. 😭

---

💻 IRC CLIENT CONFIGURATION 💻

On your IRC client, set up as many IRC servers as you have connections defined in your connection section. One for each, matching set. ✨

Host and port must match the values defined in the ip and port global options.

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 the connection sub-section.

---

👀 SEE ALSO 👀

bip(1), bipmkpw(1)

---

🌟 AUTHOR 🌟

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. 🫶

---

and that's the whole page, bestie — no cap, you're now fully certified in BIP.CONF(5). This version is dated 2 January 2022 and belongs to BIP.CONF(5), so if you're reading this in the future and something doesn't match, blame the timeline, not me. 💖 mwah, go configure something iconic. 💅✨