# OSTP Server Configuration Guide

Complete guide for deploying and configuring OSTP server on Linux systems.

---

## System Requirements

- **OS:** Linux kernel 3.10+ (Ubuntu 22.04+, Debian 11+, CentOS 8+)
- **Memory:** 512 MB minimum, 2 GB recommended for 100+ concurrent connections
- **Storage:** 1 GB for binaries and logs, additional space for user database
- **Network:** Public IPv4 address with TCP port 443 or 8443 available
- **Permissions:** Root or CAP_NET_ADMIN for TUN device creation

---

## Installation

### Binary Installation (Recommended)

```bash
# Download release binary
wget https://github.com/ospab/ospab.network/releases/ostp-server-linux-x64.tar.gz

# Extract and install
tar -xzf ostp-server-linux-x64.tar.gz
sudo mv ostp-server /usr/local/bin/
sudo chmod +x /usr/local/bin/ostp-server

# Verify installation
ostp-server --version
```

### Build from Source

```bash
# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone repository (requires access)
git clone https://github.com/ospab/ospab.network.git
cd ospab.network

# Build release binary
cargo build -p ostp-server --release

# Install
sudo cp target/release/ostp-server /usr/local/bin/
```

---

## Pre-Shared Key Generation

Generate a cryptographically secure PSK:

```bash
# Generate and display PSK
ostp-server gen-key

# Save to environment variable
export OSTP_PSK=$(ostp-server gen-key)

# Or save to file (secure permissions!)
ostp-server gen-key > /etc/ostp/server.psk
chmod 600 /etc/ostp/server.psk
```

**Security Note:** Never commit PSKs to version control. Each server should use a unique PSK shared only with authorized clients.

---

## Configuration

### Command-Line Mode

```bash
# Minimal configuration
ostp-server -l 0.0.0.0:8443 -p <hex-encoded-psk>

# With logging
ostp-server -l 0.0.0.0:8443 -p $OSTP_PSK --log-level info

# Custom database path
ostp-server -l 0.0.0.0:8443 -p $OSTP_PSK --db /var/lib/ostp/users.db
```

### Configuration File Mode

Create `/etc/ostp/server.json`:

```json
{
  "listen_addr": "0.0.0.0:8443",
  "psk": "a1b2c3d4e5f6...",
  "database_path": "/var/lib/ostp/users.db",
  "log_level": "info",
  "max_connections": 1000,
  "session_timeout_secs": 3600,
  "tun_device": "ostp0",
  "tun_ip": "10.8.0.1",
  "tun_netmask": "255.255.255.0",
  "dns_servers": ["1.1.1.1", "1.0.0.1"]
}
```

Run with config file:

```bash
ostp-server -c /etc/ostp/server.json
```

---

## Systemd Service

Create `/etc/systemd/system/ostp-server.service`:

```ini
[Unit]
Description=OSTP Stealth VPN Server
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/ostp-server -c /etc/ostp/server.json
Restart=on-failure
RestartSec=10s

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/ostp /var/log/ostp

# Resource limits
LimitNOFILE=65536
TasksMax=4096

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl daemon-reload
sudo systemctl enable ostp-server
sudo systemctl start ostp-server
sudo systemctl status ostp-server
```

---

## Firewall Configuration

### UFW (Ubuntu/Debian)

```bash
sudo ufw allow 8443/tcp comment 'OSTP Server'
sudo ufw reload
```

### firewalld (CentOS/RHEL)

```bash
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload
```

### iptables (Manual)

```bash
sudo iptables -A INPUT -p tcp --dport 8443 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4
```

---

## User Management

### Add User

```bash
# Using SQLite directly
sqlite3 /var/lib/ostp/users.db << EOF
INSERT INTO users (username, quota_gb, expiry_date) 
VALUES ('john_doe', 100, '2026-12-31');
EOF
```

### Check Active Sessions

```bash
# View logs for session info
tail -f /var/log/ostp/server.log | grep SESSION_START
```

### Reset User Quota

```bash
sqlite3 /var/lib/ostp/users.db << EOF
UPDATE users SET used_gb = 0 WHERE username = 'john_doe';
EOF
```

---

## Monitoring & Logging

### Log Levels

- `error` — Critical errors only
- `warn` — Warnings and errors
- `info` — General operation info (recommended)
- `debug` — Detailed debugging (high volume)
- `trace` — Very verbose (development only)

### Log Rotation

Create `/etc/logrotate.d/ostp`:

```
/var/log/ostp/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 root root
    sharedscripts
    postrotate
        systemctl reload ostp-server > /dev/null 2>&1 || true
    endscript
}
```

---

## Performance Tuning

### Kernel Parameters

Add to `/etc/sysctl.conf`:

```ini
# Increase connection backlog
net.core.somaxconn = 4096
net.core.netdev_max_backlog = 5000

# Enable TCP Fast Open
net.ipv4.tcp_fastopen = 3

# Increase ephemeral ports
net.ipv4.ip_local_port_range = 10000 65535

# Enable IP forwarding
net.ipv4.ip_forward = 1
```

Apply changes:

```bash
sudo sysctl -p
```

### File Descriptor Limits

Edit `/etc/security/limits.conf`:

```
root soft nofile 65536
root hard nofile 65536
```

---

## Troubleshooting

### Server Won't Start

```bash
# Check if port is already in use
sudo netstat -tulpn | grep 8443

# Check file permissions
ls -la /etc/ostp/server.json
ls -la /var/lib/ostp/users.db

# Check logs for specific error
journalctl -u ostp-server -n 50
```

### No Client Connections

```bash
# Verify firewall allows port
sudo iptables -L -n | grep 8443

# Test connectivity from client
telnet server_ip 8443

# Check PSK matches between client and server
```

### High CPU Usage

```bash
# Check number of connections
ss -tn state established '( dport = :8443 )' | wc -l

# Monitor CPU usage
top -p $(pgrep ostp-server)

# Consider lowering log level to 'warn'
```

---

## Security Best Practices

1. **Change Default Port:** Use port 443 instead of 8443 to blend with HTTPS traffic
2. **Rotate PSKs:** Change PSKs every 90 days and distribute to clients securely
3. **Limit Connections:** Set `max_connections` based on server capacity
4. **Monitor Logs:** Set up alerts for suspicious patterns or failed authentications
5. **Update Regularly:** Keep server binary updated with latest security patches
6. **Use Strong PSKs:** Always generate PSKs using `ostp-server gen-key`
7. **Separate Databases:** Use separate user databases for different client groups

---

## Backup & Recovery

### Backup User Database

```bash
# Create backup
sqlite3 /var/lib/ostp/users.db ".backup '/backup/users-$(date +%Y%m%d).db'"

# Or simple file copy
cp /var/lib/ostp/users.db /backup/users-$(date +%Y%m%d).db
```

### Restore from Backup

```bash
systemctl stop ostp-server
cp /backup/users-20260101.db /var/lib/ostp/users.db
systemctl start ostp-server
```

---

## Command Reference

| Command | Description |
|---------|-------------|
| `ostp-server gen-key` | Generate new PSK |
| `ostp-server -l <addr>` | Set listen address |
| `ostp-server -p <psk>` | Set pre-shared key |
| `ostp-server -c <file>` | Use config file |
| `ostp-server --log-level <level>` | Set log verbosity |
| `ostp-server --version` | Show version info |
| `ostp-server --help` | Display help |

---

## Support

For technical support or licensing inquiries:
- **Email:** ospab@ospab.host
- **Documentation:** See additional guides in `docs/`

---

*Last updated: January 2026*