Troubleshooting

This is early software. Have a recovery plan. The good news: you have multiple ways to recover, from one-click fixes to starting fresh in under two minutes.

These recovery steps are designed so anyone in your household or office can execute them without calling you.

Recovery Options Overview

Listed from fastest to most drastic:

Method	Time	When to Use
Disable VPN	Seconds	Isolate VPN-related issues
Redeploy Circuit	Under a minute	Server overloaded, connection jitter
Rescue Mode	1-2 minutes	Something badly broken, UI still accessible
Bootstrap	2-3 minutes	Reset to fresh state
Physical Bypass	Seconds	Need internet NOW, debug later
Fresh Install	Under 2 minutes	Nuclear option

From the Wirebump Interface

These options require web UI access at http://10.0.0.1/ (or localhost in single-NIC mode). HTTPS is also available at https://10.0.0.1/—expect a browser warning due to the self-signed certificate (this is normal for local network access).

Disable VPN (Fastest)

One click from the header toggles Wirebump into pass-through mode.

What happens: Traffic flows directly to your ISP. No VPN, no encryption on the wire, but no VPN-related issues either. Your network stays online while you investigate.

Good for:

• Isolating whether the problem is VPN-related
• Letting family members get back online immediately
• Clearing captive portals or troublesome sites

To restore: Click the VPN toggle again. Your previous circuit reactivates.

Redeploy Circuit (Most Common Fix)

One click rebuilds your VPN tunnels with fresh connections.

What happens: Wirebump tears down the current circuit and deploys a new one. You get new servers, fresh connections, and often better performance.

Good for:

• VPN server overloaded or slow
• Connection jitter on video calls
• Endpoint issues with your current servers
• Routine performance optimization

This is the fix you will use most often. VPN servers vary in load throughout the day. A quick redeploy often resolves performance issues.

Rescue Mode

Navigate to Settings and click Rescue Mode.

What happens: Wirebump runs a partial bootstrap, clears stuck state, and deactivates the VPN. The system returns to a known-good configuration.

Good for:

• Web UI is accessible but something is badly broken
• Circuits fail to deploy or tear down
• System is in an inconsistent state

After rescue mode completes, you can reconfigure and deploy circuits normally.

From Command Line

These options require terminal access. SSH in, use a physical keyboard, or access via VM console.

Rerun Bootstrap

sudo wirebump bootstrap

What happens: Resets the entire Wirebump configuration to fresh state. Interface detection, firewall rules, and VPN state all reset. Your saved VPN credentials remain intact.

Good for:

• Major configuration issues
• After system updates that changed network interfaces
• Starting over without reinstalling the OS

Fresh Start (Live USB)

The nuclear option, but faster than you might expect.

1. Boot from Ubuntu 25.10 Live USB
2. Run the installer:

   sudo bash -c "$(wget -qO- https://wirebump.net/install.sh)"

3. Add your VPN credentials
4. Deploy a circuit

Total time: Under 2 minutes from boot to VPN-protected traffic.

Good for:

• Persistent issues you cannot resolve
• Major version upgrades
• Clean slate after experimenting

Live USB means nothing persists until you choose to install. Experiment without risk.

Physical Bypass

The fastest recovery when you need internet NOW.

1. Unplug the cable from Wirebump’s upstream (WAN) port
2. Plug your modem directly into your router
3. You are back to your pre-Wirebump setup

Time: Seconds.

Good for:

• Emergency internet access
• Debug Wirebump later without time pressure
• Demonstrating to skeptical household members that reverting is trivial

To restore: plug the cables back through Wirebump. Your configuration persists (on permanent installs).

Common Issues

SSH Locked Out (Single-NIC Mode)

The firewall locks down the WAN interface by design. This is expected behavior, not a bug.

Solutions:

• Plan ahead: Establish SSH with port forwarding before bootstrap

  ssh user@server -L 8080:10.0.0.1:80

• Use console access: VM console, physical keyboard/monitor, or IPMI/iDRAC
• Reinstall: On a VM, destroy and recreate. On Live USB, reboot.

Single-NIC Mode Full documentation on single-NIC limitations and workarounds

Slow Circuit Deployment

Circuits normally deploy in seconds. If yours take noticeably longer, check your Mullvad VPN configuration.

Likely cause: DAITA, LWO, or QUIC enabled.

These features require containerized mode, which adds overhead.

Solution:

1. Disable DAITA, LWO, and QUIC
2. Verify circuits deploy quickly
3. Re-enable advanced options only if your threat model requires them

Recommended workflow: Test topologies with advanced options disabled. Once stable, re-enable if needed.

Mullvad VPN Configuration Performance tradeoffs between default and containerized mode

VPN Server Performance Issues

VPN servers get overloaded, especially popular ones during peak hours.

Try these in order:

1. Redeploy circuit - Gets new servers, often fixes the issue
2. Switch to a saved circuit - If you have alternatives configured
3. Try a different city or region - Less popular locations often perform better
4. Check provider status - Mullvad VPN and Proton VPN both publish server status pages

With parallel tunnels, one slow server drags down aggregate performance. Redeploying cycles through the server pool.

Captive Portal Issues (On-the-Go Mode)

Hotel, airport, and coffee shop WiFi often require browser-based login before internet access works.

Solution:

1. Disable VPN from the Wirebump header
2. Open a browser and navigate to any HTTP site (not HTTPS)
3. Complete the captive portal login
4. Re-enable VPN

Tip

Some captive portals only intercept HTTP traffic. If the portal does not appear, try navigating to http://neverssl.com or http://captive.apple.com.

On-the-Go Mode WiFi upstream configuration for travel and untrusted networks

Circuit Fails to Deploy

If circuits fail repeatedly:

1. Check VPN credentials - Re-enter them in Settings
2. Check internet connectivity - Can you reach the VPN provider’s API?
3. Check provider status - Server outages happen
4. Try a different provider - If you have both Mullvad VPN and Proton VPN configured
5. Run bootstrap - Resets to known-good state

Dashboard Shows Errors but Network Works

The dashboard may show stale errors after successful recovery. Refresh the page or wait for the next status update.

Verification After Recovery

After any recovery action, verify your connection is working correctly.

Verify Your Connection IP checks, latency tests, and speed measurements

Quick checks:

# Check your exit IP
curl https://ifconfig.me/

# Verify VPN connectivity (works with any VPN, not only Mullvad)
curl https://mullvad.net/en/check

Getting Help

This is early software with an active development cycle. Check wirebump.net for updates.

Before reporting issues:

• Note which recovery steps you tried
• Check if the issue reproduces after a fresh bootstrap
• Capture any error messages from the dashboard or logs

Viewing logs: Check the system journal for Wirebump service logs if you need to capture error details for debugging.

---

Mullvad and Mullvad VPN are trademarks of Mullvad VPN AB. Proton VPN is a registered trademark of Proton AG.