resist-vpn-infra/docs/USAGE.md

# Usage Guide

## Installation

### Prerequisites

**Control Machine** (your laptop/desktop):
- Linux or macOS
- Python 3.8+
- Ansible 2.15+
- SSH client

**Target Servers**:
- Ubuntu 24.04 LTS (or 22.04)
- Root or sudo access
- SSH key authentication configured
- Minimum 1GB RAM, 10GB disk

### Step 1: Install Ansible

```bash
# Using pip
pip3 install ansible

# Or using your package manager
# Ubuntu/Debian
sudo apt install ansible

# macOS
brew install ansible
```

### Step 2: Clone/Download Collection

```bash
# If from Git
git clone https://github.com/your-org/secure-vpn-server.git
cd secure-vpn-server

# Install dependencies
pip3 install -r requirements.txt
ansible-galaxy collection install -r requirements.yml
```

### Step 3: Configure SSH Access

```bash
# Generate SSH key if you don't have one
ssh-keygen -t ed25519

# Copy to server
ssh-copy-id root@185.112.147.205

# Test access
ssh root@185.112.147.205 "echo Connected"
```

## Configuration

### Inventory Setup

Create your inventory file:

```bash
cp inventory/hosts.yml inventory/production.yml
nano inventory/production.yml
```

**Single server**:
```yaml
all:
  children:
    vpn_servers:
      hosts:
        vpn-node1:
          ansible_host: 185.112.147.205
          ansible_user: root
```

**Multiple servers**:
```yaml
all:
  children:
    vpn_servers:
      hosts:
        vpn-node1:
          ansible_host: 185.112.147.205
          ansible_user: root
        vpn-node2:
          ansible_host: 203.0.113.11
          ansible_user: root
        vpn-node3:
          ansible_host: 203.0.113.12
          ansible_user: root
```

### Variable Configuration

Edit group variables:

```bash
nano inventory/group_vars/vpn_servers.yml
```

**Minimal configuration**:
```yaml
# WireGuard users
wg_peers:
  - name: alice
  - name: bob
  - name: charlie

# VPN network
wg_network: "10.100.0.0/24"

# Enable VPN-only access
vpn_only_mode: true
```

**Advanced configuration**:
```yaml
# System settings
system_timezone: "America/New_York"
ssh_port: 2222  # Custom SSH port

# WireGuard settings
wg_network: "10.100.0.0/24"
wg_server_ip: "10.100.0.1"
wg_port: 51820

# WireGuard users with manual IPs
wg_peers:
  - name: alice
    ip: 10.100.0.10
  - name: bob
    ip: 10.100.0.11
  - name: charlie
    ip: 10.100.0.12

# Firewall settings
vpn_only_mode: true
management_ports:
  - port: 2222
    proto: tcp
    comment: "SSH"
  - port: 8080
    proto: tcp
    comment: "Outline Manager"

# Security features
fail2ban_enabled: true
auditd_enabled: true
unattended_upgrades_enabled: true
```

## Deployment

### Full Deployment

Deploy everything (hardening + VPN + firewall):

```bash
ansible-playbook -i inventory/production.yml playbooks/site.yml
```

### Partial Deployment

Deploy specific components:

```bash
# Only hardening
ansible-playbook -i inventory/production.yml playbooks/hardening.yml

# Only WireGuard
ansible-playbook -i inventory/production.yml playbooks/wireguard.yml

# Only firewall
ansible-playbook -i inventory/production.yml playbooks/firewall.yml
```

### Targeted Deployment

Deploy to specific servers:

```bash
# Single server
ansible-playbook -i inventory/production.yml playbooks/site.yml --limit vpn-node1

# Multiple servers
ansible-playbook -i inventory/production.yml playbooks/site.yml --limit vpn-node1,vpn-node2
```

### Dry Run

Test without making changes:

```bash
ansible-playbook -i inventory/production.yml playbooks/site.yml --check --diff
```

## Post-Deployment

### Retrieve Client Configs

```bash
# Download all configs
scp -r root@185.112.147.205:/root/wireguard-client-configs/ ./

# View configs
ls wireguard-client-configs/
# alice.conf  alice_qr.txt
# bob.conf    bob_qr.txt
# charlie.conf charlie_qr.txt
```

### Distribute to Users

**Desktop users** (Linux/macOS/Windows):
- Send `.conf` file
- Install WireGuard: https://www.wireguard.com/install/
- Import config

**Mobile users** (iOS/Android):
- Send QR code text file
- Install WireGuard app
- Scan QR code: `cat alice_qr.txt`

### Verify Deployment

```bash
# Check services on server
ssh root@185.112.147.205

# WireGuard status
sudo wg show

# Firewall status
sudo ufw status verbose

# Service status
systemctl status wg-quick@wg0
systemctl status fail2ban
systemctl status auditd
```

## User Management

### Add New Users

1. Edit variables:
```bash
nano inventory/group_vars/vpn_servers.yml
```

2. Add user to `wg_peers`:
```yaml
wg_peers:
  - name: alice
  - name: bob
  - name: charlie
  - name: dave  # New user
```

3. Re-run playbook:
```bash
ansible-playbook -i inventory/production.yml playbooks/wireguard.yml
```

4. Retrieve new config:
```bash
scp root@185.112.147.205:/root/wireguard-client-configs/dave.conf ./
```

### Remove Users

1. Remove from `wg_peers` list
2. Re-run playbook
3. Manually remove keys from server:
```bash
ssh root@185.112.147.205
rm /etc/wireguard/keys/dave_*
```

### Rotate Keys

```bash
# Backup old keys
ssh root@185.112.147.205
cp -r /etc/wireguard/keys /root/wireguard-keys-backup-$(date +%Y%m%d)

# Remove old keys
rm -rf /etc/wireguard/keys/*

# Re-run playbook to generate new keys
ansible-playbook -i inventory/production.yml playbooks/wireguard.yml

# Distribute new configs to all users
```

## Maintenance

### Update System Packages

```bash
# Automatic updates are enabled by default
# Manual update:
ssh root@185.112.147.205
apt update && apt upgrade -y
```

### Monitor Logs

```bash
# WireGuard logs
journalctl -u wg-quick@wg0 -f

# SSH attempts
journalctl -u sshd -f

# Fail2ban
journalctl -u fail2ban -f

# Audit logs
ausearch -ts recent
```

### Backup Configuration

```bash
# Backup from server
ssh root@185.112.147.205
tar czf /root/vpn-backup-$(date +%Y%m%d).tar.gz \
  /etc/wireguard/ \
  /root/wireguard-client-configs/ \
  /etc/ssh/sshd_config \
  /etc/ufw/

# Download backup
scp root@185.112.147.205:/root/vpn-backup-*.tar.gz ./
```

### Re-run Playbook

Safe to re-run anytime (idempotent):

```bash
ansible-playbook -i inventory/production.yml playbooks/site.yml
```

## Advanced Usage

### Custom SSH Port

```yaml
# In group_vars/vpn_servers.yml
ssh_port: 2222

management_ports:
  - port: 2222  # Update firewall rule
    proto: tcp
    comment: "SSH"
```

### Multiple VPN Networks

Deploy separate VPN servers with different networks:

```yaml
# vpn-node1 (group_vars or host_vars)
wg_network: "10.100.0.0/24"

# vpn-node2
wg_network: "10.101.0.0/24"
```

### Disable VPN-Only Mode

Allow management access from internet:

```yaml
vpn_only_mode: false
```

⚠️ **Not recommended for production!**

### Custom Firewall Rules

```yaml
management_ports:
  - port: 22
    proto: tcp
    comment: "SSH"
  - port: 8080
    proto: tcp
    comment: "Outline Manager"
  - port: 8065
    proto: tcp
    comment: "Mattermost"
  - port: 443
    proto: tcp
    comment: "HTTPS"

public_ports:
  - port: 51820
    proto: udp
    comment: "WireGuard"
  - port: 80
    proto: tcp
    comment: "HTTP (public website)"
```

## Testing

### Test VPN Connection

**Desktop**:
```bash
# Import config
sudo wg-quick up alice

# Check connection
curl https://ifconfig.me
# Should show server IP

# Disconnect
sudo wg-quick down alice
```

**Mobile**:
1. Import config via QR code
2. Connect
3. Visit https://ifconfig.me
4. Verify server IP

### Test VPN-Only Access

```bash
# Before VPN: SSH should fail (if vpn_only_mode enabled)
ssh root@185.112.147.205
# Connection refused or timeout

# Connect to VPN
sudo wg-quick up alice

# After VPN: SSH should work
ssh root@10.100.0.1
# Connected!
```

### Test Firewall

```bash
# Check open ports from outside
nmap -p 22,51820 185.112.147.205

# Should show:
# 22/tcp closed (if vpn_only_mode)
# 51820/udp open
```

## Next Steps

- Read [SECURITY.md](SECURITY.md) for security best practices
- Read [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
- Set up monitoring and alerting
- Configure backups
- Document your deployment