wiki/IRC_Bouncer.html

<!--
title: IRC Bouncer
description: 
published: true
date: 2024-06-23T17:36:45.269Z
tags: pubnix
editor: ckeditor
dateCreated: 2024-06-23T17:07:19.409Z
-->

<p>Along with your pubnix account, you get access to our IRC bouncer, <a href="https://sr.ht/~emersion/soju/">soju</a>. Soju is a modern IRC bouncer, which supports the new <a href="https://ircv3.net/">IRCv3</a> extensions.</p>
<p>Our soju instance uses the pubnix's PAM for authentication, meaning it uses the same password as your pubnix user.</p>
<h2>Getting Started</h2>
<p>Your current password can be found at <code>~/pass</code>. Just like any other services, you can get it with <code>cat ~/pass</code> command. You can change it by running <code>passwd</code>.</p>
<p>The IRC client we recommend is weechat. However, there are many <a href="https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md">other clients</a> out there as well which you can try out.</p>
<p><a href="https://weechat.org/">Weechat</a> is pre-installed on the pubnix. After running it, you will be presented with a TUI (text user interface).</p>
<p>Now, you can add the server with the following command:</p>
<p><code>/server add soju p.projectsegfau.lt/6697 -ssl -username=YOUR_USERNAME -password=YOUR_PASSWORD -autoconnect</code></p>
<p>Now, install soju.py plugin, which will pre-configure a lot of stuff for you</p>
<p><code>/set script.scripts.download_enabled on
    /script install soju.py</code></p>
<p>
</p>
<p>You can also install the following plugins that help a lot with daily usage of <code>weechat</code>:</p>
<pre><code class="language-plaintext">/script install go.py
/script install autosort.py</code></pre>
<p>Past this, you need to enable the IRCv3 features:</p>
<pre><code class="language-plaintext">/set irc.server_default.capabilities account-notify,away-notify,cap-notify,chghost,extended-join,invite-notify,multi-prefix,server-time,userhost-in-names
/save</code></pre>
<p>Now, close <code>weechat</code> with /quit, and re-open it. At this point, you will be connected to our soju instance and see the MOTD.</p>
<h2>Adding IRC Servers</h2>
<p>To do so, you have to message the BouncerServ. The example below is for <a href="https://libera.chat"><code>libera.chat</code></a>, one of the most popular IRC networks. It shouldn't be very different for other networks</p>
<p><code>/msg BouncerServ network create -addr irc.libera.chat -name LiberaChat -username YOUR_USERNAME_ON_IRC_NETWORK -pass YOUR_IRC_NETWORK_PASS -realname "Self Explanatory" -enabled true</code></p>
<p>After creating all your networks, re-open weechat again, and it should be loaded. Switch to the pane of the specific network or a channel in that network to join other rooms in that network. You can easily do this with go.py:</p>
<p><code>/go &lt;autocomplete&gt;</code></p>
<p>After adding all your channels, you can sort them using autosort.py:</p>
<p><code>/autosort</code></p>
<p>
</p>
<p>By default, it sorts network-wise + alphabetically.</p>
<h2>Using IRC clients without bouncer support</h2>
<p>If you want to use an IRC client that does not directly support bouncer connections, you can use it as a regular IRC server to connect to and add a connection for each network you connect to and use chat messages to configure everything.</p>
<p>The table below contains the necessary details on connecting via your client of choice without the required IRCv3 extensions for bouncer support. See also the upstream project's documentation about <a href="https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md">client-specific configurations and workarounds</a>.</p>
<figure class="table">
  <table>
    <tbody>
      <tr>
        <td>Host&nbsp;</td>
        <td><code>p.projectsegfau.lt</code>&nbsp;</td>
      </tr>
      <tr>
        <td>Port&nbsp;</td>
        <td><code>6697</code> (with TLS enabled)&nbsp;</td>
      </tr>
      <tr>
        <td>Username&nbsp;</td>
        <td><code>username/networkname@preferred-client-name</code> (for example <code>user/irc.libera.chat@observatory</code>)&nbsp;</td>
      </tr>
      <tr>
        <td>Password&nbsp;</td>
        <td>Your pubnix user password (differs from your SSO account)&nbsp;</td>
      </tr>
    </tbody>
  </table>
</figure>
<p>This will autoconfigure an IRC connection to the network and set up the username mapping to automatically remove the <code>networkname</code> prefix from the messages. If you are using multiple connections at the same time, use a different client name for each connection so that the history playback works for each, and you do not get the messages mixed up.</p>
<p>When connecting to the network via the bouncer, you will get a "local" connection to the bouncer and the bouncer will connect to the actual network (e.g. irc.libera.chat) and not log you in yet since it has no information about your user. Also, the connection is plain by default, but you can change all that later, and it will remember the settings.</p>
<h2>Configuring the bouncer</h2>
<p>You can manage the bouncer with BouncerServ</p>
<p>You can configure NickServ login, use SASL or configure a certfp login (in this case the bouncer will simply create a new cert for each connection you use), also you can query the user (<code>sasl status</code>) and network status (<code>network status</code>) and make the bouncer connect to the network again (<code>network update</code>).</p>
<p>Anything that the bouncer does not connect will reflect in the network status of the actual connection so when you type <code>/whois username</code> to the IRC client console, you will what connection you have to the actual network like TLS status, registered user, hostname cloak and so on.</p>
<h2>Known Issues</h2>
<p>In the rare case when the IRC client does not support setting an ident string, you cannot set the target <code>networkname</code> at all, then you still can connect to multiple networks and use the different messages and channels, however the channels and users will be prefixed by the <code>networkname</code> so that you get everything in a single client connection. The only IRC client I have observed this behaviour is Revolution IRC on Android, there is no known way to configure the bouncer connection correctly (if anybody knows one, please let me know)</p>
<h2>See also</h2>
<ul>
  <li><a href="https://soju.im/doc/soju.1.html"><code>soju(1)</code> manpage</a></li>
  <li><a href="https://man.sr.ht/chat.sr.ht/">chat.sr.ht documentation</a></li>
</ul>