Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add troubleshooting page #136

Merged
merged 7 commits into from
Jan 30, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added public/docs-static/img/troubleshooting/turn.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions src/components/NavigationDocs.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,12 @@ export const docsNavigation = [
{ title: 'Supported IdPs', href: '/selfhosted/identity-providers' },
],
},
{
title: 'Troubleshooting',
links: [
{ title: 'Troubleshooting guide', href: '/troubleshooting/guide' },
],
},

]

Expand Down
84 changes: 84 additions & 0 deletions src/pages/troubleshooting/guide.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Torubleshooting guide

This document offers practical tips and insights to help you debug various problems, ensuring a seamless user experience.
In general, you can manipulate the agent using environment variables. In a Linux environment, you can set permanent
settings in the `/etc/sysconfig/netbird` file. With this code snippet you can apply the configuration parameters.

```bash {{ 'title': '/etc/sysconfig/netbir' }}
mkdir -p /etc/sysconfig
echo 'NB_LOG_LEVEL=debug' | sudo tee -a /etc/sysconfig/netbird
systemctl restart netbird
```

## NetBird agent status

Retrieves the peer status from the daemon service. See more [here](/how-to/cli#status).

## Enabling debug logs on agent

You can set `debug` or `trace` log levels. The log files are avabile on Linux in `/var/log/netbird` folder and on Windows
pappz marked this conversation as resolved.
Show resolved Hide resolved
in `C:\ProgramData\netbird` folder.

### On systemd
```shell {{ title: 'Environment variable' }}
NB_LOG_LEVEL=debug
```

### On Windows

```shell
netbird service stop
netbird service uninstall
netbird service install --log-level debug # or trace
netbird service start
```

## Enabling WireGuard in user space
The NetBird applies WireGuard with kernel module by default. With environments variable you can force to use userspace mode.
pappz marked this conversation as resolved.
Show resolved Hide resolved

```shell {{ title: 'Environment variable' }}
NB_WG_KERNEL_DISABLED=true
```

## Debugging GRPC

The NetBird agent communicate with the Managmenet and Signal server with GRPC framework. With these parameters you can
pappz marked this conversation as resolved.
Show resolved Hide resolved
set verbose logging for these service.
pappz marked this conversation as resolved.
Show resolved Hide resolved

```shell
GRPC_GO_LOG_VERBOSITY_LEVEL=99
GRPC_GO_LOG_SEVERITY_LEVEL=info
```

## Debugging peer connections

The Netbird agent do communication with other peers by the Pion ICE library. For debug the connection procedure,
pappz marked this conversation as resolved.
Show resolved Hide resolved
set verbose logging for the Pion.

```shell {{ title: 'Environment variable' }}
PIONS_LOG_DEBUG=all
NB_LOG_LEVEL=debug
```

After running your service with the environments above you should see logs in the following format:

```
2023-10-18T19:40:31+05:30 2023/10/18 14:10:31 INFO: [core] [Channel #4] Channel deleted
2023-10-18T19:40:31+05:30 2023/10/18 14:10:31 INFO: [core] [Channel #4 SubChannel #5] Subchannel deleted
2023-10-18T19:40:31+05:30 2023/10/18 14:10:31 INFO: [core] [Channel #4 SubChannel #5] Subchannel Connectivity change to SHUTDOWN
2023-10-18T19:40:31+05:30 2023/10/18 14:10:31 INFO: [core] [Channel #4] Channel Connectivity change to SHUTDOWN
```

## Debugging TURN connections

In case the peer-to-peer connection is not an option then the peer will use TURN server for the secure connection establishment.
pappz marked this conversation as resolved.
Show resolved Hide resolved

To test your TURN configuration by accessing the [online tester](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice).
pappz marked this conversation as resolved.
Show resolved Hide resolved
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>