diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml new file mode 100644 index 00000000..af54dc75 --- /dev/null +++ b/.github/workflows/codespell.yml @@ -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 diff --git a/docs/getting-started/zitadel-quickstart.md b/docs/getting-started/zitadel-quickstart.md deleted file mode 100644 index 08428318..00000000 --- a/docs/getting-started/zitadel-quickstart.md +++ /dev/null @@ -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:///.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 -``` \ No newline at end of file diff --git a/public/docs-static/img/troubleshooting/turn-test-out.png b/public/docs-static/img/troubleshooting/turn-test-out.png new file mode 100644 index 00000000..04873b21 Binary files /dev/null and b/public/docs-static/img/troubleshooting/turn-test-out.png differ diff --git a/public/docs-static/img/troubleshooting/turn.png b/public/docs-static/img/troubleshooting/turn.png new file mode 100644 index 00000000..c9ca7e7a Binary files /dev/null and b/public/docs-static/img/troubleshooting/turn.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 917db3e9..4f50076d 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -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' }, ], }, - ] diff --git a/src/pages/how-to/getting-started.mdx b/src/pages/how-to/getting-started.mdx index 7280e9e8..fa312d6a 100644 --- a/src/pages/how-to/getting-started.mdx +++ b/src/pages/how-to/getting-started.mdx @@ -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 diff --git a/src/pages/how-to/installation.mdx b/src/pages/how-to/installation.mdx index 81603860..ced37923 100644 --- a/src/pages/how-to/installation.mdx +++ b/src/pages/how-to/installation.mdx @@ -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 diff --git a/src/pages/how-to/troubleshooting-client.mdx b/src/pages/how-to/troubleshooting-client.mdx new file mode 100644 index 00000000..db238b9d --- /dev/null +++ b/src/pages/how-to/troubleshooting-client.mdx @@ -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= -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 +``` diff --git a/src/pages/selfhosted/identity-providers.mdx b/src/pages/selfhosted/identity-providers.mdx index 096eaae7..6fcb6fc1 100644 --- a/src/pages/selfhosted/identity-providers.mdx +++ b/src/pages/selfhosted/identity-providers.mdx @@ -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://`, `https://.*`, `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` diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx index 16a8171c..09dd73d1 100644 --- a/src/pages/selfhosted/selfhosted-guide.mdx +++ b/src/pages/selfhosted/selfhosted-guide.mdx @@ -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 ``` diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx index 0d704a9b..d9d5d1b2 100644 --- a/src/pages/selfhosted/selfhosted-quickstart.mdx +++ b/src/pages/selfhosted/selfhosted-quickstart.mdx @@ -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. diff --git a/src/pages/selfhosted/troubleshooting.mdx b/src/pages/selfhosted/troubleshooting.mdx new file mode 100644 index 00000000..8193f5ae --- /dev/null +++ b/src/pages/selfhosted/troubleshooting.mdx @@ -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 netbird.DOMAIN.com and PASSWORD with the information from the management.json TURNConfig, then click on Add server. + +

+ turn +

+ +You should see an output similar to the following: +

+ turn +

+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).