First Steps with WireBuddy¶

Once WireBuddy is installed and running, follow these steps to get your VPN up and running.

1. Initial Login¶

1. Navigate to http://localhost:8000 (or your server IP)
2. Login with default credentials:
3. Username: admin
4. Password: admin

2. Create Your First WireGuard Interface¶

Navigate to Settings → Interfaces¶

Click Settings in the sidebar, then select the Interfaces tab.

Click "Add Interface"¶

Fill in the interface details:

Advanced Settings¶

• MTU: Leave at 1420 (default for most networks)
• Pre/Post Up/Down: Custom commands (advanced users only)
• Firewall: Auto-configured by WireBuddy

Click Create Interface.

3. Start the Interface¶

After creation, the interface appears in the list. Click the Start button to activate it.

# On the host
sudo wg show

# Should display your interface:
interface: wg0
  public key: <your-public-key>
  private key: (hidden)
  listening port: 51820

3. Add Your First Peer (Client)¶

Navigate to Peers¶

Click Peers in the sidebar.

Click "Add Peer"¶

Configure the peer:

Routing Modes¶

WireBuddy offers three routing presets:

Advanced Peer Options¶

• Persistent Keepalive: 25 seconds (recommended for NAT traversal)
• Preshared Key: Optional additional encryption layer
• Use WireBuddy DNS: Route DNS through WireBuddy's resolver for ad-blocking. When disabled, clients use Cloudflare (1.1.1.1) and Quad9 (9.9.9.9)

Click Create Peer.

4. Configure the Client Device¶

After creating the peer, WireBuddy displays several options:

Option 1: QR Code (Mobile Devices)¶

Click Show QR Code and scan it with:

• iOS: WireGuard app from App Store
• Android: WireGuard app from Play Store

Option 2: Download Config File¶

Click Download Config and import into:

• Windows: WireGuard for Windows
• macOS: WireGuard for macOS
• Linux: Use wg-quick:

  sudo cp john-iphone.conf /etc/wireguard/wg0-client.conf
  sudo wg-quick up wg0-client
  

Option 3: Copy Configuration¶

Click Copy Config to get the configuration text directly.

[Interface]
PrivateKey = <client-private-key>
Address = 10.8.0.2/32
DNS = 10.8.0.1

[Peer]
PublicKey = <server-public-key>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

5. Test the Connection¶

On the Client¶

1. Activate the WireGuard connection
2. Verify connectivity:

   # Ping the VPN server
   ping 10.8.0.1
   
   # Check your public IP
   curl https://ifconfig.me
   # Should show your server's IP
   

In WireBuddy Dashboard¶

Navigate to Dashboard and verify:

• ✅ Peer shows as Connected (green)
• 📊 Traffic counters are increasing
• 🕒 Last handshake is recent (< 3 minutes)

6. Enable DNS Ad-Blocking (Optional)¶

WireBuddy includes an integrated Unbound DNS resolver with ad-blocking.

Navigate to DNS Settings¶

Click Settings → DNS tab.

Configure DNS¶

1. Enable DNS Resolver: Toggle ON
2. Select Blocklists:
3. StevenBlack (recommended for most users)
4. HaGeZi Pro (more aggressive blocking)
5. DNS-over-TLS: Enable for upstream privacy
6. Click Save Changes

Update Peer DNS Settings¶

Edit your peer and set:

• DNS: 10.8.0.1 (your WireGuard server IP)
• Click Update Peer

Regenerate the client config with the new DNS settings.

Monitor DNS Queries¶

Navigate to DNS page to see:

• Real-time query log
• Blocked query statistics
• Top queried domains
• Client-specific queries

7. Set Up Additional Users (Optional)¶

For multi-user environments:

Navigate to Settings → Users¶

1. Click Add User
2. Fill in details:
3. Username: john
4. Email: john@example.com
5. Role: User (read-only) or Admin
6. Set initial password
7. Click Create User

Enable MFA¶

For enhanced security:

1. User logs in
2. Click username → Enable 2FA
3. Scan QR code with authenticator app (Authy, Google Authenticator)
4. Enter verification code

Enable Passkeys (WebAuthn)¶

For passwordless authentication:

1. User navigates to Passkeys in settings
2. Click Add Passkey
3. Follow browser prompts (Touch ID, Windows Hello, security key)

8. Configure Let's Encrypt (Optional)¶

For automatic SSL certificates:

Navigate to Settings → ACME¶

1. Enable ACME: Toggle ON
2. Domain: Enter your domain (e.g., vpn.example.com)
3. Email: Contact email for Let's Encrypt
4. Challenge Type: HTTP-01 (requires port 80 accessible)
5. Click Request Certificate

9. Review Security Settings¶

Navigate to Settings → Security:

• ✅ Force HTTPS: Enable if using SSL
• ✅ Session Timeout: Set to 30 minutes for security
• ✅ Rate Limiting: Enabled by default
• ✅ Require Strong Passwords: Enforce complexity

Next Steps¶

You're now ready to use WireBuddy! Continue with:

• WireGuard Management - Advanced features
• DNS Configuration - Custom rules and blocklists
• Monitoring - Traffic analytics and GeoIP
• Security Best Practices - Harden your setup

Common Questions¶

# Backup
tar czf wirebuddy-backup-$(date +%Y%m%d).tar.gz data/

# Restore
tar xzf wirebuddy-backup-YYYYMMDD.tar.gz