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
```bash
./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
```bash
./validate_config.sh wireguard_configs/your_node.conf
```

### 3. Deploy the Configuration
```bash
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)
```ini
[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)
```ini
[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)
```ini
[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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
   ```bash
   ./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:**
   ```bash
   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:**
   ```bash
   ./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:**
   ```bash
   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"**
   ```bash
   # 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"**
   ```bash
   # Set correct permissions
   sudo chmod 600 /etc/wireguard/your_config.conf
   ```

3. **Connection issues**
   ```bash
   # Check WireGuard status
   sudo wg show
   
   # Check interface
   ip link show wg0
   
   # Check routing
   ip route show
   ```

4. **Validation errors**
   ```bash
   # Run validation script
   ./validate_config.sh your_config.conf
   ```

### Debugging Commands

```bash
# 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.