From 9d27f393dc0fb1a85369197a8fe4027cf01433ec Mon Sep 17 00:00:00 2001
From: Nomeji <nomeji@emersion.fr>
Date: Fri, 12 Jun 2020 14:06:15 +0200
Subject: [PATCH] readme: expand usage

---
 README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5660a9c..f4d9ea6 100644
--- a/README.md
+++ b/README.md
@@ -12,12 +12,57 @@ A user-friendly IRC bouncer.
 
 ## Usage
 
-    go run ./cmd/sojuctl create-user <username> -admin
+See the man page at `doc/soju.1.scd` for more information.
+
+### Server side
+
+To create an admin user and start soju, run these commands:
+
+    go run ./cmd/sojuctl create-user <soju username> -admin
     go run ./cmd/soju -listen irc+insecure://127.0.0.1:6667
 
-Then connect with username `<username>/chat.freenode.net` and join `#soju`.
+### Client side
 
-See the man page at `doc/soju.1.scd` for more information.
+soju can operate in two different modes: multi upstream and single upstream.
+
+#### Single upstream mode
+
+In this mode, 1 upstream connection to a irc server = 1 connection to your soju
+bouncer.
+
+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
+Freenode, your username will be: `<soju username>/chat.freenode.net`. Also set
+your soju password in the password field of your client configuration.
+
+This will autoconfigure soju by adding a network with the address
+`chat.freenode.net` and then autoconnect to it. You will now be able to join
+any channel like you would normally do.
+
+#### Multi upstream mode
+
+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 your 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 chat.freenode.net -name freenode
+    /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/freenode
+    /join #somechannel/rizon
+
+#### Notes
+
+soju will automatically save and restore the channels you were connected to.
 
 ## Contributing