nixos-dotfiles

nixos-dotfiles

https://git.tonybtw.com/nixos-dotfiles.git git://git.tonybtw.com/nixos-dotfiles.git
nixos-dotfiles / future-modules / IRC-SERVER-SETUP.md
7,817 bytes raw

IRC Server Setup & Connection Guide

Server Setup

1. Configure Your Server

Edit irc-public.nix and update these important fields:

Name = irc.yourdomain.com          # Your actual domain
AdminInfo1 = Your Name             # Your name
AdminInfo2 = Your Community Server # Server description
AdminEMail = admin@yourdomain.com  # Your email
CloakHostSalt = your-random-salt-here  # Generate random string

Generate a random salt for host cloaking:

openssl rand -hex 32

2. Set Up Operator Password

Generate a secure password hash:

# Generate password hash
htpasswd -nBC 10 "" | cut -d: -f2

Update the [Operator] section with the hash:

[Operator]
Name = admin
Password = $2y$10$your-generated-hash-here
Mask = *!*@yourdomain.com  # Restrict to your domain

3. Enable in Your NixOS Configuration

Add to your flake.nix modules:

modules = [
  ./configuration.nix
  ./irc-public.nix  # Add this line
  # ... other modules
];

4. Set Up DNS

Point your domain to your server's IP:

A     irc.yourdomain.com    -> YOUR_SERVER_IP
AAAA  irc.yourdomain.com    -> YOUR_SERVER_IPv6 (optional)

5. (Optional) Enable SSL/TLS

For encrypted connections, uncomment the SSL section in irc-public.nix and generate certificates:

Option A: Let's Encrypt (Recommended)

# Uncomment in irc-public.nix:
security.acme = {
  acceptTerms = true;
  defaults.email = "admin@yourdomain.com";
  certs."irc.yourdomain.com" = {
    group = "ngircd";
    postRun = "systemctl reload ngircd.service";
  };
};

Option B: Self-Signed Certificates

sudo mkdir -p /etc/ngircd/ssl
cd /etc/ngircd/ssl

# Generate DH parameters
openssl dhparam -out dhparams.pem 2048

# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout server-key.pem \
  -out server-cert.pem -days 365 -nodes \
  -subj "/CN=irc.yourdomain.com"

sudo chown ngircd:ngircd /etc/ngircd/ssl/*
sudo chmod 600 /etc/ngircd/ssl/server-key.pem

6. Deploy

sudo nixos-rebuild switch --flake /home/tony/nixos-dotfiles#nixos-btw

7. Verify Server is Running

systemctl status ngircd.service
ss -tlnp | grep 6667

How to Connect to the Server

For Users

Desktop IRC Clients

HexChat (Linux/Windows/Mac)

  1. Install HexChat from your package manager or hexchat.github.io
  2. Open HexChat and go to Network List
  3. Click "Add" and name it "Community Server"
  4. Click "Edit" and add:
    • Server: irc.yourdomain.com/6667 (or /6697 for SSL)
    • Check "Use SSL" if using port 6697
  5. Set your nickname
  6. Click "Connect"
  7. Join channels: /join #general

WeeChat (Linux/Mac Terminal)

# Install
sudo apt install weechat  # Debian/Ubuntu
# or: brew install weechat  # macOS

# Run and configure
weechat
/server add community irc.yourdomain.com/6667
/set irc.server.community.nicks "yournick"
/connect community
/join #general

Irssi (Linux/Mac Terminal)

# Install
sudo apt install irssi  # Debian/Ubuntu

# Run and connect
irssi
/network add -nick yournick Community
/server add -auto -network Community irc.yourdomain.com 6667
/connect Community
/join #general

mIRC (Windows)

  1. Download from mirc.com
  2. Tools → Options → Connect
  3. Add server:
    • Description: Community Server
    • IRC Server: irc.yourdomain.com
    • Ports: 6667 (or 6697 for SSL)
  4. Connect and join #general

Textual (macOS)

  1. Download from Mac App Store
  2. Server → New Server
  3. Enter server details:
    • Address: irc.yourdomain.com
    • Port: 6667 (or 6697 for SSL)
  4. Connect

Mobile IRC Clients

Android - Revolution IRC

  1. Install from Google Play Store
  2. Add Server:
    • Name: Community Server
    • Address: irc.yourdomain.com
    • Port: 6667 (or 6697 for SSL)
  3. Set nickname and connect
  4. Join #general

iOS - Palaver

  1. Install from App Store
  2. Add Network:
    • Server: irc.yourdomain.com
    • Port: 6667
  3. Set nickname and connect

Web Browser (if TheLounge enabled)

Visit: http://your-server-ip:9000

  • Register an account
  • Auto-connects to the server
  • Join channels from the interface

Basic IRC Commands

Essential Commands

/nick NewNickname          - Change your nickname
/join #channel             - Join a channel
/part #channel             - Leave a channel
/msg nickname message      - Send private message
/query nickname            - Open private chat window
/quit                      - Disconnect from server

Channel Commands

/topic New topic text      - Set channel topic (if op)
/me does something         - Send action message
/names                     - List users in channel
/whois nickname           - Get info about user

Channel Operator Commands

/mode #channel +o nick     - Give operator status
/mode #channel +v nick     - Give voice (can talk in moderated)
/mode #channel +m          - Moderated channel
/mode #channel +t          - Only ops can set topic
/kick #channel nick        - Kick user from channel
/mode #channel +b nick!*@* - Ban user

Default Channels

  • #general - Main discussion channel
  • #announcements - Server announcements (moderated, read-only for regular users)
  • #support - Help and support
  • #offtopic - Off-topic discussions

Server Administration

Becoming an Operator

/oper admin your-password

Managing Users

/kill nickname reason       - Disconnect user
/gline *!*@hostname 3600 reason  - Global ban for 1 hour

Server Commands

/rehash                    - Reload configuration
/restart                   - Restart server

Troubleshooting

Can't Connect

  1. Check firewall: sudo ufw status or sudo firewall-cmd --list-ports
  2. Verify service: systemctl status ngircd.service
  3. Check logs: journalctl -u ngircd.service -f
  4. Test locally: telnet localhost 6667

SSL Connection Issues

  1. Verify certificates exist in /etc/ngircd/ssl/
  2. Check certificate permissions: ls -la /etc/ngircd/ssl/
  3. Test SSL: openssl s_client -connect irc.yourdomain.com:6697

Port Already in Use

# Find what's using the port
sudo ss -tlnp | grep 6667
# Kill the process if needed
sudo systemctl stop ngircd.service

Security Best Practices

  1. Use SSL/TLS - Enable port 6697 with Let's Encrypt
  2. Strong Operator Password - Use bcrypt hash (htpasswd)
  3. Firewall Rules - Only allow IRC ports
  4. Regular Updates - Keep NixOS and ngircd updated
  5. Monitor Logs - Watch for abuse: journalctl -u ngircd.service -f
  6. Backup Config - Keep your configuration in git

Additional Features

Bridge to Discord (Optional)

Use matterbridge to bridge IRC and Discord:

services.matterbridge = {
  enable = true;
  configPath = "/etc/matterbridge/config.toml";
};

IRC Bouncer (Stay Connected)

Use ZNC to stay connected even when offline:

services.znc = {
  enable = true;
  config = {
    LoadModule = [ "webadmin" ];
    Listener.l = {
      Port = 5000;
      SSL = false;
    };
  };
};

Support

Quick Start Summary

Server Admin:

# 1. Edit irc-public.nix with your details
# 2. Add to flake.nix modules
# 3. Deploy
sudo nixos-rebuild switch --flake .#nixos-btw
# 4. Verify
systemctl status ngircd.service

Users:

# Install IRC client (e.g., HexChat)
# Connect to: irc.yourdomain.com:6667
# Join: #general
# Chat!

Enjoy your self-hosted IRC community server!