ospab/ospab.network
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: OSTP stealth VPN protocol with anti-RE protection

Browse Source 
- Core transport layer (ostp): ChaCha20-Poly1305 AEAD, X25519 key exchange, TLS mimicry
- Control plane (oncp): Session management, SQLite billing, user registry
- Network layer (osn): TUN device abstraction and routing
- DNS forwarder (osds): Stealth DNS with anti-hijack detection
- Anti-RE protection (ostp-guard): String obfuscation, anti-debug, anti-VM, control flow obfuscation
- CLI binaries: ostp-server (Linux), ostp-client (Windows) with interactive setup
- Comprehensive documentation: README, LICENSE, deployment guides
- Hardened release profile: LTO, symbol stripping, static linking
This commit is contained in:
ospab
2026-01-01 19:03:31 +03:00
parent 5fbb32d243
commit fc00214b07
5 changed files with 1608 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
docs/CLIENT.md Normal file
View File

@@ -0,0 +1,371 @@
# OSTP Client Setup Guide
Complete guide for installing and configuring OSTP client on Windows systems.
---
## System Requirements
- **OS:** Windows 10/11 (64-bit)
- **Memory:** 256 MB minimum
- **Storage:** 50 MB for binary and configuration
- **Permissions:** Administrator privileges for TUN device creation
- **Network:** Internet connection with TCP outbound access
---
## Installation
### Binary Installation (Recommended)
1. Download latest release from authorized source
2. Extract `ostp-client.exe` to preferred location (e.g., `C:\Program Files\OSTP\`)
3. Create shortcuts if desired
4. Verify installation by running:
```cmd
ostp-client --version
```
**Note:** Windows Defender SmartScreen may show a warning for first-time execution. This is expected for unsigned binaries. Click "More info" → "Run anyway".
---
## Quick Start with Setup Wizard
The easiest way to get started:
```cmd
# Run interactive setup
ostp-client setup
```
The wizard will guide you through:
1. Server address configuration
2. PSK (Pre-Shared Key) input
3. Country selection for SNI mimicry
4. Profile name assignment
5. Auto-connect preferences
---
## Manual Configuration
### Profile Management
Profiles are stored in: `%APPDATA%\ostp\profiles.json`
Example profile structure:
```json
{
"profiles": [
{
"name": "Russia-VPN",
"server": "1.2.3.4:8443",
"psk": "a1b2c3d4e5f6...",
"country": "RU",
"auto_reconnect": true
},
{
"name": "US-Server",
"server": "5.6.7.8:8443",
"psk": "f6e5d4c3b2a1...",
"country": "US",
"auto_reconnect": false
}
],
"default_profile": "Russia-VPN"
}
```
---
## Connecting to Server
### Using Profiles
```cmd
# List available profiles
ostp-client profiles
# Connect using profile
ostp-client connect --profile Russia-VPN
# Connect using default profile
ostp-client connect
```
### Direct Connection
```cmd
# Connect with explicit parameters
ostp-client connect -s 1.2.3.4:8443 -p <hex-psk> -c RU
```
### Connection Options
| Flag | Description | Example |
|------|-------------|---------|
| `-s, --server` | Server address | `1.2.3.4:8443` |
| `-p, --psk` | Pre-shared key (hex) | `a1b2c3...` |
| `-c, --country` | Country code for SNI | `RU`, `US`, `DE`, `NO`, `CN` |
| `--profile` | Profile name | `Russia-VPN` |
| `-d, --dns` | Custom DNS servers | `1.1.1.1,1.0.0.1` |
---
## Country Codes for SNI Mimicry
OSTP uses geo-aware SNI selection to blend with regional traffic:
| Code | Country | Example Domains |
|------|---------|-----------------|
| `RU` | Russia | yandex.ru, vk.com, mail.ru |
| `US` | United States | google.com, microsoft.com, cloudflare.com |
| `DE` | Germany | deutsche-bank.de, spiegel.de |
| `NO` | Norway | vg.no, nrk.no |
| `CN` | China | baidu.com, qq.com |
**Tip:** Choose a country code matching your physical location or target region to minimize suspicion from network monitors.
---
## Profile Commands
### Create Profile
```cmd
ostp-client setup
```
### List Profiles
```cmd
ostp-client profiles
```
### Edit Profile
Manually edit `%APPDATA%\ostp\profiles.json` with a text editor, or delete and recreate using the setup wizard.
### Delete Profile
Remove the profile entry from `profiles.json` manually.
---
## Advanced Usage
### Custom DNS Servers
```cmd
ostp-client connect --profile Russia-VPN --dns 1.1.1.1,1.0.0.1
```
### Verbose Logging
```cmd
ostp-client connect --profile Russia-VPN --log-level debug
```
### Background Mode (Experimental)
```cmd
start /B ostp-client connect --profile Russia-VPN
```
---
## Troubleshooting
### Connection Failures
**Error: Connection refused**
- Verify server address and port
- Check firewall allows outbound TCP connections
- Confirm server is running (`telnet server_ip port`)
**Error: Authentication failed (Silent)**
- PSK mismatch—verify hex string matches server
- Server may have rotated PSK—contact administrator
**Error: TUN device creation failed**
- Run as Administrator
- Check Windows TAP driver is installed
- Restart Windows if recently installed driver
### Performance Issues
**Slow connection speeds**
- Try different server locations
- Check local network bandwidth
- Verify server has adequate resources
**Frequent disconnections**
- Enable auto-reconnect in profile
- Check network stability
- Try different country code for SNI
### Application-Specific Issues
**Some apps don't route through VPN**
- Verify TUN device is set as default gateway
- Check app doesn't bypass system proxy
- Some apps (e.g., browsers) may have hardcoded DNS
---
## Security Features
### Anti-Tampering Protection
Release builds include runtime protection against:
- **Debugger Attachment** — Detects and terminates if debugging is detected
- **VM/Sandbox Detection** — Identifies analysis environments
- **Memory Scanning** — Detects memory analysis tools
If protection is triggered, the client will exit silently with a generic error code (0x000003E5). This is intentional to prevent revealing protocol details to attackers.
### Disabling Protection (Development Only)
Debug builds do not include protection mechanisms. Build from source:
```bash
cargo build -p ostp-client
```
**Warning:** Never use debug builds in production or restrictive environments.
---
## Configuration File Location
| Item | Path |
|------|------|
| Profiles | `%APPDATA%\ostp\profiles.json` |
| Logs | `%APPDATA%\ostp\logs\` |
| Cache | `%APPDATA%\ostp\cache\` |
To reset configuration:
```cmd
del /Q %APPDATA%\ostp\profiles.json
ostp-client setup
```
---
## PSK Security
### Obtaining PSK
PSKs are generated by server administrators using:
```bash
ostp-server gen-key
```
Never share your PSK publicly. PSKs should be transmitted via secure channels only (encrypted email, Signal, Telegram secret chats, etc.).
### PSK Format
PSKs are 64-character hexadecimal strings (32 bytes):
```
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
```
### PSK Rotation
When server administrator rotates PSK:
1. Receive new PSK via secure channel
2. Update profile: Edit `profiles.json` or recreate with `ostp-client setup`
3. Reconnect
---
## Network Requirements
OSTP requires outbound TCP access to server port (typically 443 or 8443). The protocol mimics HTTPS traffic, so it should work on networks that allow web browsing.
**Networks known to work:**
- Home broadband
- Corporate networks (if HTTPS is allowed)
- Public WiFi (coffee shops, airports, hotels)
- Mobile data (4G/5G)
**Networks with potential issues:**
- Enterprise networks with SSL/TLS inspection (may break mimicry)
- Networks blocking all non-standard TLS handshakes
- Captive portals (connect to WiFi login page first)
---
## Command Reference
| Command | Description |
|---------|-------------|
| `ostp-client setup` | Interactive profile creation wizard |
| `ostp-client connect` | Connect using default profile |
| `ostp-client connect --profile <name>` | Connect using named profile |
| `ostp-client connect -s <addr> -p <psk> -c <country>` | Direct connection |
| `ostp-client profiles` | List all saved profiles |
| `ostp-client --version` | Show version info |
| `ostp-client --help` | Display help |
---
## Uninstallation
1. Delete `ostp-client.exe`
2. Remove configuration directory:
```cmd
rmdir /S %APPDATA%\ostp
```
3. Reboot to ensure TUN device driver is fully unloaded
---
## Best Practices
1. **Use Unique PSKs:** Each user/device should have a separate PSK
2. **Rotate PSKs:** Change PSKs every 90 days
3. **Match Country Codes:** Use SNI matching your physical location when possible
4. **Keep Updated:** Install updates from authorized sources only
5. **Verify Integrity:** Check binary hash against official release
6. **Secure Storage:** Don't save PSKs in plain text notes or emails
7. **Administrator Access:** Only run as admin when connecting (required for TUN)
---
## FAQ
**Q: Can I use multiple profiles simultaneously?**
A: No, only one connection at a time. Disconnect before switching profiles.
**Q: Does OSTP work in China/Iran/Russia?**
A: OSTP is designed to evade DPI in restrictive environments, but effectiveness depends on specific network conditions. Use country-matched SNI for best results.
**Q: Can my ISP detect OSTP usage?**
A: OSTP traffic appears as legitimate HTTPS. However, determined adversaries with advanced traffic analysis may identify patterns. Use responsibly.
**Q: Why doesn't the client show detailed error messages?**
A: By design. Detailed errors could reveal protocol internals to attackers. Check logs in `%APPDATA%\ostp\logs\` for more info.
**Q: Can I run OSTP on Windows 7?**
A: Not officially supported. Windows 10/11 only.
---
## Support
For technical support or licensing inquiries:
- **Email:** ospab@ospab.host
- **Documentation:** See additional guides in `docs/`
---
*Last updated: January 2026*

617
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,617 @@
# OSTP Deployment Best Practices
Guidelines for deploying OSTP in production environments with maximum security and reliability.
---
## Infrastructure Planning
### Server Placement Strategy
**1. Geographic Distribution**
- Deploy servers in multiple regions to minimize latency
- Consider legal jurisdictions favorable to privacy
- Use data centers with strong physical security
- Avoid countries with mandatory data retention laws
**2. IP Address Selection**
- Use clean IPs without reputation issues
- Avoid IP ranges commonly associated with VPN providers
- Consider using residential proxy IPs for maximum stealth
- Rotate server IPs periodically (every 3-6 months)
**3. Network Architecture**
```
[Internet] → [CDN/Proxy] → [OSTP Server] → [Internal Network]
↓
[User Database]
[DNS Forwarder]
```
Benefits:
- CDN/proxy layer provides DDoS protection
- Hides real server IP from direct client access
- Allows for traffic distribution
---
## Security Hardening
### Server Operating System
**Minimal Installation**
```bash
# Ubuntu Server minimal install
sudo apt update
sudo apt install -y ufw fail2ban sqlite3
# Disable unnecessary services
sudo systemctl disable bluetooth
sudo systemctl disable cups
sudo systemctl disable avahi-daemon
# Enable automatic security updates
sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades
```
**Kernel Hardening** (`/etc/sysctl.conf`):
```ini
# Disable IPv6 if not needed
net.ipv6.conf.all.disable_ipv6 = 1
# SYN flood protection
net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_max_syn_backlog = 2048
# Ignore ICMP redirects
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.all.send_redirects = 0
# Disable source packet routing
net.ipv4.conf.all.accept_source_route = 0
# Log martian packets
net.ipv4.conf.all.log_martians = 1
```
### Firewall Configuration
**Defense in Depth:**
```bash
# Default deny policy
sudo ufw default deny incoming
sudo ufw default deny outgoing
# Allow only necessary ports
sudo ufw allow out 53/udp # DNS
sudo ufw allow out 123/udp # NTP
sudo ufw allow in 8443/tcp # OSTP
# Allow established connections
sudo ufw allow out on tun0 from any to any
# Enable firewall
sudo ufw enable
```
### SSH Hardening
Edit `/etc/ssh/sshd_config`:
```
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
Port 22222 # Non-standard port
AllowUsers admin
MaxAuthTries 3
ClientAliveInterval 300
ClientAliveCountMax 2
```
### Fail2Ban Configuration
Create `/etc/fail2ban/jail.local`:
```ini
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 3
[sshd]
enabled = true
port = 22222
```
---
## PSK Management
### Generation Strategy
```bash
# Generate PSK with high entropy
ostp-server gen-key > /secure/storage/psk-$(date +%Y%m%d).txt
# Or use system random
xxd -p -l 32 /dev/urandom | tr -d '\n'
```
### Distribution Methods
**Secure Channels:**
1. **Signal/Telegram Secret Chats** — End-to-end encrypted messaging
2. **PGP-Encrypted Email** — Encrypt PSK with user's public key
3. **Password Managers** — Share via 1Password/Bitwarden shared vaults
4. **QR Codes** — Generate QR codes for in-person distribution
5. **Hardware Tokens** — Store on encrypted USB drives
**Never:**
- Send PSKs via unencrypted email
- Post PSKs in public forums or chat groups
- Store PSKs in version control
- Reuse PSKs across multiple users
### Rotation Schedule
| User Type | Rotation Frequency | Method |
|-----------|-------------------|---------|
| Individual | 90 days | Manual update |
| Corporate | 30 days | Automated push |
| High-Risk | 7 days | Dynamic generation |
### Multi-PSK Architecture (Advanced)
For large deployments, use separate PSKs per user group:
```json
{
"psk_groups": {
"premium_users": "a1b2c3...",
"trial_users": "d4e5f6...",
"enterprise": "g7h8i9..."
}
}
```
Requires custom `PskValidator` implementation in `ostp/src/crypto.rs`.
---
## Monitoring & Alerting
### Metrics to Track
**Connection Metrics:**
- Active connections per minute
- Failed authentication attempts
- Average session duration
- Bandwidth per user
**System Metrics:**
- CPU usage
- Memory usage
- Disk I/O
- Network throughput
**Security Metrics:**
- Failed PSK validations
- Repeated connection attempts from same IP
- Unusual traffic patterns
- Anti-debug trigger counts
### Logging Strategy
**Log Levels by Environment:**
```
Development: debug
Staging: info
Production: warn
High-Security: error only
```
**Log Aggregation:**
```bash
# Forward logs to central syslog server
sudo apt install -y rsyslog
echo "*.* @@log-server:514" >> /etc/rsyslog.conf
sudo systemctl restart rsyslog
```
**Log Retention:**
- Keep 30 days of detailed logs
- Archive 1 year of summarized logs
- Purge logs older than 1 year
### Alerting Rules
Set up alerts for:
- Server CPU >80% for 5 minutes
- Disk usage >90%
- Failed auth rate >100/minute (potential attack)
- Service downtime >1 minute
- Certificate expiration <30 days (if using real certs)
---
## Backup & Disaster Recovery
### Backup Strategy
**Daily Backups:**
```bash
#!/bin/bash
# /usr/local/bin/ostp-backup.sh
DATE=$(date +%Y%m%d-%H%M)
BACKUP_DIR=/backup/ostp
# Backup user database
sqlite3 /var/lib/ostp/users.db ".backup '$BACKUP_DIR/users-$DATE.db'"
# Backup configuration
cp /etc/ostp/server.json $BACKUP_DIR/config-$DATE.json
# Compress and encrypt
tar czf - $BACKUP_DIR/*-$DATE.* | \
gpg --encrypt --recipient admin@ospab.host > \
$BACKUP_DIR/ostp-backup-$DATE.tar.gz.gpg
# Upload to remote storage (S3, Backblaze, etc.)
aws s3 cp $BACKUP_DIR/ostp-backup-$DATE.tar.gz.gpg \
s3://ostp-backups/
# Clean up old backups (keep 7 days)
find $BACKUP_DIR -mtime +7 -delete
```
**Crontab Entry:**
```bash
0 2 * * * /usr/local/bin/ostp-backup.sh
```
### Disaster Recovery Plan
**RTO (Recovery Time Objective): 1 hour**
**RPO (Recovery Point Objective): 24 hours**
1. **Server Failure:**
- Spin up new VPS from template
- Restore latest backup
- Update DNS records
- Notify users (if IP changed)
2. **Database Corruption:**
- Stop ostp-server
- Restore from latest backup
- Verify data integrity
- Restart service
3. **PSK Compromise:**
- Generate new PSK immediately
- Deploy to server
- Distribute to all users via secure channels
- Invalidate old PSK
---
## Performance Optimization
### Connection Limits
Based on server specs:
| RAM | CPU Cores | Max Connections | Notes |
|-----|-----------|----------------|-------|
| 1 GB | 1 core | 100 | Minimal |
| 2 GB | 2 cores | 500 | Recommended |
| 4 GB | 4 cores | 1000 | High capacity |
| 8 GB | 8 cores | 5000 | Enterprise |
### Load Balancing
For >1000 concurrent users:
```
[DNS Round-Robin]
↓
+-----------+-----------+
↓ ↓ ↓
[OSTP Server 1] [Server 2] [Server 3]
↓ ↓ ↓
[Shared Database]
```
Use database replication (PostgreSQL) instead of SQLite for multi-server deployments.
### Bandwidth Management
```bash
# Rate limit per connection (Linux tc)
tc qdisc add dev eth0 root tbf rate 10mbit burst 32kbit latency 400ms
# Or use iptables hashlimit
iptables -A INPUT -p tcp --dport 8443 \
-m hashlimit --hashlimit-name ostp \
--hashlimit-above 10/s --hashlimit-mode srcip \
-j DROP
```
---
## Compliance & Legal
### Data Retention Policies
**Recommended Minimal Logging:**
- Do NOT log plaintext traffic content
- Do NOT log destination IPs
- Do log: connection timestamps, total bytes transferred, user IDs
**Compliance Requirements:**
- GDPR (EU): User data deletion requests
- CCPA (California): Data access requests
- National regulations: Vary by jurisdiction
### Privacy by Design
1. **Minimize Data Collection:** Only collect necessary metadata
2. **Encrypt at Rest:** Database encryption for user data
3. **Anonymize Logs:** Hash IPs before storing
4. **Short Retention:** Delete logs after 30 days
5. **No Third Parties:** Never share user data
### Warrant Canary (Optional)
Create a `canary.txt` on your website:
```
As of January 1, 2026, OSTP has NOT received:
- National security letters
- Gag orders
- Warrants for user data
- Requests to install monitoring software
This canary will be updated monthly.
```
If you receive a gag order, stop updating the canary (signals users).
---
## Scaling Strategy
### Phase 1: Single Server (0-500 users)
- 1 VPS with 2GB RAM
- SQLite database
- Direct client connections
### Phase 2: Vertical Scaling (500-2000 users)
- Upgrade to 4GB RAM, 4 cores
- Optimize database indexes
- Add monitoring
### Phase 3: Horizontal Scaling (2000+ users)
- Deploy multiple servers
- Shared PostgreSQL database with replication
- DNS-based load balancing
- Separate user database server
### Phase 4: Global Infrastructure (10000+ users)
- Regional server clusters
- Geo-DNS routing
- CDN integration
- Dedicated DDoS protection
---
## Cost Analysis
### Single Server Monthly Costs
| Provider | Specs | Price | Notes |
|----------|-------|-------|-------|
| Hetzner | 2GB RAM, 40GB SSD | $5 | Best value |
| DigitalOcean | 2GB RAM, 50GB SSD | $12 | Easy setup |
| Vultr | 2GB RAM, 55GB SSD | $12 | Global locations |
| AWS Lightsail | 2GB RAM, 60GB SSD | $12 | AWS ecosystem |
**Additional Costs:**
- Domain name: $10-15/year
- Backup storage: $2-5/month
- Monitoring: $10-20/month (optional)
- DDoS protection: $20-100/month (if needed)
**Revenue Model (Optional):**
- Free tier: 5GB/month
- Basic: $5/month (100GB)
- Premium: $15/month (unlimited)
---
## Update Strategy
### Binary Updates
**Server Updates:**
```bash
# Download new version
wget https://releases.ospab.host/ostp-server-v2.0.0
# Backup current binary
cp /usr/local/bin/ostp-server /usr/local/bin/ostp-server.backup
# Replace binary
mv ostp-server-v2.0.0 /usr/local/bin/ostp-server
chmod +x /usr/local/bin/ostp-server
# Restart service
systemctl restart ostp-server
# Verify version
ostp-server --version
```
**Client Updates:**
- Provide download link via secure channel
- Include SHA256 hash for verification
- Document breaking changes
- Maintain compatibility for 1 version back
### Database Migrations
For schema changes:
```sql
-- Check current version
SELECT value FROM metadata WHERE key = 'schema_version';
-- Migrate v1 → v2
ALTER TABLE users ADD COLUMN last_seen DATETIME;
UPDATE metadata SET value = '2' WHERE key = 'schema_version';
```
---
## Incident Response
### Security Incident Playbook
**1. Detection:**
- Monitor alerts for anomalies
- Investigate suspicious patterns
- Verify authenticity of alerts
**2. Containment:**
- Isolate affected servers
- Block malicious IPs
- Rotate compromised PSKs
- Snapshot system state
**3. Eradication:**
- Identify root cause
- Patch vulnerabilities
- Remove backdoors
- Reset credentials
**4. Recovery:**
- Restore from clean backups
- Verify system integrity
- Monitor for reinfection
- Document timeline
**5. Post-Mortem:**
- Write incident report
- Implement prevention measures
- Update documentation
- Notify affected users (if required)
---
## Testing & Validation
### Pre-Deployment Checklist
- [ ] Server OS fully updated
- [ ] Firewall configured and tested
- [ ] OSTP server starts without errors
- [ ] PSK generated and secured
- [ ] Client successfully connects
- [ ] Traffic encrypted (verify with Wireshark)
- [ ] TLS mimicry working (check SNI)
- [ ] Anti-debug protection active (release build)
- [ ] Logs rotating correctly
- [ ] Backups automated and tested
- [ ] Monitoring alerts configured
- [ ] Documentation complete
### Performance Testing
```bash
# Simulate 100 concurrent connections
for i in {1..100}; do
ostp-client connect -s server:8443 -p $PSK -c US &
done
# Monitor server resources
htop
iotop
nethogs
```
### Security Testing
- **Port Scanning:** Verify only 8443 is open
- **DPI Testing:** Use GFW test tools to verify mimicry
- **Traffic Analysis:** Capture packets and analyze with Wireshark
- **Penetration Testing:** Hire professional auditors (recommended annually)
---
## Advanced Configurations
### Multi-Hop Routing
Chain OSTP servers for enhanced anonymity:
```
[Client] → [OSTP Server 1] → [OSTP Server 2] → [Internet]
```
Requires custom routing configuration.
### Split Tunneling
Route only specific traffic through VPN:
```bash
# Route only HTTPS through VPN
ip route add 0.0.0.0/0 via 10.8.0.1 table 100
ip rule add fwmark 1 table 100
iptables -t mangle -A OUTPUT -p tcp --dport 443 -j MARK --set-mark 1
```
### Bridge Mode
Allow clients to access LAN resources:
```
[OSTP Client] ←→ [OSTP Server] ←→ [Corporate LAN]
```
Requires NAT and routing configuration on server.
---
## Support & Maintenance
### Regular Maintenance Tasks
**Daily:**
- Check service status
- Review critical alerts
- Monitor disk space
**Weekly:**
- Review security logs
- Check backup integrity
- Update block lists (if applicable)
**Monthly:**
- Apply security updates
- Review user quotas
- Analyze performance metrics
- Test disaster recovery
**Quarterly:**
- Rotate PSKs
- Audit user access
- Review documentation
- Plan capacity upgrades
---
For additional guidance or enterprise support, contact ospab@ospab.host.
*Last updated: January 2026*

379
docs/SERVER.md Normal file
View File

@@ -0,0 +1,379 @@
# 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*