FAQ

Languages:

Compiling ZNC

General

The compiler dies saying it has not enough memory! / g++: internal compiler error: Killed (program cc1plus)

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.

You could also try compiling ZNC without modpython / modperl or if you need the modules, you could try adding swap.

2GB swap has usually been enough with 512MB RAM, to create a swap file of 2 GB, e.g.

sudo fallocate -l 2G /swap
sudo chmod 600 /swap
mkswap -f /swap

Now you can either swapon /swap or edit /etc/fstab and add:

/swap   none    swap    sw  0   0

and run swapon -a. This enables the swap now and on boot.

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

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

Upgrade your compiler. GCC 4.8+ and Clang 3.2+ are known to work.

As the error says, your compiler is too old. We cannot help you with it, because it's issue with your operating system and not ZNC.

You have two options for getting help:

| Using your favourite search engine.
Asking on IRC support channel of your distribution, NOT #znc.

Upgrading / updating from a previous release, to a new version

This is really simple. You can just follow the instructions on the Installation page again, but DON'T RUN --makeconf. 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 when you start it. 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.

Why should I keep my ZNC up-to-date?

ZNC is like any other software, it has bugs and security issues that are fixed in new versions and also gets improvements. By not upgrading you risk all kinds of security issues, don't trust your distribution to patch old releases as ZNC's code has changed so much that it's often impossible to apply patch from newer version to older version.

For reasons to upgrade, take a look at ChangeLogs starting from the next version to what you are currently running to the newest version.

Starting from ZNC 1.6.0 there have been two branches, e.g. 1.6.x gets only bug/security fixes and later becomes 1.6.1 which distributions can package as bugfix release.

Why should I upgrade from ZNC 0.206?

ZNC 0.206 was released on 2012-04-05 and while being ancient, it's sadly still widely used (mainly, because of distributions shipping it).

1.0
- IPv6 isn't attempted when it's not available.
- Doesn't crash when admin unloads *admin (now controlpanel) module.
1.2
- Doesn't crash when user with attached client is removed.
1.4
- CVE-2014-9403 - Denial of Service attack by adding channel that already exists without the "#", the reason why 1.4 was released.
1.6.0
- Disable SSLv3, because of POODLE and follow Mozilla's server-side TLS recommendations.
- Validate SSL certificates.
  - See also mikaela.info: ZNC 1.6.0 & SSL certificate verification
- Fix memory leak in webadmin if gzip compression is enabled (accessing webadmin is enough, no login required).
- Fix round-robins.
  - e.g. don't only resolve chat.freenode.net as rajaniemi.freenode.net even if rajaniemi.freenode.net is down.
1.6.2
- Fix use-after-delete (similar to why 1.4 was released, but more difficult to trigger)
- Build with ancient OpenSSL & OpenSSL with SSLv3 disabled
- Fix CAP :END parsing which caused some clients to timeout.
- Fix memory leak with invalid config
- Fix modpython memory leak
- Avoid infinite loops with stickychan

These are only the main points and might not be up-to-date when new versions are released. It's also entirely possible that there are security issues that haven't been found yet, but are fixed in newer versions.

Look at ChangeLog for more details and more bug-fixes.

Someone more technical should check this list and remove this comment, I don't understand e.g. the CSocket changes and do they fix issues. Mikaela Suomalainen (talk) 13:34, 16 September 2015 (CEST)

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

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.

BSD

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

Try using gmake instead.

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

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.

Debian

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

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

sudo apt-get update 
sudo apt-get 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

Try using sudo 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

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

sudo apt-get install znc-dev

Starting ZNC

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

There're few ways to supply password:

If you have decent IRC client, you can just use "username" (or "ident") field for username, optional client identifier and network (for example User@phone/freenode) and "server password" field for password.
You can supply all four in the password field like "user@phone/network:pass" (without quotes)
Just do "/quote pass PA$$WORD" manually every time you connect to ZNC

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

Avoid using special character : in your password, as this can cause errors when trying to parse the password field to look for username, client, network, and password (user@client/network:pass). If the password has : in it, everything before first : is considered to be username (also network and client), and the username sent in the normal way is ignored.

@client-identifier was added with 1.6.0 and is entirely optional. It's used by modules such as chanfilter or clientbuffer.

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

If you installed ZNC using your distribution's package manager, it may have came with a set of scripts or configuration files for the distribution's init system. For systemd, run:

sudo systemctl enable znc.service

(Note that this does not work on the packages in the repositories of Debian; those do not include an init script)

If you installed ZNC manually (from a tarball), you can 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 * * * * /usr/local/bin/znc >/dev/null 2>&1

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

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

 @reboot /usr/local/bin/znc >/dev/null 2>&1

You can also write an init script / configuration file to start ZNC using the init system, see Running ZNC as a system daemon for details.

Using ZNC

ZNC dies when I power off the device it's running on!

Of course, ZNC isn't magic. Like any other software, it doesn't run when you turn off or sleep your PC.

If you want to stay connected while your own device is off/sleeping, ZNC must be running on some other machine somewhere. That could be an always-on PC/server in your home, a remote server that you control, or a ZNC server run by someone else. If you were going to run it on your home PC—which you often power-off or sleep—consider getting a VPS or using a ZNC provider instead. That way you can stay connected even when your device is off or sleeping.

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

You have separate connection for all network. Please also read the next question.

How to use multiple networks like with psybnc?

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. See Why do I get an incorrect password every time I connect though my password is correct?

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

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.

How do I choose which IP to use for connecting to IRC?

By default user can choose any bindhost which means the host to use for connecting to IRC:

/znc setuserbindhost 1.2.3.5
/znc jump

If you want to limit users to only one bindhost, go to webadmin and set the user bindhost as whatever you want and check the "deny setbindhost" checkbox.

How can I force IPv4/IPv6 when connecting to the IRC

To force IPv4:

/znc setuserbindhost 0.0.0.0

To force IPv6 bindhost:

/znc setuserbindhost ::

How can I have separate bindhost for IPv4 and IPv6?

IMPORTANT: ZNC cannot connect from IP address that is not available on your system.

If you have root access

Edit the hosts file of your operating system and add:

0.0.0.0    my.awesome.vhost.example.com
2001:4860:4860::8888    my.awesome.vhost.example.com

and tell ZNC to use it as bindhost:

/znc setuserbindhost my.awesome.vhost.example.com

With this configuration when IPv6 was used the bindhost would be 2001:4860:4860::8888 and when IPv4 was used, any available IPv4 address was used.

If you don't have root access

You must own a domain and set the A and AAAA records however you want into it or preferably subdomain. Then tell ZNC to bind on it with /znc setuserbindhost my.awesome.vhost.example.com

How do I add a new user?

There are (at least) two 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.

Connecting with mIRC

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

Connecting with Eggdrop

See Eggdrop for a detailed explanation on how to connect Eggdrop.

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

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

How to use the loaded modules?

/msg *modulename command

or

/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 ...

.. reattach bnc!

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!

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.

Other tips

Enable Flood settings and/or set them to be less generous (by increasing their values). Disabling Flood settings may lead to some cases where you are simply sending too much information to the server. This can be done via the Web Panel

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

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 AutoClear Chan Buffer and AutoClear Query Buffer to true using either the webadmin or controlpanel module.

/msg *controlpanel set AutoClearChanBuffer $me True
/msg *controlpanel set AutoClearQueryBuffer $me True

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. The external playback module can help with this if your client supports it.

I don't see buffer playback when attaching to ZNC!

What are BINDHOSTS and why can't I make mine work?

̈́VHOSTS were renamed into BINDHOSTs very long time ago, if you still see it in your ZNC, upgrade immediately!

ZNC bindhost 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 demo.znc.in
demo.znc.in has address 208.84.148.90
% host 208.84.148.90
90.148.84.208.in-addr.arpa domain name pointer demo.znc.in.

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

/msg *status SetUserBindHost 208.84.148.90

connect to IRC and check that it's working.

If you find you are unable to connect to IRC after attempting to set bindhost 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 ClearUserBindhost

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

Your ZNC is too old, upgrade.

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

see user-module Route_replies

How can I access webadmin with my browser?

By default webadmin runs on the same PORT as your ZNC is accessible. So if you connect your IRC client to ZNC with server example.com and port 6667, then you would access webadmin by opening your web browser and going to the address http://example.com:6667.

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

Examples

Plaintext port on IPv4 localhost: http://127.0.0.1:8080
SSL port on IPv6 localhost: https://[::1]:8081

Note: Using a well-known port such as 6667 may lead to issues in some browsers, which block accessing websites over a port that is usually associated with a non-website service. It's recommended to run ZNC on a custom port (not 6667/6697), or add a custom webadmin port—but you can also often work around this in the browser.

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=<ZNC's port>.

If you are using Mozilla Firefox and keep getting the error This address is restricted, visit about:config and edit or create the setting network.security.ports.banned.override with a comma-separated list of ports over which ZNC's webadmin can be accessed—for example, 6667,6697.

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

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

How to reload ZNC config without restart?

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

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?

Upgrade to ZNC 1.6.0+ (see query_buffers) and disable "Auto Clear Query Buffer" (for storing channel messages, disable "Auto Clear Chan Buffer") using either webadmin or controlpanel.

Networks

What is this new network support?

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?

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 1.2.3.4 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.

HexChat:

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

Irssi:

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

mIRC:

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

Is it the same as in psybnc?

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.

There is proposal to IRCv3 about this.

How much memory does ZNC need to run?

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 NickServ password is stored in plaintext!

Of course, how could ZNC identify you to services otherwise?

Your ZNC password is hashed in the config file as ZNC doesn't have to know your password, because when you login your password is hashed and compared to the hash in the config file. ZNC cannot do hashing or anything else to other passwords without losing ability to use them.

In theory storing passwords encrypted some way would be possible, but that would require password inputting during ZNC startup preventing starting ZNC automatically and your passwords would still be readable from memory.

If you are using a provider and do not trust them with your credentials, seek a different provider or host ZNC yourself.

Note also that cert isn't any more secure then password if you don't trust the provider. Malicious provider can use it to identify as you and do everything as you including changing your password.

Why does ZNC connect with my altnick?

The exact answer is impossible, other than check znc -D for what happens. Most likely there was connection issue between ZNC and the server.

Keepnick should always take your primary nick when it becomes free. Alternatively if you want to get your primary nick on connect you can configure SASL and set perform to regain your nick (with Atheme IRC services) /msg *perform add NICKSERV REGAIN %defnick%.

How can I make ZNC disconnect when I'm not using it?

The primary reason ZNC exists is to keep you connected to IRC while your client is disconnected. However, some people have found other uses for ZNC and want it to disconnect or even shut down when their IRC client isn't connected.

Disconnect ZNC from IRC when the client quits

You can use the external module simple_disconnect to cause ZNC to disconnect from the IRC server when your client quits. If, for whatever reason, ZNC doesn't connect to the IRC network the next time you connect your IRC client to ZNC, simply issue the command /znc connect to manually initiate the connection between ZNC and the IRC network.

Quit ZNC when the client quits

You probably just want to disconnect ZNC rather than shut it down (see previous section). You can make ZNC quit when you disconnect, but you will then need to access the host machine (via physical access or SSH) and restart ZNC to connect your IRC client to ZNC again; obviously you can't connect your client to ZNC if ZNC is not running.

You can use the external module antiperform to issue commands at the time your IRC client disconnects from ZNC. Add the antiperform command PRIVMSG *status :shutdown to quit ZNC upon disconnecting your IRC client from ZNC. To reconnect, you must first re-launch ZNC on the host machine (for example, ssh user@host.com 'znc') before connecting your IRC client to ZNC again.

I forgot my password! How do I reset my ZNC password?

On the host running ZNC, open a terminal and issue the command:

znc --makepass

You will then be able to create a new password:

[ ** ] Type your new password.
[ ?? ] Enter password:
[ ?? ] Confirm password:

Once the new password is entered, you will be instructed on how to update your config file to use the new password:

[ ** ] Kill ZNC process, if it's running.
[ ** ] Then replace password in the <User> section of your config with this:
<Pass password>
	Method = sha256
	Hash = 846696ed153511170264b41b51008d2c0ccc96929f9e268926857677b50d98dd
	Salt = +zHiaj0~Ci:d6]/`nPizT:+e
</Pass>
[ ** ] After that start ZNC again, and you should be able to login with the new password.

How do I reload znc.pem?

znc.pem is currently (1.6.2) reloaded every time client connects to ZNC. It'll be fixed in future (https://github.com/znc/znc/issues/1215)

How do I migrate ZNC from one machine to another?

Recursively backup/copy the ~/.znc directory (or appropriate alternate DATADIR directory, if it is not ~/.znc) to the new machine, and recursively chown (chown -R newuser:newgroup ~/.znc) the new directory if needed. You will also need to recompile any third-party modules located in ~/.znc/modules/, if you have any.

What are the different module load levels? (Global vs User vs Network)

Network modules are loaded on a per-network basis, meaning they only affect the network they are loaded on. *nickserv and *sasl are examples of network-level modules; they need to be loaded on each network, and do not affect other networks.

User modules affect the ZNC user they are loaded on, as well as all networks for that user. They do not affect other users or other networks for other users.

Global modules affect the entire ZNC instance, which includes all users and all networks for those users.

Some modules can be loaded at more than one level, so it's important to note for which level you are loading a module. For example, *perform can be loaded at both the user and network level. If it is loaded at the user level, it will affect all networks for that user identically, which may cause problems as not all networks behave the same way, and you may not want to perform the same actions on all networks for that user.

Another good example of a multiple-level module is *log. *log can be loaded at all three levels, global, user, and network. Loading *log for a single network will log only that network. Loading *log for a user will log all networks for that user. Loading *log globally will log all networks for all users. NOTE: Be careful of loading the *log module at more than one level, because you will be wasting disk space by saving duplicate logs.

How to configure default settings for users I create?

Create a template user, and configure it. Then, when you want to create new user, clone that user instead. Cloning can be done via webadmin or controlpanel. Modules like cyrusauth also can clone users instead of creating one from scratch if you configured such external logging in.

Troubleshooting

My SSL certificate has expired

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 client supports server-time and all timestamps are wrong

Your clock is in wrong time either on your PC or the server you run ZNC on. Consider using NTP (Network Time Protocol) to keep your clocks on the right time.

Windows users: time.windows.com isn't known for its accuracy.

If you use systemd: sudo timedatectl set-ntp true
Windows/Linux/OS using ntp: using pool.ntp.org
- Windows (10): Start → Settings → Time and language → Add clocks for different timezones → Internet-time → Change settings, type pool.ntp.org and click OK.
OS X: System Preferences → Date and Time → (click the lock and) check "Set date and time automatically:" and enter pool.ntp.org.

My question isn't answered here

Hop on #znc@chat.freenode.net and ask! Usually someone's around, but if no one replies, just wait for a while.

Where do I report bugs?

Create a new issue on GitHub.

FAQ