valleyforge/resist-vpn-infra
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
resist-vpn-infra/docs/USAGE.md
Sparticus 28db1d2104 CIS + inital
2026-01-26 21:22:41 -05:00

7.7 KiB
Raw Permalink Blame History

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

# 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

# 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

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

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

Single server:

all:
  children:
    vpn_servers:
      hosts:
        vpn-node1:
          ansible_host: 185.112.147.205
          ansible_user: root

Multiple servers:

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:

nano inventory/group_vars/vpn_servers.yml

Minimal configuration:

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

# 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):

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

Partial Deployment

Deploy specific components:

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

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

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

Post-Deployment

Retrieve Client Configs

# 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):

Mobile users (iOS/Android):

  • Send QR code text file
  • Install WireGuard app
  • Scan QR code: cat alice_qr.txt

Verify Deployment

# 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:
nano inventory/group_vars/vpn_servers.yml
  1. Add user to wg_peers:
wg_peers:
  - name: alice
  - name: bob
  - name: charlie
  - name: dave  # New user
  1. Re-run playbook:
ansible-playbook -i inventory/production.yml playbooks/wireguard.yml
  1. Retrieve new config:
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:
ssh root@185.112.147.205
rm /etc/wireguard/keys/dave_*

Rotate Keys

# 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

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

Monitor Logs

# 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

# 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):

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

Advanced Usage

Custom SSH Port

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

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

vpn_only_mode: false

⚠️ Not recommended for production!

Custom Firewall Rules

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:

# 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

# 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

# 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 for security best practices
  • Read TROUBLESHOOTING.md for common issues
  • Set up monitoring and alerting
  • Configure backups
  • Document your deployment