mirror of
https://github.com/netbirdio/docs.git
synced 2026-10-16 18:49:04 +02:00
docs: add common issues to the troubleshooting hub and fill out the area tiles (#1039)
* docs: add common issues to the troubleshooting hub and fill out the area tiles Lead the Troubleshooting hub with a table of the issues support sees most often, and give each area tile the sections a reader actually needs, including a new Reverse Proxy tile. Add the case where a teammate signs in and gets their own account to the pending approval page, with sign-in domains as the fix. List the headings rendered by the troubleshooting components in "On this page", which previously only showed Markdown headings. * docs: address review on account-access and support wording - Personal-address teammate: drop the direct-invite advice, since a user who already has an account can't be invited; point to the work address or NetBird Support instead. - Support audience: say NetBird Support is mainly for paying Cloud customers and commercial-license deployments, consistently across the troubleshooting hub, the support page, and the report-bug page. * docs: align the troubleshooting hub table and rework Still stuck - Common issues table: fixed 50/50 columns, with the Start here column padded to line up with the right-hand area tiles at any width. - Still stuck: match the width and side padding of the tiles, center the title and buttons, and put a short audience note under each button. The report hint moves to its own line above the links, with a new Debug bundle link.
This commit is contained in:
Bruno Mercier Costa
+20
-1
@@ -165,11 +165,30 @@ function rehypeAddMDXExports(getExports) {
|
||||
}
|
||||
}
|
||||
|
||||
// Components that render their own `h2` from `title` and `id` props. The
|
||||
// heading is not in the MDX tree, so it is added to the table of contents here.
|
||||
const sectionComponents = ['TroubleshootingStart', 'TroubleshootingTiles', 'StillStuck']
|
||||
|
||||
function jsxStringAttribute(node, name) {
|
||||
let attribute = node.attributes?.find((a) => a.name === name)
|
||||
return typeof attribute?.value === 'string' ? attribute.value : undefined
|
||||
}
|
||||
|
||||
function getSections(node) {
|
||||
let sections = []
|
||||
|
||||
for (let child of node.children ?? []) {
|
||||
if (child.type === 'element' && ['h2', 'h3', 'h4', 'h5', 'h6'].includes(child.tagName)) {
|
||||
if (child.type === 'mdxJsxFlowElement' && sectionComponents.includes(child.name)) {
|
||||
let title = jsxStringAttribute(child, 'title')
|
||||
let id = jsxStringAttribute(child, 'id')
|
||||
if (title && id) {
|
||||
sections.push(`{
|
||||
title: ${JSON.stringify(title)},
|
||||
id: ${JSON.stringify(id)},
|
||||
tagName: "h2"
|
||||
}`)
|
||||
}
|
||||
} else if (child.type === 'element' && ['h2', 'h3', 'h4', 'h5', 'h6'].includes(child.tagName)) {
|
||||
sections.push(`{
|
||||
title: ${JSON.stringify(toString(child))},
|
||||
id: ${JSON.stringify(child.properties.id)},
|
||||
|
||||
@@ -1,48 +1,105 @@
|
||||
import { Fragment } from 'react'
|
||||
import Link from 'next/link'
|
||||
import { Button } from '@/components/Button'
|
||||
|
||||
/**
|
||||
* "Still stuck?" call-to-action banner for the bottom of the Troubleshooting
|
||||
* hub. Renders a short prompt and a row of action buttons.
|
||||
* hub. Renders a centered title, a row of action buttons with an optional note
|
||||
* under each, and an optional row of secondary links.
|
||||
*
|
||||
* @param {string} [title='Still stuck?']
|
||||
* @param {string} description
|
||||
* @param {Array<{label: string, href: string, primary?: boolean}>} actions
|
||||
* @param {string} [id] - Optional id for the title anchor (listed in "On this page")
|
||||
* @param {string} [description]
|
||||
* @param {Array<{label: string, href: string, primary?: boolean, note?: string}>} actions
|
||||
* @param {string} [separator] - Optional word rendered between buttons (e.g. "or"),
|
||||
* so two equally-weighted actions don't read as a recommended-vs-secondary pair.
|
||||
* @param {string} [linksLabel] - Lead-in text, on its own line above the secondary links
|
||||
* @param {Array<{label: string, href: string}>} [links] - Secondary text links
|
||||
*/
|
||||
export function StillStuck({
|
||||
title = 'Still stuck?',
|
||||
id,
|
||||
description,
|
||||
actions = [],
|
||||
separator,
|
||||
linksLabel,
|
||||
links = [],
|
||||
}) {
|
||||
// `not-prose` on the card would also drop the prose layout (left margin and
|
||||
// max width), so the outer div keeps it and matches TroubleshootingTiles.
|
||||
return (
|
||||
<div className="not-prose my-12 rounded-2xl bg-zinc-50 p-6 ring-1 ring-inset ring-zinc-900/7.5 dark:bg-white/2.5 dark:ring-white/10">
|
||||
<h2 className="text-xl font-semibold text-zinc-900 dark:text-white">
|
||||
{title}
|
||||
</h2>
|
||||
{description && (
|
||||
<p className="mt-1 max-w-2xl text-sm text-zinc-600 dark:text-zinc-400">
|
||||
{description}
|
||||
</p>
|
||||
)}
|
||||
<div className="mt-5 flex flex-wrap items-center gap-3">
|
||||
{actions.map((action, i) => (
|
||||
<Fragment key={action.href}>
|
||||
{i > 0 && separator && (
|
||||
<span className="text-sm text-zinc-500 dark:text-zinc-400">
|
||||
{separator}
|
||||
</span>
|
||||
)}
|
||||
<Button
|
||||
href={action.href}
|
||||
variant={action.primary ? 'primary' : 'secondary'}
|
||||
>
|
||||
{action.label}
|
||||
</Button>
|
||||
</Fragment>
|
||||
))}
|
||||
<div className="my-12 xl:max-w-none">
|
||||
<div className="not-prose rounded-2xl bg-zinc-50 px-4 py-6 text-center ring-1 ring-inset ring-zinc-900/7.5 dark:bg-white/2.5 dark:ring-white/10">
|
||||
<h2
|
||||
id={id}
|
||||
className="scroll-mt-24 text-xl font-semibold text-zinc-900 dark:text-white"
|
||||
>
|
||||
{title}
|
||||
</h2>
|
||||
{description && (
|
||||
<p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
|
||||
{description}
|
||||
</p>
|
||||
)}
|
||||
{/* Stacked in reading order on phones. From `sm` up, a two-row grid puts
|
||||
each note under its button and keeps the separator level with the
|
||||
buttons, not the notes. */}
|
||||
<div
|
||||
className="mt-5 flex flex-col items-center gap-2 sm:grid sm:items-start sm:justify-center sm:gap-x-4 sm:[grid-template-columns:var(--cols)]"
|
||||
style={{
|
||||
'--cols': actions.map(() => 'minmax(0, 16rem)').join(' auto '),
|
||||
}}
|
||||
>
|
||||
{actions.map((action, i) => (
|
||||
<Fragment key={action.href}>
|
||||
{i > 0 && separator && (
|
||||
<span
|
||||
className="text-sm text-zinc-500 sm:row-start-1 sm:self-center sm:[grid-column:var(--col)] dark:text-zinc-400"
|
||||
style={{ '--col': 2 * i }}
|
||||
>
|
||||
{separator}
|
||||
</span>
|
||||
)}
|
||||
<div
|
||||
className="sm:row-start-1 sm:[grid-column:var(--col)]"
|
||||
style={{ '--col': 2 * i + 1 }}
|
||||
>
|
||||
<Button
|
||||
href={action.href}
|
||||
variant={action.primary ? 'primary' : 'secondary'}
|
||||
>
|
||||
{action.label}
|
||||
</Button>
|
||||
</div>
|
||||
{action.note && (
|
||||
<p
|
||||
className="text-xs text-zinc-500 sm:row-start-2 sm:[grid-column:var(--col)] dark:text-zinc-400"
|
||||
style={{ '--col': 2 * i + 1 }}
|
||||
>
|
||||
{action.note}
|
||||
</p>
|
||||
)}
|
||||
</Fragment>
|
||||
))}
|
||||
</div>
|
||||
{links.length > 0 && (
|
||||
<div className="mt-5 text-sm text-zinc-600 dark:text-zinc-400">
|
||||
{linksLabel && <p>{linksLabel}</p>}
|
||||
<p className={linksLabel ? 'mt-1' : undefined}>
|
||||
{links.map((link, i) => (
|
||||
<Fragment key={link.href}>
|
||||
{i > 0 && <span aria-hidden="true"> · </span>}
|
||||
<Link
|
||||
href={link.href}
|
||||
className="font-medium text-zinc-900 underline decoration-[#F28C28]/40 underline-offset-2 hover:decoration-[#F28C28] dark:text-white"
|
||||
>
|
||||
{link.label}
|
||||
</Link>
|
||||
</Fragment>
|
||||
))}
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { SupportBanner } from "@/components/SupportBanner"
|
||||
|
||||
export const description =
|
||||
"NetBird Support for (paying) Cloud customers and users, and commercial-license self-hosted deployments: reach the team with a pre-filled report."
|
||||
"NetBird Support, mainly for paying Cloud customers and commercial-license self-hosted deployments: reach the team with a pre-filled report."
|
||||
|
||||
export const reportTemplate = `NetBird issue report
|
||||
=====================
|
||||
@@ -39,7 +39,7 @@ export const supportMailto = `mailto:support@netbird.io?subject=${encodeURICompo
|
||||
<SupportBanner
|
||||
tone="support"
|
||||
badge="Cloud & commercial"
|
||||
description="Reserved for (paying) Cloud customers and users, and self-hosted deployments on a commercial license. Use it for the Cloud dashboard, the managed control plane, billing, your subscription, or commercial self-hosted support. Open source self-hosted and general client questions belong in Community Support."
|
||||
description="Mainly for paying NetBird Cloud customers and self-hosted deployments on a commercial license. Use it for the Cloud dashboard, the managed control plane, billing, your subscription, or commercial self-hosted support. Open source self-hosted and general client questions belong in Community Support."
|
||||
links={[
|
||||
{ label: "Open a pre-filled support email", href: supportMailto },
|
||||
{ label: "Attach a debug bundle", href: "/help/troubleshooting-client#debug-bundle" },
|
||||
|
||||
@@ -19,7 +19,7 @@ NetBird offers two ways to get help, depending on what you are running. Pick the
|
||||
{
|
||||
href: "/help/netbird-support",
|
||||
name: "NetBird Support",
|
||||
description: "For (paying) Cloud customers and users, and commercial-license self-hosted deployments: the dashboard, control plane, billing, and subscriptions.",
|
||||
description: "Mainly for paying NetBird Cloud customers and commercial-license self-hosted deployments: the dashboard, control plane, billing, and subscriptions.",
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
export const description = "Why NetBird shows you a Waiting for Approval screen, or adds you to an account you don't recognize, and how to resolve it safely."
|
||||
export const description = "Why NetBird shows you a Waiting for Approval screen, adds you to an account you don't recognize, or gives a teammate an account of their own, and how to resolve it safely."
|
||||
|
||||
# Pending approval and account invitations
|
||||
|
||||
Signed in to NetBird and landed on a **Waiting for Approval** screen, or in a NetBird account you don't recognize? This usually is not a bug. It almost always means you were added to an existing organization automatically, and someone in that organization still has to approve you.
|
||||
|
||||
The opposite also happens: a teammate signs in and gets a new, empty account of their own instead of joining yours. See [A teammate got their own account](#a-teammate-got-their-own-account).
|
||||
|
||||
## What the Waiting for Approval screen tells you
|
||||
|
||||
After you sign in, the dashboard shows three steps: **Account Created**, **Waiting for Approval**, and **Join Account**. Your user exists, but the account requires new users to be approved before they can use it, so you are held at the second step until someone approves you.
|
||||
@@ -23,7 +25,7 @@ The screen has two buttons:
|
||||
|
||||
NetBird can add people to an account without a manual, one-by-one invite:
|
||||
|
||||
- **Indirect (domain) invites.** If an account has verified your email domain, new sign-ups with that domain join it automatically. See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites).
|
||||
- **Domain matching.** On NetBird Cloud, new sign-ups join an existing account automatically when their email domain belongs to it: either the private domain the account signed up with, or another domain the account has verified as a [sign-in domain](/manage/team/sign-in-domains). See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites).
|
||||
- **Identity provider sync.** If your organization connects NetBird to its identity provider, being added to a synced group in the IdP provisions your user in NetBird. See [Provision users and groups from your identity provider](/manage/team/idp-sync).
|
||||
- **Approval is required.** When an account turns on [user approval](/manage/team/approve-users#require-user-approval), new users stay blocked until an admin approves them. That block is the Waiting for Approval screen you see.
|
||||
|
||||
@@ -38,6 +40,28 @@ NetBird can add people to an account without a manual, one-by-one invite:
|
||||
On self-hosted NetBird, the Waiting for Approval screen needs dashboard v2.93.0 or later, and the owner's address on it needs management v0.80.0 or later. Older dashboards show a **User Approval Pending** error page with only a **Sign Out** button instead: the steps above still apply, but after you are approved, sign out and sign in again.
|
||||
</Note>
|
||||
|
||||
## A teammate got their own account
|
||||
|
||||
A teammate signs in to NetBird Cloud and lands in a new, empty account, with none of your peers, users, or policies. NetBird did not match their email domain to your account, so it created a separate one for them. One of these is usually the reason:
|
||||
|
||||
- **They use another of your business's domains.** Only the domain your account signed up with matches from the start. A country domain such as `company.co.uk`, a subsidiary, or a second brand matches only after an Owner or Admin adds and verifies it as a [sign-in domain](/manage/team/sign-in-domains).
|
||||
- **They signed in with a personal address**, such as a Gmail account. Public email domains never match an account. Ask them to sign in with their work address instead. You can't [invite them directly](/manage/team/add-users-to-your-network#direct-user-invites) now that they have their own account, so if they need to keep the personal address, contact [NetBird Support](/help/netbird-support).
|
||||
- **Your domain was not classified as private.** NetBird only groups sign-ups by domain when it classifies the domain as private. If it is unsure, it plays safe and does not group them. [NetBird Support](/help/netbird-support) can correct the classification. See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites).
|
||||
|
||||
To fix it for the next person, an Owner or Admin adds and verifies the domain under **Settings → Authentication → Sign-in Domains**, or invites the user directly. Do this before onboarding a team on another domain, not after.
|
||||
|
||||
The **Sign-in Domains** section only appears once your account's own domain is classified as private. If you don't see it, invite the user directly or contact [NetBird Support](/help/netbird-support).
|
||||
|
||||
To confirm the cause, ask your teammate which email address they signed in with, and check its domain against the Sign-in Domains list.
|
||||
|
||||
Verifying a domain does not move a teammate who already has an account of their own: it only changes where new sign-ins land. For a teammate already in a separate account, contact [NetBird Support](/help/netbird-support).
|
||||
|
||||
If your account requires user approval, a teammate who joins through domain matching is held for approval. That is the [Waiting for Approval](#what-the-waiting-for-approval-screen-tells-you) screen above, and an admin approves them as described in [What to do](#what-to-do).
|
||||
|
||||
<Note>
|
||||
On self-hosted NetBird, domain matching and sign-in domains do not apply: by default, every user joins the same account.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Still unsure who owns the account, or think you were added to the wrong one? Reach out through [NetBird Support](/help/netbird-support) and the team can help confirm the account and its owner.
|
||||
</Note>
|
||||
|
||||
@@ -2,43 +2,90 @@ import { TroubleshootingTiles } from "@/components/TroubleshootingTiles"
|
||||
import { StillStuck } from "@/components/StillStuck"
|
||||
|
||||
export const description =
|
||||
"Start here to troubleshoot NetBird. Find your issue by area and jump straight to the relevant guide."
|
||||
"Start here to troubleshoot NetBird. See the common issues, or browse by area."
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
Something not working as expected? Pick the area closest to your problem and jump to the
|
||||
guide and section that covers it. Each section links to troubleshooting docs that live
|
||||
next to the feature they cover, so nothing here is a copy.
|
||||
Something not working as expected? Check the common issues below, or browse by area.
|
||||
|
||||
## Common issues
|
||||
|
||||
The problems support sees most often.
|
||||
|
||||
<div className="xl:max-w-none [&_table]:table-fixed [&_th]:w-1/2 [&_th:last-child]:pl-8 [&_td:last-child]:pl-8">
|
||||
|
||||
| Symptom | Start here |
|
||||
|---|---|
|
||||
| The dashboard shows **Waiting for Approval** after you sign in | [Pending approval and account invitations](/help/troubleshooting-account-access) |
|
||||
| The client keeps asking you to log in again, or a peer shows `Login required` | [Peer session expiration](/manage/settings/enforce-periodic-user-authentication) |
|
||||
| A peer shows `Relayed` instead of `P2P` | [Troubleshooting relayed connections](/help/troubleshooting-relayed-connections) |
|
||||
| The tunnel works but is slow, or takes long to connect | [Troubleshooting performance](/help/troubleshooting-performance) |
|
||||
| A service behind a routing peer is unreachable, or a new resource never shows up | [Troubleshooting resource connectivity](/help/troubleshooting-resource-connectivity) |
|
||||
| A network or host firewall blocks NetBird, or traffic stops at a security product such as a SASE or SSL-inspection service | [Ports & firewalls](/about-netbird/ports-and-firewalls) <br /> On the peer itself: [Symptoms of host-based firewall issues](/about-netbird/ports-and-firewalls#symptoms-of-host-based-firewall-issues) |
|
||||
| Names do not resolve, or DNS stops working after NetBird disconnects | [DNS troubleshooting](/manage/dns/troubleshooting) |
|
||||
| A NetBird Reverse Proxy service returns `502`, times out, or its certificate is never issued | [Reverse proxy troubleshooting](/manage/reverse-proxy/troubleshooting) <br /> Certificate: [Certificate is not issued after verification](/manage/reverse-proxy/custom-domains#certificate-is-not-issued-after-verification) |
|
||||
|
||||
</div>
|
||||
|
||||
<TroubleshootingTiles
|
||||
title="Find your issue by area"
|
||||
id="find-your-issue-by-area"
|
||||
description="Pick the surface you are working with. Links open the existing troubleshooting docs in place."
|
||||
description="Pick the part of NetBird you are working with, then the problem closest to yours."
|
||||
items={[
|
||||
{
|
||||
title: "NetBird Client",
|
||||
href: "/help/troubleshooting-client",
|
||||
icon: "laptop",
|
||||
description:
|
||||
"Desktop, CLI, and mobile client problems on a peer machine.",
|
||||
"Desktop, CLI, and mobile client problems on a peer machine: status, logs, login, and platform quirks.",
|
||||
chips: [
|
||||
{ label: "Connection issues", href: "/help/troubleshooting-client#debugging-ice-connections" },
|
||||
{ label: "Client status", href: "/help/troubleshooting-client#net-bird-client-status" },
|
||||
{ label: "Debug bundle", href: "/help/troubleshooting-client#debug-bundle" },
|
||||
{ label: "Debug logs", href: "/help/troubleshooting-client#enabling-debug-logs-on-the-client" },
|
||||
{ label: "Login & SSO", href: "/help/troubleshooting-client#client-login-failures" },
|
||||
{ label: "DNS resolution", href: "/manage/dns/troubleshooting" },
|
||||
{ label: "Routes & exit nodes", href: "/help/troubleshooting-client#debugging-access-to-network-resources" },
|
||||
{ label: "Windows SSO port 53000", href: "/help/troubleshooting-client/windows#sso-login-fails-to-bind-tcp-53000" },
|
||||
{ label: "Stuck at Connecting", href: "/help/troubleshooting-client#debugging-ice-connections" },
|
||||
{ label: "Host firewall fallback", href: "/help/troubleshooting-client#when-the-client-cannot-manage-firewall-rules" },
|
||||
{ label: "Linux", href: "/help/troubleshooting-client/linux" },
|
||||
{ label: "Windows", href: "/help/troubleshooting-client/windows" },
|
||||
{ label: "macOS", href: "/help/troubleshooting-client/macos" },
|
||||
{ label: "Android", href: "/help/troubleshooting-client/android" },
|
||||
{ label: "iOS", href: "/help/troubleshooting-client/ios" },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: "Self-hosted",
|
||||
href: "/selfhosted/troubleshooting",
|
||||
icon: "server",
|
||||
// No dedicated troubleshooting page, so the title is plain text.
|
||||
title: "Connectivity & networking",
|
||||
icon: "firewall",
|
||||
description:
|
||||
"Your own Management, Signal, Relay, and Dashboard services.",
|
||||
"Peers that relay, never connect, or can't reach resources, plus DNS and speed, whether you use NetBird Cloud or self-host.",
|
||||
chips: [
|
||||
{ label: "Management service", href: "/selfhosted/troubleshooting/connectivity#management-service-unreachable" },
|
||||
{ label: "Signal service", href: "/about-netbird/how-netbird-works#signal-service" },
|
||||
{ label: "Relay", href: "/selfhosted/troubleshooting/connectivity#debugging-relay-connections" },
|
||||
{ label: "Dashboard", href: "/selfhosted/troubleshooting/dashboard" },
|
||||
{ label: "Relayed connections", href: "/help/troubleshooting-relayed-connections" },
|
||||
{ label: "Control plane unreachable", href: "/help/troubleshooting-relayed-connections#step-2-is-the-control-plane-reachable" },
|
||||
{ label: "Resource connectivity", href: "/help/troubleshooting-resource-connectivity" },
|
||||
{ label: "Routing peer forwarding", href: "/help/troubleshooting-resource-connectivity#step-3-does-the-peer-forward-it" },
|
||||
{ label: "Routing peer checks", href: "/manage/networks/how-routing-peers-work#observability-and-troubleshooting" },
|
||||
{ label: "Performance", href: "/help/troubleshooting-performance" },
|
||||
{ label: "Reconnect delays", href: "/help/troubleshooting-performance#startup-and-reconnect-delays" },
|
||||
{ label: "MTU", href: "/help/troubleshooting-performance#rule-out-packet-size-mtu" },
|
||||
{ label: "DNS", href: "/manage/dns/troubleshooting" },
|
||||
{ label: "Ports & firewalls", href: "/about-netbird/ports-and-firewalls" },
|
||||
{ label: "Corporate firewalls & SASE", href: "/about-netbird/ports-and-firewalls#corporate-firewalls" },
|
||||
{ label: "Other VPNs on Linux", href: "/client/environment-variables#networking-and-routing" },
|
||||
],
|
||||
},
|
||||
{
|
||||
// No dedicated troubleshooting page, so the title is plain text;
|
||||
// chips point to the sections that diagnose policy decisions.
|
||||
title: "Access control",
|
||||
icon: "shield",
|
||||
description:
|
||||
"Traffic allowed or denied unexpectedly by a policy or posture check.",
|
||||
chips: [
|
||||
{ label: "Check the matching policy", href: "/help/troubleshooting-resource-connectivity#step-2-is-there-a-route-and-a-matching-policy" },
|
||||
{ label: "Trace firewall rules", href: "/help/troubleshooting-client#tracing-firewall-rules" },
|
||||
{ label: "When posture checks run", href: "/manage/access-control/posture-checks#when-posture-checks-are-evaluated" },
|
||||
{ label: "Posture check limits", href: "/manage/access-control/posture-checks#known-limitations" },
|
||||
],
|
||||
},
|
||||
{
|
||||
@@ -47,41 +94,47 @@ next to the feature they cover, so nothing here is a copy.
|
||||
title: "Cloud & identity",
|
||||
icon: "cloud",
|
||||
description:
|
||||
"SSO and user provisioning (Cloud and self-hosted), account approvals, and Cloud plans and quotas.",
|
||||
"Approvals, landing in the right account, session expiry, SSO and provisioning, MSP tenants, and NetBird Cloud plans.",
|
||||
chips: [
|
||||
{ label: "Pending approval", href: "/help/troubleshooting-account-access" },
|
||||
{ label: "IdP & SSO setup", href: "/manage/team/single-sign-on" },
|
||||
{ label: "User provisioning", href: "/manage/team/idp-sync" },
|
||||
{ label: "Plan limits & quotas", href: "/manage/settings/plans-and-billing" },
|
||||
{ label: "Teammate got their own account", href: "/help/troubleshooting-account-access#a-teammate-got-their-own-account" },
|
||||
{ label: "Sign-in domains", href: "/manage/team/sign-in-domains" },
|
||||
{ label: "Session expiration", href: "/manage/settings/enforce-periodic-user-authentication" },
|
||||
{ label: "SSO setup guides", href: "/manage/team/single-sign-on" },
|
||||
{ label: "User provisioning setup", href: "/manage/team/idp-sync" },
|
||||
{ label: "MSP tenants", href: "/manage/for-partners/msp-portal#delayed-tenant-domain-verification" },
|
||||
{ label: "Plans & billing", href: "/manage/settings/plans-and-billing" },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: "Connectivity & networking",
|
||||
href: "/help/troubleshooting-relayed-connections",
|
||||
icon: "firewall",
|
||||
title: "Reverse Proxy",
|
||||
href: "/manage/reverse-proxy/troubleshooting",
|
||||
icon: "globe",
|
||||
description:
|
||||
"Cross-cutting network issues regardless of how you deploy.",
|
||||
"Services you expose with the NetBird Reverse Proxy: errors, timeouts, and custom domains.",
|
||||
chips: [
|
||||
{ label: "Relayed connections", href: "/help/troubleshooting-relayed-connections" },
|
||||
{ label: "Resource connectivity", href: "/help/troubleshooting-resource-connectivity" },
|
||||
{ label: "Performance", href: "/help/troubleshooting-performance" },
|
||||
{ label: "Reverse proxy", href: "/manage/reverse-proxy/troubleshooting" },
|
||||
{ label: "NAT & firewall ports", href: "/about-netbird/ports-and-firewalls" },
|
||||
{ label: "Corporate firewalls", href: "/about-netbird/ports-and-firewalls#corporate-firewalls" },
|
||||
{ label: "DNS", href: "/manage/dns/troubleshooting" },
|
||||
{ label: "Network routes", href: "/manage/network-routes" },
|
||||
{ label: "Quick checklist", href: "/manage/reverse-proxy/troubleshooting#quick-diagnostics-checklist" },
|
||||
{ label: "502 to the routing peer's own IP", href: "/manage/reverse-proxy/troubleshooting#issue-1-502-errors-when-routing-peer-forwards-to-its-own-ip" },
|
||||
{ label: "Service on localhost", href: "/manage/reverse-proxy/troubleshooting#issue-2-service-bound-to-localhost-is-unreachable" },
|
||||
{ label: "TCP service gets no response", href: "/manage/reverse-proxy/troubleshooting#issue-4-tcp-service-is-active-but-connections-get-no-response" },
|
||||
{ label: "Domain Pending Verification", href: "/manage/reverse-proxy/custom-domains#domain-shows-as-pending-verification" },
|
||||
{ label: "Certificate not issued", href: "/manage/reverse-proxy/custom-domains#certificate-is-not-issued-after-verification" },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: "Access control",
|
||||
href: "/manage/access-control",
|
||||
icon: "shield",
|
||||
title: "Self-hosted",
|
||||
href: "/selfhosted/troubleshooting",
|
||||
icon: "server",
|
||||
description:
|
||||
"Traffic being allowed or denied unexpectedly.",
|
||||
"Your own NetBird server: installation, identity, dashboard, certificates, connectivity, and database.",
|
||||
chips: [
|
||||
{ label: "Policies", href: "/manage/access-control" },
|
||||
{ label: "Posture checks", href: "/manage/access-control/posture-checks" },
|
||||
{ label: "Groups", href: "/manage/access-control#understanding-groups" },
|
||||
{ label: "Installation", href: "/selfhosted/troubleshooting/installation" },
|
||||
{ label: "Embedded IdP", href: "/selfhosted/troubleshooting/identity-provider" },
|
||||
{ label: "Dashboard", href: "/selfhosted/troubleshooting/dashboard" },
|
||||
{ label: "Certificates", href: "/selfhosted/troubleshooting/certificates" },
|
||||
{ label: "Connectivity", href: "/selfhosted/troubleshooting/connectivity" },
|
||||
{ label: "Management unreachable", href: "/selfhosted/troubleshooting/connectivity#management-service-unreachable" },
|
||||
{ label: "Database", href: "/selfhosted/troubleshooting/database" },
|
||||
],
|
||||
},
|
||||
]}
|
||||
@@ -89,10 +142,16 @@ next to the feature they cover, so nothing here is a copy.
|
||||
|
||||
<StillStuck
|
||||
title="Still stuck?"
|
||||
description="Bring your debug bundle. The community and the team can help from there."
|
||||
id="still-stuck"
|
||||
separator="or"
|
||||
actions={[
|
||||
{ label: "Contact our Community", href: "/help/community-support", primary: true },
|
||||
{ label: "Contact NetBird Support", href: "/help/netbird-support", primary: true },
|
||||
{ label: "Contact our Community", href: "/help/community-support", primary: true, note: "Free for everyone." },
|
||||
{ label: "Contact NetBird Support", href: "/help/netbird-support", primary: true, note: "Mainly for paying NetBird Cloud customers and commercial-license deployments." },
|
||||
]}
|
||||
linksLabel="Preparing a report? Include your NetBird version (netbird version) and steps to reproduce. For problems on a peer, add a debug bundle."
|
||||
links={[
|
||||
{ label: "Debug bundle", href: "/help/troubleshooting-client#debug-bundle" },
|
||||
{ label: "Record a HAR file", href: "/help/recording-a-har-file" },
|
||||
{ label: "Support matrix", href: "/help/support-matrix" },
|
||||
]}
|
||||
/>
|
||||
|
||||
@@ -41,6 +41,7 @@ This page helps with issues when self-hosting NetBird. Collect the diagnostics b
|
||||
<TroubleshootingStart
|
||||
eyebrow="Start here"
|
||||
title="Collect diagnostics first"
|
||||
id="collect-diagnostics-first"
|
||||
description="Almost every self-hosted issue is faster to resolve with service status and logs in hand. Grab these before you go deeper."
|
||||
steps={[
|
||||
{ label: "1. Check services", title: "Service status", command: "docker compose ps", hint: "Are netbird-server and dashboard Up, plus traefik if you chose the built-in Traefik? Installs from before v0.65.0 run separate management, signal, and relay services instead." },
|
||||
|
||||
Reference in New Issue
Block a user