README

blabouncer - An IRC bouncer written in C

== Running ==

To run from the current directory once compiled run "./blabouncer".

Run with command line arguments like so:
./blabouncer [-f] [-c /path/to/blabouncer.conf]

-f sets foreground mode (without this, blabouncer will detach and run in the background as a daemon)
-c sets a path to a configuration file

All arguments are optional, but they must be specified in the order shown above if given.

== Configuration ==

An example configuration file is provided named "blabouncer.conf.example".

Configuration options are either simple single string options, or multiple line arrays.  The usage is
explained in the example configuration file.

If you don't specify one using "-c /path/to/configuration/file" then the example one will be created
for you at $HOME/.blabouncer/blabouncer.conf when starting for the first time.

Certain configuration options can be changed at runtime by changing them in the configuration file, then
issuing a BLABOUNCER REHASH command, or by sending SIGHUP to the blabouncer process.  This will also
reload the client-side TLS certificate and key if clienttls = "1".

These options can be changed by issuing a BLABOUNCER REHASH command or by sending SIGHUP to blabouncer:
 - nicks
 - replaymode
 - replayseconds
 - replaydates
 - password
 - logging
 - replaylogging
 - debug
 - certfile
 - keyfile
 - alertconnect
 - alertauthfail
 - alertauthsuccess
 - alertunautheddisconnect
 - alertautheddisconnect

== Commands ==

Once connected to blabouncer with an IRC client, you can use the following special blabouncer commands:

"BLABOUNCER REPLAY [[[days:]hours:]minutes]" (To replay a given length of time of replay log.)
"BLABOUNCER QUIT [quit message]" (To quit blabouncer, optionally sending [quit message] to the server.)
"BLABOUNCER REHASH" (To reload configuration file settings and the client-side TLS certificate/key - see above for details.)
"BLABOUNCER CLIENTCODE [clientcode]" (To set an identifier for the current client for auto replaying just
what this client has missed.)
"BLABOUNCER LISTCLIENTS" (To list all connected clients and their authentication status.)
"BLABOUNCER DISCONNECT [FD]" (To disconnect a client with file descriptor number [FD] (see LISTCLIENTS
output).)
"BLABOUNCER VERSION" (To show the current blabouncer version.)

Blabouncer commands are all prefixed with BLABOUNCER which you can usually send using "/QUOTE BLABOUNCER".

== Replaying history ==

You can request that history is replayed at any time by using the command BLABOUNCER REPLAY
[[[days:]hours:]minutes], assuming replaylogging is enabled in blabouncer.conf.

In addition, you can have history automatically replayed upon a client connecting.  There are multiple
automatic replay methods available by setting "replaymode" in blabouncer.conf:

- "none"
  Don't auto replay logs at all.

- "time"
  Always send the last "replayseconds" worth of logs.

- "lastspoke"
  All messages since your current nick last spoke.

- "noclients"
  All messages since you last had no clients connected.

- "lastchange"
  All messages since your last client connection/disconnection.

- "perclient".
  All messages since the current client last disconnected.  Clients are uniquely identified using the
  BLABOUNCER CLIENTCODE command.
  The intention is that a given client (for instance that on a given device) will be configured to send
  BLABOUNCER CLIENTCODE as a connect command automatically, thus getting all replay history since it was
  last connected.

== Client SSL/TLS ==

To use TLS for client connections, which is enabled by default in the example configuration file, you will
need to provide both a certificate and a key file.

One way of creating these is to use OpenSSL:

$ openssl genrsa 2048 > ~/.blabouncer/key.pem
$ openssl req -x509 -days 30 -new -key ~/.blabouncer/key.pem -out ~/.blabouncer/cert.pem

But you can create them however you like, or disable client TLS (not recommended) using the "clienttls"
configuration file option.

By default blabouncer looks for the certificate and key files in $HOME/.blabouncer/cert.pem and
$HOME/.blabouncer/key.pem, respectively.

== Server SSL/TLS ==

Server TLS is also enabled by default in the example configuration file, and can be disabled (not
recommended) using the "servertls" configuration file option.