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.

FAQ: Difference between revisions

From ZNC
Jump to navigation Jump to search
← Older edit
→Networks: new question
Razzi (talk | contribs)
2 edits
 
(50 intermediate revisions by 18 users not shown)
Line 1: Line 1:
{{Languages}}
{{Languages|FAQ}}
If your question isn't answered here, feel free to '''/join [irc://irc.efnet.org/znc #znc]''' on [http://www.efnet.org/ EFNet] to talk about this or any other ZNC related issues.  We are happy to help wherever we can.


== Compiling ZNC ==
== Compiling ZNC ==
=== General ===
=== 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 <code>--disable-optimization</code> to configure. This will disable <code>-O2</code> and instead use <code>-O0"</code>. GCC should need less memory now.


==== The compiler dies saying it has not enough memory! ====
If you still can't compile ZNC, try <code>./configure --disable-optimization CXXFLAGS="--param ggc-min-expand=2 --param ggc-min-heapsize=20000"</code> but be prepared for looong wait.
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 <code>swapon /swap</code> or edit ''/etc/fstab'' and add:
/swap  none    swap    sw  0  0
and run <code>swapon -a</code>. This enables the swap now and on boot.


==== configure: error: pkg-config could not find znc (znc.pc) ====
==== 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.
Use <code>PKG_CONFIG_PATH=~/znc/lib/pkgconfig ./configure</code> and replace <code>~/znc</code> 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:
# [https://duckduckgo.com/?q=YOUR_DISTRIBUTION_HERE+install+gcc+4.8 | 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 ====
==== 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. 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: <code>tar cfvj znc-backup.tar.gz ~/.znc</code>.
This is really simple. You can just follow the instructions on the [[Installation]] page again, but ''DON'T RUN'' <code>--makeconf</code>. 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: <code>tar cfvj znc-backup.tar.gz ~/.znc</code>.
 
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 [[:Category:ChangeLog|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 [[:Category:ChangeLog|ChangeLog]]s 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).''
 
* [[ChangeLog/1.0|1.0]]
** IPv6 isn't attempted when it's not available.
** Doesn't crash when admin unloads *admin (now [[controlpanel]]) module.
* [[ChangeLog/1.2|1.2]]
** Doesn't crash when user with attached client is removed.
* [[ChangeLog/1.4|1.4]]
** [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-9403 CVE-2014-9403] - Denial of Service attack by adding channel that already exists without the "#", the reason why 1.4 was released.
* [[ChangeLog/1.6.0|1.6.0]]
** Disable SSLv3, because of [https://en.wikipedia.org/wiki/POODLE POODLE] and follow [https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28default.29 Mozilla's server-side TLS recommendations.]
** Validate SSL certificates.
*** See also [https://mikaela.info/english/2015/02/24/znc160-ssl.html 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.
* [[ChangeLog/1.6.2|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 <code>CAP :END</code> 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. [[User:Mkaysi|Mikaela Suomalainen]] ([[User talk:Mkaysi|talk]]) 13:34, 16 September 2015 (CEST)


==== Do I have to shut down and restart ZNC during an upgrade to a new version? ====
==== Do I have to shut down and restart ZNC during an upgrade to a new version? ====
Line 25: Line 84:
Try using gmake instead.
Try using gmake instead.
====ZNC crashes at making a config file or adding a user via webadmin on FreeBSD 7.x 64bit====
====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.
Try to compile znc from source with g++42/gcc42 from the ports instead of the default gcc (<code>./configure CXX=g++42</code>) and check your compile output for g++42.


=== Debian ===
=== Debian ===
==== I'm getting the error: configure: error: C++ compiler cannot create executables ====
==== I'm getting the error: configure: error: C++ compiler cannot create executables ====
There are missing some compiler packages, you need to install them via:
There are missing some compiler packages, you need to install them via:
  sudo aptitude update  
  sudo apt-get update  
  sudo aptitude install build-essential make bin86
  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.
If you aren't on Debian, Ubuntu, or related distro, you need to install <code>g++</code>, <code>make</code> and possibly other things using your package manager.


==== I'm compiling under debian and I don't have an openssl/include directory available ====
==== I'm compiling under debian and I don't have an openssl/include directory available ====
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.)
Try using <code>sudo apt-get install libssl-dev</code> 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 ====
==== 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:
You need to add the development files to your debian/ubuntu:
  sudo aptitude install znc-dev
  sudo apt-get install znc-dev


== Starting ZNC ==
== Starting ZNC ==
=== Why do I get an "Incorrect Password" every time I connect even though my pass is correct? ===
=== Why do I get an "Incorrect Password" every time I connect even though my pass is correct? ===
There're few ways to supply password:
There're few ways to supply password:
# If you have decent IRC client, you can just use "username" (or "ident") field for username and "server password" field for password.
# If you have decent IRC client, you can just use "username" (or "ident") field for username, optional client identifier and network (for example <code>User@phone/freenode</code>) and "server password" field for password.
# You can supply both your user and pass as the server password separated by a colon like "user:pass" (without quotes)
# 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
# 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.
Also, make sure you did not accidentally load one of the [[cyrusauth]] or [[imapauth]] modules.
 
Avoid using special character <code>:</code> 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 <code>:</code> in it, everything before first <code>:</code> 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.)? ===
=== How can I restart ZNC automatically (in case of a machine reboot, crash, etc.)? ===
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:
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:
  */10 * * * *   /home/you/znc/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. <code>LoadModule = away yourpassword</code>).
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. <code>LoadModule = awaystore yourpassword</code>).


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


   @reboot your_username /home/you/znc/bin/znc >/dev/null 2>&1
   @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 ==
== 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 [[providers|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 [[Wikipedia:Virtual private server|VPS]] or using a [[providers|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? ===
=== How do I tell ZNC which network/server a channel belongs to? ===
<!--
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|Networks]]). Please also read the next question.
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|Networks]]). Please also read the next question.
-->
You have separate connection for all network. Please also read the next question.


=== How to use multiple networks like with psybnc? ===
=== How to use multiple networks like with psybnc? ===
ZNC works differently. One user represents one network. (Note: since 0.207 it has been changed, user can have several networks now, see [[#Networks|Networks]]) So you need to use a separate ZNC username for each network. You can have multiple ZNC users in one and the same config file, running in one and the same ZNC process.
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 [[FAQ#Why_do_I_get_an_.22Incorrect_Password.22_every_time_I_connect_even_though_my_pass_is_correct.3F|Why do I get an incorrect password every time I connect though my password is correct?]]
<!--
In order to choose which network, you format your server password like this:
 
username/network:password
 
For example, when you wish to connect to both freenode and efnet, open two separate connections with your client, one pointing at


See [http://sourceforge.net/tracker/index.php?func=detail&aid=1698410&group_id=115828&atid=672824 this feature request] on sf.net for technical details.
  username/freenode:password


If you make multiple users for multiple networks you can use the following mIRC script to make multiple connections to your bouncer:
and the other pointing at


on *:start: {
  username/efnet:password
  server my.bouncer.net:6697 user1:password1 -i Nickname AltNick Email Fullname
  server -m my.bouncer.net:6697 user2:password2 -i Nickname AltNick Email Fullname
  server -m my.bouncer.net:6697 user3:password3 -i Nickname AltNick Email Fullname
}


Connections to ZNC using SSL:
For more detailed documentation on how to connect with several clients, refer to [[FAQ#How_do_I_connect_to_my_networks.3F|How do I connect to my networks?]]


on *:start: {
''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.''
  server my.bouncer.net:+6697 user1:password1 -i Nickname AltNick Email Fullname
-->
  server -m my.bouncer.net:+6697 user2:password2 -i Nickname AltNick Email Fullname
  server -m my.bouncer.net:+6697 user3:password3 -i Nickname AltNick Email Fullname
}


=== I added several different servers, but ZNC connects only to one of them! ===
=== I added several different servers, but ZNC connects only to one of them! ===
Line 91: Line 174:
So you can add several servers of one network to server list of one user.
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 ===
=== How do I choose which IP to use for connecting to IRC? ===
By default user can choose any bindhost:
 
  /znc setbindhost 1.2.3.5
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
  /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 1.2.3.4
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.
  /znc addbindhost 1.2.3.5
 
==== 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 <code>hosts</code> file of your operating system and add:
 
<pre>
0.0.0.0    my.awesome.vhost.example.com
2001:4860:4860::8888    my.awesome.vhost.example.com
</pre>
 
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 <code>/znc setuserbindhost my.awesome.vhost.example.com</code>


=== How do I add a new user? ===
=== How do I add a new user? ===
There are (at least) three ways to 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.
The easiest way is to load and use the [[webadmin]] module.


If you want to do it from IRC, load the [[admin]] module and check out ''/msg *admin help''.
If you want to do it from IRC, load the [[controlpanel]] module and check out <code>/msg *controlpanel help</code>.
<!--


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.
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 ===
=== Connecting with mIRC ===
You can add your ZNC to the list of servers via the following command:
See [[MIRC]] for a detailed explanation on how to connect with mIRC.
/server -a _IP_ -p _PORT_ -g gZNC -w _USER_/_NETWORK_:_PASSWORD_ -d ZNC
So for example:
/server -a 127.0.0.1 -p 12345 -g gZNC -w Test/freenode:123456 -d ZNC
/server -m ZNC
To connect with SSL first download and run the OpenSSL installer available [http://www.mirc.com/ssl.html here], then you can connect by adding a + sign before the port number, like this:
/server 127.0.0.1:+12345 username/network:password
Adding it your server list is as simple as:
/server -a 127.0.0.1 -p +12345 -g gZNC -w Test/freenode:123456 -d ZNC


=== Connecting with Eggdrop ===
=== Connecting with Eggdrop ===
Add this to your eggdrop configuration:
 
set servers {
See [[Eggdrop]] for a detailed explanation on how to connect Eggdrop.
    <server>:<port>:<user>:<pass>
}


=== I got banned from #channel and ZNC keeps trying to rejoin ===
=== I got banned from #channel and ZNC keeps trying to rejoin ===
Line 134: Line 239:
"*" is the StatusPrefix, which you can change in config file. You could start trying the help command which should work on all modules.
"*" 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! ===
=== I keep getting kicked for flood when I ... ===
This happens if you use "many" channels, due to IRC clients flooding the server with commands upon reattach. There is no throttling/fix for this yet. A workaround is enabling keepbuffer and setting some lines of buffer for each channel. (You should experiment how many is enough.)
==== .. 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 [[Configuration|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 [[Configuration#Network|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! ===
=== 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:
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.
  KeepBuffer = false
 
using the webadmin module, or in the configuration file.
/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! ====
 
See also the previous question.
 
If ''AutoClear Chan Buffer'' and ''AutoClear Query Buffer'' (commonly referred as ''AutoClear*Buffer'') are true, ZNC clears the buffers after they have been sent to client. This has some drawbacks such as sometimes the messages getting lost when client has lost network connection or another client not receiving messages, because one was already running and clearing buffers.
 
/msg *controlpanel set AutoClearChanBuffer $me False
/msg *controlpanel set AutoClearQueryBuffer $me False
 
In case you wish to only clear buffers automatically for specific clients, take a look at the external [[clientbuffer]] module which is basically ''AutoClear*Buffer'' for clients added to it.
 
Check also that your ''ChanBufferSize'' and ''QueryBufferSize'' are higher than 0 (disabled). They default to 50 meaning you get 50 lines of what was said before you attached to ZNC.


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 BINDHOSTS and why can't I make mine work? ===


=== What are VHOSTS 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, [[installation|upgrade]] immediately!''


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:
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
  % host demo.znc.in
  demo.znc.in has address 208.84.148.90
  demo.znc.in has address 208.84.148.90
Line 152: Line 283:
  90.148.84.208.in-addr.arpa domain name pointer demo.znc.in.
  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
As long as the response looks similar then you should be able to
  /msg *status SetVHost 208.84.148.90
  /msg *status SetUserBindHost 208.84.148.90
connect to IRC and check that it's working.
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
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 ClearVHost
  /msg *status ClearUserBindhost
and try to connect again.
and try to connect again.


To get ride of several missunderstandings vhost was renamed to bindhost since version [[ChangeLog/0.096|0.096]].
To get rid of several misunderstandings vhost was renamed to bindhost since version [[ChangeLog/0.096|0.096]].
 
==== But I want to hide my IP! How to do that? ====
 
Set up ZNC on some remote server, then that server's IP will be shown instead of your home IP. Or use VPN, or use [[Tor]].


=== I get 'Could not find znc-config. Please (re)install' when using znc-buildmod ===
=== I get 'Could not find znc-config. Please (re)install' when using znc-buildmod ===
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
Your ZNC is too old, [[Installation|upgrade]].
./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 ===
=== I keep getting a lot of stuff like /who replies when connected with multiple clients to one znc-user ===
Line 174: Line 303:


=== How can I access webadmin with my browser? ===
=== How can I access webadmin with my browser? ===
By default [[web UI]] runs on the same PORT as your ZNC is accessible.
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 '''<nowiki>http://example.com:6667</nowiki>'''.
 
If ZNC listens using SSL, use the HTTP'''S''' protocol (http'''s'''://) instead of just HTTP (http://). If your web interface won't come up, please ensure that you are using the correct protocol for connecting.


If your webinterface won't come up, please ensure that you are using the correct protocol
; Examples:
for connecting. If ZNC listens using SSL, use the HTTPS protocol (https://) instead of just HTTP (http://).
:* Plaintext port on IPv4 localhost: <code><nowiki>http://127.0.0.1:8080</nowiki></code>
:* SSL port on IPv6 localhost: <code><nowiki>https://[::1]:8081</nowiki></code>


If you are using Google Chrome and keep getting an Error 312 (net::ERR_UNSAFE_PORT)
'''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.
then try calling Chrome with the parameter "--explicitly-allowed-ports=PORT".
 
If you are using Google Chrome and keep getting an <tt>Error 312 (net::ERR_UNSAFE_PORT)</tt>, then try calling Chrome with the parameter <code>--explicitly-allowed-ports=<ZNC's port></code>.
 
If you are using Mozilla Firefox and keep getting the error <tt>This address is restricted</tt>, visit <tt>about:config</tt> and edit or create the setting <tt>network.security.ports.banned.override</tt> with a comma-separated list of ports over which ZNC's webadmin can be accessed—for example, <tt>6667,6697</tt>.


=== My IRC-Client doesn't allow multiple connections to one server/host ===
=== My IRC-Client doesn't allow multiple connections to one server/host ===
Line 187: Line 322:
=== How to reload ZNC config without restart? ===
=== How to reload ZNC config without restart? ===
The best way is '''NOT''' to change znc.conf and other files manually while ZNC is running.
The best way is '''NOT''' to change znc.conf and other files manually while ZNC is running.
Try to use [[webadmin]] or [[admin]] instead, or use <code>/msg *status help</code>
Use [[webadmin]] or [[controlpanel]] instead, or use <code>/msg *status help</code>
 
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, there're 2 ways to do that: from IRC (<code>/msg *status rehash</code>)
If you ''really'' need to rehash config from file without restart, there're 2 ways to do that: from IRC (<code>/msg *status rehash</code>)
and from shell (<code>pkill -SIGHUP znc</code>).
and from shell (<code>pkill -SIGHUP znc</code>). But don't complain if something is broken (because it ''will'' be broken for sure)


=== [10053] Software caused connection abort ===
=== [10053] Software caused connection abort ===
Line 196: Line 333:


=== How to store private messages even when user is attached, so other clients can see them? ===
=== How to store private messages even when user is attached, so other clients can see them? ===
Here's simple workaround.


First, you should know number of wanted clients. Let's say that you want 3 clients: 1 xchat and 2 irssi-s. Let's say that your username is johndoe.
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]].
<!--
''Pre-1.6.0:'' 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_xchat, johndoe_irssi1, johndoe_irssi2. This naming scheme isn't strict - everything is up to you.
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.
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_xchat, johndoe_irssi1 and johndoe_irssi2 to 127.0.0.1 to the same ZNC, to user johndoe_ircd.
Connect user johndoe_ircd to IRC server. Connect users johndoe_hexchat, johndoe_irssi1 and johndoe_irssi2 to 127.0.0.1 to the same ZNC, to user johndoe_ircd.


Connect xchat to johndoe_xchat, and irssis to johndoe_irssiN.
Connect hexchat to johndoe_hexchat, and irssis to johndoe_irssiN.


<pre>
<pre>
xchat -----> ZNC,johndoe_xchat -----------\
          ___________________________________________________
                                          v
          /                                                  \
irssi1 -----> ZNC,johndoe_irssi1 -----> ZNC,johndoe_ircd -----> IRC server
        |                        ZNC                        |
                                          ^
        |                                via 127.0.0.1      |
irssi2 -----> ZNC,johndoe_irssi2 ---------/
hexchat ----|> user "johndoe_hexchat"----------\               |
        |                                    v               |
irssi1 -----|> user "johndoe_irssi1" ---|> user "johndoe_ircd" -----|> IRC server
        |                                    ^               |
irssi2 -----|> user "johndoe_irssi2" ----------/                |
        |                                                    |
          \___________________________________________________/
</pre>
</pre>
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.
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.
-->
<!-- Note: in 1.0+ you can use either networks instead of users, if that suits you better. (uncomment this if/when network can have own statusprefix) -->


=== Networks ===
=== Networks ===
Line 220: Line 370:
==== What is this new network support? ====
==== What is this new network support? ====


'''This works only if you use git version. No released version has this yet.'''
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.


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 previous versions.
[[HexChat]]:
<pre>
/server 1.2.3.4 7778 ZNCUser/EFnet:PassWord
/server -ssl 1.2.3.4 7777 ZNCUser/freenode:PassWord
</pre>


==== How do I connect to my networks? ====
[[Irssi]]:
<pre>
/server 1.2.3.4 7778 ZNCUser/EFnet:PassWord
/server -SSL 1.2.3.4 7777 ZNCUser/freenode:PassWord
</pre>


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 password field you can use `username/network:password`.
[[mIRC]]:
<pre>
/server -m 1.2.3.4 7778 ZNCUser/EFnet:PassWord
/server -m 1.2.3.4 +7777 ZNCUser/freenode:PassWord
</pre>


==== Is it the same as in psybnc? ====
==== Is it the same as in psybnc? ====
Line 235: Line 411:


If ZNC ever supports connecting to all networks together, it will be done properly, without those prefixes, but via an IRC protocol extension instead.
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 [http://ircv3.org IRCv3], to allow client developers to support it easier.
Also that extension should be standardized at [http://ircv3.net IRCv3], to allow client developers to support it easier.
 
''[https://github.com/ircv3/ircv3-specifications/pull/92 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|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 than a password if you don't trust the provider. Malicious providers 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 <code>znc -D</code> 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) <code>/msg *perform add NICKSERV REGAIN %defnick%</code>.
 
=== How can I make ZNC disconnect when I'm not using it? ===
 
[[File:Overview network scheme.png|thumb|128px|ZNC's reason to exist]]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 [[:Category:External Modules|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 <code>/znc connect</code> 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 [[{{FULLPAGENAME}}#Disconnect ZNC from IRC when the client quits|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 [[:Category:External Modules|external module]]  '''[[antiperform]]''' to issue commands at the time your IRC client disconnects from ZNC. Add the antiperform command <code>PRIVMSG *status :shutdown</code> to quit ZNC upon disconnecting your IRC client from ZNC. To reconnect, you must first re-launch ZNC on the host machine (for example, <code>ssh user@host.com 'znc'</code>) 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 = 846696​ed153511170264b41b51008d2c0ccc​96929f9e268926857677b50d98dd
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 (<code>chown -R newuser:newgroup ~/.znc</code>) the new directory if needed.  You will also need to recompile any third-party modules located in ~/.znc/modules/, if you have any.  Machine or host-specific bindhosts will also need updating.
 
=== 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.  [http://wiki.znc.in/Nickserv *nickserv] and [http://wiki.znc.in/Sasl *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, [http://wiki.znc.in/Perform *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 [http://wiki.znc.in/Log *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 ==
== 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.
''[http://support.ntp.org/bin/view/Support/WindowsTimeService Windows users: time.windows.com isn't known for its accuracy. ]''
* If you use systemd: <code>sudo timedatectl set-ntp true</code>
* Windows/Linux/OS using ntp: [http://www.pool.ntp.org/en/use.html using pool.ntp.org]
** Windows (10): Start → Settings → Time and language → Add clocks for different timezones → Internet-time → Change settings, type <code>pool.ntp.org</code> and click OK.
* OS X: System Preferences → Date and Time → (click the lock and) check "Set date and time automatically:" and enter <code>pool.ntp.org</code>.
=== My question isn't answered here ===
Hop on [ircs://irc.libera.chat:6697/#znc #znc on Libera.Chat] and ask! Usually someone's around, but if no one replies, just wait for a while.


=== Where do I report bugs? ===
=== Where do I report bugs? ===

Latest revision as of 18:45, 7 August 2023

Languages Languages: 

English

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:

  1. | Using your favourite search engine.
  2. 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
  • 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:

  1. 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.
  2. You can supply all four in the password field like "user@phone/network: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 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!

See also the previous question.

If AutoClear Chan Buffer and AutoClear Query Buffer (commonly referred as AutoClear*Buffer) are true, ZNC clears the buffers after they have been sent to client. This has some drawbacks such as sometimes the messages getting lost when client has lost network connection or another client not receiving messages, because one was already running and clearing buffers. 

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

In case you wish to only clear buffers automatically for specific clients, take a look at the external clientbuffer module which is basically AutoClear*Buffer for clients added to it.

Check also that your ChanBufferSize and QueryBufferSize are higher than 0 (disabled). They default to 50 meaning you get 50 lines of what was said before you attached 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.

But I want to hide my IP! How to do that?

Set up ZNC on some remote server, then that server's IP will be shown instead of your home IP. Or use VPN, or use Tor.

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 than a password if you don't trust the provider. Malicious providers 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?

ZNC's reason to exist

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 = 846696​ed153511170264b41b51008d2c0ccc​96929f9e268926857677b50d98dd
	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. Machine or host-specific bindhosts will also need updating.

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 on Libera.Chat 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.

Retrieved from "https://wiki.znc.in/index.php?title=FAQ&oldid=3013"