| 1 | # [soju]
|
|---|
| 2 |
|
|---|
| 3 | [](https://builds.sr.ht/~emersion/soju/commits?)
|
|---|
| 4 |
|
|---|
| 5 | A user-friendly IRC bouncer.
|
|---|
| 6 |
|
|---|
| 7 | - Multi-user
|
|---|
| 8 | - Support multiple clients for a single user, with proper backlog
|
|---|
| 9 | synchronization
|
|---|
| 10 | - Support connecting to multiple upstream servers via a single IRC connection
|
|---|
| 11 | to the bouncer
|
|---|
| 12 |
|
|---|
| 13 | ## Usage
|
|---|
| 14 |
|
|---|
| 15 | See the man page at `doc/soju.1.scd` for more information.
|
|---|
| 16 |
|
|---|
| 17 | ### Server side
|
|---|
| 18 |
|
|---|
| 19 | To create an admin user and start soju, run these commands:
|
|---|
| 20 |
|
|---|
| 21 | go run ./cmd/sojuctl create-user <soju username> -admin
|
|---|
| 22 | go run ./cmd/soju -listen irc+insecure://127.0.0.1:6667
|
|---|
| 23 |
|
|---|
| 24 | If you're migrating from ZNC, a tool is available to import users, networks and
|
|---|
| 25 | channels from a ZNC config file:
|
|---|
| 26 |
|
|---|
| 27 | go run ./contrib/znc-import.go <znc config file>
|
|---|
| 28 |
|
|---|
| 29 | ### Client side
|
|---|
| 30 |
|
|---|
| 31 | soju can operate in two different modes: multi upstream and single upstream.
|
|---|
| 32 |
|
|---|
| 33 | #### Single upstream mode
|
|---|
| 34 |
|
|---|
| 35 | In this mode, 1 upstream connection to a irc server = 1 connection to your soju
|
|---|
| 36 | bouncer.
|
|---|
| 37 |
|
|---|
| 38 | The easiest and fastest way to use this is to specify the address of the server
|
|---|
| 39 | in your username in your client configuration. For example to connect to
|
|---|
| 40 | Freenode, your username will be: `<soju username>/chat.freenode.net`. Also set
|
|---|
| 41 | your soju password in the password field of your client configuration.
|
|---|
| 42 |
|
|---|
| 43 | This will autoconfigure soju by adding a network with the address
|
|---|
| 44 | `chat.freenode.net` and then autoconnect to it. You will now be able to join
|
|---|
| 45 | any channel like you would normally do.
|
|---|
| 46 |
|
|---|
| 47 | #### Multi upstream mode
|
|---|
| 48 |
|
|---|
| 49 | In this mode, a single connection to your soju bouncer can handle multiple
|
|---|
| 50 | upstream connections. You will need to manually configure each upstream
|
|---|
| 51 | connection using the the special `BouncerServ` user.
|
|---|
| 52 |
|
|---|
| 53 | Connect to your soju server by specifying your soju username in the username
|
|---|
| 54 | field in your client and your password in the password field.
|
|---|
| 55 |
|
|---|
| 56 | You should now be able to send private messages to the `BouncerServ`. You can
|
|---|
| 57 | send it commands to configure soju. Create new networks:
|
|---|
| 58 |
|
|---|
| 59 | /msg BouncerServ network create -addr chat.freenode.net -name freenode
|
|---|
| 60 | /msg BouncerServ network create -addr irc.rizon.net -name rizon
|
|---|
| 61 |
|
|---|
| 62 | You will now be able to join channels on these networks by specifying their
|
|---|
| 63 | name:
|
|---|
| 64 |
|
|---|
| 65 | /join #soju/freenode
|
|---|
| 66 | /join #somechannel/rizon
|
|---|
| 67 |
|
|---|
| 68 | #### Notes
|
|---|
| 69 |
|
|---|
| 70 | soju will automatically save and restore the channels you were connected to.
|
|---|
| 71 |
|
|---|
| 72 | ## Contributing
|
|---|
| 73 |
|
|---|
| 74 | Send patches on the [mailing list] or on [GitHub], report bugs on the
|
|---|
| 75 | [issue tracker]. Discuss in #soju on Freenode.
|
|---|
| 76 |
|
|---|
| 77 | ## License
|
|---|
| 78 |
|
|---|
| 79 | AGPLv3, see LICENSE.
|
|---|
| 80 |
|
|---|
| 81 | Copyright (C) 2020 The soju Contributors
|
|---|
| 82 |
|
|---|
| 83 | [soju]: https://soju.im
|
|---|
| 84 | [mailing list]: https://lists.sr.ht/~emersion/soju-dev
|
|---|
| 85 | [GitHub]: https://github.com/emersion/soju
|
|---|
| 86 | [issue tracker]: https://todo.sr.ht/~emersion/soju
|
|---|
