ospab.network/dist/linux-x64/README.md

# OSTP Server - Linux x64 Distribution

Universal Linux binaries (statically linked with musl) for OSTP VPN server deployment.

## 📦 Contents

- **ostp-server** (9.2 MB) - VPN server with AEAD encryption, TLS mimicry, UDP-over-TCP
- **oncp-master** (4.8 MB) - Control plane API server for node/user management
- **SHA256SUMS** - Integrity verification checksums
- **deploy.sh** - Automated deployment script
- **server.json.example** - ostp-server configuration template
- **server-enrollment.json.example** - ostp-server with enrollment token
- **ostp-server.service** - systemd service unit for ostp-server
- **oncp-master.service** - systemd service unit for oncp-master

## 🚀 Quick Start

### 1. Verify Integrity

```bash
sha256sum -c SHA256SUMS
```

### 2. Deploy with Script (Recommended)

```bash
chmod +x deploy.sh
sudo ./deploy.sh
```

The script will:
- Install binaries to `/usr/local/bin/`
- Create systemd services
- Generate PSK and network configuration
- Set up firewall rules
- Start services

### 3. Manual Installation

```bash
# Make binaries executable
chmod +x ostp-server oncp-master

# Copy to system path
sudo cp ostp-server oncp-master /usr/local/bin/

# Generate PSK for ostp-server
PSK=$(openssl rand -hex 32)
echo "Generated PSK: $PSK"

# Start oncp-master (control plane)
sudo ./oncp-master serve --listen 0.0.0.0:8080 --network-octet 42

# Generate enrollment token (expires in 3 minutes)
./oncp-master node token --expiry 3

# Start ostp-server (VPN server)
sudo ./ostp-server -l 0.0.0.0:443 -p $PSK --master http://localhost:8080
```

## 🔧 Configuration

### ostp-server Configuration

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

```json
{
  "listen_addr": "0.0.0.0:443",
  "psk": "YOUR_64_CHAR_HEX_PSK",
  "master_url": "http://localhost:8080",
  "country_code": "US",
  "max_clients": 1000
}
```

### oncp-master Configuration

Environment variables:
- `ONCP_DATABASE` - SQLite database path (default: `oncp.db`)
- `ONCP_NETWORK_OCTET` - Second octet for 10.X.0.0/16 subnet (default: `42`)
- `ONCP_LOG_LEVEL` - Logging level: error, warn, info, debug, trace

## 🌐 Network Architecture

**Master Node Subnet:** `10.X.0.0/16` (where X = network-octet)
- Master Node IP: `10.X.0.1`
- Client IPs: `10.X.0.2` - `10.X.255.254`
- Capacity: ~65,000 clients per Master Node

## 🔐 Security Features

### OTP Enrollment Tokens
Nodes must provide time-limited one-time tokens during enrollment:

```bash
# Generate token (3 minute expiry)
./oncp-master node token --expiry 3

# Node uses token in enrollment request
./ostp-server --token ABC123XYZ0 --master https://master-url
```

### Silent Validation
Invalid tokens result in silent connection close (HTTP 444) - prevents enumeration.

## 📊 Management Commands

### Node Management

```bash
# List pending enrollments
./oncp-master node pending

# Approve node (allocates IP + generates PSK)
./oncp-master node approve <node-id>

# Reject enrollment
./oncp-master node reject <node-id>

# List all nodes
./oncp-master node list
```

### User Management

```bash
# Create user with 100GB quota, 30 days
./oncp-master user create --quota 100 --days 30

# List users
./oncp-master user list

# Show network statistics
./oncp-master stats
```

### SNI Management

```bash
# Update SNI domains for specific country
./oncp-master sni update --country RU --add example.com

# Block domain globally
./oncp-master sni block --domain blocked.com
```

## 🖥️ System Requirements

- **OS:** Any Linux distribution with glibc or musl (universal binary)
- **RAM:** 512 MB minimum, 2 GB recommended
- **CPU:** 1 core minimum, 2+ cores recommended
- **Network:** Public IP with ports 443 (ostp-server), 8080 (oncp-master) open
- **Storage:** 100 MB for binaries, 1 GB+ for logs/database

## 🛡️ Firewall Configuration

```bash
# Allow ostp-server (VPN)
sudo ufw allow 443/tcp

# Allow oncp-master API (restrict to internal network in production)
sudo ufw allow 8080/tcp
```

## 📝 Logs

- **ostp-server:** `/var/log/ostp-server.log` or stdout
- **oncp-master:** `/var/log/oncp-master.log` or stdout

View logs with systemd:
```bash
sudo journalctl -u ostp-server -f
sudo journalctl -u oncp-master -f
```

## 🔄 Updates

```bash
# Stop services
sudo systemctl stop ostp-server oncp-master

# Replace binaries
sudo cp ostp-server oncp-master /usr/local/bin/

# Restart services
sudo systemctl start ostp-server oncp-master
```

## 📚 Documentation

- Project Repository: https://github.com/ospab/ospab.network
- Architecture Overview: See `prompt.md` in repository
- API Documentation: `http://<master-ip>:8080/health` (health check)

## ⚠️ Production Checklist

- [ ] Change default PSK (64 hex characters)
- [ ] Configure unique network octet (0-255, avoid 0 and 255)
- [ ] Set up SSL/TLS for oncp-master API (use reverse proxy)
- [ ] Restrict oncp-master port to internal network
- [ ] Configure log rotation
- [ ] Set up monitoring (Prometheus/Grafana)
- [ ] Enable automatic backups of oncp.db
- [ ] Configure firewall rules
- [ ] Set resource limits in systemd services

## 🆘 Support

For issues and questions:
- GitHub Issues: https://github.com/ospab/ospab.network/issues
- Security: Report vulnerabilities via private disclosure

---

**Version:** 0.1.0  
**Build Date:** January 2, 2026  
**License:** Proprietary