=== Badwolf Web IRC Client - Configuration Guide ===


Version: 5.2.0
Last Updated: January 18, 2026


=== Table of Contents ===

1. WordPress Plugin Configuration
2. UnrealIRCd Server Configuration
3. SSL/TLS Certificate Setup
4. Advanced Configuration Options
5. Security Considerations


================================================================================
1. WORDPRESS PLUGIN CONFIGURATION
================================================================================


After activating the plugin, navigate to:
WordPress Admin → Settings → Badwolf Web IRC Client


--- Required Settings ---


WebSocket URL:
• Format: wss://irc.yourdomain.com:7443
• Must use wss:// (secure WebSocket) for production
• Port must match your UnrealIRCd WebSocket listener
• Example: wss://irc.example.com:7443


Default Channel:
• IRC channel users will join automatically
• Can include or omit the # symbol
• Example: #general or general
• Must be a valid IRC channel name


--- Optional Settings ---


Nickname Prefix:
• Prefix for auto-generated nicknames
• Random numbers will be appended
• Example: guest → guest1234
• Default: supportguest


Real Name:
• Default real name shown in IRC
• Visible in /WHOIS queries
• Example: Web IRC User
• Default: Web IRC User


Theme:
• Light or Dark theme
• Can be overridden per shortcode
• Default: light


Auto Connect:
• Yes: Connect automatically when page loads
• No: User must click to connect
• Default: Yes


--- Shortcode Usage ---


Basic shortcode:
  [web_irc_client]


With custom attributes:
  [web_irc_client theme="dark" width="100%" height="600px"]


Available attributes:
• theme: "light" or "dark"
• width: Any CSS width value (100%, 800px, etc.)
• height: Any CSS height value (70vh, 500px, etc.)


================================================================================
2. UNREALIRCD SERVER CONFIGURATION
================================================================================


--- Minimum Requirements ---


UnrealIRCd Version: 6.0.0 or higher
Modules Required: websocket, webserver


--- Load Required Modules ---


Add to your unrealircd.conf:


  loadmodule "websocket";
  loadmodule "webserver";


--- WebSocket Listener Configuration ---


Basic WebSocket with TLS (Recommended):


  listen {
      ip *;
      port 7443;
      options {
          tls;
          websocket;
      }
      tls-options {
          certificate "/path/to/fullchain.pem";
          key "/path/to/privkey.pem";
          options {
              no-client-certificate;
          }
      }
  }


Multiple Ports Configuration:


Regular IRC with TLS

  listen {
      ip *;
      port 6697;
      options { tls; }
      tls-options {
          certificate "/path/to/fullchain.pem";
          key "/path/to/privkey.pem";
      }
  }


WebSocket with TLS

  listen {
      ip *;
      port 7443;
      options {
          tls;
          websocket;
      }
      tls-options {
          certificate "/path/to/fullchain.pem";
          key "/path/to/privkey.pem";
          options {
              no-client-certificate;
          }
      }
  }


Plain IRC (not recommended for production)

  listen {
      ip *;
      port 6667;
  }


--- Important Notes ---

1. Always use TLS (wss://) for production environments
2. Certificate paths must be absolute paths
3. UnrealIRCd user must have read access to certificate files
4. After config changes, restart UnrealIRCd (not just rehash)


--- Restart UnrealIRCd ---


  cd /path/to/unrealircd
  ./unrealircd restart


--- Verify Configuration ---


Check if UnrealIRCd is running

  ps aux | grep unrealircd


Check if port is listening

  sudo netstat -tlnp | grep 7443


Check logs for errors

  tail -f /path/to/unrealircd/logs/ircd.log


================================================================================
3. SSL/TLS CERTIFICATE SETUP
================================================================================


--- Using Let's Encrypt (Recommended) ---


Step 1: Install Certbot


Debian/Ubuntu

  sudo apt-get update
  sudo apt-get install certbot


CentOS/RHEL

  sudo yum install certbot


Step 2: Obtain Certificate


Standalone method (requires port 80 to be free)

  sudo certbot certonly --standalone -d irc.yourdomain.com


Webroot method (if you have a web server running)

  sudo certbot certonly --webroot -w /var/www/html -d irc.yourdomain.com


Step 3: Copy Certificates to UnrealIRCd


  sudo cp /etc/letsencrypt/live/irc.yourdomain.com/fullchain.pem /path/to/unrealircd/conf/tls/
  sudo cp /etc/letsencrypt/live/irc.yourdomain.com/privkey.pem /path/to/unrealircd/conf/tls/


Step 4: Set Correct Permissions


  sudo chown unrealircd:unrealircd /path/to/unrealircd/conf/tls/*.pem
  sudo chmod 600 /path/to/unrealircd/conf/tls/privkey.pem
  sudo chmod 644 /path/to/unrealircd/conf/tls/fullchain.pem


Step 5: Restart UnrealIRCd


  cd /path/to/unrealircd
  ./unrealircd restart


--- Auto-Renewal Setup ---


Create renewal hook script:


  sudo nano /etc/letsencrypt/renewal-hooks/deploy/copy-to-unrealircd.sh


Add this content (adjust paths):


  #!/bin/bash
  cp /etc/letsencrypt/live/irc.yourdomain.com/fullchain.pem /path/to/unrealircd/conf/tls/
  cp /etc/letsencrypt/live/irc.yourdomain.com/privkey.pem /path/to/unrealircd/conf/tls/
  chown unrealircd:unrealircd /path/to/unrealircd/conf/tls/*.pem
  chmod 600 /path/to/unrealircd/conf/tls/privkey.pem
  chmod 644 /path/to/unrealircd/conf/tls/fullchain.pem
  /path/to/unrealircd/unrealircd rehash


Make it executable:


  sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/copy-to-unrealircd.sh


Test auto-renewal:


  sudo certbot renew --dry-run


--- Using Self-Signed Certificates (Testing Only) ---


Generate self-signed certificate:


  cd /path/to/unrealircd/conf/tls
  openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -days 365 -nodes


Note: Self-signed certificates will show browser warnings and are NOT recommended for production.


================================================================================
4. ADVANCED CONFIGURATION OPTIONS
================================================================================


--- Connection Limits ---


In unrealircd.conf, adjust connection limits:


  class clients {
      pingfreq 90;
      maxclients 1000;
      sendq 200k;
      recvq 8000;
  }


  allow {
      mask *;
      class clients;
      maxperip 15;  # Max connections per IP
  }


--- Channel Configuration ---


Set default channel modes:


  set {
      modes-on-join "+nt";  # No external messages, topic protection
  }


--- Anti-Flood Settings ---


Configure flood protection:


  set {
      anti-flood {
          connect-flood 3:60;  # 3 connections per 60 seconds
      }
  }


--- WebSocket-Specific Settings ---


If you need to adjust WebSocket behavior, check UnrealIRCd documentation:
https://www.unrealircd.org/docs/WebSocket_support


================================================================================
5. SECURITY CONSIDERATIONS
================================================================================


--- Essential Security Measures ---

1. ALWAYS use TLS (wss://) in production
- Never use ws:// (unencrypted) for public-facing sites
- Browsers may block non-secure WebSocket connections

2. Use valid SSL certificates
- Let's Encrypt provides free, trusted certificates
- Self-signed certificates cause browser warnings

3. Keep certificates up to date
- Set up auto-renewal
- Monitor certificate expiration

4. Firewall Configuration
- Only open necessary ports
- Consider IP whitelisting for admin access

5. Regular Updates
- Keep UnrealIRCd updated
- Keep WordPress and plugin updated
- Monitor security advisories


--- Firewall Rules ---


Allow WebSocket port:


UFW

  sudo ufw allow 7443/tcp


iptables

  sudo iptables -A INPUT -p tcp --dport 7443 -j ACCEPT
  sudo iptables-save


--- Connection Rate Limiting ---


Use UnrealIRCd's built-in connection throttling:


  set {
      connthrottle {
          new-users {
              local-throttle 20:60;
              global-throttle 30:60;
          }
      }
  }


--- Monitoring ---


Monitor UnrealIRCd logs regularly:


  tail -f /path/to/unrealircd/logs/ircd.log


Check for:
• Failed connection attempts
• Certificate warnings
• Unusual activity patterns


================================================================================


For more information and support:
• GitHub: https://github.com/badwolf1972/web-irc-client
• UnrealIRCd Docs: https://www.unrealircd.org/docs/
• WordPress Support: https://wordpress.org/support/plugin/badwolf-web-irc-client/