sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-15 23:16:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add troubleshooting page (#136)

Browse Source 
---------

Co-authored-by: Maycon Santos <mlsmaycon@gmail.com>
This commit is contained in:
Zoltan Papp
2024-01-30 13:56:19 +01:00
committed by GitHub
parent 1a2fa325e6
commit d19c0da982
12 changed files with 219 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
.github/workflows/codespell.yml vendored Normal file
View File

@@ -0,0 +1,22 @@
name: codespell
on: [pull_request]
permissions:
contents: read
pull-requests: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.head_ref || github.actor_id }}
cancel-in-progress: true
jobs:
codespell:
name: codespell
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: codespell
uses: codespell-project/actions-codespell@v2
with:
skip: package.json,package-lock.json

133
docs/getting-started/zitadel-quickstart.md
View File

@@ -1,133 +0,0 @@
---
sidebar_position: 4
title: Zitadel Quickstart Guide
---
NetBird is open-source and can be self-hosted on your servers.
This guide describes how to quickly get started with a self-hosted NetBird instance with an auto-configured Zitadel identity provider. It explains the steps to set up and configure this configuration, enabling you to efficiently start using your own self-hosted NetBird instance.
### Step 1: Create Zitadel Service User
In this step we will create a `netbird` service user.
- Navigate to zitadel console
- Click `Users` in the top menu
- Select `Service Users` tab
- Click `New`
- Fill in the form with the following values:
- User Name: `netbird`
- Name: `netbird`
- Description: `Netbird Service User`
- Access Token Type: `JWT`
- Click `Create`
![](/img/getting-started/zitadel-create-user.png)
In this step we will generate `ClientSecret` for the `netbird` service user.
- Click `Actions` in the top right corner and click `Generate Client Secret`
- Copy `ClientSecret` from the dialog will be used later to set `ClientSecret` when prompted.
![](/img/getting-started/zitadel-service-user-secret.png)
### Step 2: Grant manage-organization role to netbird service user
In this step we will grant `Org User Manager` role to `netbird` service user.
- Click `Organization` in the top menu
- Click `+` in the top right corner
- Search for `netbird` service user
- Check `Org Owner` checkbox
- Click `Add`
![](/img/getting-started/zitadel-service-account-role.png)
### Step 3: Get the latest stable NetBird code
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.19.0
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG
# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```
Then switch to the infra folder that contains docker-compose file:
```bash
cd netbird/infrastructure_files/
```
### Step 4: Prepare configuration files
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.zitadel.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.zitadel.tmpl) files.
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
```bash
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR-ZITADEL-HOST-AND-PORT>/.well-known/openid-configuration"
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_IDP_PROVIDER="zitadel"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
:::tip
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
:::
:::info
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](self-hosting#advanced-running-netbird-behind-an-existing-reverse-proxy).
:::
### Step 5: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
In most cases, this is the desired behavior.
If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.
### Step 6: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
./configure.sh
```
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
### Step 7: Run docker compose:
```bash
docker-compose up -d
```
### Step 8: Check docker logs (Optional)
```bash
docker-compose logs signal
docker-compose logs management
docker-compose logs coturn
docker-compose logs dashboard
```

BIN
public/docs-static/img/troubleshooting/turn-test-out.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 89 KiB

BIN
public/docs-static/img/troubleshooting/turn.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

4
src/components/NavigationDocs.jsx
View File

@@ -62,7 +62,7 @@ export const docsNavigation = [
{ title: 'Delete your NetBird account', href: '/how-to/delete-account' }, { title: 'Delete your NetBird account', href: '/how-to/delete-account' },
{ title: 'IdP sync', href: '/how-to/idp-sync' }, { title: 'IdP sync', href: '/how-to/idp-sync' },
{ title: 'Report bugs and issues', href: '/how-to/report-bug-issues' }, { title: 'Report bugs and issues', href: '/how-to/report-bug-issues' },
{ title: 'Troubleshooting client issues', href: '/how-to/troubleshooting-client' },
], ],
}, },
{ {
@@ -72,9 +72,9 @@ export const docsNavigation = [
{ title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' }, { title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' },
{ title: 'Management SQLite Store', href: '/selfhosted/sqlite-store'}, { title: 'Management SQLite Store', href: '/selfhosted/sqlite-store'},
{ title: 'Supported IdPs', href: '/selfhosted/identity-providers' }, { title: 'Supported IdPs', href: '/selfhosted/identity-providers' },
{ title: 'Troubleshooting', href: '/selfhosted/troubleshooting' },
], ],
}, },
] ]

4
src/pages/how-to/getting-started.mdx
View File

@@ -242,9 +242,9 @@ Recommended way is to add NetBird in firewall settings:
You need to replace some variables from the URL above: You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released verion. - Replace **VERSION** with the latest released version.
- Replace **OS** with "linux", "darwin" for MacOS or "windows" - Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU archtecture - Replace **Arch** with your target system CPU architecture
</Note> </Note>

4
src/pages/how-to/installation.mdx
View File

@@ -191,9 +191,9 @@ NetBird has an official Android application that you can download at Google Play
You need to replace some variables from the URL above: You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released verion. - Replace **VERSION** with the latest released version.
- Replace **OS** with "linux", "darwin" for MacOS or "windows" - Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU archtecture - Replace **Arch** with your target system CPU architecture
</Note> </Note>

163
src/pages/how-to/troubleshooting-client.mdx Normal file
View File

@@ -0,0 +1,163 @@
# Troubleshooting client issues
This document offers practical tips and insights to help you debug various problems, ensuring a seamless user experience.
## NetBird agent status
The netbird agent is a daemon service that runs in the background; it provides information about peers connected and about the NetBird control services. You can check the status of the agent with the following command:
```shell
netbird status --detail
````
This will output the following information:
```shell
Peers detail:
server-a.netbird.cloud:
NetBird IP: 100.75.232.118/32
Public key: kndklnsakldvnsld+XeRF4CLr/lcNF+DSdkd/t0nZHDqmE=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): 10.128.0.35:51820/10.128.0.54:51820
Last connection update: 2024-01-30 08:52:51
Last Wireguard handshake: 2024-01-30 10:58:13
Transfer status (received/sent) 6.1 KiB/20.6 KiB
server-b.netbird.cloud:
NetBird IP: 100.75.226.48/32
Public key: Mi6jtrK5Tokndklnsakldvnsld+XeRF4CLr/lcNF+DSdkd=
Status: Connected
-- detail --
Connection type: Relayed
Direct: false
ICE candidate (Local/Remote): relay/host
ICE candidate endpoints (Local/Remote): 108.54.10.33:60434/10.128.0.12:51820
Last connection update: 2024-01-30 08:52:51
Last Wireguard handshake: 2024-01-30 10:58:13
Transfer status (received/sent) 6.1 KiB/20.6 KiB
Daemon version: 0.25.5
CLI version: 0.25.5
Management: Connected to https://api.netbird.io:443
Signal: Connected to https://signal.netbird.io:443
Relays:
[stun:turn.netbird.io:5555] is Available
[turns:turn.netbird.ioo:443?transport=tcp] is Available
FQDN: maycons-mbp-2.netbird.cloud
NetBird IP: 100.75.143.239/16
Interface type: Kernel
Peers count: 2/2 Connected
```
As you can see, the output shows the peers connected, the NetBird IP address, the public key, the connection status, and the connection type.
The status will also report if there is an issue connecting to the relay servers, the management server, or the signal server.
As for Peers, the status will show the following information:
* `Connection type`: P2P, Relayed, where relayed connections indicate a limitation in the network that prevents a direct connection between the peers.
* `Direct`: true/false, where true indicates a direct connection between the peers without a local proxy. This case is common when the local peer is allocating the relay connection.
* `ICE candidate (Local/Remote)`: relay/host, where relay indicates that the local peer is using a relay connection and host indicates that the remote peer is using a direct connection.
* `Last Wireguard handshake`: Indicating the last time the Wireguard handshake was performed. Usually, this is performed every 2 minutes, and if you don't see an update here or if the value is empty, that indicates that the connection wasn't possible yet.
* `Transfer status (received/sent)`: Indicating the amount of data received and sent by the peer. This is useful to check if the connection is being used.
See more details about the status command [here](/how-to/cli#status).
## Getting client logs
By default, client logs are located in the `/var/log/netbird/client.log` folder on macOS and Linux and in the `C:\ProgramData\netbird\client.log` folder on Windows.
You can analyze the logs to identify the root cause of the problem. If you need help, open a [github issue](https://github.com/netbirdio/netbird/issues/new/choose) and attach the logs.
## Enabling debug logs on agent
### On Linux with systemd
The default systemd unit file reads a set of environment variables from the path `/etc/sysconfig/netbird`. You can add the following line to the file to enable debug logs:
```shell
sudo mkdir -p /etc/sysconfig
echo 'NB_LOG_LEVEL=debug' | sudo tee -a /etc/sysconfig/netbird
sudo systemctl restart netbird
```
### On Other Linux and MacOS
```shell
sudo netbird service stop
sudo netbird service uninstall
sudo netbird service install --log-level debug # or trace
sudo netbird service start
```
### On Windows
You need to run the following commands with an elevated Powershell window.
```shell
netbird service stop
netbird service uninstall
netbird service install --log-level debug # or trace
netbird service start
```
### On Docker
You can set the environment variable `NB_LOG_LEVEL` to `debug` to enable debug logs.
```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:/etc/netbird netbirdio/netbird:latest
```
## Running the agent in foreground mode
You can run the agent in foreground mode to see the logs in the terminal. This is useful to debugging issues with the agent.
### Linux and MacOS
```shell
sudo netbird service stop
sudo netbird up -F
```
### Windows
On Windows, the agent depends on the Wireguard's `wintun.dll` and can only be executed as a system account.
To run the agent in foreground mode, you need to use a tool called [PSExec](https://learn.microsoft.com/en-us/sysinternals/downloads/psexec).
Once you have downloaded and extracted `psexec` open 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"
```
In case you need to configure environment variables, you need to add them as system variables so they get picked up by the agent on the next psexec run:
```shell
[Environment]::SetEnvironmentVariable("PIONS_LOG_DEBUG", "all", "Machine")
````
## Enabling WireGuard in user space
Sometimes, you want to test NetBird running on userspace mode instead of a kernel module. That can be a check to see if there is a problem with NetBird's firewall management in kernel mode.
You must run the agent in foreground mode and set the environment variable `NB_WG_KERNEL_DISABLED` to `true`.
```shell
sudo netbird service stop
sudo bash -c 'NB_WG_KERNEL_DISABLED=true netbird up -F' > /tmp/netbird.log
```
## Debugging GRPC
The NetBird agent communicates with the Management and Signal servers using the GRPC framework. With these parameters, you can
set verbose logging for this service.
```shell
sudo netbird service stop
sudo bash -c 'GRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info netbird up -F' > /tmp/netbird.log
```
## Debugging ICE connections
The Netbird agent communicates with other peers through the Interactive Connectivity Establishment (ICE) protocol described in the [RFC 8445](https://datatracker.ietf.org/doc/html/rfc8445). To debug the connection procedure,
set verbose logging for the the [Pion/ICE](https://github.com/pion/ice) library with the `PIONS_LOG_DEBUG` or `PIONS_LOG_TRACE` variable.
```shell {{ title: 'Environment variable' }}
PIONS_LOG_DEBUG=all
NB_LOG_LEVEL=debug
```
```shell
sudo netbird service stop
sudo bash -c 'PIONS_LOG_DEBUG=all NB_LOG_LEVEL=debug netbird up -F' > /tmp/netbird.log
```

6
src/pages/selfhosted/identity-providers.mdx
View File

@@ -472,7 +472,7 @@ In this step, we will create OAuth2/OpenID Provider in Authentik.
- Name: `Netbird` - Name: `Netbird`
- Authentication Flow: `default-authentication-flow (Welcome to authentik!)` - Authentication Flow: `default-authentication-flow (Welcome to authentik!)`
- Authorization Flow: `default-provider-authorization-explicit-consent (Authorize Application)` - Authorization Flow: `default-provider-authorization-explicit-consent (Authorize Application)`
- Protocal Settings: - Protocol Settings:
- Client type: `Public` - Client type: `Public`
- Redirect URIs/Origins (RegEx): `https://<domain>`, `https://<domain>.*`, `http://localhost:53000` (Each URI should be entered on a new line) - Redirect URIs/Origins (RegEx): `https://<domain>`, `https://<domain>.*`, `http://localhost:53000` (Each URI should be entered on a new line)
- Advanced protocol settings: - Advanced protocol settings:
@@ -726,7 +726,7 @@ Before you start creating and configuring an Okta application, ensure that you h
In this step, we will create and configure Netbird single-page application in okta. In this step, we will create and configure Netbird single-page application in okta.
- Navigate to Okta Admin Dashboard - Navigate to Okta Admin Dashboard
- Click `Applications` in the left menu and then click on `Applications` - Click `Applications` in the left menu and then click on `Applications`
- Click `Create App Intergration` - Click `Create App Integration`
- Fill in the form with the following values and click `Next` - Fill in the form with the following values and click `Next`
- Sign-in method: `OIDC - OpenID Connect` - Sign-in method: `OIDC - OpenID Connect`
- Application type: `Single-Page Application` - Application type: `Single-Page Application`
@@ -761,7 +761,7 @@ In this step, we will create and configure Netbird single-page application in ok
In this step, we will create and configure Netbird native application in okta. In this step, we will create and configure Netbird native application in okta.
- Navigate to Okta Admin Dashboard - Navigate to Okta Admin Dashboard
- Click `Applications` in the left menu and then click on `Applications` - Click `Applications` in the left menu and then click on `Applications`
- Click `Create App Intergration` - Click `Create App Integration`
- Fill in the form with the following values and click `Next` - Fill in the form with the following values and click `Next`
- Sign-in method: `OIDC - OpenID Connect` - Sign-in method: `OIDC - OpenID Connect`
- Application type: `Native Application` - Application type: `Native Application`

2
src/pages/selfhosted/selfhosted-guide.mdx
View File

@@ -38,7 +38,7 @@ REPO="https://github.com/netbirdio/netbird/"
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest)) LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG echo $LATEST_TAG
# this comman will clone the latest tag # this command will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO git clone --depth 1 --branch $LATEST_TAG $REPO
``` ```

2
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -98,7 +98,7 @@ rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-
### Troubleshoot ### Troubleshoot
- I'm trying to register a user but I didn't receive a verification code. Whats is the problem? - I'm trying to register a user but I didn't receive a verification code. What's the problem?
The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network. The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network.
If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See [this guide](https://zitadel.com/docs/guides/manage/console/instance-settings#smtp) or details. If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See [this guide](https://zitadel.com/docs/guides/manage/console/instance-settings#smtp) or details.

23
src/pages/selfhosted/troubleshooting.mdx Normal file
View File

@@ -0,0 +1,23 @@
# Troubleshooting
This page will help with various issues when self-hosting NetBird.
## Debugging TURN connections
In the case that the peer-to-peer connection is not an option then the peer will use the TURN server for the secure connection establishment. If the connection is not possible even with TURN (Relay),
then we need to confirm that your turn configuration is correct and that it is available.
To test your TURN configuration you can access the [online tester](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice).
There you will find a ICE servers input box, where you can select and remove the existing server, then add your turn server
configuration as follows:
Please replace <b>netbird.DOMAIN.com</b> and <b>PASSWORD</b> with the information from the <b>management.json</b> TURNConfig, then click on <b>Add server</b>.
<p>
<img src="/docs-static/img/troubleshooting/turn.png" alt="turn" width="700" className="imagewrapper"/>
</p>
You should see an output similar to the following:
<p>
<img src="/docs-static/img/troubleshooting/turn-test-out.png" alt="turn" width="700" className="imagewrapper"/>
</p>
Where you have the following types: `host` (local address), `srflx` (STUN reflexive address), `relay`
(TURN relay address). If `srflx` and `relay` are not present then the TURN server is not working or not accessible and you should review the required ports in the [requirements section](/selfhosted/selfhosted-guide#requirements).