diff --git a/public/docs-static/img/get-started/android-tv/change-server.png b/public/docs-static/img/get-started/android-tv/change-server.png new file mode 100644 index 00000000..ed2ab292 Binary files /dev/null and b/public/docs-static/img/get-started/android-tv/change-server.png differ diff --git a/public/docs-static/img/get-started/android-tv/main-menu-change-server.png b/public/docs-static/img/get-started/android-tv/main-menu-change-server.png new file mode 100644 index 00000000..66551eb6 Binary files /dev/null and b/public/docs-static/img/get-started/android-tv/main-menu-change-server.png differ diff --git a/public/docs-static/img/get-started/android-tv/main-screen.png b/public/docs-static/img/get-started/android-tv/main-screen.png new file mode 100644 index 00000000..a5cac45d Binary files /dev/null and b/public/docs-static/img/get-started/android-tv/main-screen.png differ diff --git a/public/docs-static/img/get-started/tvos/authentication-screen.png b/public/docs-static/img/get-started/tvos/authentication-screen.png new file mode 100644 index 00000000..23e3b7fb Binary files /dev/null and b/public/docs-static/img/get-started/tvos/authentication-screen.png differ diff --git a/public/docs-static/img/get-started/tvos/confirm-add-vpn-config.png b/public/docs-static/img/get-started/tvos/confirm-add-vpn-config.png new file mode 100644 index 00000000..9b5e578a Binary files /dev/null and b/public/docs-static/img/get-started/tvos/confirm-add-vpn-config.png differ diff --git a/public/docs-static/img/get-started/tvos/confirm-change-server.png b/public/docs-static/img/get-started/tvos/confirm-change-server.png new file mode 100644 index 00000000..a7e618e5 Binary files /dev/null and b/public/docs-static/img/get-started/tvos/confirm-change-server.png differ diff --git a/public/docs-static/img/get-started/tvos/main-screen-connected.png b/public/docs-static/img/get-started/tvos/main-screen-connected.png new file mode 100644 index 00000000..894357b2 Binary files /dev/null and b/public/docs-static/img/get-started/tvos/main-screen-connected.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 90444461..e6204131 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -37,7 +37,9 @@ export const docsNavigation = [ { title: 'MacOS', href: '/get-started/install/macos' }, { title: 'Docker', href: '/get-started/install/docker' }, { title: 'iOS', href: '/get-started/install/ios' }, + { title: 'tvOS', href: '/get-started/install/tvos'}, { title: 'Android', href: '/get-started/install/android' }, + { title: 'Android TV', href: '/get-started/install/android-tv'} ], }, { diff --git a/src/pages/get-started/install/android-tv.mdx b/src/pages/get-started/install/android-tv.mdx new file mode 100644 index 00000000..7023d648 --- /dev/null +++ b/src/pages/get-started/install/android-tv.mdx @@ -0,0 +1,86 @@ +import {Note} from "@/components/mdx"; + +# Install NetBird on an Android TV + +The Android TV app supports devices running Android 8.0 or later. + + + Android TV support is currently in beta. + + +## Where to Download + +NetBird has an official Android application that you can download at Google Play Store: + +

+ + playstore + + +

+ +APK releases are also available to install directly on your Android device via the [NetBird Android GitHub repository](https://github.com/netbirdio/android-client/releases). + +## Configure Netbird on Android TV + +### First Launch + +Upon first launch, NetBird will inform you that it's using the default managemet server. + +firstinstall + +Select 'Continue' to ackownledge and you'll be greeted with the app's main screen. + +android-tv-main-screen + +### Management Server Configuration + + + This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to [Connecting to Your Network](#connecting-to-your-network) + + +Select the hamburger menu on the top left of the main screen (or hold the left directional button) and navigate to the 'Change Server' menu. + +android-tv-main-menu + +Changing servers erases the device's current NetBird config, so you'll need to confirm the action before proceeding: + +confirm-erase-cponfig + +Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to your management.json configuration file if you're unsure. + +If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'change' to apply your new management server config, and if successful you'll see the following: + +serverchanged + +You're now ready to connect to your Netbird network! + +#### Connecting to Your Network + +Select the NetBird logo button to connect. The app will request permission to create a VPN connection: + +vpnconnectionrequest + +Select 'OK'. If you didn't enter a setup key in the 'Change Server' menu, then you'll need to authenticate with your SSO provider. NetBird will open a browser window where you'll be instructed to sign in to your SSO provider. + +After logging in, NetBird will confirm your authentication. Once you close the browser window, your device should be connected! + +#### Authenticating + + + For self-hosted users _not_ enrolling the device with a setup key, Device Authentication needs to be enabled in the management server config. + + +Since Android TV doesn't ship with a built-in browser, and entering credentials with a remote may be less than ideal, the TV client uses a slightly different authentication flow to the mobile app. If you're not using a setup key, then after you grant the app permission +to create a VPN connection, you'll be presented a QR code and device ID: + +tvssoqr + +Scan the QR code with your phone and you'll be able to sign in to your SSO provider there. If asked to confirm your device code, confirm that the code underneath the QR code matches the one presented by your SSO provider. Once you've completed +the SSO flow, the QR code dialog in the NetBird app will automatically dismiss itself, and your device should now be connected! + +## What's next? +- Manage your device's [access](/manage/access-control/manage-network-access) to the network +- Use your device for [remote access access to your home network](/manage/networks/homelab/access-home-network) +- Use your device as an [exit node](/manage/network-routes/configuring-default-routes-for-internet-traffic#make-the-peer-an-exit-node-routing-peer) + diff --git a/src/pages/get-started/install/android.mdx b/src/pages/get-started/install/android.mdx index ecbe4cae..b2c9eb64 100644 --- a/src/pages/get-started/install/android.mdx +++ b/src/pages/get-started/install/android.mdx @@ -2,11 +2,7 @@ import {Note} from "@/components/mdx"; # Install NetBird on an Android -The Android supports mobile devices, tablets and Android TV devices running Android 8.0 or later. - - - Android TV support is currently in beta. - +The Android supports mobile devices, tablets and [Android TV](android-tv) devices running Android 8.0 or later. ## Where to Download @@ -14,7 +10,7 @@ NetBird has an official Android application that you can download at Google Play

- playstore + playstore

@@ -36,10 +32,10 @@ Select 'Continue' to ackownledge and you'll be greeted with the app's main scree ### Management Server Configuration - This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to . + This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to [Connecting to Your Network](#connecting-to-your-network) -Select the hamburger menu on the top left of the main screen (or hold the left directional button on Android TV) and navigate to the 'Change Server' menu. +Select the hamburger menu on the top left of the main screen and navigate to the 'Change Server' menu. changeserver @@ -63,17 +59,10 @@ Select the NetBird logo button to connect. The app will request permission to cr Select 'OK'. If you didn't enter a setup key in the 'Change Server' menu, then you'll need to authenticate with your SSO provider. NetBird will open a browser window where you'll be instructed to sign in to your SSO provider. -After logging in, NetBird will confirm your authentication. Once you close the browser window, your device should be connected! - -#### Authenticating on Android TV - -Since Android TV doesn't ship with a built-in browser, and entering credentials with a remote may be less than ideal, the TV client uses a slightly different authentication flow. If you're not using a setup key, then after you grant the app permission -to create a VPN connection, you'll be presented a QR code and device ID: - -tvssoqr +After logging in, NetBird will confirm your authentication. Once you close the browser window, your device should be connected! -Scan the QR code with your phone and you'll be able to sign in to your SSO provider there. If asked to confirm your device code, confirm that the code underneath the QR code matches the one presented by your SSO provider. Once you've completed -the SSO flow, the QR code dialog in the NetBird app will automatically dismiss itself, and your device should now be connected! +## What's next? +- Configure the device's [group & policy](example.com) memberships diff --git a/src/pages/get-started/install/tvos.mdx b/src/pages/get-started/install/tvos.mdx new file mode 100644 index 00000000..f3884e1d --- /dev/null +++ b/src/pages/get-started/install/tvos.mdx @@ -0,0 +1,58 @@ +import {Note} from "@/components/mdx"; + +# tvOS (Apple TV) + +The tvOS app supports all Apple TV devices running tvOS 17.0 or later. It's available to download in the Apple TV app store. + + + tvOS support is currently in beta. + + +## Configure NetBird on tvOS + +### First Launch + +tvos-confirm-add-vpn-config + +Upon first launch, NetBird will request permission to create a new VPN configuration. Select 'Allow' to continue. + +### Management Server Configuration + + + This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to [Connecting & Authenticating](#connecting-and-authenticating) + + +By default, the app is configured to connect to NetBird's cloud management server. If you're a self-hosted user, or you'd like to enroll the device with a setyo key, you'll need to +change the management server settings. + +Navigate to **'Settings > Change Server'**, and the app will warn you that changing management server settings will erase your current config and disconnect if a connection is currently active: + +tvos-confirm-change-server + +After confirming, you'll be presented with a dialog to enter your management server URL. Cloud users who want to enroll the device with a setup key should enter the URL For cloud users, this is `https://api.netbird.io:443`. +For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to your management.json configuration file if you're unsure. + +If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'Change' to apply your new management server config. NetBird will run a brief verification step +on the details you've entered, after which you can move on to connecting. + +### Connecting & Authenticating + +On the main 'Connection' screen, select the 'Connect' button to initiate a connection to your NetBird network. + + + For self-hosted users _not_ enrolling the device with a setup key, Device Authentication needs to be enabled in the management server config. + + +If you're not using a setup key, you'll be presented a QR code and device ID: + +tvos-authentication + +Scan the QR code with a mobile device and you'll be able to sign in to your SSO provider there. If asked to confirm your device code, confirm that the code underneath the QR code matches the one presented by your SSO provider. Once you've completed +the SSO flow, after a few seconds the authentication dialog in the NetBird app will automatically dismiss itself. Select the 'Connect' button once more, and your device should now be connected! + +tvos-main-screen-connected + +## What's next? +- Manage your device's [access](/manage/access-control/manage-network-access) to the network +- Use your device for [remote access access to your home network](/manage/networks/homelab/access-home-network) +- Use your device as an [exit node](/manage/network-routes/configuring-default-routes-for-internet-traffic#make-the-peer-an-exit-node-routing-peer) diff --git a/src/pages/ipa/resources/dns.mdx b/src/pages/ipa/resources/dns.mdx new file mode 100644 index 00000000..e2548a37 --- /dev/null +++ b/src/pages/ipa/resources/dns.mdx @@ -0,0 +1,380 @@ +export const description = 'Control DNS management behavior for peer groups' + +# DNS Settings + +DNS Settings allow you to control whether NetBird manages DNS configuration for specific peer groups. This is useful when certain peers need to maintain their existing DNS setup. + +## Understanding DNS Management Modes + +NetBird supports two DNS management modes per peer: + +### Managed Mode (Default) + +When a peer's group is **not** in the disabled management list: + +- ✅ NetBird configures the system's DNS settings +- ✅ All DNS queries route through NetBird's local resolver +- ✅ Configured nameservers apply to this peer +- ✅ Centralized DNS control from the dashboard + +**Use managed mode when**: You want full control over DNS resolution for the peer. + +### Unmanaged Mode + +When a peer's group **is** in the disabled management list: + +- ✅ NetBird does not modify system DNS settings +- ✅ Peer uses its pre-existing DNS configuration +- ✅ All configured nameservers are ignored for this peer +- ✅ Peer maintains complete DNS independence + +**Use unmanaged mode when**: +- Peer has conflicting VPN or DNS requirements +- Corporate policy requires specific DNS settings +- Testing or troubleshooting DNS issues +- Peer is in a restricted environment + +### Client-Side DNS Control + +You can also disable DNS management directly on a peer using the `--disable-dns` flag: + +```bash +# Disable DNS management on this peer +netbird up --disable-dns + +# Enable DNS management on this peer +netbird up --disable-dns=true +``` + +This is useful when: +- You need to disable DNS on a single peer without changing server-side settings +- Testing DNS behavior locally +- The peer has special DNS requirements not covered by group settings + + +The `--disable-dns` flag takes precedence over server-side DNS settings. Even if the management server configures nameservers for this peer's group, the peer will ignore them when this flag is set. + + +## Configuring DNS Settings + +### View Current Settings + +1. Log in to NetBird dashboard +2. Navigate to **DNS** in the sidebar +3. Click **DNS Settings** tab + +You'll see: +DNS settings + + +### Disable DNS Management for a Group + +To prevent NetBird from managing DNS for specific groups: + +1. Go to **DNS** → **DNS Settings** +2. Click the groups selection box and select groups existing groups, or type a new group name and press enter. This will create a new group inline and disable DNS management for said new group. +3. Click 'Save Changes'. + + +Changes take effect within 10-30 seconds. Peers in disabled groups will revert to their original DNS settings. + + +### Re-enable DNS Management + +To restore NetBird DNS management: + +1. Go to **DNS** → **DNS Settings** +2. Remove the group from **Disabled Management Groups** +3. Click 'Save Changes'. + +The peer will start using configured nameserver groups again. + +--- + +## Common Use Cases + +### Use Case 1: VPN Conflict + +**Problem**: Peers using another VPN conflict with NetBird's DNS management. + +**Solution**: +1. Create a distribution group for VPN users (e.g., "External VPN Users") +2. Add this group to disabled management groups +3. These peers keep their VPN's DNS settings + +### Use Case 2: Corporate DNS Policy + +**Problem**: Company policy requires specific DNS servers on certain devices. + +**Solution**: +1. Group affected peers (e.g., "Compliance Devices") +2. Disable DNS management for this group +3. Manually configure DNS on these devices per policy + +### Use Case 3: Gradual Rollout + +**Problem**: Want to test DNS changes on a subset of peers first. + +**Solution**: +1. Create "DNS Beta" and "DNS Production" groups +2. Initially disable management for "DNS Production" +3. Test with "DNS Beta" group +4. Once validated, enable management for "DNS Production" + +### Use Case 4: Troubleshooting + +**Problem**: Suspect NetBird DNS is causing connectivity issues. + +**Solution**: +1. Temporarily add peer's group to disabled management +2. Test if issue persists with original DNS +3. If fixed, investigate nameserver configuration +4. If not fixed, issue is unrelated to NetBird DNS + +--- + +## How Peers Behave in Each Mode + +### Managed Mode Behavior + +``` +Peer Startup: +1. NetBird client starts +2. Receives nameserver configuration from management +3. Configures local DNS resolver (127.0.0.1:53) +4. Updates OS DNS settings to point to 127.0.0.1 +5. Routes queries based on configured nameservers + +During Operation: +- All DNS queries go through NetBird resolver +- Configuration updates apply automatically +``` + +### Unmanaged Mode Behavior + +``` +Peer Startup: +1. NetBird client starts +2. Sees group is in disabled management list +3. Does NOT modify DNS settings +4. Does NOT start local DNS resolver for management +5. Uses existing system DNS configuration + +During Operation: +- DNS queries use system's configured servers +- NetBird nameservers have no effect +- NetBird provides connectivity only +``` + +--- + +## Checking Peer DNS Mode + +### Linux/macOS + +```bash +# Check if NetBird resolver is active +cat /etc/resolv.conf +# Should show: +# nameserver <100.X.X.X> (NetBird IP - managed) +# or other IPs (unmanaged) +``` + +### Windows + +```powershell +# Check DNS servers for NetBird adapter +Get-DnsClientServerAddress -InterfaceAlias "NetBird" + +# Managed: Shows <100.X.X.X> (NetBird IP) +# Unmanaged: Shows other servers or nothing +``` + +#### Using the NetBird CLI + +```bash +# Check NetBird status +netbird status -d +``` + +Example Output: +``` +... +Nameservers: + [1.1.1.1:53] for [.] is Available +... +``` +--- + +## Mixing Managed and Unmanaged Peers + +You can have both modes in the same network: + +**Example Configuration**: +- **All Peers** group: Mixed management + - Most peers: Managed (use configured nameservers) + - VPN users: Unmanaged (keep VPN DNS) + - Guest devices: Unmanaged (no internal DNS) + +**Result**: +- Managed peers can resolve internal domains +- Unmanaged peers only see public DNS +- Both can communicate over NetBird network + + +Even in unmanaged mode, peers can still communicate over the NetBird network. DNS management only affects name resolution, not connectivity. + + +--- + +## API Configuration + +You can manage DNS settings programmatically: + +### Get Current Settings + +```bash +curl -X GET https://api.netbird.io/api/dns/settings \ + -H "Authorization: Token " +``` + +### Update Settings + +```bash +curl -X PUT https://api.netbird.io/api/dns/settings \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{ + "disabled_management_groups": [ + "ch8i4ug6lnn4g9hqv7m0", + "ch8i4ug6lnn4g9hqv7m1" + ] + }' +``` + +See full [API Reference](/ipa/resources/dns) for more details. + +--- + +## Best Practices + +### 1. Default to Managed Mode + +Unless there's a specific reason, keep DNS managed for centralized control and consistency. + +### 2. Use Groups Strategically + +Create distribution groups that align with DNS management needs: +- ✅ Good: "External VPN Users", "Compliance Devices", "Guest Devices" +- ❌ Bad: Disabling management for individual peers repeatedly + +### 3. Document Exceptions + +Keep a record of why certain groups are unmanaged: + +``` +Disabled Management Groups: +- "External VPN Users" → Conflict with corporate VPN +- "Legacy Systems" → Cannot modify DNS (embedded systems) +- "DNS Beta" → Temporary during testing +``` + +### 4. Review Periodically + +Regularly audit disabled groups: +- Are they still needed? +- Can peers be migrated to managed mode? +- Are there security implications? + +### 5. Consider Security + +Unmanaged peers: +- May bypass corporate DNS filtering +- Could be vulnerable to DNS hijacking +- Might not respect DNS-based access controls + +Only use unmanaged mode when necessary. + +--- + +## Troubleshooting + +### Peer Not Respecting Nameservers + +**Symptom**: Configured nameservers don't apply to a peer. + +**Check**: +```bash +# On the dashboard +1. Go to DNS → DNS Settings +2. Check if peer's group is in disabled_management_groups + +# If yes → Remove from list or expected behavior +# If no → Check peer logs for errors +``` + +### Peer Reverting to Old DNS + +**Symptom**: Peer keeps using previous DNS settings after configuration change. + +**Possible causes**: +1. Group added to disabled management +2. Peer not receiving updates (connectivity issue) +3. Peer not restarted after significant change + +**Solution**: +```bash +# Restart NetBird client +netbird down +netbird up + +# Or full restart +systemctl restart netbird # Linux +# Windows: Restart NetBird service +``` + +### Cannot Disable Management for Group + +**Symptom**: Changes to DNS settings don't save or revert. + +**Check**: +- Permissions: Do you have admin rights? +- API errors: Check browser console for error messages +- Group exists: Verify the group ID is correct + +--- + +## Migration Scenarios + +### Moving from Unmanaged to Managed + +When enabling DNS management for a previously unmanaged group: + +1. **Communicate**: Warn users about DNS changes +2. **Prepare**: Create and test nameservers +3. **Schedule**: Choose low-impact time +4. **Enable**: Remove group from disabled list +5. **Verify**: Check peers are using NetBird DNS +6. **Monitor**: Watch for issues in first 24 hours + +### Moving from Managed to Unmanaged + +When disabling DNS management: + +1. **Document**: Note reason for change +2. **Disable**: Add group to disabled management +3. **Verify**: Confirm peers revert to system DNS +4. **Configure**: Manually set DNS if needed +5. **Test**: Ensure connectivity still works + +--- + +## Next Steps + +- **[Configuring Nameservers](/manage/dns/nameserver-groups)** - Configure DNS servers and domains +- **[Troubleshooting](/manage/dns/troubleshooting)** - Diagnose DNS issues +- **[API Reference](/ipa/resources/dns)** - Automate DNS settings + + +Questions about DNS settings? Check the [troubleshooting guide](/manage/dns/troubleshooting) or ask in the [NetBird community](https://netbird.io/slack). + \ No newline at end of file diff --git a/src/styles/tailwind.css b/src/styles/tailwind.css index af0cb75a..52d842a5 100644 --- a/src/styles/tailwind.css +++ b/src/styles/tailwind.css @@ -50,7 +50,7 @@ box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19); border-radius: 4px; overflow: hidden; - width: 40%; + width: 50%; } .imagewrapper-big {