wgtool/SETUP_GUIDE.md

WireGuard Configuration Setup Guide

This guide provides a complete solution for creating WireGuard VPN configurations based on the patterns found in the TESTING/ directory.

Overview

The solution consists of three main components:

1. wireguard_setup.sh - Main interactive setup script
2. validate_config.sh - Configuration validation tool
3. example_setup.sh - Example automation script

Quick Start

1. Run the Setup Script

./wireguard_setup.sh

The script will guide you through:

• Generating private/public key pairs
• Setting up node configuration (client or server)
• Adding peers to your configuration
• Creating configuration files

2. Validate Your Configuration

./validate_config.sh wireguard_configs/your_node.conf

3. Deploy the Configuration

sudo cp wireguard_configs/your_node.conf /etc/wireguard/
sudo chmod 600 /etc/wireguard/your_node.conf
sudo wg-quick up your_node

Configuration Patterns

Based on the TESTING/ directory analysis, there are three main configuration types:

1. Client Configuration (aza.conf, galaxy.conf)

[Interface]
PrivateKey = <private_key>
Address = 10.8.0.x/24

[Peer]
PublicKey = <server_public_key>
AllowedIPs = 10.8.0.0/24
Endpoint = server.example.com:51820
PersistentKeepalive = 25

Use case: Simple client connecting to a central server (Zion included as default peer)

2. Server Configuration (zion.conf)

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = <private_key>
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = <client_public_key>
AllowedIPs = 10.8.0.x/32

Use case: Central hub server that routes traffic between clients

3. Hybrid Configuration (cth.conf, nyan.conf)

[Interface]
Address = 10.8.0.x/24
ListenPort = <port>
PrivateKey = <private_key>

[Peer]
PublicKey = <server_public_key>
AllowedIPs = 10.8.0.0/24
Endpoint = server.example.com:51820
PersistentKeepalive = 25

[Peer]
PublicKey = <direct_peer_public_key>
AllowedIPs = 10.8.0.y/32
Endpoint = peer.example.com:port
PersistentKeepalive = 25

Use case: Node that connects to central server AND has direct peer connections

Network Topology Examples

Star Topology (Most Common)

zion (10.8.0.1) - Central Server
├── aza (10.8.0.2) - Client
├── cth (10.8.0.10) - Hybrid
├── galaxy (10.8.0.99) - Client
└── nyan (10.8.0.20) - Client

Mesh Topology

zion (10.8.0.1) - Hub
├── cth (10.8.0.10) - Hybrid
│   └── nyan (10.8.0.20) - Direct peer
└── galaxy (10.8.0.99) - Client

Script Features

Main Setup Script (wireguard_setup.sh)

Features:

• Interactive step-by-step configuration
• Automatic key generation
• Input validation (IP addresses, ports, keys)
• Support for client, server, and hybrid configurations
• File overwrite protection to prevent accidental data loss
• Colored output for better readability
• Automatic summary file generation

Usage:

# Basic usage
./wireguard_setup.sh

# Custom output directory
./wireguard_setup.sh --dir /path/to/output

# Show help
./wireguard_setup.sh --help

Validation Script (validate_config.sh)

Features:

• Validates WireGuard configuration syntax
• Checks file permissions
• Validates key formats, IP addresses, ports
• Supports single file or directory validation
• Detailed error reporting

Usage:

# Validate single file
./validate_config.sh wireguard_configs/test.conf

# Validate all files in directory
./validate_config.sh wireguard_configs/

# Validate TESTING directory
./validate_config.sh TESTING/

Example Script (example_setup.sh)

Features:

• Demonstrates automated configuration creation
• Pre-configured examples for client and server setups
• Useful for testing and learning

Usage:

# Create client example
./example_setup.sh client

# Create server example
./example_setup.sh server

Step-by-Step Configuration Process

For a Client Node (like aza.conf)

1. Run the setup script:

   ./wireguard_setup.sh
   

2. Follow the prompts:

   • Node name: aza
   • IP address: 10.8.0.2/24
   • Server mode: n (no)
   • Add peer: y (yes)
   • Peer name: zion
   • Peer public key: <zion_public_key>
   • Allowed IPs: 10.8.0.0/24
   • Has endpoint: y (yes)
   • Endpoint: ugh.im:51820
   • Keepalive: 25
   • Add more peers: n (no)

3. Deploy:

   sudo cp wireguard_configs/aza.conf /etc/wireguard/
   sudo chmod 600 /etc/wireguard/aza.conf
   sudo wg-quick up aza
   

For a Server Node (like zion.conf)

1. Run the setup script:

   ./wireguard_setup.sh
   

2. Follow the prompts:

   • Node name: zion
   • IP address: 10.8.0.1/24
   • Server mode: y (yes)
   • Listen port: 51820
   • Add peers: y (yes)
   • Add each client as a peer (no endpoints needed)

3. Deploy:

   sudo cp wireguard_configs/zion.conf /etc/wireguard/
   sudo chmod 600 /etc/wireguard/zion.conf
   sudo wg-quick up zion
   

Security Best Practices

1. Key Management:

   • Never share private keys
   • Use unique keys for each node
   • Store keys securely

2. File Permissions:

   • Set config files to 600 permissions
   • Restrict access to configuration files

3. Network Security:

   • Use strong, unique keys
   • Configure appropriate firewall rules
   • Monitor network traffic

4. Deployment:

   • Test configurations before production
   • Use validation script to check syntax
   • Keep backups of configurations

Troubleshooting

Common Issues

1. "wg command not found"

   # Install WireGuard tools
   sudo apt install wireguard  # Ubuntu/Debian
   sudo yum install wireguard-tools  # CentOS/RHEL
   sudo pacman -S wireguard-tools  # Arch
   

2. "Permission denied"

   # Set correct permissions
   sudo chmod 600 /etc/wireguard/your_config.conf
   

3. Connection issues

   # Check WireGuard status
   sudo wg show
   
   # Check interface
   ip link show wg0
   
   # Check routing
   ip route show
   

4. Validation errors

   # Run validation script
   ./validate_config.sh your_config.conf
   

Debugging Commands

# Check WireGuard status
sudo wg show

# Check interface status
ip link show wg0

# Check routing table
ip route show

# Check firewall rules
sudo iptables -L -n -v

# Check system logs
sudo journalctl -u wg-quick@your_interface

File Structure

wireguard/
├── wireguard_setup.sh      # Main setup script
├── validate_config.sh      # Validation tool
├── example_setup.sh        # Example automation
├── README.md              # Main documentation
├── SETUP_GUIDE.md         # This guide
├── TESTING/               # Example configurations
│   ├── aza.conf          # Client example
│   ├── cth.conf          # Hybrid example
│   ├── galaxy.conf       # Client example
│   ├── nyan.conf         # Hybrid example
│   └── zion.conf         # Server example
└── wireguard_configs/    # Generated configurations
    ├── your_node.conf
    └── your_node_summary.txt

Next Steps

1. Test the scripts with the example configurations
2. Create your own configurations using the interactive script
3. Validate your configurations before deployment
4. Deploy and test your WireGuard network
5. Monitor and maintain your VPN setup

Support

For issues or questions:

1. Check the troubleshooting section
2. Run the validation script on your configurations
3. Review the example configurations in the TESTING/ directory
4. Check WireGuard documentation and community resources

The scripts are designed to be self-documenting and include extensive error checking to help you create valid configurations quickly and safely.