# Install ZNC from Source ## Overview [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 to keep you online. ## 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. For [tar](/tar/usage), the options xvzf stand for e(x)tract, (v)erbose, un(z)ip, and (f)ile. $ tar xvzf znc-1.8.2b.tar.gz ### Building ZNC Next, we build ZNC: $ cd znc-1.8.2 $ mkdir build $ cd build We then use cmake to configure the files to install to ~/.local, then make and make install: $ cmake .. -DCMAKE_INSTALL_PREFIX="$HOME/.local" $ make $ make install You should see this message: ZNC was successfully installed. You can use '/home/username/.local/bin/znc --makeconf' to generate a config file. If you need help with using ZNC, please visit our wiki at: http://znc.in ## Creating znc.conf Follow the instructions to generate the config file: $ ~/.local/bin/znc --makeconf [ .. ] Checking for list of available modules... [ ** ] [ ** ] -- Global settings -- [ ** ] [ ?? ] Listen on port (1025 to 65534): If you are on a shell account, you must use the [ports](/tcpip/ports) that were reserved for your username. **WARNING:** Shell accounts users must **not** randomly choose ports. Shell accounts servers often have firewalls in place that will block ports not reserved to you. If you are unable to connect to ZNC, double check to see if the firewall is blocking the connection. [ ?? ] Listen using SSL (yes/no) [no]: yes [ ?? ] Listen using both IPv4 and IPv6 (yes/no) [yes]: no [SSL](/tls/overview) helps to encrypt messages sent between client and server. In other words, if you turn it on, messages sent from your IRC program to ZNC are kept secure. It's more trouble to set up, and some older IRC programs don't support it, so some users prefer to turn off SSL. **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 for both IPv4 and IPv6. [IPv4](IPv4/overview) is the default networking protocol. [IPv6](/IPv6/overview) is becoming more popular now, especially for mobile devices. [IPv4](IPv4/overview) is the default networking protocol. [IPv6](/IPv6/overview) is becoming more popular now, especially for mobile devices. [ .. ] Verifying the listener... [ ** ] Unable to locate pem file: [/home/username/.znc/znc.pem], creating it [ .. ] Writing Pem file [/home/username/.znc/znc.pem]... [ ** ] Enabled global modules [webadmin] 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. If you'd like a properly signed SSL certificate, ask your sysadmin or request one yourself using [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): username ### Bindhosts Next, you'll be asked to specify an optional bindhost. The bindhost will give you a nice-looking vhost, like `username@username.example.com`. **WARNING**: You cannot pick any arbitrary [bindhost](/dns/vhost) that you want. If your bindhost does not work, your vhost will not show up properly, and you may not be able to connect at all! A vhost must have proper [forward](dns/overview) and [reverse DNS](/DNS/rDNS) [records](/dns/records) to work. If you're using an IRCNow shell account, you should have been provided with one at registration. You can also ask your sysadmin to change it for you, or leave it blank. A vhost must have proper [forward](dns/overview) and [reverse DNS](/DNS/rDNS) [records](/dns/records) to work. If you're using an IRCNow shell account, you should have been provided with one at registration. You can also ask your sysadmin to change it for you, or leave it blank. To test if your bindhost works properly, check the [host](/host/usage) guide. You will want to run host on your bindhost: $ host username.example.com username.example.com has address 192.168.1.1 username.example.com has IPv6 address 2001:bd8:: Your bindhost should show both an IPv4 and IPv6 address. If it's missing an IPv4 address, it can **only** connect by IPv6 to an IRC network. If it's missing an IPv6 address, then it can **only** connect by IPv4 to an IRC network. If it's missing both, it **cannot** connect to **any** network. For this reason, you don't want to put an IPv6 address directly into the bindhost. This prevents ZNC from being able to connect to an IPv4 only network. Instead, you want to use a hostname that has both [A and AAAA records](dns/records) defined in [DNS](/dns/overview). For this reason, you don't want to put an IPv6 address directly into the bindhost. This prevents ZNC from being able to connect to an IPv4 only network. Instead, you want to use a hostname that has both [A and AAAA records](dns/records) defined in [DNS](/dns/overview). [ ?? ] Bind host (optional): username.example.com ### User Modules You'll want to enable all the user modules: [ ** ] Enabled user modules [chansaver, controlpanel] [ ** ] ### Set Up a Network You can optionally set up a network at this stage: [ ?? ] Set up a network? (yes/no) [yes]: yes [ ** ] [ ** ] -- Network settings -- [ ** ] [ ?? ] Name [freenode]: ircnow [ ?? ] Server host (host only): irc6.ircnow.org [ ?? ] Server uses SSL? (yes/no) [no]: yes [ ?? ] Server port (1 to 65535) [6697]: [ ?? ] Server password (probably empty): [ ?? ] Initial channels: #ircnow [ ** ] Enabled network modules [simple_away] [ ** ] [ .. ] Writing config [/home/username/.znc/configs/znc.conf]... This will cause ZNC to automatically connect to your favorite network (IRCNow). Next, it's better **not** to launch ZNC. There are still some settings you will want to add and configure: [ ** ] 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 +12345 username: [ ** ] [ ** ] To manage settings, users and networks, point your web browser to [ ** ] https://:12345/ [ ** ] [ ?? ] Launch ZNC now? (yes/no) [yes]: no ### Stop ZNC If you accidentally launch ZNC, you will see: [ .. ] Opening config [/home/username/.znc/configs/znc.conf]... [ .. ] Loading global module [webadmin]... [ .. ] Binding to port [+12345]... [ ** ] Loading user [username] [ ** ] Loading network [ircnow] [ .. ] Loading network module [simple_away]... [ >> ] [/home/username/.local/lib/znc/simple_away.so] [ .. ] Adding 1 servers... [ .. ] Loading user module [chansaver]... [ .. ] Loading user module [controlpanel]... [ .. ] Forking into the background... [ >> ] [pid: 86542] [ ** ] ZNC 1.8.2 - https://znc.in To stop ZNC once it is launched, you can [kill](/kill/usage) it: $ kill -TERM You will want to replace with the [process ID](/ps/usage) you see above (86542): $ kill -TERM 86542 This will send a (TERM)ination signal to ZNC so that it dies. **NOTE**: You will need to replace 8542 with your process ID. If you don't know the process ID, you can type: $ ps -U | grep znc Replace with your username. ## Recreate znc.conf If at any time you mess up the configuration, you can delete your znc.conf and rerun the makeconf command again: $ rm ~/.znc/configs/znc.conf $ ~/.local/bin/znc --makeconf ## Configuration Here are some recommended changes to make to the default znc.conf so that it works nicely. Replace the top portion of znc.conf with these settings: AnonIPLimit = 10000 AuthOnlyViaModule = false ConfigWriteDelay = 60 ConnectDelay = 1 HideVersion = false MaxBufferSize = 10000 ProtectWebSessions = true ServerThrottle = 1 Version = 1.8.2 **WARNING**: Do not duplicate listeners or settings, or else ZNC will fail. For a full explanation of these settings, please consult the [ZNC wiki](/https://wiki.znc.in/Configuration). Next, we load the following modules: LoadModule = chansaver LoadModule = adminlog LoadModule = certauth PidFile = /home/znc/.znc/znc.pid If you want to store logs on the shell account, you can add this line: LoadModule = log **NOTE**: sysadmins can read logs stored on the server. Also, in the event of a security breach, an attacker can also read these logs. ### SSL certs (Optional) If you want properly validating SSL certs, you can add these lines to set the paths for the SSL files: SSLCertFile = /home/znc/.znc/username.example.com.crt SSLKeyFile = /home/znc/.znc/username.example.com.key SSLDHParamFile = /home/znc/.znc/dhparam.pem **NOTE**: For the SSL certs, you will need to ask the admin. You will need to replace username.example.com with the unique hostname that your admin provides. **WARNING: If you did not yet generate your own SSL certs, don't add these lines! ### Listeners Next, you'll want to create listeners. Each listener specifies a unique combination of IP address and port ([a TCP socket](/tcpip/sockets)): 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 = / `Host = 192.168.1.1` and `Port = 1337` tells ZNC to [listen](/tcpip/sockets) on that IP address. You **must** replace 192.168.1.1 and 2001:db8:: with your real IP addresses and you **must** replace 1337 and 31337 with the ports you were given during account registration. **WARNING**: If you don't use the correct IP address and port, ZNC may refuse to launch, or you may be unable to connect. You can find your IP addresses by running host on your unique hostname: $ host username.example.com username.example.com has address 198.51.100.1 username.example.com has IPv6 address fe80:c001:d00d:: **WARNING**: You must replace 192.168.1.1 and 2001:db8:: with your real IP address, or znc will fail to launch. ## Run ZNC To start ZNC right away: $ ~/.local/bin/znc >> ~/.znc/znc.log 2>&1 & This will store all znc log messages to ~/.znc/znc.log. If ZNC fails to start or crashes, you can consult this file for the full error log. ## Connecting to ZNC From here, you will want to consult the [ZNC client guides](/bouncer/bouncer) to see how to connect to ZNC. ## Creating a cronjob You will want to create a [cronjob](/crontab/edit) which will restart znc every 5 minutes in case it ever crashes. Then, type: $ crontab -e */5 * * * * ~/.local/bin/znc >> ~/.znc/znc.log 2>&1 & **NOTE:** znc checks its own pid to see if it is running and quits if it is. Keep in mind this in mind when using cron to restart processes like this. ## Troubleshooting If you run into errors, check the error log in ~/.znc/znc.log, or turn on debugging: ~/.local/bin/znc -D ## Changing Password If you forget the password set during --makeconf, you can generate a new one: $ 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. This gives the password block needed to use in your [/home/znc/home/znc/.znc/configs/znc.conf](/https://wiki.znc.in/Configuration) file. Follow the instructions above: kill ZNC, edit your znc.conf to use the new password block, then restart znc. 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 ## Copying SSL certs (optional) If you want to have properly validating SSL certs, your sysadmin can provide them for you in your ~/ssl/ folder. We will need to create a symbolic link for them to your znc folder: $ ln -s ~/ssl/username.example.com.crt ~/.znc/username.example.com.crt $ ln -s ~/ssl/username.example.com.key ~/.znc/username.example.com.key You must replace username.example.com with your actual hostname. Afterwards, we can create a dhparam file: $ openssl dhparam -out ~/.znc/dhparam.pem 2048