techircd/docs/SERVICES_INTEGRATION.md

# Services Integration Guide

TechIRCd is designed to work with external IRC services packages like Anope, Atheme, or IRCServices. This document explains how to set up services integration.

## Supported Services Packages

### Recommended: Anope Services
- **Website**: https://www.anope.org/
- **Features**: NickServ, ChanServ, OperServ, MemoServ, BotServ, HostServ
- **Database**: MySQL, PostgreSQL, SQLite
- **Protocol**: Full IRCd linking support

### Alternative: Atheme Services
- **Website**: https://atheme.github.io/
- **Features**: NickServ, ChanServ, OperServ, MemoServ
- **Database**: Multiple backend support
- **Protocol**: Standard IRC linking

## TechIRCd Services Integration Features

### 1. Standard IRC Protocol Support
TechIRCd implements the standard IRC protocol that services packages expect:
- **Server-to-Server linking** (`linking.json` configuration)
- **Standard IRC commands** (NICK, JOIN, PART, PRIVMSG, etc.)
- **Operator commands** (KILL, SQUIT, STATS, etc.)
- **User and channel modes**
- **IRCv3 capabilities** for enhanced features

### 2. Services Connection Methods

#### Method A: Services as Linked Server (Recommended)
Configure services to connect as a linked server using the linking configuration:

```json
{
  "linking": {
    "enable": true,
    "links": [
      {
        "name": "services.yourdomain.com",
        "host": "127.0.0.1",
        "port": 6697,
        "password": "services-link-password",
        "auto_connect": true,
        "hub": false,
        "class": "services"
      }
    ],
    "classes": {
      "services": {
        "recvq": 16384,
        "sendq": 16384,
        "max_links": 1
      }
    }
  }
}
```

#### Method B: Services as Local Client
Services can also connect as regular IRC clients with special privileges.

### 3. Services User Modes
TechIRCd supports standard services user modes:
- `+S` - Service mode (identifies services bots)
- `+o` - IRC Operator mode
- `+B` - Bot mode
- `+r` - Registered user mode

### 4. Channel Modes for Services
- `+r` - Registered channel
- `+R` - Registered users only
- `+M` - Registered/voiced users only speak
- `+S` - Services bots only

## Anope Configuration Example

### anope.conf snippet:
```
uplink
{
    host = "127.0.0.1"
    port = 6667
    password = "link-password"
}

serverinfo
{
    name = "services.yourdomain.com"
    description = "Services for TechNet"
}

networkinfo
{
    networkname = "TechNet"
    ircd = "techircd"
}
```

### TechIRCd linking.json for Anope:
```json
{
  "linking": {
    "enable": true,
    "server_port": 6697,
    "password": "link-password",
    "links": [
      {
        "name": "services.yourdomain.com",
        "host": "127.0.0.1", 
        "port": 6697,
        "password": "link-password",
        "auto_connect": false,
        "hub": false,
        "class": "services"
      }
    ]
  }
}
```

## Setup Instructions

### 1. Configure TechIRCd
1. Edit `configs/linking.json` to add services link
2. Set up linking passwords
3. Configure operator access for services management

### 2. Install Anope Services
```bash
# Download and compile Anope
wget https://github.com/anope/anope/releases/latest
tar -xzf anope-*.tar.gz
cd anope-*
./configure --prefix=/opt/anope
make && make install
```

### 3. Configure Anope
1. Edit `/opt/anope/conf/services.conf`
2. Set TechIRCd as the uplink server
3. Configure database settings
4. Set up services nicknames and channels

### 4. Start Services
```bash
# Start TechIRCd first
./techircd start

# Then start Anope services
/opt/anope/bin/anoperc start
```

## Services Protocol Support

TechIRCd supports the standard IRC server protocol features needed by services:

### User Management
- `NICK` - Nickname changes
- `USER` - User registration
- `QUIT` - User disconnection
- `KILL` - Force disconnect users

### Channel Management  
- `JOIN/PART` - Channel membership
- `MODE` - Channel and user modes
- `TOPIC` - Channel topics
- `KICK/BAN` - Channel moderation

### Network Management
- `SQUIT` - Server disconnection
- `SERVER` - Server introduction
- `BURST` - Network state synchronization
- `STATS` - Server statistics

### Services-Specific
- `SVSNICK` - Services nickname enforcement
- `SVSMODE` - Services mode changes
- `SVSJOIN` - Services-forced joins
- `SVSPART` - Services-forced parts

## Troubleshooting

### Services Won't Connect
1. Check linking password in both configs
2. Verify port configuration
3. Check TechIRCd logs for connection attempts
4. Ensure services hostname resolves

### Services Commands Not Working
1. Verify services have operator status
2. Check services user modes (+S +o)
3. Review channel access levels
4. Check services configuration

### Database Issues
Services handle their own database - TechIRCd doesn't need database access.

## Benefits of External Services

### For TechIRCd:
- ✅ **Simplified codebase** - Focus on IRC protocol
- ✅ **Better performance** - No database overhead
- ✅ **Higher reliability** - Services crashes don't affect IRC
- ✅ **Easier maintenance** - Separate concerns

### For Users:
- ✅ **Mature services** - Anope/Atheme are battle-tested
- ✅ **Rich features** - Full services functionality
- ✅ **Database choice** - MySQL, PostgreSQL, SQLite
- ✅ **Web interfaces** - Many services offer web panels

## Getting Help

- **TechIRCd Support**: GitHub Issues
- **Anope Support**: https://www.anope.org/
- **Atheme Support**: https://atheme.github.io/
- **IRC Help**: #anope or #atheme on irc.anope.org