ospab.network/dist/ostp-client-linux/README.md

OSTP Client - Linux x64 CLI

Universal Linux VPN client with TUN interface support (statically linked with musl).

📦 Contents

• ostp-client-linux (2.0 MB) - CLI VPN client with profile management
• SHA256SUMS - Integrity verification checksum
• client.json.example - Configuration file template

🚀 Quick Start

1. Verify Integrity

sha256sum -c SHA256SUMS

2. Install

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

3. Setup Profile (Interactive)

ostp-client-linux setup

The wizard will prompt for:

• Server address (e.g., vpn.example.com:443)
• Pre-shared key (64 hex characters - get from admin)
• Country code for SNI mimicry (US, RU, DE, NO, CN, etc.)
• Profile name (e.g., "US-West", "RU-Moscow")

4. Connect

# 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_64_CHAR_HEX_PSK \
  --country US

5. Check Status

ostp-client-linux status

Output:

🌍 VPN Connection Status

   Status: Connected
   Interface:  ostp0
   RX Bytes:   123 MB
   TX Bytes:   456 MB
   RX Packets: 98765
   TX Packets: 54321

6. Disconnect

sudo ostp-client-linux disconnect

🛠️ Commands

Connection Management

# Connect with profile
sudo ostp-client-linux connect --profile <name>

# Connect with parameters
sudo ostp-client-linux connect \
  --server <ip:port> \
  --psk <hex_key> \
  --country <code>

# Run in background (daemon mode)
sudo ostp-client-linux connect --profile default --daemon

# Disconnect
sudo ostp-client-linux disconnect

# Show status
ostp-client-linux status

Profile Management

# List all profiles
ostp-client-linux profiles list

# Add new profile
ostp-client-linux profiles add \
  --name "US-West" \
  --server 1.2.3.4:443 \
  --psk YOUR_PSK \
  --country US

# Remove profile
ostp-client-linux profiles remove "US-West"

# Set default profile
ostp-client-linux profiles set-default "US-West"

Testing

# Test connection (handshake only, no tunnel)
ostp-client-linux test \
  --server 1.2.3.4:443 \
  --psk YOUR_PSK

📂 Configuration

Profile Storage

Profiles are stored at: ~/.config/ostp/profiles.json

{
  "profiles": [
    {
      "name": "US-West",
      "server": "1.2.3.4:443",
      "psk": "64_character_hex_key",
      "country": "US"
    },
    {
      "name": "RU-Moscow",
      "server": "5.6.7.8:443",
      "psk": "another_64_char_hex_key",
      "country": "RU"
    }
  ],
  "default_profile": "US-West"
}

Manual Configuration

You can also edit client.json for advanced settings:

{
  "server": "vpn.example.com:443",
  "psk": "your_64_character_hex_psk_key",
  "country": "US",
  "auto_connect": false,
  "kill_switch": true,
  "dns_servers": ["1.1.1.1", "8.8.8.8"]
}

🔐 Security Features

Stealth Mode

• TLS 1.3 Mimicry - Looks like HTTPS traffic to DPI systems
• Geo-specific SNI - Uses country-appropriate domains (cloudflare.com, google.com, etc.)
• UDP-over-TCP Framing - Random padding to avoid pattern detection
• No Protocol Signatures - Unidentifiable traffic

Anti-Analysis (Production Build)

• VM Detection - Refuses to run in analysis sandboxes
• Debugger Detection - Exits if debugger attached
• Tool Detection - Checks for IDA, Ghidra, GDB, strace, etc.
• Weighted Scoring - Smart heuristics to avoid false positives on VPS

Encryption

• AEAD Cipher: ChaCha20-Poly1305
• Key Exchange: X25519 ECDH
• PSK Validation: HMAC-SHA256 with silent drop

🌐 Network Configuration

After successful connection:

• Interface: ostp0 (TUN device)
• Client IP: Assigned by Master Node (10.X.Y.Z/16)
• Gateway: Master Node (10.X.0.1)
• DNS: Configurable (default: 1.1.1.1, 8.8.8.8)
• MTU: 1420 (optimized for tunneling)

🖥️ System Requirements

• OS: Any Linux distribution (kernel 3.10+)
• Architecture: x86_64 (AMD64)
• RAM: 64 MB minimum
• Privileges: Root required for TUN interface
• Dependencies: None (static binary with musl)

🔧 Troubleshooting

Permission Denied

# Solution: Run with sudo
sudo ostp-client-linux connect --profile default

No TUN Interface

# Check if TUN module is loaded
lsmod | grep tun

# Load TUN module
sudo modprobe tun

# Make persistent (add to /etc/modules)
echo "tun" | sudo tee -a /etc/modules

Connection Fails

# Test handshake only
ostp-client-linux test --server 1.2.3.4:443 --psk YOUR_PSK

# Check if server is reachable
ping 1.2.3.4
telnet 1.2.3.4 443

# Check logs (if running in daemon mode)
sudo journalctl -f | grep ostp

Profile Not Found

# List available profiles
ostp-client-linux profiles list

# Create new profile
ostp-client-linux setup

DNS Not Working

# Check DNS configuration
cat /etc/resolv.conf

# Manually set DNS
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf

# Or use systemd-resolved
sudo systemctl restart systemd-resolved

📊 Performance Tips

Optimize MTU

# Find optimal MTU
ping -M do -s 1472 1.1.1.1

# Set custom MTU (after connection)
sudo ip link set ostp0 mtu 1400

Background Mode

# Run in background
sudo ostp-client-linux connect --profile default --daemon

# Check if running
ostp-client-linux status

Kill Switch (TODO)

Automatically block all traffic when VPN disconnects:

# Configure in client.json
"kill_switch": true

🔄 Updates

Check for updates:

ostp-client-linux --version

Download latest release from:

• GitHub: https://github.com/ospab/ospab.network/releases
• Gitea: http://localhost:4000/ospab/ospab.network/releases

📚 Advanced Usage

Multiple Profiles

# Add multiple profiles for different regions
ostp-client-linux profiles add --name US --server us.vpn.com:443 --psk KEY1 --country US
ostp-client-linux profiles add --name RU --server ru.vpn.com:443 --psk KEY2 --country RU
ostp-client-linux profiles add --name DE --server de.vpn.com:443 --psk KEY3 --country DE

# Switch between profiles
sudo ostp-client-linux disconnect
sudo ostp-client-linux connect --profile RU

Scripting

#!/bin/bash
# Auto-connect script

if ! ostp-client-linux status | grep -q "Connected"; then
    echo "Connecting to VPN..."
    sudo ostp-client-linux connect --profile default --daemon
    sleep 3
    
    if ostp-client-linux status | grep -q "Connected"; then
        echo "✓ Connected successfully"
    else
        echo "✗ Connection failed"
        exit 1
    fi
fi

Systemd Service

Create /etc/systemd/system/ostp-client.service:

[Unit]
Description=OSTP VPN Client
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/ostp-client-linux connect --profile default
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable ostp-client
sudo systemctl start ostp-client

⚠️ Important Notes

• Root Required: TUN interface creation requires root privileges
• PSK Security: Never share your PSK publicly or commit to git
• Production Mode: Anti-analysis checks only run in release builds
• Single Instance: Only one client can run at a time
• Network Changes: Route tables are modified during connection

🆘 Support

For issues and questions:

• GitHub Issues: https://github.com/ospab/ospab.network/issues
• Documentation: See project README.md
• Email: support@ospab.network

📝 Version History

• 0.1.0 (January 2, 2026)
  • Initial release
  • Profile management system
  • TLS mimicry with geo-SNI
  • Anti-VM/debugger detection
  • Interactive setup wizard

---

Version: 0.1.0
Build Date: January 2, 2026
License: Proprietary
Copyright: © 2026 Ospab Network