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:

```json
{
  "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:

```json
{
  "logging": {
    "level": "debug"
  }
}
```

## Example Network Setup

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

### Hub Server (hub.technet.org)
```json
{
  "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)
```json
{
  "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)
```json
{
  "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