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

sha256sum -c SHA256SUMS

2. Deploy with Script

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

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

2. Setup Profile

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

# 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

ostp-client-linux status

5. Disconnect

sudo ostp-client-linux disconnect

3. Manual Installation

Full Stack Mode (Master + Server)

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

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

{
  "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):

{
  "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:

# 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

# 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

# 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

# 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

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

sudo journalctl -u ostp-server -f
sudo journalctl -u oncp-master -f

🔄 Updates

# 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