~sircmpwn/sr.ht-docs

sr.ht-docs/chat.sr.ht/quickstart.md -rw-r--r-- 3.4 KiB
b345d3deConrad Hoffmann Add link to package installation instructions 14 days ago

#chat.sr.ht quick-start for experienced IRC users

chat.sr.ht provides an IRC bouncer, which maintains a persistent IRC session for you with one or more "upstream" IRC networks. For example, you may connect to chat.sr.ht, then chat.sr.ht will connect to Libera Chat for you, and it will maintain a persistent connection while you're away. Setting up chat.sr.ht is thus two steps: connecting to chat.sr.ht, and configuring which upstream networks you want chat.sr.ht to connect to.

The webchat is available at https://chat.sr.ht and requires no configuration to use. It will automatically connect you to your bouncer account. Instructions for configuring your upstream networks are then shown on-screen.

#Connecting with your own IRC client

You can also connect directly to the bouncer using your own IRC client. The easiest way to use the bouncer is to use a plugin for your client which implements the "soju.im/bouncer-networks" extension. This allows you to set up your bouncer connection details just once, then automatically configure all of your upstream IRC networks. If your client does not have a supported plugin, or you would prefer to configure networks manually, see the next section.

To set up your bouncer connection, you will need to generate an OAuth 2.0 personal access token to use as the server password. Visit the personal access token issuance page to generate a token. Then add a network to your IRC client using the following credentials:

Hostname
chat.sr.ht
Port
6697
SSL/TLS
Yes
SASL
Yes
Username
your sourcehut username
Password
your personal access token

This will connect you to the bouncer, but you will still have to configure any upstream networks you wish to use by chatting with the special "BouncerServ" user. Use /msg BouncerServ help for a full list of supported commands.

To add a new IRC network via BouncerServ:

/msg BouncerServ network create -addr <hostname> [options...]

See soju(1) for details on the supported options.

You may have to restart your client to auto-connect to any new networks.

#Connecting without a client plugin

Connecting without a plugin is also possible. Using the same configuration settings recommended above, connect at least once and configure your upstream networks with BouncerServ (or set them up with the webchat). Then, configure a new IRC network in your IRC client for each upstream network you want to connect to using the same settings, but update your username to the format "username/network-name". For instance, I use "sircmpwn/liberachat" to connect to my Libera upstream.

#Multi-client identification

If you intend to use multiple clients, it is recommended that you append "@clientname" to your username. For example, I might use "sircmpwn@workstation" as my username for my desktop PC, and "sircmpwn@phone" for my smartphone. If you are configuring networks manually instead of using a plugin, the client ID is placed after the network name: "sircmpwn/liberachat@workstation".