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
|
## 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
|
If your client doesn't provide a UI to manage IRC networks, you can talk to
|
||||||
bouncer.
|
`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
|
### Other clients
|
||||||
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
|
You will need to setup one separate server in your client for each server you
|
||||||
your soju password in the password field of your client configuration.
|
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
|
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
|
`irc.libera.chat` and then autoconnect to it. You will now be able to join
|
||||||
any channel like you would normally do.
|
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
|
[man page]: https://soju.im/doc/soju.1.html#IRC_SERVICE
|
||||||
upstream connections. You will need to manually configure each upstream
|
[client list]: ../contrib/clients.md
|
||||||
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
|
|
||||||
|
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