ERGO IRC GUIDE This is a guide to IRC, known in full as the Internet Relay Chat. IRC predates the World Wide Web and has been around since 1988, making it one of the oldest chat protocols still in use today. For this guide I am exploring the Ergo IRC server (also called an IRC daemon or IRCd), for the Dell-shaped prison I call Windows 11. This page serves as my personal guide for all things IRC, as well as for any of you who want to join me. CONTENTS Part 1: Setting the Scene Part 2: Establishing the Server Part 3: Testing the Server Part 4: Going Online Part 5: Managing your Server PART 1: SETTING THE SCENE Step 1: Downloading your Daemon 1. Go to: https://github.com/ergochat/ergo/releases/latest Under "Assets", download the Windows build. It will be named something like: ergo-2.17.0-windows-x86_64.zip 2. Extract the ZIP into your folder of choice. 3. Ergo ships with a default config called default.yaml. A YAML file is an easy-to-read configuration format used in various programs. You need to copy this YAML file and name it ircd.yaml. Leave the default.yaml alone, it is there as a guide in case you get stuck with the formatting. YAML files can be quite picky; even one mis-spacing is enough to throw things off. 4. Enter Windows Powershell to generate your TLS certificates. Your server needs valid certificates to run, but especially if you want to make it go online. Ergo lets you generate self-signed certificates (but from here we will call them certs), which you will need to do in the terminal. 5. Type this exact code into the terminal: ./ergo.exe mkcerts You should now see privkey and fullchain pop up in your Ergo folder. These are PEM files, and your main two certs. You cannot have one without the other, they must be together. You have now created the bare bones of an IRC server. The certs you just generated will be used by the TLS listeners on ports 6667 and 6697. 6667 serves plaintext, which is usable but not recommended for private communications. For an encrypted chat, you will want to use 6697. Now you can proceed to Part 2 to create the rest of your server. If you try to connect anything to anything right now, you will not get a peep. PART 2: ESTABLISHING THE SERVER Step 1: Creating an Operator Account 1. Open PowerShell in your Ergo folder and run: ./ergo.exe genpasswd 2. It will ask you to create a password, which it will then ask you to confirm. Both entries must match, though this is complicated by the fact that terminals do not show passwords. Make sure it is strong, but not too much of a pain to type. 3. Once you have confirmed your password, you will be given a long hash starting with $2a$. Hold onto this hash and treat it like you would any other password. 4. Open your ircd.yaml file in your plaintext editor of choice, preferably Notepad. 5. Using your program's find-tools, look for the opers block of the file. The oper is named "admin" by default, and you should find a line with the words: password: "PASTE_YOUR_HASH_HERE" 6. Replace PASTE_YOUR_HASH_HERE with the hash you just generated, keeping the quotes. You now have a password for your IRC server. You can change it any time by repeating the process above. Step 2: Changing the Listeners 1. Using the find-tool in your program, find the listeners section. In it you should find these two lines around line 43: "127.0.0.1:6667": "[::1]:6667": 2. Comment out those two lines by putting a hashtag in front of them. This symbol turns a line into a comment which will not execute as code anymore. Make sure the spacing lines up evenly. Doing this disables the localhost-only listeners so the LAN-wide listener can accept connections from other machines on your network. 3. Check that it looks exactly like this. The third line (":6667":) should already exist in the default config, you are just making sure the two lines above it are commented out: # "127.0.0.1:6667": # "[::1]:6667": ":6667": Troubleshooting: if Ergo starts but you can only connect from the same machine, double-check the spacing in this section. YAML is whitespace sensitive and if your commented lines have different indentation than the surrounding lines, the parser may choke silently. Step 3: Changing the Firewalls 1. Open PowerShell as Administrator, otherwise it will not let you do this step in particular. 2. Copy-paste these commands into the terminal: New-NetFirewallRule -DisplayName "IRC 6667" -Direction Inbound -Protocol TCP -LocalPort 6667 -Action Allow -Profile Any -Enabled True New-NetFirewallRule -DisplayName "IRC 6697" -Direction Inbound -Protocol TCP -LocalPort 6697 -Action Allow -Profile Any -Enabled True 3. Set your Wi-Fi network to Private by running: Set-NetConnectionProfile -InterfaceAlias "Wi-Fi" -NetworkCategory Private This part is important: if Windows thinks you are on a Public network, it will block incoming connections, even with these firewall rules in place. 4. If you want to check your network's firewall profile, run: Get-NetConnectionProfile Troubleshooting: if the firewall commands fail, make sure you opened PowerShell as Administrator (right-click, Run as Administrator). If the network profile command errors out, your adapter name may differ. Run Get-NetAdapter to see the exact name and substitute it for "Wi-Fi". Your home network should now know your server exists. If you are running a chatroom with family or roommates, you can theoretically stop here. Though you still have to test it, and you will likely want to make it go online too. PART 3: TESTING THE SERVER To use an IRC server, you need a client. This guide will be using HexChat, a free and widely-used IRC client for Windows. Note that HexChat is no longer actively maintained, but it is perfectly safe and has plenty of forks. If you would rather use a different client, the general steps are roughly the same. Step 1: Installing HexChat 1. Download HexChat from https://hexchat.github.io and run the installer. The defaults are fine. 2. On every launch, HexChat will show a Network List. Here you will be adding your own. Fill in a nickname at the top, then click Add to create a new network entry. Name it whatever you like, e.g. My IRC Server. 3. Click Edit on your new network. 4. Under the Servers tab, remove the placeholder entry and add your server address. Since you are only connecting locally for now, use your machine's local IP followed by the port 6697. If you do not know what your IP address is, run ipconfig in PowerShell and look for the IPv4 Address in the Wi-Fi section. 5. While you are in the client's Edit window, tick "Use SSL for all the servers on this network" if you are using port 6697. Since you are using a self-signed cert for now, also tick "Accept invalid SSL certificates". You can untick this once you have a real cert from WinACME later. 6. Click Close to exit the Edit window. Step 2: Entering your Server 1. If your server is not running, open the terminal from your Ergo folder and run it with: ./ergo.exe run If your server is not running from a terminal, it will not let you enter. 2. You should see lines like the following appear. Keep this window open, closing it stops the server. now listening on :6667, tls=false ... now listening on :6697, tls=true ... Server running 3. In a second PowerShell window, run: netstat -an | findstr 6667 4. You should see 0.0.0.0:6667, which means it is reachable from other computers. If you only see 127.0.0.1:6667, the YAML change did not take effect. Check Step 2 of Part 2 again. Troubleshooting: if you see nothing at all, Ergo likely did not start properly. Switch back to the Ergo PowerShell window and look for error messages. The most common cause is a YAML formatting mistake (wrong indentation, tabs instead of spaces). Step 3: Connecting with HexChat 1. With Ergo running, go back to HexChat and click Connect. You will be met with Ergo's default Message-Of-The-Day and the chat interface itself. 2. If you are curious, feel free to try out some commands. Type /join #general (or any channel name you like) in the text box and press Enter. If the channel does not exist yet, Ergo will create it on the spot. 3. You can join multiple channels at once, just repeat the /join command. Each channel will open as a new tab in HexChat, just like a web browser. Your server is now working on a basic LAN connection. Anyone on your local network can connect the same way you just did. If you are only using IRC for immediate friends, family or roommates, you can theoretically stop here. However, you will not be able to connect your server to any web-based clients, which we will be going over in Part 4. PART 4: GETTING YOUR SERVER ONLINE To get your server online, you will need a stable domain, two authentic TLS certs, several opened ports in your router and a slight addition to your YAML file. While there are a lot of moving pieces, it means you own your server fully, without relying on third party services such as VPS providers. You may not be able to proceed with the free method if: 1. Your ISP does not support inbound connections. Some ISPs use CGNAT (Carrier-Grade NAT), which means multiple households share one public IP. This renders port-forwarding impossible. 2. Your ISP blocks port 80, which you will need for generating your HTTPS certs. Assuming you have not had either of these issues, you can proceed onto the rest of this section without any problems. Step 1: Setting up No-IP Dynamic DNS This gives your server a stable hostname (e.g. yourserver.ddns.net) regardless of the changes your home IP address might experience. WinACME needs this hostname to issue a real TLS certificate, and your web client uses it to connect. 1. Go to https://www.noip.com and sign up for a free account. Once you are logged in, go to Dynamic DNS, then No-IP Hostnames, and create a new hostname such as yourserver.ddns.net. Write this down and treat it like you would any other password. 2. Download the No-IP DUC (Dynamic Update Client) from https://www.noip.com/download?page=win This is a small background app that watches your public IP address and automatically updates No-IP whenever it changes. Without it, your hostname will point to the wrong IP after a router restart. 3. Install the DUC, log in with your No-IP account credentials, and make sure your hostname is ticked. Set it to run on startup so it is always active in the background. 4. Once the DUC is running, verify everything is working by looking up your hostname at https://www.nslookup.io The A record should match your current public IP, which you can check at https://www.whatismyip.com Note: No-IP's free tier requires you to confirm your hostname every 30 days, or they will delete it. Keep an eye on your inbox for their reminder emails. Step 2: Generating Certificates with WinACME Self-signed certs (from mkcerts) work for HexChat on your LAN, but browsers will outright refuse a WebSocket connection to a self-signed cert. To use Kiwi IRC from the internet you need a real, trusted certificate. This is where WinACME comes in. It gets you a free Let's Encrypt certificate to go with your No-IP hostname. Before you start: make sure Ergo is not running, port 80 is forwarded on your router and opened in your firewall. Opening port 80 is a temporary measure, as WinACME needs to answer a challenge on this port to prove you control the domain. 1. Download WinACME from https://www.win-acme.com Extract the ZIP somewhere convenient, e.g. C:\Users\YourName\Downloads\win-acme\ 2. Open PowerShell as Administrator in the WinACME folder and run: ./wacs.exe You will be walked through an interactive menu. Here is what to pick at each step: Choose "Create certificate (full options)", not the simple IIS option. For source, pick "Manual input" and enter your No-IP hostname, e.g. yourserver.ddns.net For validation, pick "Self-hosted (HTTP-01)". WinACME will spin up a tiny temporary HTTP server on port 80 so Let's Encrypt can confirm you control the hostname. Leave the private key type as the default (RSA). For storage, pick "PEM encoded files". This gives you separate .pem files that Ergo can read. Choose a folder to save them to, e.g. C:\Users\YourName\Downloads\Ergo\certs\ Accept the defaults for any remaining prompts and proceed. 3. If everything has executed correctly, WinACME will save PEM files to your chosen folder. The exact filenames depend on your WinACME version, but you will find a certificate chain file and a private key file. Look for files ending in -chain.pem and -key.pem. 4. Open ircd.yaml and update the cert paths in two places, the 6697 TLS listener and the 8097 WebSocket listener. Make sure both point to the same folder: ":6697": tls: cert: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-chain.pem key: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-key.pem ":8097": tls: cert: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-chain.pem key: C:\Users\YourName\Downloads\Ergo\certs\yourserver.ddns.net-key.pem websocket: true 5. Start Ergo again with ./ergo.exe run The TLS warning in HexChat should now be gone on port 6697, and Kiwi IRC will be able to connect on port 8097. Note on renewal: Let's Encrypt certs expire after 90 days. WinACME installs a scheduled task to auto-renew them, so you should not need to do anything. If renewal fails (e.g. port 80 is not forwarded), WinACME will send a reminder email to the address you registered with. Step 3: Port Forwarding on your Router For anyone outside your home network to reach your server, your router needs to forward the right ports to your machine. 1. Find your router's admin page. Usually this involves entering a specific IP address, though this may vary between ISPs. 2. Log in with your router's admin credentials. These should be visible on the back of the router alongside your Wi-Fi password. 3. Find your PC's local IP by running ipconfig on the laptop and looking for the IPv4 Address in the Wi-Fi section, something like 192.168.1.161. It is worth assigning this as a static IP in your router's DHCP settings (look for "DHCP reservation" or "static lease") so it never changes and breaks your forwarding rules. 4. In your router's port forwarding section (often under Advanced, Port Forwarding, or NAT, Virtual Servers), add the following rules pointing to your laptop's local IP: TCP 6667 to 6667 Plain IRC TCP 6697 to 6697 TLS IRC (HexChat with SSL) TCP 8097 to 8097 WSS WebSocket (Kiwi IRC) TCP 80 to 80 HTTP (WinACME certificate verification only) 5. Save the rules. You can test that a port is reachable from outside using https://www.yougetsignal.com/tools/open-ports/ Enter your No-IP hostname and port number to confirm it is open. Note: port 80 only needs to be forwarded while running WinACME to issue or renew your certificate. You can remove it afterwards if you prefer. Step 4: Connecting from Kiwi IRC Kiwi IRC is a browser-based IRC client, no installation needed. It connects to your server over WebSocket Secure (WSS) on port 8097, which is why the real TLS cert from WinACME was necessary. 1. On any device, open a browser and go to: https://kiwiirc.com/nextclient/ 2. Fill in the connection screen as follows: Server address: yourserver.ddns.net Port: 8097 SSL/TLS: ON Channel: #general Nick: YourName 3. Hit Connect. You should see the server welcome message and land in your channel. This works from any network, your phone on mobile data, a friend's house, anywhere, as long as Ergo is running at home. Troubleshooting your online connection: "Unable to connect": Check that Ergo is running and port 8097 is forwarded on your router. "Certificate error": The WinACME cert may have expired or the paths in ircd.yaml are wrong. Check the cert files still exist and run /rehash in your IRC client. "Connection closed immediately": SSL must be ON for port 8097. Make sure it is ticked. Congratulations, you have just set up an IRC server. Invite your friends, or drag them kicking and screaming. If your company is hesitant to make the switch, try Kiwi or The Lounge for a modernised IRC experience. IRC is a protocol, there is no one way to run or use it, so it is more about finding what works best for your needs.