# OSTP Linux Server Binaries

## Binaries

- **ostp-server** (4.0 MB) - OSTP Stealth VPN Server
- **oncp-master** (4.7 MB) - CDN Control Plane Master Node

## System Requirements

- **OS**: Linux x86_64 (Debian 13+ / Ubuntu 24.04+ / RHEL 9+)
- **glibc**: 2.41+ (built on Debian Trixie)
- **Libraries**: libssl3, libcrypto3
- **Privileges**: Root/sudo required for:
  - Binding to privileged ports (< 1024)
  - TUN device creation
  - System DNS modification

## Installation

### 1. Install System Dependencies

**Debian/Ubuntu:**
```bash
sudo apt update
sudo apt install -y libssl3 openssl ca-certificates
```

**RHEL/Rocky/AlmaLinux:**
```bash
sudo dnf install -y openssl-libs openssl ca-certificates
```

### 2. Deploy Binaries

```bash
# Copy binaries
sudo cp ostp-server oncp-master /usr/local/bin/
sudo chmod +x /usr/local/bin/{ostp-server,oncp-master}

# Verify
ostp-server --version
oncp-master --version
```

## ostp-server Setup

### Generate PSK

```bash
ostp-server gen-key
```

Save the output securely - this is your Pre-Shared Key.

### Configuration File

Create `/etc/ostp/server.json`:

```json
{
  "listen": "0.0.0.0:8443",
  "psk": "YOUR_64_CHAR_HEX_PSK_HERE",
  "max_connections": 1024,
  "log_level": "info"
}
```

### Node Enrollment (Optional)

For automatic CDN registration:

```json
{
  "listen": "0.0.0.0:8443",
  "psk": "AUTO",
  "master_node_url": "https://master.ospab.internal:8080",
  "node_name": "node-us-west-1",
  "hardware_id": "unique-hardware-id",
  "region": "us-west",
  "country_code": "US",
  "max_connections": 1024,
  "log_level": "info"
}
```

When `psk: "AUTO"`, the server will:
1. Submit enrollment request to master node
2. Display Node ID
3. Wait for administrator approval
4. Update config with approved PSK

### Systemd Service

Create `/etc/systemd/system/ostp-server.service`:

```ini
[Unit]
Description=OSTP Stealth VPN Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/ostp-server -c /etc/ostp/server.json
Restart=on-failure
RestartSec=10s
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/etc/ostp

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

## oncp-master Setup

### Initialize Database

```bash
# Create data directory
sudo mkdir -p /var/lib/oncp
cd /var/lib/oncp

# Initialize (creates oncp.db)
oncp-master stats
```

### Configuration

Create `/etc/oncp/config.env`:

```bash
ONCP_DATABASE=/var/lib/oncp/oncp.db
ONCP_LISTEN=0.0.0.0:8080
RUST_LOG=info
```

### Run API Server

```bash
oncp-master serve --listen 0.0.0.0:8080
```

### Systemd Service

Create `/etc/systemd/system/oncp-master.service`:

```ini
[Unit]
Description=ONCP Master Node - CDN Control Plane
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=oncp
Group=oncp
WorkingDirectory=/var/lib/oncp
EnvironmentFile=/etc/oncp/config.env
ExecStart=/usr/local/bin/oncp-master serve --listen 0.0.0.0:8080 --database /var/lib/oncp/oncp.db
Restart=on-failure
RestartSec=10s

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/oncp

[Install]
WantedBy=multi-user.target
```

Create user and start:

```bash
sudo useradd -r -s /bin/false oncp
sudo chown -R oncp:oncp /var/lib/oncp
sudo systemctl daemon-reload
sudo systemctl enable oncp-master
sudo systemctl start oncp-master
sudo systemctl status oncp-master
```

## Node Enrollment Workflow

### On Master Node:

```bash
# List pending enrollment requests
oncp-master node pending

# Approve node (generates PSK)
oncp-master node approve <NODE_ID>

# Copy the generated PSK
```

### On Server Node:

Update `/etc/ostp/server.json` with approved PSK:

```json
{
  "listen": "0.0.0.0:8443",
  "psk": "APPROVED_PSK_FROM_MASTER_HERE",
  "master_node_url": "https://master.ospab.internal:8080",
  ...
}
```

Restart server:

```bash
sudo systemctl restart ostp-server
```

## Management Commands

### oncp-master CLI

```bash
# Dashboard (live monitoring)
oncp-master dashboard

# Node management
oncp-master node list
oncp-master node add -n "node-1" -a "1.2.3.4:8443" -c US
oncp-master node pending
oncp-master node approve <NODE_ID>
oncp-master node reject <NODE_ID>

# User management
oncp-master user list
oncp-master user create -q 100 -d 30
oncp-master user config <USER_UUID>

# SNI management
oncp-master sni list
oncp-master sni add cloudflare.com -c US
oncp-master sni block example.com

# Statistics
oncp-master stats
```

### ostp-server CLI

```bash
# Generate PSK
ostp-server gen-key

# Run with config
ostp-server -c /etc/ostp/server.json

# Run with CLI args
ostp-server -l 0.0.0.0:8443 -p <PSK_HEX>
```

## API Endpoints

Master Node REST API (default port 8080):

- `GET /health` - Health check
- `GET /api/v1/nodes` - List nodes
- `POST /api/v1/nodes` - Register node
- `POST /api/v1/nodes/:id/checkin` - Node heartbeat
- `GET /api/v1/nodes/best?country=US&limit=3` - CDN steering
- `POST /api/v1/enrollment/request` - Submit enrollment
- `GET /api/v1/enrollment/pending` - List pending
- `POST /api/v1/enrollment/:id/approve` - Approve node
- `GET /api/v1/users` - List users
- `POST /api/v1/users` - Create user
- `GET /api/v1/sni` - List SNIs
- `POST /api/v1/sni` - Update SNI
- `GET /api/v1/stats` - Network statistics

## Firewall Configuration

### ostp-server (Server Node)

```bash
# Allow OSTP port
sudo ufw allow 8443/tcp comment 'OSTP Server'

# Allow outbound to master node
sudo ufw allow out 8080/tcp comment 'ONCP Master'
```

### oncp-master (Master Node)

```bash
# Allow API access
sudo ufw allow 8080/tcp comment 'ONCP API'

# Restrict to server IPs only (recommended)
sudo ufw allow from <SERVER_IP> to any port 8080 proto tcp
```

## Logs

```bash
# ostp-server logs
sudo journalctl -u ostp-server -f

# oncp-master logs
sudo journalctl -u oncp-master -f
```

## Troubleshooting

### Check Binary Compatibility

```bash
ldd ostp-server
ldd oncp-master
```

If you see "not found" errors, install missing libraries.

### Check glibc Version

```bash
ldd --version
```

Required: glibc 2.41+ (Debian 13+ / Ubuntu 24.04+)

For older distributions, build from source:

```bash
cargo build -p ostp-server -p oncp-master --release --target x86_64-unknown-linux-musl
```

### Permission Errors

Ensure running as root or with appropriate capabilities:

```bash
sudo setcap cap_net_bind_service,cap_net_admin+ep /usr/local/bin/ostp-server
```

### Network Connectivity

Test master node API:

```bash
curl http://localhost:8080/health
```

Expected: `{"status":"ok","version":"0.1.0","nodes_online":0}`

## Security Notes

1. **PSK Protection**: Never commit PSKs to version control
2. **TLS**: Use reverse proxy (nginx/caddy) for TLS termination on API
3. **Firewall**: Restrict master node API to known server IPs
4. **Updates**: Keep binaries updated for security patches
5. **Monitoring**: Use `oncp-master dashboard` for network health

## Support

- GitHub: https://github.com/ospab/ospab.network
- Issues: https://github.com/ospab/ospab.network/issues

## Build Info

- **Built**: January 2, 2026
- **Rust**: 1.85.0
- **Target**: x86_64-unknown-linux-gnu
- **glibc**: 2.41 (Debian Trixie)
- **Profile**: Release (optimized)