FreeBSD Manual Pages

home | help

soju(1) General Commands Manual soju(1)

NAME
soju - IRC bouncer

SYNOPSIS
soju [options...]

DESCRIPTION
soju is a user-friendly IRC bouncer. It connects to upstream IRC
servers on behalf of the user to provide extra features.

• Multiple separate users sharing the same bouncer, each with their
own upstream servers
• Sending the backlog (messages received while the user was discon-
nected from the bouncer), with per-client buffers

To connect to the bouncer, use the bouncer username and password. To
use a client which doesn't support the soju.im/bouncer-networks IRC ex-
tension, setup one connection per server configured in soju, and indi-
cate the network name in the username: "<username>/<network>". Then
channels can be joined and parted as if you were directly connected to
the upstream server.

For per-client history to work on clients which don't support the IRCv3
chathistory extension, clients need to indicate their name. This can be
done by adding a "@<client>" suffix to the username.

When joining a channel, the channel will be saved and automatically
joined on the next connection. When registering or authenticating with
NickServ, the credentials will be saved and automatically used on the
next connection if the server supports SASL. When parting a channel
with the reason "detach", the channel will be detached instead of being
left.

If a network specified in the username doesn't exist, and the network
name is a valid hostname, the network will be automatically added.

When all clients are disconnected from the bouncer, the user is auto-
matically marked as away by default.

soju will reload the configuration file, the TLS certificate/key and
the MOTD file when it receives the HUP signal. The configuration op-
tions listen, db and log cannot be reloaded.

Administrators can broadcast a message to all bouncer users via /notice
$<hostname> <text>, or via /notice $* <text> if the connection isn't
bound to a particular network. All currently connected bouncer users
will receive the message from the special BouncerServ service.

OPTIONS
-h, -help
Show help message and quit.

-config <path>
Path to the config file. If unset, a default config file is used.

-debug
Enable debug logging (this will leak sensitive information such as
passwords).

-listen <uri>
Listening URI (default: ":6697"). Can be specified multiple times.

CONFIG FILE
The config file has one directive per line.

Example:

listen ircs://
tls cert.pem key.pem
hostname example.org

The following directives are supported:

listen <uri>
Listening URI (default: ":6697").

The following URIs are supported:

• [ircs://][host][:port] listens with TLS over TCP (default port
if omitted: 6697)
• irc+insecure://[host][:port] listens with plain-text over TCP
(default port if omitted: 6667)
• unix://<path> listens on a Unix domain socket
• https://[host][:port] listens for HTTPS connections (default
port: 443) and handles WebSocket requests at endpoint /socket
• http+insecure://[host][:port] listens for plain-text HTTP con-
nections (default port: 80) and handles WebSocket requests at
endpoint /socket
• http+unix://<path> listens for plain-text HTTP connections on a
Unix domain socket and handles WebSocket requests at endpoint
/socket
• wss://[host][:port] listens for WebSocket connections over TLS
(default port: 443)
• ws+insecure://[host][:port] listens for plain-text WebSocket
connections (default port: 80)
• ws+unix://<path> listens for plain-text WebSocket connections
on a Unix domain socket
• ident://[host][:port] listens for plain-text ident connections
(default port: 113)
• http+prometheus://localhost:<port> listens for plain-text HTTP
connections and serves Prometheus metrics (host must be "local-
host")
• http+pprof://localhost:<port> listens for plain-text HTTP con-
nections and serves pprof runtime profiling data (host must be
"localhost"). For more information, see:
<https://pkg.go.dev/net/http/pprof>.
• unix+admin://[path] listens on a Unix domain socket for admin-
istrative connections, such as sojuctl (default path:
/run/soju/admin)

If the scheme is omitted, "ircs" is assumed. If multiple listen di-
rectives are specified, soju will listen on each of them.

hostname <name>
Server hostname (default: system hostname).

This should be set to a fully qualified domain name.

title <title>
Server title. This will be sent as the ISUPPORT NETWORK value when
clients don't select a specific network.

tls <cert> <key>
Enable TLS support. The certificate and the key files must be PEM-
encoded.

db <driver> <source>
Set the database location for user, network and channel storage. By
default, a sqlite3 database is opened in "./soju.db".

Supported drivers:

• sqlite3 expects source to be a path to the SQLite file
• postgres expects source to be a space-separated list of
key=value parameters, e.g. db postgres "host=/run/postgresql
dbname=soju". Note that sslmode defaults to require. For more
information on connection strings, see:
<https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Pa-
rameters>.

message-store <driver> [source]
Set the database location for IRC messages. By default, an in-mem-
ory message database is used.

Supported drivers:

• memory stores messages in memory. For each channel/user, only
the latest 4K messages are kept in memory, older messages are
discarded. This driver is very basic and doesn't support fea-
tures such as the chathistory extension and search.
• fs stores messages on disk, in the same format as ZNC. source
is required and is the root directory path for the database.
This on-disk format is lossy: some IRCv3 messages (e.g. TAGMSG)
and all message tags are discarded.
• db stores messages in the database. A full-text search index is
used to speed up search queries.

(log is a deprecated alias for this directive.)

file-upload <driver> [source]
Set the database location for uploaded files.

File upload requires setting up an HTTP listener (see https:// and
http+insecure:// URIs in the listen directive).

Supported drivers:

• fs stores uploaded files on disk. source is required.

http-origin <patterns...>
List of allowed HTTP origins for WebSocket listeners. The parame-
ters are interpreted as shell patterns, see glob(7).

By default, only the request host is authorized. Use this directive
to enable cross-origin WebSockets.

http-ingress <url>
External URL on which HTTPS listeners are exposed.

By default, this is https://<hostname>.

accept-proxy-ip <cidr...>
Allow the specified IPs to act as a proxy. Proxys have the ability
to overwrite the remote and local connection addresses (via the
PROXY protocol, the Forwarded HTTP header field defined in RFC 7239
or the X-Forwarded-* HTTP header fields). The special name "local-
host" accepts the loopback addresses 127.0.0.0/8 and ::1/128.

By default, all IPs are rejected.

max-user-networks <limit>
Maximum number of networks per user. By default, there is no limit.

motd <path>
Path to the MOTD file. The bouncer MOTD is sent to clients which
aren't bound to a specific network. By default, no MOTD is sent.

upstream-user-ip <cidr...>
Enable per-user IP addresses. One IPv4 range and/or one IPv6 range
can be specified in CIDR notation. One IP address per range will be
assigned to each user and will be used as the source address when
connecting to an upstream network.

This can be useful to avoid having the whole bouncer banned from an
upstream network because of one malicious user.

disable-inactive-user <duration>
Disable inactive users after the specified duration.

A user is inactive when the last downstream connection is closed.

The duration is a positive decimal number followed by the unit "d"
(days). For instance, "30d" disables users 30 days after they last
disconnect from the bouncer.

enable-user-on-auth true|false
Enable users when they successfully authenticate.

This can be used together with disable-inactive-user to seamlessly
disable and re-enable users during lengthy inactivity.

When external authentication is used (e.g. auth oauth2), bouncer
users are automatically created after successfull authentication.

auth <driver> ...
Set the authentication method. By default, internal authentication
is used.

Supported drivers:

auth internal
Use internal authentication.
auth oauth2 <url>
Use external OAuth 2.0 authentication. The authorization server
URL must be provided. The client ID and client secret can be
provided as username and password in the URL. The authorization
server must support OAuth 2.0 Authorization Server Metadata
(RFC 8414) and OAuth 2.0 Token Introspection (RFC 7662).
auth pam
Use PAM authentication.

IRC SERVICE
soju exposes an IRC service called BouncerServ to manage the bouncer.
Commands can be sent via regular private messages (/msg BouncerServ
<command> [args...]). Commands may be written in full or abbreviated
form, for instance network can be abbreviated as net or just n.

Commands are parsed according the POSIX shell rules. In particular,
words can be quoted (via double or single quotes) and a backslash es-
capes the next character.

help [command]
Show a list of commands. If command is specified, show a help mes-
sage for the command.

network create -addr <addr> [options...]
Connect to a new network at addr. -addr is mandatory.

addr supports several connection types:

• [ircs://]<host>[:port] connects with TLS over TCP
• irc+insecure://<host>[:port] connects with plain-text TCP
• irc+unix:///<path> connects to a Unix socket

For example, to connect to Libera Chat:

net create -addr irc.libera.chat

Other options are:

-name <name>
Short network name. This will be used instead of addr to refer
to the network.

-username <username>
Connect with the specified username. By default, the nickname
is used.

-pass <pass>
Connect with the specified server password.

-realname <realname>
Connect with the specified real name. By default, the account's
realname is used if set, otherwise the network's nickname is
used.

-certfp <fingerprint>
Instead of using certificate authorities to check the server's
TLS certificate, check whether the server certificate matches
the provided fingerprint. This can be used to connect to
servers using self-signed certificates. The fingerprint format
is SHA512. An empty string removes any previous fingerprint.

The following command can be used to fetch the certificate fin-
gerprint of an IRC server:

openssl s_client -connect irc.example.org:6697 -verify_quiet </dev/null | openssl x509 -fingerprint -sha512 -noout -in /dev/stdin

-nick <nickname>
Connect with the specified nickname. By default, the account's
username is used.

-auto-away true|false
Enable or disable the auto-away feature. If the feature is en-
abled, the user will be marked as away when all clients are
disconnected from the bouncer. By default, auto-away is en-
abled.

-enabled true|false
Enable or disable the network. If the network is disabled, the
bouncer won't connect to it. By default, the network is en-
abled.

-connect-command <command>
Send the specified quoted string as a raw IRC command right af-
ter connecting to the server. This can be used to identify to
an account when the server doesn't support SASL.

For instance, to identify with NickServ, the following command
can be used:

"PRIVMSG NickServ :IDENTIFY <password>"

The flag can be specified multiple times to send multiple IRC
messages. To clear all commands, set it to the empty string.

network update [name] [options...]
Update an existing network. The options are the same as the network
create command.

When this command is executed, soju will disconnect and re-connect
to the network.

If name is not specified, the current network is updated.

network delete [name]
Disconnect and delete a network.

If name is not specified, the current network is deleted.

network quote [name] <command>
Send a raw IRC line as-is to a network.

If name is not specified, the command is sent to the current net-
work.

network status
Show a list of saved networks and their current status.

channel status [options...]
Show a list of saved channels and their current status.

Options:

-network <name>
Only show channels for the specified network. By default, only
the channels in the current network are displayed.

channel update <name> [options...]
Update the options of an existing channel.

Options are:

-detached true|false
Attach or detach this channel.

A detached channel is joined but is hidden by the bouncer. This
is useful to e.g. collect logs and highlights in low-interest
or high-traffic channels.

-relay-detached <mode>
Set when to relay messages from detached channels to the user
with a BouncerServ NOTICE.

Modes are:

message
Relay any message from this channel when detached.

highlight
Relay only messages mentioning you when detached.

none
Don't relay any messages from this channel when detached.

default
Currently same as highlight. This is the default behaviour.

-reattach-on <mode>
Set when to automatically reattach to detached channels.

Modes are:

message
Reattach to this channel when any message is received.

highlight
Reattach to this channel when any message mentioning you is
received.

none
Never automatically reattach to this channel.

default
Currently same as none. This is the default behaviour.

-detach-after <duration>
Automatically detach this channel after the specified duration
has elapsed without receving any message corresponding to -de-
tach-on.

Example duration values: 1h30m, 30s, 2.5h.

Setting this value to 0 will disable this behaviour, i.e. this
channel will never be automatically detached. This is the de-
fault behaviour.

-detach-on <mode>
Set when to reset the auto-detach timer used by -detach-after,
causing it to wait again for the auto-detach duration timer be-
fore detaching. Joining, reattaching, sending a message, or
changing any channel option will reset the timer, in addition
to the messages specified by the mode.

Modes are:

message
Receiving any message from this channel will reset the
auto-detach timer.

highlight
Receiving any message mentioning you from this channel will
reset the auto-detach timer.

none
Receiving messages from this channel will not reset the
auto-detach timer. Sending messages or joining the channel
will still reset the timer.

default
Currently same as message. This is the default behaviour.

channel delete <name>
Leave and forget a channel.

certfp generate [options...]
Generate self-signed certificate and use it for authentication (via
SASL EXTERNAL).

Generates a 3072-bit RSA private key by default.

Options are: