From 18bb3e61386b5a1cb388b2a0fe1a7d5d2ed57aa3 Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Thu, 24 Mar 2022 19:16:43 +0100 Subject: [PATCH] doc: split off multi-upstream documentation Multi-upstream mode is confusing for new users. Let's explain how it works in a separate file. --- doc/getting-started.md | 46 +++++++++++++++++------------------------- doc/multi-upstream.md | 29 ++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 27 deletions(-) create mode 100644 doc/multi-upstream.md diff --git a/doc/getting-started.md b/doc/getting-started.md index 2e945b8..aacef75 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -14,39 +14,31 @@ channels from a ZNC config file: ## Client side -soju can operate in two different modes: multi upstream and single upstream. +### Client supporting `soju.im/bouncer-networks` -### Single upstream mode +If your are using a client supporting the `soju.im/bouncer-networks` IRC +extension (see the [client list]), then you can just connect to soju with your +username and password. -In this mode, 1 upstream connection to a irc server = 1 connection to your soju -bouncer. +If your client doesn't provide a UI to manage IRC networks, you can talk to +`BouncerServ`. See the [man page] or use `/msg BouncerServ help`. -The easiest and fastest way to use this is to specify the address of the server -in your username in your client configuration. For example to connect to -Libera Chat, your username will be: `/irc.libera.chat`. Also set -your soju password in the password field of your client configuration. +### Other clients + +You will need to setup one separate server in your client for each server you +want soju to connect to. + +The easiest way to get started is to specify the IRC server address directly in +the username in the client configuration. For example to connect to Libera Chat, +your username will be: `/irc.libera.chat`. Also set your soju +password in the password field of your client configuration. This will autoconfigure soju by adding a network with the address `irc.libera.chat` and then autoconnect to it. You will now be able to join any channel like you would normally do. -### Multi upstream mode +For more advanced configuration options, you can talk to `BouncerServ`. See the +[man page] or use `/msg BouncerServ help`. -In this mode, a single connection to your soju bouncer can handle multiple -upstream connections. You will need to manually configure each upstream -connection using the the special `BouncerServ` user. - -Connect to your soju server by specifying `/*` in the username -field in your client and your password in the password field. - -You should now be able to send private messages to the `BouncerServ`. You can -send it commands to configure soju. Create new networks: - - /msg BouncerServ network create -addr irc.libera.chat -name libera - /msg BouncerServ network create -addr irc.rizon.net -name rizon - -You will now be able to join channels on these networks by specifying their -name: - - /join #soju/libera - /join #somechannel/rizon +[man page]: https://soju.im/doc/soju.1.html#IRC_SERVICE +[client list]: ../contrib/clients.md diff --git a/doc/multi-upstream.md b/doc/multi-upstream.md new file mode 100644 index 0000000..957d57e --- /dev/null +++ b/doc/multi-upstream.md @@ -0,0 +1,29 @@ +# Multi-upstream mode + +When setting up a new IRC client which doesn't support the +`soju.im/bouncer-networks` extension, one needs to configure as many servers as +there are networks configured in soju. Whenever a network is added or removed +from the soju configuration, all client configurations also need to be updated +accordingly. This can be cumbersome especially when dealing with many clients. + +To address this issue, soju supports a _multi-upstream mode_. Instead of +configuring multiple servers in the client, only one connection to the bouncer +is required. soju will expose all channels and users from all configured +networks on this single connection. Channel names and nicknames will be suffixed +with the network name. For instance, the `#soju` channel will appear with the +name `#soju/libera`, and to talk to `emersion` on OFTC one would need to send a +message to `emersion/oftc`. The special `BouncerServ` service won't have a +suffix. + +To enable this mode, connect to the bouncer with the username +`/*`. + +To add a new network, send messages to `BouncerServ`, for instance: + + /msg BouncerServ network create -addr irc.libera.chat -name libera + +To join a channel or message a user, remember to use the correct suffix, for +instance: + + /join #soju/libera + /query emersion/libera