Documentation Improvement Suggestions (IRC: Bouncers/ZNC)

[eski-dev]

Version
autobrr: v1.30.0 (docker)
znc: 1.7.2+deb3 (pkg)
Note: autobrr and znc are on entirely separate hosts

Description
See: feature/irc-add-bouncer-support
After going through the motions of setting up Autobrr with my ZNC bouncer, I have some suggestions on how to clarify and improve the setup process documentation.

ZNC + Autobrr setup

While bouncing around is good for the initial setup of ZNC, the remaining documentation on how to integrate ZNC with Autobrr (using the bouncer in autobrr) was not very clear. In many cases, "server", "network", "username", "nick", "nickname", etc. can get confusing for users. Beyond that, screenshots can sometimes be much easier for some people to grok quickly, instead of parsing technical jargon that is mostly out of scope for their use-case. The feature/irc-add-bouncer-support entry contained most of the information needed, albeit with a little more trial and error involved.
My recommendation would be to provide a screenshot of the IRC > Update Network screen with explicit instructions for each field, such as this:

Or, simply providing a screenshot without annotations, but adding descriptions for each field such that the user will understand what is needed and not confuse fields with one another.

In addition to the above, I was able to confirm that when using ZNC (or, I would assume, any bouncer), it is unnecessary to include the automatically configured invite command and sasl/nickserv login credentials when utilizing a pre-defined indexer in Autobrr. For clarity, I use the perform module to accomplish this.

Autobrr automatic channel /part and leveraging ZNC modules to reduce channel noise/clutter

If someone intends to use their ZNC bouncer for both Autobrr and personal client use, ensuring they work alongside happily without interfering with one another is important. One thing I quickly discovered was that while testing, Autobrr will part from any channels that are not defined in the network definition (see: the very bottom of the previous screenshot). For example, if I have "#general" and "#announce" defined in ZNC, but only "#announce" is listed under the network on Autobrr, Autobrr will /part from "#general".
@zze0s has added a PR for removing this automatic feature here: feat(irc): disable auto chan part when using bouncer. After some discussion, I encouraged that a toggle be added that allows users to choose if they want this feature or not. Obviously if a toggle were to be added, a description explaining its use would need to be added to the wiki.

However, regardless of how that plays out, there are ways to mitigate this behavior in ZNC itself:

ZNC > User Modules - webadmin: Your Settings > Networks: Edit (for each network being setup in autobrr) > Channels: Edit (for the announce channels) > Flags: Detached OR Module stickychan: Channel is sticky

The stickychan module in ZNC allows a user to prevent any and all clients from leaving a channel.

As an aside, a user can leverage detaching to specify that the "#announce" channel in ZNC, when only intended for use with Autobrr, is not automatically joined when using an interactive IRC client. It needs to be explicitly specified, as per the IRC network configuration in Autobrr. This reduces channel clutter and noise in the user's client.

Final Result

In my current config, I have announce channels set to detached, but all channels for a particular network are set to sticky. This allows Autobrr to join the announce channel, but my client does not. Stickychan also prevents Autobrr from /part'ing from channels it doesn't know about. So announce/Autobrr will work silently in the background, and will not interfere with my interactive IRC client.

[zze0s]

This is great feedback! Thanks a lot for taking the time eski!

[eski-dev]

Small update for a minor issue I encountered relating to my above post.
If wanting to hide announce channels using the detach flag in ZNC, it's important to disable the Autoattach module for that particular server. Otherwise, even if you manually close/leave/part that channel in your interactive client, it will automatically rejoin at some point in the near future when there is activity.

[Lebowski89]

If I can add to this discussion as someone who has only ever set up ZNC for the first time yesterday - the Autobrr documentation for ZNC was confusing. This documentation helped, but one point important point was easy to skip over, ' Note: autobrr and ZNC are on entirely separate hosts'. I had set up ZNC for my non-bot accounts in thelounge but was still having issues with Autobrr. Turned out that even though you keep the SSL address for the tracker network (i.e, 'irc.p2p-network.net:6697'), the SSL toggle in autobrr is for your ZNC network. It sounds obvious, but having the tracker address still there, and having the SSL toggle right below that address, it actually wasn't obvious at all this beginner. thelounge was more beginner-friendly as you input the ZNC address and port in the actual address fields. Another oddity for me - I only needed my ZNC user password for the password field, I didn't need 'znctracker/privatetracker:' before it. But maybe that's because I'm doing a single network per server?

(My Autobrr and ZNC are on the same server on the same docker network)