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

# OSTP Server - Linux x64 Distribution

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

## 📦 Contents

**Server Binaries:**
- **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

**Client Binary:**
- **ostp-client-linux** (2.0 MB) - CLI VPN client for Linux (TUN interface)

**Supporting Files:**
- **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

### Deployment Modes

The OSTP server can be deployed in two modes:

1. **Full Stack Mode** - Deploy ostp-server + oncp-master on one host (master node)
2. **Standalone Mode** - Connect ostp-server to existing master node using enrollment token

### Server Installation (Recommended Method)

#### 1. Verify Integrity

```bash
sha256sum -c SHA256SUMS
```

#### 2. Deploy with Script

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

The script will prompt you to choose deployment mode:
- **Mode 1 (Standalone)**: Connect to existing master node with enrollment token
- **Mode 2 (Full Stack)**: Install both master and server on this host

**Full Stack Mode** will:
- Install both ostp-server and oncp-master
- Generate PSK and enrollment tokens
- Set up 10.X.0.0/16 network
- Create systemd services
- Configure firewall rules

**Standalone Mode** will:
- Install ostp-server only
- Submit enrollment request to master
- Wait for admin approval
- Auto-configure after approval

### Client Installation

#### 1. Install Client Binary

```bash
chmod +x ostp-client-linux
sudo cp ostp-client-linux /usr/local/bin/
```

#### 2. Setup Profile

```bash
ostp-client-linux setup
```

Interactive wizard will prompt for:
- Server address (e.g., `vpn.example.com:443`)
- Pre-shared key (64 hex characters)
- Country code for SNI mimicry (US, RU, DE, etc.)
- Profile name (e.g., "US-West")

#### 3. Connect to VPN

```bash
# Using saved profile
sudo ostp-client-linux connect --profile default

# Or with explicit parameters
sudo ostp-client-linux connect --server 1.2.3.4:443 --psk YOUR_PSK --country US
```

#### 4. Check Status

```bash
ostp-client-linux status
```

#### 5. Disconnect

```bash
sudo ostp-client-linux disconnect
```

### 3. Manual Installation

#### Full Stack Mode (Master + Server)

```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 60 minutes)
./oncp-master node token --expiry 60

# Start ostp-server (VPN server)
sudo ./ostp-server -c /etc/ostp/server.json
```

#### Standalone Mode (Connect to Existing Master)

```bash
# Copy server binary
chmod +x ostp-server
sudo cp ostp-server /usr/local/bin/

# Create enrollment config (see server-enrollment.json.example)
cat > /etc/ostp/server.json <<EOF
{
  "listen": "0.0.0.0:443",
  "psk": "AUTO",
  "master_node_url": "http://master.example.com:8080",
  "enrollment_token": "PASTE_TOKEN_HERE",
  "node_name": "node-01",
  "country_code": "US",
  "region": "eu-west",
  "hardware_id": "server-xyz",
  "max_connections": 1000
}
EOF

# Submit enrollment request
sudo ostp-server -c /etc/ostp/server.json
# Server will submit enrollment and exit

# Ask admin to approve node:
# oncp-master node pending
# oncp-master node approve <node-id>

# After approval, update config with provided PSK and restart
```

## 🔧 Configuration

### ostp-server Configuration (Full Stack Mode)

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

```json
{
  "listen": "0.0.0.0:443",
  "psk": "YOUR_64_CHAR_HEX_PSK",
  "master_node_url": "http://localhost:8080",
  "country_code": "US",
  "max_connections": 1000
}
```

### ostp-server Configuration (Standalone Mode with Enrollment)

Create `/etc/ostp/server.json` (see `server-enrollment.json.example`):

```json
{
  "listen": "0.0.0.0:443",
  "psk": "AUTO",
  "master_node_url": "http://master.example.com:8080",
  "enrollment_token": "TOKEN_FROM_MASTER",
  "node_name": "node-01",
  "country_code": "US",
  "region": "eu-central",
  "hardware_id": "server-123",
  "max_connections": 1000
}
``` (Time-Limited One-Time Passwords)

Nodes **must** provide a valid enrollment token to join the network:

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

# Token is shown once, must be used immediately
# Example: A1B2C3D4E5

# Invalid or expired tokens are silently dropped (no error response)
# This prevents token enumeration attacks
```

**Token Security:**
- Cryptographically secure random generation
- Stored in memory only (wiped after use or expiration)
- One-time use (consumed on first valid request)
- Time-based expiration (default 3 minutes)
- Silent drop on validation failure (no fingerprinting)rop if invalid - no error message)
4. Admin approves: `oncp-master node approve <node-id>`
5. Node receives PSK and assigned IP from 10.X.0.0/16 pool
6. Update config with PSK, change `psk: "AUTO"` to actual PSK
7. Restart server

### 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