/\/ Amiga Chat Network \/\ /\/ ACN \/\
zircd – Quickstart

Version: 0.51
Last Updated: June, 2026

Get your server linked to the main zircd network in 10 minutes

This guide covers setting up a new zircd server and linking it to the existing Zircd main and hub1 server’s for the first time.

Prerequisites

Required:

  • Linux: (Ubuntu, Debian, Fedora, etc.), Amd64/Arm64 supported.
  • Windows: See the Windows setup guide for full Windows instructions.
  • Python 3.11 or newer
  • Network access to main server on port 8899

Install Python dependencies:

pip install cryptography

Step 1: Get zircd

Linux:

cd ~
unzip zircd*.zip
cd zircd
chmod +x *.py

Windows:

cd %USERPROFILE%
:: Extract the zip using File Explorer or:
tar -xf zircd*.zip
cd zircd

Step 2: Generate RSA Keys

python3 gpw5.py --genkey

When prompted:

Enter server ID (e.g., mainserver, ciabbs): mybbs

Server ID / NetworkID Rules:

  • Maximum 15 characters
  • No spaces – use underscores instead (e.g., Reign_of_Fire not Reign of Fire)
  • Case-sensitive – MYBBS and mybbs are different IDs. Both sides of a link must match exactly.

Output:

  RSA key pair generated successfully!
  Private key: keys/mybbs.key
  Public key:  keys/mybbs.pub

Base64-encoded public key (for AdminServ ADDPEERKEY):
LS0tLS1CRUdJTi....(long base64 string)....QVBERQ==

IMPORTANT: Copy the public key – you’ll send this to the main Zircd server admin.

Step 3: Generate a random password

python3 gpw5.py --randpass

When prompted press enter to accept the defaults:

Copy the Random password (32 bytes, base64-encoded) as both ends require this.

Step 3: Contact Main Server’s Admin

Contact the main server administrator and provide them:

  1. Your NetworkID (e.g., “MYBBS”)
  2. Your public key from Step 2
  3. Link password (random base64 password)

Step 4: Configure Your Server

Edit zircd.cfg:

[Server]
NetworkName = ACN
NetworkID = MYBBS              # Your unique server ID
Hostname = mybbs.example.com   # Your hostname
Hostport = 8888                # Client connection port
PrivateKey = keys/mybbs.key
PublicKey = keys/mybbs.pub
MinPasswordLength = 8          # Match this value on ALL linked servers
PasswordComplexity = no        # Match this value on ALL linked servers
# Admin_module_load = no       # Omit or set to no (you're not main server)

[Link1]
NetworkID = Zircd                                 # Main server's NetworkID
Password = thisisareallylongstringthatisapassword # Password from admin
ConnectTo = ftn.vk3heg.net                        # Main server hostname
Hostport = 8899                                   # Main server link port
PeerPublicKey = keys/zircd.pub                    # Main server's public key

Note: The password must match exactly on both sides (main Zircd server has same password for your link).

NetworkID reminder: Max 15 characters, no spaces (use underscores), case-sensitive – must match
exactly in both your [Server] section and the main server’s [LinkN] section for your server.

Step 5: Start Your Server

Option A: Run Directly – Linux (Testing)

python3 zircd.py

Option B: Run Directly – Windows (Testing)

python zircd.py 0.0.0.0:8888

Or use the included batch file:

zircd.bat 0.0.0.0:8888

Windows will prompt to allow Python through the firewall on first run – click Allow.

Option C: Run as System Service – Linux (Production)

Create systemd service file:

sudo nano /etc/systemd/system/zircd.service

Paste:

[Unit]
Description=zircd IRC Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/zircd
ExecStart=/usr/bin/python3 /home/youruser/zircd/zircd.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable zircd
sudo systemctl start zircd

Option D: Run as a Service – Windows (Production)

Use NSSM (Non-Sucking Service Manager) from nssm.cc:

nssm install zircd "C:\Path\To\Python\python.exe" "C:\Path\To\zircd\zircd.py" "0.0.0.0:8888"
nssm start zircd

See the Windows setup guide for full details.

Step 6: Verify Link

Check your server logs:

tail -f logs/zircd.log

Look for these messages:

INFO - LinkServer initialized on :::8899
INFO - Link server listening on :::8899
INFO - Initiating outbound link to Zircd at ftn.vk3heg.net:8899
INFO - Connected to Zircd at 10.0.0.1:8899
INFO - Remote server Zircd version: 0.13, local version: 0.13
INFO - Link Zircd: Version match (v0.13)
INFO - Link Zircd encryption established (initiator)
INFO - Receiving state sync from Zircd
INFO - State sync complete from Zircd

Success! Your server is now linked to the network.

Step 7: Test Connectivity

Connect with ZIRC Client

# You should see users from the main server
/who #bbs

# Test sending a message
Nickname> Hello from my new server!

Users on the main server will see your message!

Check Synchronized Data

# On your server
ls -la *.json

# You should see:
# users.json     - Synced NickServ registrations
# chansrv.json   - Synced ChanServ registrations

Step 8: Register Your Nick

/msg NickServ REGISTER yourpassword [email protected]

This registration will sync to the main server and all other linked servers!

Troubleshooting

“Link authentication failed”

  • Check: Password matches exactly on both sides
  • Check: NetworkID matches configuration on main server
  • Verify: grep "Link1" zircd.cfg shows correct NetworkID and Password

“Key exchange failed”

  • Check: PeerPublicKey file exists: ls -la keys/zircd.pub
  • Check: Public key is correct (verify with main Zircd server admin)
  • Re-run: python3 gpw5.py --showkey and compare keys

“Connection refused”

  • Check: Main Zircd server is running: contact admin
  • Check: Port 8899 is open on main server firewall
  • Test: nc -zv ftn.vk3heg.net 8899
  • Check: ConnectTo hostname/IP is correct in zircd.cfg

“No state sync messages”

  • Check: Link authentication succeeded (see logs)
  • Check: Encryption established (see logs)
  • Wait: Sync can take a few seconds
  • Restart: sudo systemctl restart zircd or Ctrl+C and restart

What’s Synced Automatically?

  • NickServ registrations – All registered nicknames
  • ChanServ registrations – All registered channels with topics and access lists
  • Active users – Users currently connected to all servers
  • Active channels – Channels and their members across the network
  • Channel topics – Current and registered topics

Next Steps

Monitor Your Server

# Watch logs in real-time
tail -f logs/zircd.log

# Check systemd status
sudo systemctl status zircd

# View recent errors
sudo journalctl -u zircd -n 50

Security Reminders

Keep private keys secure:

chmod 600 keys/*.key
chmod 600 chansrv.json users.json

Use strong passwords:

  • Link passwords: 32+ random bytes (use gpw5.py --randpass)
  • Admin passwords: 16+ characters, unique
  • NickServ passwords: minimum 8 characters (enforced by server). Complexity enforcement (uppercase, lowercase, number, special character) can be enabled in zircd.cfg.

Match password policy across all linked servers:

The MinPasswordLength and PasswordComplexity settings in [Server] should be the same on every server in the network. NickServ registrations done on a secondary server are validated against that server’s own policy before syncing to the main server as a hash, the main server never sees the plaintext. If policies differ, a secondary with weaker settings could accept passwords the main server would reject.

Keep your server updated – Check with main server admin for updates

Getting Help

  1. Check logs: tail -f logs/zircd.log
  2. Read documentation: Linking guide, Windows setup (Windows users)
  3. Contact network admin: Email main server administrator
  4. Report issues: Contact Vorlon in the channel, or email [email protected]

Congratulations! Your zircd server is now part of the network. Users can connect to your server on port 8888 and chat with users across all linked servers.