diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index 32d7aff5..79b62b29 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -20,4 +20,4 @@ jobs: uses: codespell-project/actions-codespell@v2 with: skip: package.json,package-lock.json - ignore_words_list: erro + ignore_words_list: erro,wasn diff --git a/src/pages/how-to/troubleshooting-client.mdx b/src/pages/how-to/troubleshooting-client.mdx index da8f8af3..fce07399 100644 --- a/src/pages/how-to/troubleshooting-client.mdx +++ b/src/pages/how-to/troubleshooting-client.mdx @@ -79,8 +79,8 @@ As for Peers, the status will show the following information: * `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. + 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. @@ -99,82 +99,91 @@ a [github issue](https://github.com/netbirdio/netbird/issues/new/choose) and att A debug archive containing the recent logs and the status at the time of execution can be generated with the following command. -Adding the `-A` flag will anonymize the logs, removing sensitive information such as public IP addresses and domain -names. Adding the `-S` flag will add system information like network routes and interfaces +Adding the `--anonymize (-A)` flag will anonymize the logs, removing sensitive information such as public IP addresses and domain +names. In case you have tunneling issues, omitting the `--anonymize` flag might help our analysis. +Adding the `--system-info (-S)` flag will add system information like network routes and interfaces ```shell -netbird debug bundle -AS +netbird debug bundle --anonymize --system-info ``` This will output the path of the generated file. The output file is owned by and can only be accessed by the user -NetBird is running as, by default it is: `Administrator` on Windows, `root` on MacOS/Linux or the operating system's +NetBird is running as, by default it is: `Administrator` on Windows, `root` on MacOS/Linux or the operating system\'s equivalent. -### Debug bundle uploads - - -New in version `0.43.1`. - - -Without local administrative privileges you can still share the debug bundles with us -by using the `-U` / `--upload-bundle` flag. -It will securely upload the debug bundle to our servers for access by the NetBird support team. - -```shell -netbird debug bundle -AS -U -``` - -This will output an `Upload file key`, which is effectively a random filename in our internal storage system -and can be safely shared with us through insecure channels such as GitHub Issues or Slack. - -```text -> sudo netbird debug bundle -U -Local file: -/tmp/netbird.debug.2611377582.zip -Upload file key: -1234567890ab27fb37c88b3b4be7011e22aa2e5ca6f38ffa9c4481884941f726/12345678-90ab-cdef-1234-567890abcdef -``` - -### Debug bundle uploads with GUI - - -New in version `0.43.2`. - - -You can also use the GUI `Settings` > `Create Debug Bundle` wizard to upload the bundle: - -

- service-user-overview -

- -

- service-user-overview -

- -

- service-user-overview -

- ### Debug for a specific time To capture logs for a specific time period, you can use the `debug for` command. This will generate a debug bundle after the specified time has elapsed. ```shell -netbird debug for 5m -AS +netbird debug for 5m --system-info ``` + + The flag `--anonymize (-A)` can be used to anonymize IP addresses and non-netbird.io domains in logs and status output when needed. + To capture any issues arising during the `up` and `down` processes, this will set the log level to `TRACE` and bring netbird `up` and `down` up to a few times. After 5 minutes the netbird status will be restored to the previous state and the debug bundle will be generated. + +### Debug bundle uploads +Since version `0.43.1`, you can share debug bundle with the NetBird development team without local administrative privileges +by using the `--upload-bundle (-U)` flag. +It will securely generate and upload the debug bundle to our servers for access by the NetBird development team. See examples below: + +Run debug for a specific time and upload the bundle: +```shell +netbird debug for 1m --system-info --upload-bundle +``` +To generate a bundle without restarting the client and then uploading: +```shell +netbird debug bundle --system-info --upload-bundle +``` + +This will output an `Upload file key`, which is effectively a random filename in our internal storage system +and can be safely shared with us through public channels such as GitHub Issues or Slack. + +```shell +netbird debug bundle --system-info --upload-bundle +Local file: +/tmp/netbird.debug.2611377582.zip +Upload file key: +1234567890ab27fb37c88b3b4be7011e22aa2e5ca6f38ffa9c4481884941f726/12345678-90ab-cdef-1234-567890abcdef +``` + + The flag `--anonymize` can be used to anonymize IP addresses and non-netbird.io domains in logs and status output when needed. + +### Debug bundle uploads with GUI +Since version `0.43.2` users can upload their debug bundle via the GUI client. + +To generate a bundle via GUI, you can access the application then go to `Settings` > `Create Debug Bundle` and follow the wizard to upload the bundle: + +

+ service-user-overview +

+ + If needed, you can update the upload URL and select to anonymize sensitive information like IP addresses and non-netbird.io domains in logs and status output. + +

+ service-user-overview +

+By default running with trace log enable before generating the bundle is selected. This will restart the client connections and provide a `disconnect to connected` information for our engineers. + +If you uncheck this option, a bundle will be generated without running this step. Which is very useful when you have an issue that recovers when restarting the client. +

+ service-user-overview +

+Once the bundle generation is complete, you can click on `Copy Key` to get the uploaded key and share with NetBird\'s team. + ## Enabling debug logs on agent Logs can be temporarily set using the following command. ```shell netbird debug log level debug -```` +``` or @@ -213,10 +222,8 @@ sudo netbird service start You need to run the following commands with an elevated PowerShell or `cmd.exe` window. ```shell -netbird service stop -netbird service uninstall -netbird service install --log-level debug # or trace -netbird service start +[Environment]::SetEnvironmentVariable("NB_LOG_LEVEL", "debug", "Machine") +netbird service restart ``` ### On Docker @@ -335,7 +342,7 @@ The most notable examples of encountering the issue are: - shared machines, - a machine that was previously logged in using Setup Key, but now attempts SSO login, -- a machine's Peer got removed from the Dashboard without clearing the file, +- a machine\'s Peer got removed from the Dashboard without clearing the file, - the user uses different browser/profile or selects the wrong account during SSO login at the start of the workday, ## Debugging access to network resources @@ -754,7 +761,7 @@ sudo netstat -ltnup | grep ':53' | grep netbird When you configure an internal _Nameserver_, not accessible from the Internet in addition to steps described in the previous section _Public nameservers_ -you should make sure the _Nameserver_'s IP addresses are properly routed and accessible. +you should make sure the _Nameserver_\'s IP addresses are properly routed and accessible. Please refer to _Access from `peer-a` to `srv-c`_ section above.