chore: initial commit of wgtool
This commit is contained in:
sapient
339
SETUP_GUIDE.md
Normal file
339
SETUP_GUIDE.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user