# Chroot ZNC In this guide, we will install ZNC inside a chroot. [ZNC](https://wiki.znc.in) is an IRC bouncer. It runs on a server and stays connected after you turn off your computer or phone. It saves chat messages and replays them when you reconnect, and also helps to hide your IP address. If you are running it on IRCNow, your server may also offer [DDoS protection](/openbsd/ddos) to keep you online. [ZNC](https://wiki.znc.in) is an IRC bouncer. It runs on a server and stays connected after you turn off your computer or phone. It saves chat messages and replays them when you reconnect, and also helps to hide your IP address. If you are running it on IRCNow, your server may also offer [DDoS protection](/openbsd/ddos) to keep you online. ## Before You Begin You will want to set up [ZNC](/Znc/Install) once without a chroot, as a normal user without root powers. This will give you a better understanding of how ZNC works before you attempt a more complex, chrooted install. Next, read the [introduction to chroots](/chroot/intro) to get familiar with the concept of chroots. In this guide, we use a chroot for extra security. ## Public ZNCs If you are offering a public ZNC service for many users, you will want to get a ddos-filtered IPv4 address and an IPv6 subnet from your internet provider ([BuyVM guide](/openbsd/buyvm)). ## Installing Dependencies The below installation was tested on [OpenBSD 7.1 stable](/openbsd/syspatch). ZNC will run inside a chroot at /home/znc. Before beginning the installation, check to make sure you are using OpenBSD 7.1 and that your system is patched: $ uname -a OpenBSD username.example.com 7.1 GENERIC#443 amd64 $ doas syspatch Next, we install needed dependencies: $ doas pkg_add icu4c boost cmake gettext-runtime gettext-tools ## Installing from Packages **WARNING**: OpenBSD 6.9 (and later) may contain a bug that causes ZNC to crash with a segmentation fault. To avoid this, we recommend applying a [custom patch to ZNC](/znc/patch). If you are running on a single core server, you can install znc from packages: $ doas pkg_add znc ## Compiling from Source ### Patched Source Due to a bug in OpenBSD 6.9, we have applied a [custom patch to ZNC](/znc/patch): $ cd ~ $ ftp https://ircnow.org/software/znc-1.8.2b.tar.gz On OpenBSD, [ftp](/ftp/usage) can also be used to download files from the web. Next, [extract and unzip](/tar/usage) the files: $ tar xvzf znc-1.8.2b.tar.gz For [tar](/tar/usage), the options xvzf stand for e(x)tract, (v)erbose, un(z)ip, and (f)ile. Next, we build ZNC: $ cd znc-1.8.2 $ mkdir build $ cd build $ cmake .. $ make $ doas make install ## Configuring the Chroot We want to [create a new unprivileged user account](/openbsd/adduser) for security: $ doas useradd -m -d /home/znc -s /sbin/nologin znc `-m` tells [useradd](/https://man.openbsd.org/useradd) to create a home folder; `-d` says the home folder is `/home/znc`; `-s` specifies the default shell as `/sbin/nologin`, meaning no user can login. The username created is znc. ### Login Class Add the following lines to the end of [/etc/login.conf](/https://man.openbsd.org/login.conf): znc:\ :openfiles-cur=4096:\ :openfiles-max=8182:\ :openfiles=4096:\ :stacksize-cur=48M:\ :stacksize-max=48M:\ :maxproc-max=infinity:\ :maxproc-cur=4096:\ :tc=daemon: **WARNING**: Use tabs and not spaces. Spaces will fail and as a result, znc will not get the file resources it needs. The [login.conf](/openbsd/loginconf) guide explains the attributes in more detail. Each time znc creates a new connection for a user, it requires at least one file descriptor. So, if your file descriptor limit is set too low, znc will be unable to make new connections to networks. openfiles sets the maximum number of open file descriptors per process. -cur specifies the current limit and -max specifies the maximum limit. The current and maximum stack size controls how much stack memory a user can use. We set it at 48M to give ZNC plenty of room. `maxproc` limits how many processes a user in this class can create. We set the maximum to infinity and the current amount to 4096. `tc=daemon` means that the default values will come from the `daemon` login class. Now we change znc's default login class to znc: $ doas usermod -L znc znc This can also be edited with a text editor using [[openbsd/vipw]]. To confirm that the login class has been changed, check [/etc/master.passwd](/https://man.openbsd.org/./man5/passwd.5). $ doas grep '^znc' /etc/master.passwd znc:*:1001:1001:znc:0:0:znc:/home/znc:/sbin/nologin [grep](grep/usage) searches for the line that begins with `znc` in [/etc/passwd](/https://man.openbsd.org/./man5/passwd.5). [grep](grep/usage) searches for the line that begins with `znc` in [/etc/passwd](/https://man.openbsd.org/./man5/passwd.5). The 5th field needs to say znc: $ doas grep '^znc' /etc/master.passwd | cut -d : -f 5 znc **NOTE**: If /etc/login.conf.db exists, make sure to delete it (or recreate the database), otherwise login.conf changes won't apply. To delete: $ doas rm /etc/login.conf.db Next, we temporarily change znc's shell to ksh: $ doas chsh -s /bin/ksh znc Next, we login with the username znc, with the login class znc: $ doas su -c znc znc $ ulimit -a time(cpu-seconds) unlimited file(blocks) unlimited coredump(blocks) unlimited data(kbytes) 33554432 stack(kbytes) 32768 lockedmem(kbytes) 329478 memory(kbytes) 985092 nofiles(descriptors) 4096 processes 1310 `ulimit -a` displays all process limits for our current user. **WARNING**: If nofiles(descriptors) is not 4096, you may have an error in your configuration! Press ctrl+d to signal the end of file to logout and change znc's login shell back to /sbin/nologin. Then, while inside znc-1.8.2, run the chroot.sh script as root: $ ^D $ doas chsh -s /sbin/nologin znc $ cd ~/znc-1.8.2 $ doas sh chroot.sh ## Configuring ZNC ### Makeconf At first, you will need to create a conf file: $ doas su # export HOME=/home/znc/ # chroot -u znc -g znc /home/znc znc --makeconf [ .. ] Checking for list of available modules... [ ** ] [ ** ] -- Global settings -- [ ** ] [ ?? ] Listen on port (1025 to 65534): 31337 [ ?? ] Listen using SSL (yes/no) [no]: yes [ ?? ] Listen using both IPv4 and IPv6 (yes/no) [yes]: no [ .. ] Verifying the listener... [ ** ] Unable to locate pem file: [/home/znc/.znc/znc.pem], creating it [ .. ] Writing Pem file [/home/znc/.znc/znc.pem]... [ ** ] Enabled global modules [webadmin] [ ** ] We're going to configure ZNC to listen on ports 1337 and 31337. Port 1337 will be plaintext, port 31337 will be SSL. This convention is followed by IRCNow's public servers. **WARNING**: Do **not** listen to both IPv4 and IPv6. There appears to be a bug in ZNC v1.8.2 on OpenBSD 6.9 where selecting 'yes' will cause IPv4 to stop working. Instead, as shown later in the guide, you can create separate listeners to allow listening to both IPv4 and IPv6. You will want to enable connecting both with and without [SSL](/tls/overview). Although SSL helps to encrypt messages, some older IRC programs don't support it, so it is important to offer ZNC in plaintext. ZNC will automatically create its own SSL certificate. This certificate, however, will be self-signed and hence will show up as invalid or untrusted by your IRC client. To get a properly signed SSL certificate, you will need to configure [openhttpd](openhttpd/configure) and request the certificate with [acme-client](/acme-client/configure). ZNC will automatically create its own SSL certificate. This certificate, however, will be self-signed and hence will show up as invalid or untrusted by your IRC client. To get a properly signed SSL certificate, you will need to configure [openhttpd](openhttpd/configure) and request the certificate with [acme-client](/acme-client/configure). [ ** ] -- Admin user settings -- [ ** ] [ ?? ] Username (alphanumeric): username [ ?? ] Enter password: [ ?? ] Confirm password: [ ?? ] Nick [username]: [ ?? ] Alternate nick [username_]: [ ?? ] Ident [username]: [ ?? ] Real name (optional): ### Bindhosts Next, you'll be asked to specify an optional bindhost. For now, we will leave this blank. [ ?? ] Bind host (optional): **WARNING**: You cannot pick any arbitrary [bindhost](/dns/vhost) that you want. If the bindhost does not work, your vhost will not show up properly, and you may not be able to connect at all! The bindhost is used to pick which IP address to use for a server with multiple IP addresses. It can allow you to pick a nice-looking vhost, like `username@username.example.com`, once [DNS](/dns/overview) has been properly set up. A [vhost|dns/vhost]] must have proper [forward](dns/overview) and [reverse DNS](/DNS/rDNS) [records](/dns/records) to work. If these have not been configured properly, first leave the bindhost blank. A [vhost|dns/vhost]] must have proper [forward](dns/overview) and [reverse DNS](/DNS/rDNS) [records](/dns/records) to work. If these have not been configured properly, first leave the bindhost blank. To test if your bindhost works properly, check the [host](/host/usage) guide. You will want to run host on your hostname and IP address to make sure they both match. [ ** ] Enabled user modules [chansaver, controlpanel] [ ** ] [ ?? ] Set up a network? (yes/no) [yes]: [ ** ] We will turn on the chansaver and controlpanel modules and set up a network. [ ** ] -- Network settings -- [ ** ] [ ?? ] Name [freenode]: example [ ?? ] Server host (host only): irc.example.com [ ?? ] Server uses SSL? (yes/no) [no]: yes [ ?? ] Server port (1 to 65535) [6697]: [ ?? ] Server password (probably empty): [ ?? ] Initial channels: #channel [ ** ] Enabled network modules [simple_away] Configure a network. The network name is usually just a single word; it is not the same as the server host. IRC normally uses port 6667 if there is no SSL, and 6697 if there is SSL. [ ** ] [ .. ] Writing config [/home/znc//.znc/configs/znc.conf]... [ ** ] [ ** ] To connect to this ZNC you need to connect to it as your IRC server [ ** ] using the port that you supplied. You have to supply your login info [ ** ] as the IRC server password like this: user/network:pass. [ ** ] [ ** ] Try something like this in your IRC client... [ ** ] /server +31337 username: [ ** ] [ ** ] To manage settings, users and networks, point your web browser to [ ** ] https://:31337/ [ ** ] [ ?? ] Launch ZNC now? (yes/no) [yes]: no For now, avoid setting up the web server on port 31337. We will instead use [relayd](/relayd/acceleration) so that the web server can viewed on the default port for https: port 443. ## Configuring SSL In order to provide SSL for the bouncer, you must first configure [OpenHTTPd](openhttpd/configure) and request a certificate with [acme-client](/acme-client/configure). In order to provide SSL for the bouncer, you must first configure [OpenHTTPd](openhttpd/configure) and request a certificate with [acme-client](/acme-client/configure). Once that is done, you can copy the certificate: # cp /etc/ssl/bnc.example.com.crt /home/znc/home/znc/.znc/ # cp /etc/ssl/private/bnc.example.com.key /home/znc/home/znc/.znc/ # chown znc:znc /home/znc/home/znc/.znc/bnc.example.com.{crt,key} In the above commands, replace `bnc.example.com` with your real hostname. Next, we create dhparam: $ openssl dhparam -out dhparam.pem 2048 $ doas chown znc:znc dhparam.pem $ doas mv dhparam.pem /home/znc/home/znc/.znc/ Next, edit [/home/znc/home/znc/.znc/configs/znc.conf](/https://wiki.znc.in/Configuration) to use this configuration: // WARNING // // Do NOT edit this file while ZNC is running! // Use webadmin or *controlpanel instead. // // Read up on /znc saveconfig and /znc rehash. // Also check https://wiki.znc.in/Configuration AnonIPLimit = 10000 AuthOnlyViaModule = false ConfigWriteDelay = 60 ConnectDelay = 1 HideVersion = false LoadModule = chansaver LoadModule = lastseen LoadModule = adminlog LoadModule = identfile LoadModule = webadmin LoadModule = certauth MaxBufferSize = 10000 ProtectWebSessions = true SSLCertFile = /home/znc/.znc/bnc.example.com.crt SSLDHParamFile = /home/znc/.znc/dhparam.pem SSLKeyFile = /home/znc/.znc/bnc.example.com.key PidFile = /home/znc/.znc/znc.pid ServerThrottle = 1 Version = 1.8.2 AllowIRC = true AllowWeb = false Host = 192.168.1.1 IPv4 = true IPv6 = false Port = 1337 SSL = false URIPrefix = / AllowIRC = true AllowWeb = false Host = 192.168.1.1 IPv4 = true IPv6 = false Port = 31337 SSL = true URIPrefix = / AllowIRC = true AllowWeb = false Host = 2001:db8:: IPv4 = false IPv6 = true Port = 1337 SSL = false URIPrefix = / AllowIRC = true AllowWeb = false Host = 2001:db8:: IPv4 = false IPv6 = true Port = 31337 SSL = true URIPrefix = / AllowIRC = true AllowWeb = false Host = 127.0.0.1 IPv4 = true IPv6 = false Port = 1337 SSL = false URIPrefix = / AllowIRC = false AllowWeb = true Host = 127.0.0.1 IPv4 = true IPv6 = false Port = 1338 SSL = false URIPrefix = / Pass = sha256#014eab533f25fe65621963f712ecaf3b86fe840859ab6f4c675200c73d02e6d1#ytZ8/L,:MtZ5cMCe5IJX# Admin = true Nick = username AltNick = username_ Ident = username LoadModule = chansaver LoadModule = controlpanel LoadModule = simple_away Server = irc.example.com +6697 Make sure you read the [ZNC wiki](/https://wiki.znc.in/Configuration) to understand the meaning of each option. You must replace `bnc.example.com` with your actual hostname. In the listeners, you must replace `192.168.1.1` and `2001:db8::` with your server's [public IPv4 and IPv6 address](/IP/myaddress). **NOTE**: Do **not** replace `127.0.0.1`. This is [localhost](/localhost/intro) and must not be changed. We recommended you use ports 1337 for plaintext, 31337 for SSL, and 1338 for web. This convention is followed on the public servers on IRCNow. Note that znc binds to port 1338 without SSL for the web server. We later use [relayd](/openbsd/relayd) to provide TLS acceleration on port 443. **WARNING**: Within the same listener, do **not** listen to both IPv4 and IPv6. You need separate listeners for each. For the username block, use the defaults that ZNC's makeconf generated. Don't edit or delete the values that ZNC generated automatically. Please read the [ZNC wiki](/https://wiki.znc.in/Configuration) to understand the meaning of each option. ## Ident Notice the above config loads the identfile module by default. This is necessary to provide proper ident using [oidentd](oidentd/ZNC). You will need to configure [oidentd](/oidentd/ZNC) for the module to work. Notice the above config loads the identfile module by default. This is necessary to provide proper ident using [oidentd](oidentd/ZNC). You will need to configure [oidentd](/oidentd/ZNC) for the module to work. ## Packet Filter If [packet filter](/pf/intro) is set to deny all incoming connects, you can add this rule to /etc/pf.conf: pass in log quick proto tcp to port {http https} keep state (max-src-conn 300, max-src-conn-rate 300/60) #relayd web pass in log quick proto tcp to port {1337 31337} keep state (max 3000, max-src-conn 300) #bnc To load the new ruleset: # pfctl -f /etc/pf.conf ## Starting ZNC To run znc: # export HOME=/home/znc # /usr/sbin/chroot -u znc -g znc /home/znc znc >>/var/log/znc.log 2>&1 & ## Recreate znc.conf If at any time you mess up the configuration, move your current znc.conf to a new location (to back it up), then rerun the makeconf command again: $ doas mv /home/znc/home/znc/.znc/configs/{znc.conf,znc.conf.bak} $ doas chroot -u znc -g znc /home/znc znc --makeconf ## Changing Password If you forget the password you set during the --makeconf, you can generate a new one like this: # /usr/sbin/chroot -u znc -g znc /home/znc znc --makepass [ ** ] Type your new password. [ ?? ] Enter password: [ ?? ] Confirm password: [ ** ] Kill ZNC process, if it's running. [ ** ] Then replace password in the section of your config with this: Method = sha256 Hash = 49396054dc8263b573d11c9c01e43f89ee772f6dc89b3c630e6dffa9acea4a3e Salt = ovexwSL50cC?jE2eCM?x [ ** ] After that start ZNC again, and you should be able to login with the new password. The example output above shows the hash generated for a password of "password". This gives you the password block you need to add to your [/home/znc/home/znc/.znc/configs/znc.conf](/https://wiki.znc.in/Configuration) file. **NOTE:** You'll need to replace the original generated Pass = line. The new user section of your config will look something like this: Method = sha256 Hash = 49396054dc8263b573d11c9c01e43f89ee772f6dc89b3c630e6dffa9acea4a3e Salt = ovexwSL50cC?jE2eCM?x Admin = true Nick = username AltNick = username_ Ident = username LoadModule = chansaver LoadModule = controlpanel LoadModule = simple_away Server = irc.example.com +6697 ## Editing Config The best way to edit the conf file is by [logging in to znc](bouncer/bouncer) with your IRC client, then using the *status or *controlpanel module. You can also use the [webpanel](/znc/webpanel) once it has been set up. The best way to edit the conf file is by [logging in to znc](bouncer/bouncer) with your IRC client, then using the *status or *controlpanel module. You can also use the [webpanel](/znc/webpanel) once it has been set up. Sometimes, however, it may be necessary to edit your configuration file directly and then reload it (rehash). ### Shutting down and restarting If the only person using ZNC is yourself, you can easily shut down ZNC, edi the conf, then restart ZNC. # pkill -U znc This will kill all processes run by the user znc, which should kill the bouncer. Then edit the znc.conf file, and restart ZNC as described above. ### Live rehash If you have other users connected to a public ZNC, or you cannot afford to take ZNC offline, you may need to rehash ZNC. First, [log in to znc](/bouncer/bouncer) with your IRC client, then save the config: /msg *status saveconfig Next, edit [/home/znc/home/znc/.znc/configs/znc.conf](/https://wiki.znc.in/Configuration). Finally, send a rehash message over IRC to ZNC: /msg *status rehash We add a [cron job](/openbsd/cron) to have ZNC restart every 5 minutes. ZNC will only start if no other ZNC instance is running, so this is safe: # echo "HOME=/home/znc" >> /var/cron/tabs/root # echo "*/5 * * * * /usr/sbin/chroot -u znc -g znc /home/znc znc >>/var/log/znc.log 2>&1 &" >> /var/cron/tabs/root ## Testing ZNC To test the connection in plaintext (**warning**: insecure), consult the [netcat irc guide](/netcat/irc). To test the connection using SSL, run: $ openssl s_client -connect bnc.example.com:31337 Replace `bnc.example.com` with your actual hostname. Check to make sure you have the proper SSL cert configured. Once an SSL session has been established, consult the [netcat irc guide](/netcat/irc). ## Web Panel Use [relayd](/znc/relayd) to allow visitors to use port 443 to access the ZNC web panel. ## Control Panel See [[znc/usage]] for help on how to use the controlpanel. (:if false:) ## rc.d script Create /etc/rc.d/znc: #!/bin/ksh # # $OpenBSD: znc,v 1.2 2020/01/21 19:27:07 rpe Exp $ daemon_pidfile="/home/znc/home/znc/.znc/znc.pid" daemon="env HOME=/home/znc /usr/sbin/chroot -u znc -g znc /home/znc znc" service_stop() { if [ -f $daemon_pidfile ]; then pid=$(sed 's/[^0-9]*//g' $daemon_pidfile) kill $pid fi } case "$1" in stop) service_stop ;; esac . /etc/rc.d/rc.subr rc_reload=NO rc_cmd $1 doas chmod +x /etc/rc.d/znc ## Automatic start This script will automatically restart znc in case it crashes. doas mkdir /usr/local/project_name/ doas touch /usr/local/project_name/checker_znc.sh doas chmod +x /usr/local/project_name/checker_znc.sh #!/bin/sh SERVICE_NAME="znc" SERVICE_USER="znc" SERVICE_PID="/home/znc/home/znc/.znc/znc.pid" if # pgrep -u $SERVICE_USER -x "$SERVICE_NAME" > /dev/null then if [ -f $SERVICE_PID ]; then rm -f $SERVICE_PID rcctl -d restart $SERVICE_NAME fi fi # echo "*/2 * * * * /usr/local/project_name/checker_znc.sh 2>&1 &" >> /var/cron/tabs/root (:ifend:) ## Custom vhosts **WARNING**: do **not** set individual IPv6 addresses for a user's bindhost. Do not set a user's bindhost to be something like 2605:6400:10::. If you specify an IPv6 address for the bindhost, that user can *only* connect to networks that support IPv6. IPv4-only networks completely fail. It is better to set the bindhost to be username.fruit.ircnow.org. Then, for the [nameserver](/openbsd/nsd), create an AAAA record and an A record. That way, the bindhost will use IPv6 if the network is IPv6-only, and IPv4 if it is an IPv4-only network. This solution is more flexible and allows your user to fall back to IPv4 when IPv6 is not supported. If a user requests to change their vhost, do not edit the bindhost -- all you need to do is update the rDNS record (see the [buyvm web panel](/openbsd/buyvm). Don't delete the bindhost or the DNS A/AAAA records. For example, suppose the vhost was formerly user.fruit.ircnow.org. If the user wants to change it to example.com, you just need to update the rDNS to example.com, but leave the znc bindhost as username.fruit.ircnow.org and keep the A/AAAA records for username.fruit.ircnow.org. Once example.com's AAAA record is working, and the rDNS has been configured properly, you can reconnect the user (either the user types `/znc connect` or you type `/msg *controlpanel reconnect `), and the vhost will update properly. Keeping the old A/AAAA record and bindhost working will make it easier if the user changes vhosts or if their 3rd party dns server for example.com fails for whatever reason. This method will allow the user to still connect. Otherwise, if the 3rd party dns server fails for example.com (which frequently happens with cheap, free dns services), users will be unable to connect and blame you. ## Troubleshooting If your user is getting disconnected, these are the most likely causes: # mismatch of ports or SSL (using plaintext on 6697 or SSL on 6667) # SSL is not supported # user has a server password where none belongs (most likely he confused server password with nickserv password) # ident is not working # ircd bans a certain username or ident for no good reason (the ircd mistakenly assumes your connection is a bot and glines it) # typo of server name or IP address # dns lookup error You may be need to install icu4c-68.2v0. ### IPv4/IPv6 mismatch If a znc user has a bindhost that is IPv6 only but the network is IPv4 only, or vice versa, it will not connect. To prevent this, you **must** use a symbolic hostname (such as username.example.com) for the bindhost. Each hostname needs a single [A record](dns/records) and a single [AAAA record](/dns/records) in the [DNS zone](/nsd/zone). If any part is misconfigured, users will be unable to connect. To prevent this, you **must** use a symbolic hostname (such as username.example.com) for the bindhost. Each hostname needs a single [A record](dns/records) and a single [AAAA record](/dns/records) in the [DNS zone](/nsd/zone). If any part is misconfigured, users will be unable to connect. To check if any bindhosts are incorrectly using fixed IPv6 or IPv4 addresses, run: # sed -nE '/.*(\ ~/bindhost $ vi ~/bindhost Then with vi: :%25s_.* = _host _g Then: $ sh ~/bindhost If you see any records there with only a single IPv4 address but no IPv6, or a single IPv6 but no IPv4, or any NXDOMAIN responses, you need to fix your DNS records. There should be exactly one shared IPv4 and one unique IPv6 for each hostname, and zero NXDOMAIN responses. ### Missing libraries If you are get errors such as: ld.so: znc: can't load library 'libc++abi.so.5.0' Then you may be on the wrong OpenBSD version (6.9 or earlier); or you did not apply [syspatch](/openbsd/syspatch); or you did not upgrade all dependencies: $ doas syspatch $ doas pkg_add -Uu Delete the build folder and compile again.