ospab
f779404e0f
New CLI client for Linux with TUN interface support: - Interactive setup wizard with profile management - Connect/disconnect commands with root privilege check - Status monitoring (interface stats, traffic counters) - Test connection (handshake verification) - Profile management (add/remove/set-default) - Anti-VM detection (production mode only) - Stealth mode (TLS mimicry, geo-SNI selection) Features: - Static musl binary (2.0 MB) - universal Linux - Config storage: ~/.config/ostp/profiles.json - TUN interface: ostp0 (10.X.Y.Z) - Security: libc::geteuid() root check, ostp-guard integration - Error handling: graceful disconnect on Ctrl+C Commands: - ostp-client-linux setup # Interactive wizard - ostp-client-linux connect --profile default - ostp-client-linux connect --server 1.2.3.4:443 --psk HEX - ostp-client-linux status # Show connection info - ostp-client-linux disconnect # Kill running client - ostp-client-linux profiles list # List saved profiles - ostp-client-linux test --server X --psk Y Distribution updates: - Added ostp-client-linux (2.0 MB) to linux-x64 package - Updated SHA256SUMS with all 3 binaries - Updated README.md with client installation guide - Rebuilt ostp-server-linux-x64.tar.gz (6.86 MB total) Note: TUN interface and traffic relay are TODO (placeholders)
270 lines
6.1 KiB
Markdown
270 lines
6.1 KiB
Markdown
# 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
|
|
|
|
### Server Installation
|
|
|
|
#### 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
|
|
|
|
### 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
|
|
|
|
```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
|