Skip to content

Commit 2137d34

Browse files
mr-karanmr-karan
committed
feat: add troubleshooting section and improve interface naming
- Add collapsible troubleshooting section to web interface with firewall fixes - Include firewall-cmd commands for CentOS/RHEL/Fedora TCP connection issues - Add common issues and solutions (app binding, handshake failures, permissions) - Update interface naming from wg.conf to burrow.conf throughout documentation - Improve user experience with better guidance for common problems
1 parent 8f1acaf commit 2137d34

File tree

5 files changed

+98
-15
lines changed

5 files changed

+98
-15
lines changed

‎README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ Secure HTTP tunnels to localhost using WireGuard. Share your local development s
88

99
```bash
1010
# 1. Get tunnel config (replace 3000 with your local port)
11-
curl https://arbok.mrkaran.dev/3000 > wg.conf
11+
curl https://arbok.mrkaran.dev/3000 > burrow.conf
1212

1313
# 2. Start tunnel
14-
sudo wg-quick up ./wg.conf
14+
sudo wg-quick up ./burrow.conf
1515

1616
# 3. Stop tunnel when done
17-
sudo wg-quick down ./wg.conf
17+
sudo wg-quick down ./burrow.conf
1818
```
1919

2020
Your local service is now accessible at the HTTPS URL shown in the config file.
@@ -64,10 +64,10 @@ Test without DNS setup using Host headers:
6464
python3 -m http.server 3000 &
6565

6666
# Create tunnel
67-
curl http://localhost:8080/3000 > wg.conf
68-
sudo wg-quick up ./wg.conf
67+
curl http://localhost:8080/3000 > burrow.conf
68+
sudo wg-quick up ./burrow.conf
6969

70-
# Test with Host header (replace subdomain from wg.conf)
70+
# Test with Host header (replace subdomain from burrow.conf)
7171
curl -H "Host: your-subdomain.localhost" http://localhost:8080
7272
```
7373

‎docs/internals.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ This document provides a deep technical dive into how Arbok implements secure HT
2222
### 1. Tunnel Provisioning
2323

2424
```bash
25-
curl https://tunnel.domain.com/3000 > tunnel.conf
25+
curl https://tunnel.domain.com/3000 > burrow.conf
2626
```
2727

2828
**Process:**
@@ -50,7 +50,7 @@ curve25519.ScalarBaseMult(&pub, &priv)
5050
### 2. WireGuard Connection Establishment
5151

5252
```bash
53-
wg-quick up ./tunnel.conf
53+
wg-quick up ./burrow.conf
5454
```
5555

5656
**Network Setup:**

‎internal/api/handlers.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -205,9 +205,9 @@ func (s *Server) handleProvisionSimple(w http.ResponseWriter, r *http.Request) {
205205
# https://%s.%s
206206
#
207207
# Usage:
208-
# 1. Save this config: curl %s/%d > wg.conf
209-
# 2. Start tunnel: sudo wg-quick up ./wg.conf
210-
# 3. Stop tunnel: sudo wg-quick down ./wg.conf
208+
# 1. Save this config: curl %s/%d > burrow.conf
209+
# 2. Start tunnel: sudo wg-quick up ./burrow.conf
210+
# 3. Stop tunnel: sudo wg-quick down ./burrow.conf
211211
#
212212
%s`,
213213
t.CreatedAt.Format(time.RFC3339),

‎internal/api/web/index.html‎

Lines changed: 47 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@ <h1 class="hero-title">Secure HTTP tunnels to localhost</h1>
3737
<div class="command-section">
3838
<div class="command-label">Start tunnel:</div>
3939
<div class="command-block">
40-
<code class="command-text">curl https://arbok.mrkaran.dev/3000 > wg.conf && sudo wg-quick up ./wg.conf</code>
41-
<button class="copy-button" data-copy="curl https://arbok.mrkaran.dev/3000 > wg.conf && sudo wg-quick up ./wg.conf">
40+
<code class="command-text">curl https://arbok.mrkaran.dev/3000 > burrow.conf && sudo wg-quick up ./burrow.conf</code>
41+
<button class="copy-button" data-copy="curl https://arbok.mrkaran.dev/3000 > burrow.conf && sudo wg-quick up ./burrow.conf">
4242
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
4343
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
4444
<path d="m5 15-4-4 4-4"></path>
@@ -55,8 +55,8 @@ <h1 class="hero-title">Secure HTTP tunnels to localhost</h1>
5555
<div class="command-section">
5656
<div class="command-label">Stop tunnel:</div>
5757
<div class="command-block">
58-
<code class="command-text">sudo wg-quick down ./wg.conf</code>
59-
<button class="copy-button" data-copy="sudo wg-quick down ./wg.conf">
58+
<code class="command-text">sudo wg-quick down ./burrow.conf</code>
59+
<button class="copy-button" data-copy="sudo wg-quick down ./burrow.conf">
6060
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
6161
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
6262
<path d="m5 15-4-4 4-4"></path>
@@ -144,6 +144,49 @@ <h4 class="advanced-title">API Access</h4>
144144
</div>
145145
</details>
146146
</section>
147+
148+
<section class="troubleshooting">
149+
<details class="advanced-toggle">
150+
<summary class="advanced-summary">Troubleshooting</summary>
151+
<div class="advanced-content">
152+
<div class="advanced-section">
153+
<h4 class="advanced-title">🔥 Firewall Issues (CentOS/RHEL/Fedora)</h4>
154+
<p class="troubleshooting-desc">If you can ping through the tunnel but TCP connections fail, add the WireGuard interface to the trusted zone:</p>
155+
<div class="command-block">
156+
<code class="command-text">sudo firewall-cmd --permanent --zone=trusted --add-interface=burrow</code>
157+
<button class="copy-button" data-copy="sudo firewall-cmd --permanent --zone=trusted --add-interface=burrow">
158+
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
159+
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
160+
<path d="m5 15-4-4 4-4"></path>
161+
</svg>
162+
</button>
163+
</div>
164+
<div class="command-block">
165+
<code class="command-text">sudo firewall-cmd --reload</code>
166+
<button class="copy-button" data-copy="sudo firewall-cmd --reload">
167+
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
168+
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
169+
<path d="m5 15-4-4 4-4"></path>
170+
</svg>
171+
</button>
172+
</div>
173+
</div>
174+
175+
<div class="advanced-section">
176+
<h4 class="advanced-title">🔍 Common Issues</h4>
177+
<div class="troubleshooting-item">
178+
<strong>App not accessible:</strong> Ensure your app binds to <code>0.0.0.0:PORT</code> not <code>127.0.0.1:PORT</code>
179+
</div>
180+
<div class="troubleshooting-item">
181+
<strong>Handshake fails:</strong> Generate a fresh config - old configs become invalid after server restarts
182+
</div>
183+
<div class="troubleshooting-item">
184+
<strong>Permission denied:</strong> WireGuard requires root/sudo privileges to create network interfaces
185+
</div>
186+
</div>
187+
</div>
188+
</details>
189+
</section>
147190
</main>
148191

149192
<script src="/static/script.js"></script>

‎internal/api/web/style.css‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -478,6 +478,46 @@ body {
478478
margin-bottom: var(--space-sm);
479479
}
480480

481+
/* Troubleshooting Section */
482+
.troubleshooting {
483+
padding: var(--space-xl) 0;
484+
border-top: 1px solid var(--border-primary);
485+
}
486+
487+
.troubleshooting-desc {
488+
color: var(--text-secondary);
489+
font-size: 0.95rem;
490+
line-height: 1.5;
491+
margin-bottom: var(--space-md);
492+
}
493+
494+
.troubleshooting-item {
495+
padding: var(--space-sm);
496+
background: var(--bg-secondary);
497+
border-radius: 6px;
498+
margin-bottom: var(--space-sm);
499+
border-left: 3px solid var(--accent-purple);
500+
}
501+
502+
.troubleshooting-item:last-child {
503+
margin-bottom: 0;
504+
}
505+
506+
.troubleshooting-item strong {
507+
color: var(--text-primary);
508+
font-weight: 600;
509+
}
510+
511+
.troubleshooting-item code {
512+
background: var(--bg-primary);
513+
padding: 2px 6px;
514+
border-radius: 4px;
515+
font-family: var(--font-mono);
516+
font-size: 0.875rem;
517+
color: var(--accent-purple);
518+
border: 1px solid var(--border-primary);
519+
}
520+
481521
/* Responsive Design */
482522
@media (max-width: 768px) {
483523
.nav-content {

0 commit comments

Comments
 (0)