mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-15 23:16:36 +00:00
Add troubleshooting page (#136)
--------- Co-authored-by: Maycon Santos <mlsmaycon@gmail.com>
This commit is contained in:
Zoltan Papp
22
.github/workflows/codespell.yml
vendored
Normal file
22
.github/workflows/codespell.yml
vendored
Normal 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
|
||||
@@ -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`
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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`
|
||||
|
||||
|
||||
|
||||
|
||||
### 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
BIN
public/docs-static/img/troubleshooting/turn-test-out.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 89 KiB |
BIN
public/docs-static/img/troubleshooting/turn.png
Normal file
BIN
public/docs-static/img/troubleshooting/turn.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 77 KiB |
@@ -62,7 +62,7 @@ export const docsNavigation = [
|
||||
{ title: 'Delete your NetBird account', href: '/how-to/delete-account' },
|
||||
{ title: 'IdP sync', href: '/how-to/idp-sync' },
|
||||
{ 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: 'Management SQLite Store', href: '/selfhosted/sqlite-store'},
|
||||
{ title: 'Supported IdPs', href: '/selfhosted/identity-providers' },
|
||||
{ title: 'Troubleshooting', href: '/selfhosted/troubleshooting' },
|
||||
],
|
||||
},
|
||||
|
||||
]
|
||||
|
||||
|
||||
|
||||
@@ -242,9 +242,9 @@ Recommended way is to add NetBird in firewall settings:
|
||||
|
||||
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 **Arch** with your target system CPU archtecture
|
||||
- Replace **Arch** with your target system CPU architecture
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
- Replace **VERSION** with the latest released verion.
|
||||
- Replace **VERSION** with the latest released version.
|
||||
- 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>
|
||||
|
||||
|
||||
163
src/pages/how-to/troubleshooting-client.mdx
Normal file
163
src/pages/how-to/troubleshooting-client.mdx
Normal 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
|
||||
```
|
||||
@@ -472,7 +472,7 @@ In this step, we will create OAuth2/OpenID Provider in Authentik.
|
||||
- Name: `Netbird`
|
||||
- Authentication Flow: `default-authentication-flow (Welcome to authentik!)`
|
||||
- Authorization Flow: `default-provider-authorization-explicit-consent (Authorize Application)`
|
||||
- Protocal Settings:
|
||||
- Protocol Settings:
|
||||
- Client type: `Public`
|
||||
- Redirect URIs/Origins (RegEx): `https://<domain>`, `https://<domain>.*`, `http://localhost:53000` (Each URI should be entered on a new line)
|
||||
- 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.
|
||||
- Navigate to Okta Admin Dashboard
|
||||
- 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`
|
||||
- Sign-in method: `OIDC - OpenID Connect`
|
||||
- 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.
|
||||
- Navigate to Okta Admin Dashboard
|
||||
- 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`
|
||||
- Sign-in method: `OIDC - OpenID Connect`
|
||||
- Application type: `Native Application`
|
||||
|
||||
@@ -38,7 +38,7 @@ REPO="https://github.com/netbirdio/netbird/"
|
||||
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
@@ -98,7 +98,7 @@ rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-
|
||||
|
||||
### 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.
|
||||
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
23
src/pages/selfhosted/troubleshooting.mdx
Normal 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).
|
||||
Reference in New Issue
Block a user