Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Install and configure znc on a raspberry pi

Installing And Configuring ZNC On A Raspberry Pi


  • Using a PC or mac, download raspberry pi os lite from
  • Unpack the .zip file and flash the .img file to the micro sd card using a card reader&writer with a program called Etcher.
  • Disconnect and reconnect the micro sd card and in the /boot volume create an empty file: save this file as ssh. Doing this will enable and start the ssh daemon on the raspberry pi.
  • Insert the micro sd card into the raspberry pi. Connect the ethernet cable to the pi and your router, power it up.
  • (Optional) Connect a HDMI cable to your pi and a monitor, so you may see the assigned IP address.
  • Find out the IP address and ssh into your raspberrypi with username pi and password raspberry. On a mac, simply open terminal and ssh pi@raspberrypi.local or ssh pi@<ipaddress>. Windows, download and use Putty.
  • Assign a DHCP reservation to this IP address.

First Things First

  • After logging in with ssh, use the command: sudo raspi-config to expand the filesystem, set amount of display memory from 64MB to 16MB, set your timezone and set a new password for the pi user. You may want to set a new hostname too, if you have more than one raspberry pi. Exit the program and you will be asked to reboot: Yes. (or manually: sudo reboot)
  • Pull latest updates and install: sudo apt-get update && sudo apt-get upgrade

Installing ZNC

  • Install znc (and make sure nano is installed): sudo apt-get install znc znc-dev nano
  • Setup the znc user account: sudo useradd --create-home -d /var/lib/znc --system --shell /sbin/nologin --comment "Account to run ZNC daemon" --user-group znc
  • Create the znc .conf file: sudo -u znc /usr/bin/znc --datadir=/var/lib/znc --makeconf
  • You will have to answer some questions: For Listen on port: I choose 1337. Listen on SSL: Yes. Important are your admin account username + password as well as your IRC nickname and IRC alt nickname (alt nickname = nickname postfixed with an underscore). Ident, real name and Bind host, just leave blank (just hit <Enter>). When asked to setup a network, choose No. Finally, when asked to launch now, choose No.

The ZNC service file

  • Open the file for writing: sudo nano /etc/systemd/system/znc.service
  • Paste the following, then hit Ctrl-X to exit (hit Y to save):
    Description=ZNC, an advanced IRC bouncer
    ExecStart=/usr/bin/znc -f --datadir=/var/lib/znc

Fire Up ZNC

  • Enable the service (this will start the service on boot): sudo systemctl enable znc
  • Start the service: sudo systemctl start znc

Optional DDNS and Letsencrypt Certificate

Dynamic DNS Setup with DUCKDNS.ORG

  • Go to DUCKDNS, login with your <Persona|Twitter|Github|Reddit|Google> account.
  • Create a domain, for example: znc-acvxqs It will be added to your account.
  • Up in the top menu, select Install and under Operating systems choose pi, then select the domain you created. Follow the steps as outlined.

Letsencrypt Certificate

  • Make dir ~/certbot: mkdir ~/certbot

  • Open ~/certbot/ for writing: nano ~/certbot/

  • Paste the following, replace "foo" with "your_token", then hit Ctrl-X and select Y:

    [[ "$(curl -s "${}&token=${DUCKDNS_TOKEN}&txt=${CERTBOT_VALIDATION}")" = "OK" ]] 
  • Open ~/certbot/ for writing: nano ~/certbot/

  • Paste the following, replace "foo" with "your_token", then hit Ctrl-X and select Y:

    [[ "$(curl -s "${}&token=${DUCKDNS_TOKEN}&txt=${CERTBOT_VALIDATION}&clear=true")" = "OK" ]] 
  • Make executable: chmod +x ~/certbot/ ~/certbot/

  • Install certbot: sudo apt-get install certbot

  • Obtain certificate: sudo certbot certonly --manual --preferred-challenges dns --manual-auth-hook ~/certbot/ --manual-cleanup-hook ~/certbot/

  • Answer questions:

    • Enter your email address ->
    • Agree to the Terms of Service -> A
    • Share your email address with EFF -> N
    • Enter your domain name(s) -> (obviously yours is ~ <your_name>
    • OK with IP being logged -> Y
  • Open file for writing: sudo nano /etc/letsencrypt/renewal-hooks/deploy/

  • Paste the following, replace znc-acvxqs with your_name, then hit Ctrl-X and select Y:

    [[ $RENEWED_LINEAGE != "/etc/letsencrypt/live/$YOURDOMAIN" ]] && exit 0
    echo "Updating certs"
    cat /etc/letsencrypt/live/$YOURDOMAIN/{privkey,fullchain}.pem > /var/lib/znc/znc.pem
  • Make executable: sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/

  • Elevate to root: sudo su

  • Run the following command, where znc-acvxqs is replaced by yourname: cat /etc/letsencrypt/live/{privkey,fullchain}.pem > /var/lib/znc/znc.pem

  • Exit to normal pi user: exit

Port Forward

You will have to configure port forwarding on your router to expose port 1337 on the raspberrypi.local device. For example if you configure public port 1337 to direct to its ip address and port 1337 on your LAN, you will now be able to access it from wherever you are:


Because your znc webinterface is now open to the internet (, it is a good idea to enable fail2ban in Global Settings with parameters 30 2 (Bantime and number of failed logins before action is taken).

Multiple devices

If you wish to connect with multiple devices to your znc configured networks, you'll want to install/enable route_replies and CyberShadow's clientbuffer. More information here. You may also want to read Jay2k1's article on multiple clients here.

Copy link

mhenry commented Nov 2, 2021

Note, if you're installing modules yourself they need to be located at /var/lib/znc/modules and NOT at /home/pi/.znc/modules or ~/.znc/modules.

Copy link

acvxqs commented Nov 3, 2021

Note, if you're installing modules yourself they need to be located at /var/lib/znc/modules and NOT at /home/pi/.znc/modules or ~.znc/modules.

That is correct and an oversight in the guide on my part. Glad you sorted it out :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment