Skip to content

Instantly share code, notes, and snippets.

@Daeraxa

Daeraxa/znc-halloy.md

Last active July 8, 2023 14:57
Show Gist options
  • Save Daeraxa/3355fdb5a5c418f3ca9691e6f8fd1a0c to your computer and use it in GitHub Desktop.
Save Daeraxa/3355fdb5a5c418f3ca9691e6f8fd1a0c to your computer and use it in GitHub Desktop.
Download ZIP
ZNC & Halloy setup
Raw
znc-halloy.md

Setting up a ZNC server and configuring Halloy to use it

What is ZNC? The official wording is probably best placed to describe it "ZNC, an advanced IRC bouncer that is left connected so an IRC client can disconnect/reconnect without losing the chat session."

Basically IRC only delivers messages whilst you are connected. ZNC is something you have running on an always on server (for example a home server or even a Raspberry Pi), that keeps you connected to the IRC server and allows you to connect in at will so you don't miss out on any of the conversation.

I used a couple of resources to get this working which are listed at the bottom of this guide but I've tried to take the best parts of each one as well as add any Halloy specific parts that are required.

Installing ZNC

The official installation instructions detail exactly how to install it. ZNC is available in most major Linux distro's package managers. It is also available on macOS via brew and Windows via cygwin or WSL. This guide will only be covering how to set it up on Linux.

This is also only covers self-signed certificates (which require an additional option on Halloy) so if you want to have certificates signed by Let's Encrypt for example then following this guide has information on it.

Debian/Ubuntu

apt install znc

Fedora/RHEL

dnf install znc

# or 

yum install znc

Setting up ZNC

Once ZNC has been installed run

znc --makeconf

To start the configuration tool. You can select your own responses where needed but below is an example configuration:

Listen on port (1025 to 65534): 6698
Listen using SSL: yes
Listen using both IPv4 and IPv6: yes
Username (alphanumeric): <enter username here>
Enter password: ****************
Confirm password: ****************
Nick [username]: you can press return here to accept default
Alternate nic [username_]: you can press return here to accept default
Ident [username]: you can press return here to accept default
Set up a network?: no
Launch ZNC now?: no

Next we want to make ZNC run as a service and let the OS handle it for us.

Create a blank znc.service file in /etc/systemd/system/ and open it with the text editor of your choice. (You will likely need superuser privileges here):

touch /etc/systemd/system/znc.service

vim /etc/systemd/system/znc.service

Insert the following into the file, remembering to exchange <YOUR_USER> for your own username:

[Unit]
Description=ZNC - IRC Bouncer
Requires=nss-user-lookup.target
After=network-online.target nss-user-lookup.target

[Service]
User=<YOUR_USER>
ExecStart=/usr/bin/znc --foreground
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
KillSignal=SIGINT
SuccessExitStatus=2

[Install]
WantedBy=multi-user.target

Now lets start the service and check its status:

systemctl daemon-reload
systemctl enable znc
systemctl start znc
systemctl status znc

That should now be it for your basic configuration, now we can configure ZNC itself.

Configuring ZNC

At this point your server should now be up and running at your IP address and the port you set. You should be able to access this via your web browser (ignore any security errors claiming it is "unsafe").

e.g. http://192.168.0.1:6698

This should open your ZNC web interface where you can now log in at the top with the username and password you configured earlier.

webadmin > Global Settings

This is the basic setup page and generally don't change anything here unless you know what you are doing. This is where you can enable or disable various modules as well as changing or adding a port if needed. For the purpose of this guide we can leave this page alone.

webadmin > Your Settings

This is the main page we are interested in.

The bit we really need to configure is in Networks.

Networks

  • Click Add, it will take you to a new page.

  • Enter your nickname etc. for the server you are interested in (in this case we are going to be using libera.chat).

In the section Servers of this IRC network, click Add. Here we can add the details of the server we want to join.

  • Click Add and enter the following details:
    • Hostname: irc.libera.chat
    • Port: 6697

Now we can add our channels we want to join automatically.

Channels

  • Click Add, it will take you to a new page and you can add the following details:

  • Channel Name: #halloy (or whatever channel you want)

  • Buffer Size: 300 (you can set this to what you want, this is the maximum number of lines that will "play back" when you rejoin the server from Halloy).

  • Click "Save and return"

Now we have finished our channel and network setup we can hit "Save and return" at the very bottom of the page to save these settings.

At this point we should be good to go to connect Halloy!

Configuring Halloy

  • Open up your config file:
    • Linux: $HOME/.config/halloy/themes
    • macOS: $HOME/Library/Application Support/halloy/themes
    • Windows: {FOLDERID_RoamingAppData}\halloy\themes

The area we want to focus on is in servers.

  • Make sure you nickname is set
  • Add a new line password: <YOUR_PASSWORD>
  • Change server to your ZNC IP address
  • Change port to your ZNC port
  • Add a new line dangerously_accept_invalid_certs: true (this will not be required if you set up proper signed certificates).

It should now look something like this:

servers:
  # Configuration for Libera server
  liberachat:
    # Nickname to be used on the server
    nickname: myNick
    
    password: hunter2
    
    # Server address
    server: 192.168.0.1
    
    # Server port number
    port: 6698
    
    # Whether to use TLS
    use_tls: true
    
    dangerously_accept_invalid_certs: true
    
    # Channels to join upon connecting to the server
    channels:
      - "#halloy"

Now if everything was done correctly you should be able to start Halloy and it will connect to your ZNC and it will look and feel just like you had connected to the main server.

At this point you should be able to do everything you need to do.

Resources

Not covered

  • Signed certificates via Let's Encrypt etc.
  • Any additional config needed for logging into registered accounts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment