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
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 and setup is detailed at Setup

Please note that some directories in outline may differ in your setup, 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 [source] [znc >= 1.6.0] (original, updated version linked below)
This is the buffer playback ZNC offers, but it keeps track of which client has received the buffer and which client hasn't.
The version above has become rather out-of-date. You may find the fork by CyberShadow here to work better. Fixes/improvements include: timestamps fixed, 1.7.x support (which takes advantage of the new APIs, and is still backwards compatible), timelimit option, code cleanup, and additional smaller fixes.
Also, note the patch by BtbN to fix this issue with high CPU and disk usage on connect here. The functionality of this patch is included in CyberShadow's version linked directly above.
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.