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


From ZNC
(Redirected from Faq)
Jump to: navigation, search


Compiling ZNC[edit]


The compiler dies saying it has not enough memory![edit]

Starting from ZNC 0.062, you can use the --disable-optimization to configure. This will disable "-O2" and instead use "-O0". GCC should need less memory now.

If you still can't compile ZNC, try ./configure --disable-optimization CXXFLAGS="--param ggc-min-expand=2 --param ggc-min-heapsize=20000" but be prepared for looong wait.

configure: error: pkg-config could not find znc (znc.pc)[edit]

Use PKG_CONFIG_PATH=~/znc/lib/pkgconfig ./configure and replace ~/znc with the path you installed ZNC to.

Upgrading / updating from a previous release, to a new version[edit]

This is really simple. You can just follow the instructions on the Installation page again. Your configuration won't be deleted. If you'd like to make a backup before, however, you can backup ZNC's config folder. It is usually located at ~/.znc. You can use tar to make a backup, like this: tar cfvj znc-backup.tar.gz ~/.znc.

Your existing configuration will be upgraded to new version. If new ZNC will complain about few missing modules, you may need to remove them from znc.conf. That can happen if some modules which were loaded to your ZNC are removed in new version. See ChangeLog for details.

Do I have to shut down and restart ZNC during an upgrade to a new version?[edit]

Yes. You have to. There's no way to avoid it and also no feasible technical way to do it in a future version, sorry.


I get a "Need an operator" error when running make in bsd[edit]

Try using gmake instead.

ZNC crashes at making a config file or adding a user via webadmin on FreeBSD 7.x 64bit[edit]

Try to compile znc from source with g++42/gcc42 from the ports instead of the default gcc (./configure CXX=g++42) and check your compile output for g++42.


I'm getting the error: configure: error: C++ compiler cannot create executables[edit]

There are missing some compiler packages, you need to install them via:

sudo aptitude update 
sudo aptitude install build-essential make bin86

If you aren't on Debian, Ubuntu, or related distro, you need to install g++, make and possibly other things using your package manager.

I'm compiling under debian and I don't have an openssl/include directory available[edit]

Try using apt-get install libssl-dev to get the development version of OpenSSL. (Something similar may be the case for other distros with package managers.)

I've installed znc, but when i try to compile modules it says that there is no command znc-buildmod[edit]

You need to add the development files to your debian/ubuntu:

sudo aptitude install znc-dev

Starting ZNC[edit]

Why do I get an "Incorrect Password" every time I connect even though my pass is correct?[edit]

There're few ways to supply password:

  1. If you have decent IRC client, you can just use "username" (or "ident") field for username and "server password" field for password.
  2. You can supply both your user and pass as the server password separated by a colon like "user:pass" (without quotes)
  3. Just do "/quote pass PA$$WORD" manually every time you connect to ZNC

Also, make sure you did not accidentally load one of the saslauth or imapauth modules.

How can I restart ZNC automatically (in case of a machine reboot, crash, etc.)?[edit]

Add a cron entry to execute ZNC regularly. If there is already one copy of ZNC running on a particular config file, new copies won't be spawned. Example cron entry:

*/10 * * * *   /home/you/.local/bin/znc >/dev/null 2>&1

This will check if ZNC is running every 10 minutes. If you load a module (like away) that needs user input to run, you can add the input to the LoadModule line in your config file (ie. LoadModule = away yourpassword).

If you're using Vixie's cron, you can start it on start-up like this.

 @reboot /home/you/.local/bin/znc >/dev/null 2>&1

Using ZNC[edit]

How do I tell ZNC which network/server a channel belongs to?[edit]

You don't. That's not how ZNC works (because the IRC protocol isn't capable of handling multiple servers in one connection and therefore no IRC clients can support it). You need to add one ZNC user per network (Note: since 0.207 it has been changed, user can have several networks now, see Networks). Please also read the next question.

How to use multiple networks like with psybnc?[edit]

ZNC works a bit differently since version 1.0. Each user can have multiple networks, but you need to connect ZNC multiple times; once per network. In order to choose which network, you format your server password like this:


For example, when you wish to connect to both freenode and efnet, open two separate connections with your client, one pointing at


and the other pointing at


For more detailed documentation on how to connect with several clients, refer to How do I connect to my networks?

Note: if you don't see options for multiple networks in your webadmin, it is strongly recommended you upgrade to the latest version of ZNC.

I added several different servers, but ZNC connects only to one of them![edit]

You need to have separate user per IRC network (see previous question). (Note: since 0.207 it has been changed, user can have several networks now, see Networks) Additional servers for the same user are for fallback. If one server doesn't work, ZNC tries to connect to another server. So you can add several servers of one network to server list of one user.

I have two ips on my server and i would like to add both to ZNC[edit]

By default user can choose any bindhost:

/znc setbindhost
/znc jump

If you want to limit users to choose only from the list, or simply to show the list at webadmin at all, you can do this:

/znc addbindhost
/znc addbindhost

How do I add a new user?[edit]

There are (at least) three ways to add a new user.

The easiest way is to load and use the webadmin module.

If you want to do it from IRC, load the controlpanel module and check out /msg *controlpanel help.

It's not suggested if you are new to ZNC, but it's also possible to add a new user via the config file. To do that, edit znc.conf and add a new <User> section. After that, rehash ZNC by issuing /msg *status rehash from IRC or kill -SIGHUP `pidof znc` from the shell.

Connecting with mIRC[edit]

See MIRC for a detailed explanation on how to connect with mIRC.

Connecting with Eggdrop[edit]

Add this to your eggdrop configuration:

set servers {

I got banned from #channel and ZNC keeps trying to rejoin[edit]

Just do /part #channel and ZNC will remove the channel.

How to use the loaded modules?[edit]

/msg *modulename command


/znc *modulename command

"*" is the StatusPrefix, which you can change in config file. You could start trying the help command which should work on all modules.

I keep getting kicked for flood when I ...[edit]

.. reattach bnc![edit]

This happens if you use "many" channels, due to IRC clients flooding the server with commands upon reattach. A workaround is decreasing size of buffer for each channel. (You should experiment how many is enough.)

... start bnc![edit]

There is a per-User setting to control this:

  • MaxJoins - How many channels should ZNC join at once. Lower this if you get disconnected for 'Excess flood.

Every time I connect to my BNC, I see the channel buffers from the last time I connected![edit]

If you have a large channel buffer, it may be annoying to see the channel buffer every time you reconnect. To have ZNC erase the channel buffer every time you connect, set:

KeepBuffer = false 

using the webadmin module, or in the configuration file.

This will result in only the missed messages being played back to you upon reconnecting. Be careful if you use more than one client as znc will still see you as connected when one drops off and messages will not be buffered. Also, if your connection to znc dies unnaturally, znc might take a little bit to realize you're gone and thus not buffer a few of the messages that you haven't yet seen.

What are VHOSTS and why can't I make mine work?[edit]

ZNC VHOST option controls the IP address ZNC will attempt to make connections to the IRC servers from. For this to be successful the computer you're running ZNC on must have this IP address configured and usable for your user. For it to show up as a host name on IRC there must be matching forward and reverse DNS in place. You can check this with:

% host has address
% host domain name pointer

As long as the response looks similar then you should be able to

/msg *status SetVHost

connect to IRC and check that it's working.

If you find you are unable to connect to IRC after attempting to set VHOST options then it is likely you have set an IP address or host name that is not available on your computer. The easiest way to resolve this and get connected to IRC is to

/msg *status ClearVHost

and try to connect again.

To get rid of several misunderstandings vhost was renamed to bindhost since version 0.096.

I get 'Could not find znc-config. Please (re)install' when using znc-buildmod[edit]

If you manually provided a --prefix option when building znc then you will need to ensure that this prefix is in PATH. For example, if you did

./configure --prefix="$HOME/.local"

you will need to ensure that

echo $PATH

includes $HOME/.local/bin (expanded to your home dir, not literally $HOME). If it doesn't then a quick, one-time fix is to type

export PATH="$HOME/.local/bin:$PATH"

and retry. You can also put the above line into your ~/.profile or ~/.bashrc so it gets set when you login.

I keep getting a lot of stuff like /who replies when connected with multiple clients to one znc-user[edit]

see user-module Route_replies

How can I access webadmin with my browser?[edit]

By default webadmin runs on the same PORT as your ZNC is accessible.

If your webinterface won't come up, please ensure that you are using the correct protocol for connecting. If ZNC listens using SSL, use the HTTPS protocol (https://) instead of just HTTP (http://).

If you are using Google Chrome and keep getting an Error 312 (net::ERR_UNSAFE_PORT) then try calling Chrome with the parameter "--explicitly-allowed-ports=PORT".

My IRC-Client doesn't allow multiple connections to one server/host[edit]

Try to use different local aliases for the bnc-host.

How to reload ZNC config without restart?[edit]

The best way is NOT to change znc.conf and other files manually while ZNC is running. Use webadmin or controlpanel instead, or use /msg *status help

If you really need to do something in znc.conf, stop ZNC, make your changes and start it again.

If you really need to rehash config from file without restart, there're 2 ways to do that: from IRC (/msg *status rehash) and from shell (pkill -SIGHUP znc). But don't complain if something is broken (because it will be broken for sure)

[10053] Software caused connection abort[edit]

Socket error 10053 can be caused by attempting to connect without SSL to a znc bouncer with SSL enabled (or vice versa). Refer to your IRC-client's documentation on how to establish a SSL-secured connection to a server.

How to store private messages even when user is attached, so other clients can see them?[edit]

Here's simple workaround.

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.


What is this new network support?[edit]

It means you can add multiple IRC networks such as EFnet and freenode onto a single user. Instead of creating multiple users for each network like you did in versions before 1.0.

How do I connect to my networks?[edit]

When you supply your username to ZNC in your client, you can include the network as `username/network`. If you send your username in the server password field you can use `username/network:password`.

There needs to be one connection between the client and the ZNC if you wish to connect to multiple networks at the same time.

As every IRC client is slightly different, please consult the documentation for your IRC client on where to put the server password, or if you wish to configure autoconnect when the IRC client starts.

Examples for mIRC, irssi, and HexChat:

Note: Where is an IP your ZNC instance is listening on, 7777 and 7778 are the port numbers the listeners are using, ZNCUser is the name of the ZNC user account, and PassWord is the password. In these examples, the second line uses SSL whereas the first one does not.

Note: The network name is arbitrarily defined when setting it up in ZNC, though many users will use the name of the actual network for clarity.


/server 7778 ZNCUser/EFnet:PassWord
/server -ssl 7777 ZNCUser/freenode:PassWord


/server 7778 ZNCUser/EFnet:PassWord
/server -SSL 7777 ZNCUser/freenode:PassWord


/server -m 7778 ZNCUser/EFnet:PassWord
/server -m +7777 ZNCUser/freenode:PassWord

Is it the same as in psybnc?[edit]

No, ZNC doesn't use stupid tags for networks, which mix up different channels and nick together to one big network with prefixes. Instead, you should connect to ZNC multiple times, once for each network, see previous question on how to do that. Also you may switch between networks on the fly via /msg *status JumpNetwork command.

If ZNC ever supports connecting to all networks together, it will be done properly, without those prefixes, but via an IRC protocol extension instead. Also that extension should be standardized at IRCv3, to allow client developers to support it easier.

How much memory does ZNC need to run?[edit]

This question is very difficult to answer because it depends highly on how much you use it. However, personal ZNC instances, where you are the only user, are unlikely to require a great deal of memory to run.

In an effort to give a better idea of how much memory ZNC may use in different situations, a page with anecdotal reports from users has been added. It may be found here: ZNC Memory Usage

Please update the page with your reports.


My SSL certificate has expired[edit]

If your ZNC SSL certificate has expired, you can delete the old one (the filename is znc.pem) and generate a new one with the following command:

 znc --makepem

My question isn't answered here[edit]

Hop on freenode and ask! Usually someone's around, but if noone replies, just wait for a while.

Where do I report bugs?[edit]

Create a new issue on GitHub.