Added all of the existing code
This commit is contained in:
290
docs/LINKING.md
Normal file
290
docs/LINKING.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user