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:

WireBuddy allocates the peer's VPN address automatically from the selected interface.

Routing Modes¶

WireBuddy offers three routing presets:

Advanced Peer Options¶

• Use Ad-blocking DNS (WireBuddy): Routes DNS through WireBuddy's resolver with optional per-peer blocklists
• Client Isolation: Prevents the device from reaching other VPN devices on the same WireGuard interface

Click Create Device.

4. Configure the Client Device¶

After creating the peer, WireBuddy displays these actions in the peer list:

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
  

[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 configure the DNS & Filtering section:

• Use Ad-blocking DNS (WireBuddy): Enable to route DNS through WireBuddy
• Active Blocklists: Select all, a subset, or none of the globally enabled blocklists

Then regenerate the client config using Download Config or Show QR Code.

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