bouncer/docs/USAGE.md

Usage

Starting the Bouncer

bouncer -c config/bouncer.toml -v

Flag	Description
-c, --config PATH	Config file (default: config/bouncer.toml)
-v, --verbose	Debug logging
--version	Show version

Connection Lifecycle

The bouncer goes through several states when connecting to an IRC server:

DISCONNECTED -> CONNECTING -> REGISTERING -> PROBATION -> READY
                    |              |              |
                    `--------------+--------------'
                         (failure = reconnect)

1. Stealth Registration

On connect, the bouncer registers with a random identity:

• Nick: pronounceable markov-generated word (e.g., heliagu, crewo, midon)
• User/Ident: random pronounceable word
• Realname: random capitalized word

No fixed prefix or pattern -- each attempt looks like a different person.

2. Probation (15 seconds)

After registration succeeds (001 RPL_WELCOME), the bouncer enters a 15-second probation window. During this time it watches for:

• ERROR messages (K-line, ban)
• Server closing the connection

If the connection drops during probation, the bouncer reconnects with a fresh random identity and tries again.

3. Ready

Once probation passes without incident:

1. Bouncer switches to your configured nick (NICK mynick)
2. Joins configured channels (if autojoin = true)
3. Begins relaying messages to/from connected clients

4. Reconnection

On any disconnection, the bouncer reconnects with exponential backoff:

Attempt	Delay
1	5s
2	10s
3	30s
4	60s
5	120s
6+	300s

Each reconnection uses a fresh random identity.

DNS Resolution

Hostnames are resolved locally before being passed to the SOCKS5 proxy. If a hostname resolves to multiple IPs, the bouncer tries each one until a connection succeeds. This handles proxies that don't support remote DNS and avoids IPs that are unreachable through the proxy.

Connecting with an IRC Client

Configure your IRC client to connect to the bouncer:

Setting	Value
Server	127.0.0.1
Port	6667 (or as configured)
Password	yourpassword

Password Format

PASS <password>

The password is the bouncer.password value from config. A single connection automatically attaches to all configured networks.

Client Examples

irssi:

/connect -password mypassword 127.0.0.1 6667

weechat:

/server add bouncer 127.0.0.1/6667 -password=mypassword
/connect bouncer

hexchat:

Set server password to mypassword in the network settings.

Multi-Network Namespacing

All configured networks are multiplexed onto a single client connection. Channels and nicks carry a /network suffix so you can tell which network they belong to:

Client sees:         Server wire:
#libera/libera  <->  #libera       (on libera network)
#debian/oftc    <->  #debian       (on oftc network)
user123/libera  <->  user123       (on libera network)

Rules

• Channels: #channel/network in client, #channel on wire
• Foreign nicks: nick/network in client, nick on wire
• Own nicks: shown without suffix (prevents client confusion)
• Sending messages: include the /network suffix in the target

/msg #libera/libera hello     -> sends "hello" to #libera on libera network
/join #test/oftc              -> joins #test on oftc network
/msg user123/libera hi        -> private message to user123 on libera

Comma-Separated JOIN/PART

Targets can span networks:

/join #a/libera,#b/oftc       -> joins #a on libera AND #b on oftc

Multiple clients can attach simultaneously. All receive the same namespaced messages in real time.

What Clients Receive on Connect

When a client authenticates:

1. Backlog replay -- missed messages (namespaced) from all networks
2. Synthetic welcome -- 001-004 numeric replies listing all networks
3. Channel state -- synthetic JOIN, TOPIC, and NAMES for every joined channel across all networks (all namespaced with /network suffix)

Backlog

Messages are stored in bouncer.db (SQLite) next to the config file. When you reconnect, missed messages are automatically replayed.

Configure in bouncer.toml:

[bouncer.backlog]
max_messages = 10000       # per network, 0 = unlimited
replay_on_connect = true   # set false to disable replay

Stored commands: PRIVMSG, NOTICE, TOPIC, KICK, MODE.

Configuration Reference

[bouncer]
bind = "127.0.0.1"        # listen address
port = 6667                # listen port
password = "changeme"      # client authentication password

[bouncer.backlog]
max_messages = 10000       # per network, 0 = unlimited
replay_on_connect = true   # replay missed messages on client connect

[proxy]
host = "127.0.0.1"        # SOCKS5 proxy address
port = 1080                # SOCKS5 proxy port

[networks.libera]
host = "irc.libera.chat"  # IRC server hostname
port = 6697                # server port (default: 6697 if tls, 6667 otherwise)
tls = true                 # use TLS for server connection
nick = "mynick"            # desired IRC nick (set after probation)
channels = ["#test"]       # channels to join (after probation)
autojoin = true            # auto-join channels on ready (default: true)
password = ""              # IRC server password (optional, for PASS command)

Stopping

Press Ctrl+C or send SIGTERM. The bouncer shuts down gracefully, closing all network connections and the backlog database.