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

```bash
sha256sum -c SHA256SUMS
```

### 2. Install

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

### 3. Setup Profile (Interactive)

```bash
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

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

### 5. Check Status

```bash
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

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

## 🛠️ Commands

### Connection Management

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

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

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

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

```json
{
  "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

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

### No TUN Interface

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

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

```bash
# List available profiles
ostp-client-linux profiles list

# Create new profile
ostp-client-linux setup
```

### DNS Not Working

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

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

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

```bash
# Configure in client.json
"kill_switch": true
```

## 🔄 Updates

Check for updates:
```bash
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

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

```bash
#!/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`:

```ini
[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:
```bash
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