wireguard-lab-overlay/GETTING_STARTED.md

Getting Started with WireGuard Lab Overlay

Prerequisites

On Management Server

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
    terraform \
    ansible \
    python3-pip \
    git \
    docker.io \
    docker-compose

# Install Ansible collections
ansible-galaxy collection install community.routeros
ansible-galaxy collection install ansible.netcommon

# Install Python packages
pip3 install librouteros prometheus-client

On Linux Gateways

# Ensure WireGuard is available
sudo apt-get install -y wireguard wireguard-tools bridge-utils python3

On MikroTik Routers

• RouterOS 7.6 or higher
• API access enabled
• Admin credentials

Initial Setup

Step 1: Configure Your Lab Networks

1. Copy the example configuration:

cd terraform
cp terraform.tfvars.example terraform.tfvars

2. Edit terraform.tfvars with your lab networks:

lab_networks = {
  lab100 = {
    vni           = 100
    subnet        = "10.100.0.0/24"
    wireguard_net = "172.16.100.0/24"
    dhcp_mode     = "simple"  # or "failover"
    road_warrior  = false     # Enable later
    gateways = [
      {
        hostname  = "lab100-gw1"
        type      = "linux"
        mgmt_ip   = "192.168.1.11"  # Change to your IPs
        api_port  = 22
        lab_if    = "eth1"  # Interface facing lab devices
        dhcp_role = "primary"
      },
      {
        hostname  = "lab100-gw2"
        type      = "linux"
        mgmt_ip   = "192.168.1.12"
        api_port  = 22
        lab_if    = "eth1"
        dhcp_role = "secondary"
      }
    ]
  }
}

Step 2: Set Up Ansible

1. Configure SSH access to your gateways:

ssh-copy-id admin@192.168.1.11
ssh-copy-id admin@192.168.1.12

2. For MikroTik devices, create vault password:

cd ansible
echo "your-vault-password" > .vault_pass
chmod 600 .vault_pass

3. Encrypt MikroTik credentials:

ansible-vault create inventory/group_vars/mikrotik_gateways.yml

Add:

ansible_password: your-mikrotik-password

Step 3: Deploy

Option A: Automated (Recommended)

./deploy.sh

Option B: Manual Steps

# 1. Initialize and apply Terraform
cd terraform
terraform init
terraform apply
terraform output -json > outputs.json

# 2. Generate Ansible inventory
terraform output ansible_inventory > ../ansible/inventory/hosts.yml

# 3. Deploy to gateways
cd ../ansible
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# 4. Start monitoring
cd ../monitoring
docker-compose up -d

Step 4: Verify Deployment

# Check gateway health
cd ansible
ansible-playbook playbooks/health-check.yml

# Check WireGuard tunnels
ansible linux_gateways -m shell -a "wg show"

# Check bridges
ansible linux_gateways -m shell -a "ip link show type bridge"

Common Tasks

Add Road Warrior Access

1. Edit terraform/terraform.tfvars:

lab_networks = {
  lab100 = {
    road_warrior = true  # Enable this
    # ...
  }
}

road_warrior_users = {
  "jdoe" = {
    email = "john.doe@company.com"
    labs  = ["lab100"]
  }
}

2. Apply changes:

cd terraform
terraform apply
cd ../ansible
ansible-playbook playbooks/generate-road-warrior.yml

3. Distribute configs:

ls ../road-warrior/generated/jdoe/
# lab100.conf - WireGuard config file
# lab100-qr.html - QR code for mobile devices

Add New Lab Network

ansible-playbook playbooks/add-lab-network.yml

Follow the prompts to configure the new lab.

Emergency Shutdown

ansible-playbook playbooks/emergency-shutdown.yml

Restore Lab

ansible-playbook playbooks/restore-lab.yml

Monitoring

Access the monitoring stack:

• Grafana: http://your-server:3000

  • Username: admin
  • Password: admin

• Prometheus: http://your-server:9090

Troubleshooting

WireGuard tunnel not coming up

# On gateway:
sudo wg show
sudo journalctl -u wg-quick@wg-lab100 -n 50

# Check connectivity
ping <peer-wireguard-ip>

DHCP not working

# Check DHCP server
sudo systemctl status dnsmasq
# or for failover mode:
sudo systemctl status isc-dhcp-server

# Check leases
sudo tail -f /var/lib/misc/dnsmasq.lab100.leases

Can't reach lab devices

1. Check bridge is up:

ip link show br-lab100

2. Check VXLAN interface:

ip -d link show vxlan100

3. Check FDB entries:

bridge fdb show br br-lab100

Next Steps

• Read docs/architecture.md for detailed architecture
• Read docs/operations.md for operational procedures
• Set up alerting in Grafana
• Configure backup for Terraform state
• Implement proper secret management (HashiCorp Vault)

Support

For issues:

1. Check logs: journalctl -u wg-quick@wg-lab*
2. Run health check: ansible-playbook playbooks/health-check.yml
3. Review documentation in docs/