techircd/docs/LINKING.md

TechIRCd Server Linking

TechIRCd now supports IRC server linking, allowing multiple IRC servers to form a network. This enables users on different servers to communicate with each other seamlessly.

Features

• Server-to-Server Communication: Full IRC protocol compliance for server linking
• Hub and Leaf Configuration: Support for hub/leaf network topologies
• Auto-Connect: Automatic connection to configured servers on startup
• Operator Commands: Manual connection and disconnection controls
• Security: Password-based authentication for server connections
• Network Transparency: Users can see and communicate across the entire network

Configuration

Server linking is configured in the config.json file under the linking section:

{
  "linking": {
    "enable": true,
    "server_port": 6697,
    "password": "linkpassword123",
    "hub": false,
    "auto_connect": false,
    "links": [
      {
        "name": "hub.technet.org",
        "host": "127.0.0.1",
        "port": 6697,
        "password": "linkpassword123",
        "auto_connect": false,
        "hub": true,
        "description": "TechNet Hub Server"
      }
    ]
  }
}

Configuration Options

• enable: Enable or disable server linking functionality
• server_port: Port to listen on for incoming server connections
• password: Default password for server authentication
• hub: Whether this server acts as a hub (can connect to multiple servers)
• auto_connect: Automatically attempt to connect to configured links on startup
• links: Array of server configurations to link with

Link Configuration

Each link in the links array supports:

• name: Unique server name (should match the remote server's configured name)
• host: Hostname or IP address of the remote server
• port: Port number the remote server is listening on for server connections
• password: Authentication password (must match on both servers)
• auto_connect: Whether to automatically connect to this server
• hub: Whether the remote server is a hub server
• description: Human-readable description of the server

Operator Commands

Operators can manually control server links using these commands:

CONNECT

Connect to a configured server:

/CONNECT <servername> <port> [host]

Examples:

/CONNECT hub.technet.org 6697
/CONNECT hub.technet.org 6697 192.168.1.100

SQUIT

Disconnect from a linked server:

/SQUIT <servername> [reason]

Examples:

/SQUIT hub.technet.org
/SQUIT hub.technet.org :Maintenance required

LINKS

Show all connected servers:

/LINKS

This displays the network topology showing all connected servers.

Network Topology

TechIRCd supports both hub-and-leaf and mesh network topologies:

Hub-and-Leaf

    [Hub Server]
    /    |    \
[Leaf1] [Leaf2] [Leaf3]

In this configuration:

• The hub server (hub: true) connects to multiple leaf servers
• Leaf servers (hub: false) only connect to the hub
• All inter-server communication routes through the hub

Mesh Network

[Server1] --- [Server2]
    |     \   /    |
    |      \ /     |
[Server3] --- [Server4]

In this configuration:

• All servers can connect to multiple other servers
• Provides redundancy and multiple communication paths
• More complex but more resilient

Server-to-Server Protocol

TechIRCd implements standard IRC server-to-server protocol commands:

• PASS: Authentication password
• SERVER: Server introduction and information
• PING/PONG: Keep-alive and lag detection
• SQUIT: Server quit/disconnect
• NICK: User nickname propagation
• USER: User information propagation
• JOIN/PART: Channel membership changes
• PRIVMSG/NOTICE: Message routing between servers
• QUIT: User disconnection notifications

Message Routing

When servers are linked, messages are automatically routed across the network:

1. User Messages: Private messages and notices are routed to the correct server
2. Channel Messages: Broadcast to all servers with users in the channel
3. User Lists: WHO, WHOIS, and NAMES commands work across the network
4. Channel Lists: LIST shows channels from all linked servers

Security Considerations

• Passwords: Always use strong, unique passwords for server links
• Network Access: Restrict server linking ports to trusted networks
• Operator Permissions: Only trusted operators should have CONNECT/SQUIT privileges
• Link Validation: Server names and passwords are validated before connection

Troubleshooting

Connection Issues

1. Check Configuration: Ensure server names, hosts, ports, and passwords match
2. Network Connectivity: Verify network connectivity between servers
3. Firewall: Ensure server linking ports are open
4. Logs: Check server logs for connection errors and authentication failures

Common Error Messages

• No link configuration found: Server not configured in links array
• Server already connected: Attempted to connect to already linked server
• Authentication failed: Password mismatch between servers
• Connection refused: Network connectivity or firewall issues

Debugging

Enable debug logging to see detailed server linking information:

{
  "logging": {
    "level": "debug"
  }
}

Example Network Setup

Here's an example of setting up a 3-server network:

Hub Server (hub.technet.org)

{
  "server": {
    "name": "hub.technet.org"
  },
  "linking": {
    "enable": true,
    "server_port": 6697,
    "hub": true,
    "links": [
      {
        "name": "leaf1.technet.org",
        "host": "192.168.1.101",
        "port": 6697,
        "password": "linkpass123",
        "auto_connect": true,
        "hub": false
      },
      {
        "name": "leaf2.technet.org",
        "host": "192.168.1.102",
        "port": 6697,
        "password": "linkpass123",
        "auto_connect": true,
        "hub": false
      }
    ]
  }
}

Leaf Server 1 (leaf1.technet.org)

{
  "server": {
    "name": "leaf1.technet.org"
  },
  "linking": {
    "enable": true,
    "server_port": 6697,
    "hub": false,
    "links": [
      {
        "name": "hub.technet.org",
        "host": "192.168.1.100",
        "port": 6697,
        "password": "linkpass123",
        "auto_connect": true,
        "hub": true
      }
    ]
  }
}

Leaf Server 2 (leaf2.technet.org)

{
  "server": {
    "name": "leaf2.technet.org"
  },
  "linking": {
    "enable": true,
    "server_port": 6697,
    "hub": false,
    "links": [
      {
        "name": "hub.technet.org",
        "host": "192.168.1.100",
        "port": 6697,
        "password": "linkpass123",
        "auto_connect": true,
        "hub": true
      }
    ]
  }
}

This creates a hub-and-leaf network where:

• The hub automatically connects to both leaf servers
• Leaf servers connect only to the hub
• Users on any server can communicate with users on other servers
• Channels span across all servers in the network

Performance Considerations

• Network Latency: High latency between servers may affect user experience
• Bandwidth: Server linking uses additional bandwidth for message propagation
• CPU Usage: Message routing and protocol handling requires CPU resources
• Memory Usage: Additional memory is needed to track remote users and channels

Future Enhancements

Planned improvements for server linking include:

• Services Integration: Support for network services (NickServ, ChanServ, etc.)
• Channel Bursting: Optimized channel synchronization
• Network Statistics: Detailed network topology and performance metrics
• Load Balancing: Intelligent routing for optimal performance
• Redundancy: Automatic failover and connection recovery