mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-29 03:01:26 +02:00
Restructure Troubleshooting into a hub with per-area pages (#814)
* Restructure Troubleshooting into a hub with per-area pages - Add a Troubleshooting hub (/help/troubleshooting) with icon/chip cards and a "Still stuck?" CTA - Split NetBird Client troubleshooting into an overview + per-OS pages (Linux, Windows, macOS, Android, iOS) - Split Self-hosted troubleshooting into an overview + per-area pages (installation, IdP, dashboard, certificates, connectivity, database) - Split "Report bugs and issues" into Community Support and NetBird Support pages - Add Troubleshooting resource connectivity and a NetBird Cloud pending-approval page - Add DNS troubleshooting Issue 8 (Windows NRPT rule blocked by a lingering GPO) - Cross-reference the new pages from networks, DNS, and reverse-proxy docs; update nav Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Address review: client terminology, dead props, labels, cross-links - Use "client" instead of "agent" across the client troubleshooting pages (headings, prose, anchors) - Remove unused source: props from the Troubleshooting hub tiles - Relabel the "NetBird Cloud" grouping to "Cloud & identity" (SSO/provisioning also apply to self-hosted) - Add a Tiles title on the report-bug landing; add reverse-proxy -> resource-connectivity cross-link - Fix comma splices introduced by the em-dash cleanup in relayed-connections Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Add client-side hash redirect for moved self-hosted anchors Old deep links like /selfhosted/troubleshooting#debugging-turn-connections now forward to the per-area page, since next.config redirects can't act on the URL fragment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Apply docs-skill review: conventions + reshape area pages - "open source" (no hyphen), expand NRPT on first use, descriptive alt text + captions on TURN images - Fix inherited "Netbird" casing in the client glossary - Reshape the six self-hosted area pages to Symptom -> likely causes (ordered) -> Fix -> Confirm, preserving anchored headings Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Fix two typos in client glossary (CodeRabbit) - "nunning" -> "running" in the glossary - possessive "it's" -> "its" in the routing-table sentence Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: fix two broken links in troubleshooting pages - database: point the "upgrade path" link at /selfhosted/maintenance/upgrade; selfhosted-quickstart has no #upgrade anchor so the old link landed at page top - client: add HashRedirect so old #net-bird-agent-status deep links forward to the renamed #net-bird-client-status section on the same page * docs: address review follow-ups (deep-link redirects + client casing) - self-hosted troubleshooting: extend the HashRedirect map with the per-issue (###-level) anchors from the old single page, so old deep links land on the exact sub-section of the new area page rather than just the page top - client glossary: lowercase "NetBird client" in the peer-a/peer-b entries (house convention) and fix "linux" -> "Linux" * docs: review polish — fix image class + first-use acronym glosses - connectivity: fix bad CSS class imagewrapper-nig -> imagewrapper on the TURN-test screenshot (the typo'd class matched no style and broke zoom) - gloss acronyms on first use: GPO (DNS Issue 8), IdP/SSO (identity-provider), ACME (certificates), CORS (dashboard) --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
This commit is contained in:
Bruno Mercier Costa
committed by
GitHub
GitHub
parent
ffb72cfa34
commit
5729ad035e
16
src/pages/help/troubleshooting-client/android.mdx
Normal file
16
src/pages/help/troubleshooting-client/android.mdx
Normal file
@@ -0,0 +1,16 @@
|
||||
export const description =
|
||||
"Android-specific NetBird client troubleshooting: enabling trace logs and capturing them with ADB."
|
||||
|
||||
# NetBird client on Android
|
||||
|
||||
Android-specific steps for the NetBird client. For everything cross-platform (client status, connectivity, login, and DNS), start from [Troubleshooting client issues](/help/troubleshooting-client).
|
||||
|
||||
## Enable trace logs and capture them with ADB
|
||||
|
||||
1. Enable **ADB** in the device's developer options.
|
||||
2. In the NetBird app, set the **Trace** log level (a checkbox in the advanced menu).
|
||||
3. Install the ADB platform tools (part of the [SDK platform-tools](https://developer.android.com/tools/releases/platform-tools) pack), then capture the logs. On Linux:
|
||||
|
||||
```shell
|
||||
sudo adb logcat -v time | grep GoLog
|
||||
```
|
||||
14
src/pages/help/troubleshooting-client/ios.mdx
Normal file
14
src/pages/help/troubleshooting-client/ios.mdx
Normal file
@@ -0,0 +1,14 @@
|
||||
import {Note} from "@/components/mdx"
|
||||
|
||||
export const description =
|
||||
"iOS-specific NetBird client troubleshooting and how to capture logs from the app."
|
||||
|
||||
# NetBird client on iOS
|
||||
|
||||
iOS-specific steps for the NetBird client. Most troubleshooting is cross-platform, so start from [Troubleshooting client issues](/help/troubleshooting-client).
|
||||
|
||||
On-device debugging on iOS is more limited than on desktop platforms. To share diagnostics, capture logs from the NetBird iOS app and attach them to your report.
|
||||
|
||||
<Note>
|
||||
There are no iOS-specific debug commands yet. For status, connectivity, and DNS issues, follow the cross-platform [Troubleshooting client issues](/help/troubleshooting-client) and [DNS Troubleshooting](/manage/dns/troubleshooting) guides. If you can reproduce a problem, report it through [Community Support](/help/community-support).
|
||||
</Note>
|
||||
42
src/pages/help/troubleshooting-client/linux.mdx
Normal file
42
src/pages/help/troubleshooting-client/linux.mdx
Normal file
@@ -0,0 +1,42 @@
|
||||
export const description =
|
||||
"Linux-specific NetBird client troubleshooting: setting the debug log level (systemd, service, Docker) and host-based firewalls."
|
||||
|
||||
# NetBird client on Linux
|
||||
|
||||
Linux-specific steps for the NetBird client. For everything cross-platform (client status, the debug bundle, GRPC and ICE debugging, login failures, and reaching resources), start from [Troubleshooting client issues](/help/troubleshooting-client).
|
||||
|
||||
## Set the log level permanently
|
||||
|
||||
The [temporary log level](/help/troubleshooting-client#enabling-debug-logs-on-the-client) resets when the daemon restarts. To make it permanent on Linux, use one of the following.
|
||||
|
||||
### systemd
|
||||
|
||||
The default systemd unit reads environment variables from `/etc/sysconfig/netbird`:
|
||||
|
||||
```shell
|
||||
sudo mkdir -p /etc/sysconfig
|
||||
echo 'NB_LOG_LEVEL=debug' | sudo tee -a /etc/sysconfig/netbird
|
||||
sudo systemctl restart netbird
|
||||
```
|
||||
|
||||
### Other init systems
|
||||
|
||||
```shell
|
||||
sudo netbird service stop
|
||||
sudo netbird service uninstall
|
||||
sudo netbird service install --log-level debug # or trace
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
Set `NB_LOG_LEVEL=debug` on the container:
|
||||
|
||||
```shell
|
||||
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d \
|
||||
-e NB_SETUP_KEY=<SETUP KEY> -e NB_LOG_LEVEL=debug -v netbird-client:/var/lib/netbird netbirdio/netbird:latest
|
||||
```
|
||||
|
||||
## Host-based firewall
|
||||
|
||||
NetBird manages its own rules, but UFW, firewalld, or endpoint security software can conflict and silently drop traffic. See [Ports & Firewalls: Host-based firewalls](/about-netbird/ports-and-firewalls#host-based-firewalls) for UFW and firewalld symptoms, remediation, and diagnostic commands.
|
||||
21
src/pages/help/troubleshooting-client/macos.mdx
Normal file
21
src/pages/help/troubleshooting-client/macos.mdx
Normal file
@@ -0,0 +1,21 @@
|
||||
export const description =
|
||||
"macOS-specific NetBird client troubleshooting: setting the debug log level and host-based firewalls."
|
||||
|
||||
# NetBird client on macOS
|
||||
|
||||
macOS-specific steps for the NetBird client. For everything cross-platform (client status, the debug bundle, GRPC and ICE debugging, login failures, and reaching resources), start from [Troubleshooting client issues](/help/troubleshooting-client).
|
||||
|
||||
## Set the log level permanently
|
||||
|
||||
The [temporary log level](/help/troubleshooting-client#enabling-debug-logs-on-the-client) resets when the service restarts. To make it permanent on macOS, reinstall the service with the level set:
|
||||
|
||||
```shell
|
||||
sudo netbird service stop
|
||||
sudo netbird service uninstall
|
||||
sudo netbird service install --log-level debug # or trace
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
## Host-based firewall
|
||||
|
||||
The built-in macOS application firewall or third-party endpoint security software can block NetBird traffic before it leaves the machine. If connectivity works with that software temporarily disabled, add an exception for the NetBird process. See [Ports & Firewalls: Host-based firewalls](/about-netbird/ports-and-firewalls#host-based-firewalls) for the general approach.
|
||||
47
src/pages/help/troubleshooting-client/windows.mdx
Normal file
47
src/pages/help/troubleshooting-client/windows.mdx
Normal file
@@ -0,0 +1,47 @@
|
||||
import {Note} from "@/components/mdx"
|
||||
|
||||
export const description =
|
||||
"Windows-specific NetBird client troubleshooting: debug log level, foreground mode via PSExec, host-based firewall, and Windows DNS scenarios."
|
||||
|
||||
# NetBird client on Windows
|
||||
|
||||
Windows-specific steps for the NetBird client. For everything cross-platform (client status, the debug bundle, GRPC and ICE debugging, login failures, and reaching resources), start from [Troubleshooting client issues](/help/troubleshooting-client).
|
||||
|
||||
## Set the log level permanently
|
||||
|
||||
The [temporary log level](/help/troubleshooting-client#enabling-debug-logs-on-the-client) resets when the service restarts. To make it permanent, run an elevated PowerShell or `cmd.exe` window:
|
||||
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable("NB_LOG_LEVEL", "debug", "Machine")
|
||||
netbird service restart
|
||||
```
|
||||
|
||||
## Run the client in foreground mode
|
||||
|
||||
On Windows the client depends on WireGuard's `wintun.dll` and can only run as the system account. To run it in foreground mode, use [PSExec](https://learn.microsoft.com/en-us/sysinternals/downloads/psexec). In an elevated PowerShell window:
|
||||
|
||||
```shell
|
||||
netbird service stop
|
||||
.\PsExec64.exe -s cmd.exe /c "netbird up -F --log-level debug > c:\windows\temp\netbird.out.log 2>&1"
|
||||
```
|
||||
|
||||
To pass environment variables, set them as machine-level variables so the client picks them up on the next PSExec run:
|
||||
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable("PIONS_LOG_DEBUG", "all", "Machine")
|
||||
```
|
||||
|
||||
## Host-based firewall
|
||||
|
||||
Windows Firewall or endpoint security software can block NetBird traffic before it leaves the machine. See [Ports & Firewalls: Host-based firewalls](/about-netbird/ports-and-firewalls#host-based-firewalls) for Windows Firewall symptoms, remediation, and diagnostic commands.
|
||||
|
||||
## Windows DNS scenarios
|
||||
|
||||
DNS on Windows has a few platform-specific failure modes worth checking separately:
|
||||
|
||||
- **Match-domain names don't resolve, even though the NRPT (Name Resolution Policy Table) rule was written.** A lingering Group Policy `DnsPolicyConfig` container can stop NetBird's rule from taking effect on an off-domain machine. See [DNS Troubleshooting: Issue 8 (lingering GPO)](/manage/dns/troubleshooting#issue-8-windows-nrpt-rule-is-written-but-never-takes-effect-lingering-gpo).
|
||||
- **Active Directory login, mapped drives, or DFS fail** while a file share by IP works. This is usually a DC-locator (`SRV` record) problem. See [Domain Controllers as routing peers](/manage/dns/internal-dns-servers#domain-controllers-as-routing-peers).
|
||||
|
||||
<Note>
|
||||
For the full DNS diagnostic flow on any platform, see [DNS Troubleshooting](/manage/dns/troubleshooting).
|
||||
</Note>
|
||||
Reference in New Issue
Block a user