To create new wiki account, please join us on #znc at Libera.Chat and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.

Multiple clients

From ZNC
Revision as of 00:47, 11 June 2024 by MetaNova (talk | contribs) (slight rewording for consistency)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


It's rather commonly asked how to solve <x> problem when you are running ZNC with two or more clients connected to one user.

This page aims to describe some helpful modules you might wish to load to see if they fit your needs, and can be used as reference to see what is available.

The step-by-step installation is detailed at Setup.

Please note that some directories in Setup may differ in your environment, such as ~/.znc/modules/ actually being /var/lib/znc/modules/ if you installed from a package, for example. You will need to be aware of your environment.

Core Modules

Core Modules are included by default with ZNC and can be enabled at any time with /znc LoadMod <module_name>

Route Replies by multiple authors [source] [znc >= 0.094]
Essential if you have multiple clients. This ensures responses to what the client requests (mostly within the background) from the server (e.g. /WHO, /WHOIS, and so on) are routed to the correct client. If you are seeing a bunch of WHO responses in your status window of your client, it probably means you need to load this module.

External Modules

External Modules are not officially supported by ZNC, and can be enabled by Compiling the Modules yourself.

Client Buffer by jpnurmi and CyberShadow [source] [znc >= 1.6.0] (updated fork, more details below)
This module allows for things such as clearing a buffer for a channel or query for one client but retaining a different client's copy. It is not strictly required for a multiple-client setup to work, but most people find it preferable.
CyberShadow's version includes: timestamps fixed, 1.7.x support (which takes advantage of the new APIs, and is still backwards compatible), timelimit option, code cleanup, additional smaller fixes, and incorporates the patch by BtbN which fixes this issue with high CPU and disk usage on connect.
Chanfilter by jpnurmi [source] [znc >= 1.6.0]
The channel filter module maintains client specific channel lists for identified clients. A typical use case is to have a subset of channels visible for a mobile client.
Playback by jpnurmi [source] [znc >= 1.6.0]
The advanced playback module for ZNC makes it possible for IRC clients to avoid undesired repetitive buffer playback.


ZNC version needs to be >=1.6.0. In the below examples "$me" is a literal, because for *controlpanel it stands for "current user."

  1. Load *route_replies for every network for every user (and consequently load it for any networks created after this point):
    • /msg *status loadmod route_replies
    Note - needs to be done for each network
  2. Per Clientbuffer#Configuration you want to disable AutoClearChanBuffer and AutoClearQueryBuffer. For each user:
    • /msg *status loadmod controlpanel
    • /msg *controlpanel set AutoClearChanBuffer $me false
    • /msg *controlpanel set AutoClearQueryBuffer $me false
    Note - needs to be done for each user
  3. Build the latest/patched clientbuffer module, assuming your ZNC path is ~/.znc, update as necessary. You also need znc-buildmod, what package that is in depends on your distro (commonly znc-dev or znc-devel). If you compiled ZNC from source, you already have znc-buildmod. This step (and the below example commands) should result in ~/.znc/modules/ existing. Example commands (shell session):
    Note - needs to be done once
  4. Load the clientbuffer module on each network (be sure to include the 'autoadd' load argument to prevent the need to do /msg *clientbuffer addclient <clientid>):
    • /msg *status loadmod clientbuffer autoadd
    Note - needs to be done for each network
  5. Make sure your IRC clients all login with a client identifier. See Clientbuffer#Identifiers and ZNC and look for "clientid", ie: username@CLIENTID/network
    • Each clientid you want to have an independent history for must be a unique name (eg, zncuser@hexchat, zncuser@irssi, zncuser@desktop, zncuser@laptop, zncuser@phone, etcetera. you can name them as you please)
    • You will need to put a clientid on every client, if you do not on a client the behavior is (TBD)
    • Verify that each clientid is received/identified in *clientbuffer with /msg *clientbuffer listclients
    Note - reconnect each client after specifying the desired clientid for them to be used
  6. Make sure your config is saved
    • /msg *status saveconfig
  7. Optional things to consider
    • Set up the Playback module to make clients pick up where they last left off on a per-clientid basis. Useful for mobile clients to prevent the entire buffer from being displayed.
    • Chanfilter might also be of interest for mobile users. Enables selective display of channels on a per-clientid basis (zncuser@desktop can see all channels while zncuser@phone can only see #lobby and #social, for example)
    • Backlog is also useful to request additional logs, requires the Log module having logged the data first.

Older way

This is how you could achieve similar results (and more!) before 1.6.0, and it still works today. This is posted here for posterity reasons, and for advanced users who want better per-client control than what's available above via modules above.

First, you should know number of wanted clients. Let's say that you want 3 clients: 1 hexchat and 2 irssi-s. Let's say that your username is johndoe.

Make following users: johndoe_ircd, johndoe_hexchat, johndoe_irssi1, johndoe_irssi2. This naming scheme isn't strict - everything is up to you. Set StatusPrefix for "client users" to something else, for example ^, because otherwise you won't be able to speak to both *status-es.

Connect user johndoe_ircd to IRC server. Connect users johndoe_hexchat, johndoe_irssi1 and johndoe_irssi2 to to the same ZNC, to user johndoe_ircd.

Connect hexchat to johndoe_hexchat, and irssis to johndoe_irssiN.

          /                                                   \
         |                         ZNC                         |
         |                                 via       |
hexchat ----> user "johndoe_hexchat"----------\                |
         |                                     v               |
irssi1 -----> user "johndoe_irssi1" ---> user "johndoe_ircd" -----> IRC server
         |                                     ^               |
irssi2 -----> user "johndoe_irssi2" ----------/                |
         |                                                     |

This way, every private message that johndoe_ircd gets, is sent to all "client users", and they remain in those buffers until that client reads them. Also you can have completely different modules, settings, etc for different clients.