doc: split off multi-upstream documentation
Multi-upstream mode is confusing for new users. Let's explain how it works in a separate file.
This commit is contained in:
parent
0ec3e63ace
commit
18bb3e6138
@ -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: `<soju username>/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: `<soju username>/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 `<soju username>/*` 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
|
||||
|
29
doc/multi-upstream.md
Normal file
29
doc/multi-upstream.md
Normal file
@ -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
|
||||
`<soju 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
|
Loading…
Reference in New Issue
Block a user