diff --git a/public/docs-static/img/manage/settings/ipv6/ipv6-network-settings.png b/public/docs-static/img/manage/settings/ipv6/ipv6-network-settings.png new file mode 100644 index 00000000..3aa5ae0d Binary files /dev/null and b/public/docs-static/img/manage/settings/ipv6/ipv6-network-settings.png differ diff --git a/public/docs-static/img/manage/settings/ipv6/ipv6-peer-page.png b/public/docs-static/img/manage/settings/ipv6/ipv6-peer-page.png new file mode 100644 index 00000000..cd0adf5e Binary files /dev/null and b/public/docs-static/img/manage/settings/ipv6/ipv6-peer-page.png differ diff --git a/public/docs-static/img/manage/settings/ipv6/ipv6-status-client-exit-node.png b/public/docs-static/img/manage/settings/ipv6/ipv6-status-client-exit-node.png new file mode 100644 index 00000000..9ee77c93 Binary files /dev/null and b/public/docs-static/img/manage/settings/ipv6/ipv6-status-client-exit-node.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 02c4ed1d..30e12291 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -444,6 +444,7 @@ export const docsNavigation = [ title: 'Multi-Factor Authentication', href: '/manage/settings/multi-factor-authentication', }, + { title: 'IPv6 Overlay Addressing', href: '/manage/settings/ipv6' }, { title: 'Auto Update', href: '/manage/peers/auto-update' }, { title: 'Lazy Connections', href: '/manage/peers/lazy-connection' }, { diff --git a/src/pages/get-started/cli.mdx b/src/pages/get-started/cli.mdx index 79f16808..cbd502f9 100644 --- a/src/pages/get-started/cli.mdx +++ b/src/pages/get-started/cli.mdx @@ -97,7 +97,7 @@ The command will check if the peer is logged in and connect to the management se --disable-client-routes Disable client routes. If enabled, the client won't process client routes received from the management service. --disable-dns Disable DNS. If enabled, the client won't configure DNS settings. --disable-firewall Disable firewall configuration. If enabled, the client won't modify firewall rules. - --disable-ipv6 Disable IPv6 overlay. If enabled, the client won't request or use an IPv6 overlay address. + --disable-ipv6 Disables IPv6 overlay addressing. The client will not receive an IPv6 address or accept IPv6 traffic from peers. (v0.68.0+) --disable-server-routes Disable server routes. If enabled, the client won't act as a router for server routes received from the management service. --disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication. --dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best IP and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address "" diff --git a/src/pages/get-started/install/docker.mdx b/src/pages/get-started/install/docker.mdx index 9922991a..96b30b5e 100644 --- a/src/pages/get-started/install/docker.mdx +++ b/src/pages/get-started/install/docker.mdx @@ -21,6 +21,29 @@ docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap- See [Docker example](/use-cases/examples#net-bird-client-in-docker) for details. +### IPv6 overlay + +If you are using [IPv6 overlay addressing](/manage/settings/ipv6) and the container is not running with `--network=host`, add the IPv6 sysctls so the kernel forwards v6 traffic inside the container: + +```bash +docker run ... \ + --sysctl net.ipv6.conf.all.disable_ipv6=0 \ + --sysctl net.ipv6.conf.all.forwarding=1 \ + netbirdio/netbird:latest +``` + +Or in Docker Compose: + +```yaml +services: + netbird-client: + sysctls: + - net.ipv6.conf.all.disable_ipv6=0 + - net.ipv6.conf.all.forwarding=1 +``` + +With `network_mode: host` the container inherits the host's sysctls, so the flags can be dropped as long as the host has IPv6 forwarding enabled. + ### Troubleshooting 1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL which is ```https://api.netbird.io:443```. diff --git a/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx index f42637d4..949156c3 100644 --- a/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx +++ b/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx @@ -12,9 +12,7 @@ Exit nodes route all internet-bound traffic from your devices through a designat A default route (`0.0.0.0/0` for IPv4) directs all internet traffic through a designated routing peer. - - IPv6 traffic is currently not supported and is blocked to prevent unintentional leakage. - +When [IPv6 overlay addressing](#ipv6-support) is enabled for the peer, the management server automatically creates a matching `::/0` route so that both IPv4 and IPv6 internet traffic flow through the exit node. Peers without IPv6 enabled have their IPv6 traffic blocked to prevent leakage. ### Routing Peer @@ -101,6 +99,24 @@ Add a DNS server with the match domain set to `ALL`. Local DNS servers may not b See [Manage DNS in your network](/manage/dns) for details. +## IPv6 Support + + + IPv6 overlay addressing requires NetBird v0.68.0 or later on both the routing peer and the clients. + + +When IPv6 is enabled in your account settings and the exit node peer supports it, the management server automatically generates a `::/0` route alongside the `0.0.0.0/0` route. No additional configuration is needed. + +For peers that do not have IPv6 enabled (older clients, or accounts with IPv6 disabled), IPv6 traffic is blocked at the tunnel interface to prevent unintentional leakage through the exit node. + +You can disable IPv6 on individual clients with the `--disable-ipv6` flag: + +```bash +netbird up --disable-ipv6 +``` + +See [IPv6 Overlay Addressing](/manage/settings/ipv6) for more details on enabling IPv6 for your account. + ## High Availability Exit nodes support high availability configurations. See [Creating Highly Available Routes](/manage/network-routes#creating-highly-available-routes) for more information. diff --git a/src/pages/manage/settings/ipv6.mdx b/src/pages/manage/settings/ipv6.mdx new file mode 100644 index 00000000..dd2c7011 --- /dev/null +++ b/src/pages/manage/settings/ipv6.mdx @@ -0,0 +1,121 @@ +# IPv6 Overlay Addressing + + + IPv6 overlay addressing requires NetBird v0.71.0 or later. + + +NetBird supports dual-stack overlay networking, where each peer can receive both an IPv4 and an IPv6 overlay address. Each account gets a unique IPv6 prefix (for example, `fd00:1234:5678::/64`) from which peer addresses are allocated. + +## Enabling IPv6 + +New accounts have IPv6 enabled by default for the **All** group, so every peer receives an IPv6 address out of the box. Existing accounts can enable it from the dashboard. + +Navigate to **Settings > Network** and select which groups should have IPv6 enabled. Only peers that belong to at least one selected group will receive an IPv6 address. + +![IPv6 network settings in the dashboard](/docs-static/img/manage/settings/ipv6/ipv6-network-settings.png) + +When a peer belongs to an IPv6-enabled group, it receives an overlay address from the account's IPv6 range. Peers that do not belong to any IPv6-enabled group only receive an IPv4 address. + +The IPv6 network range is configured alongside your IPv4 range. Valid prefix lengths are `/48` through `/112`, and the default `/64` prefix provides enough addresses for most deployments. + +## Disabling IPv6 on a Client + +Individual clients can opt out of IPv6 with the `--disable-ipv6` CLI flag: + +```bash +netbird up --disable-ipv6 +``` + +This prevents the client from receiving an IPv6 overlay address, advertising IPv6 support to management, or accepting IPv6 traffic from remote peers. + +The flag is also available in the desktop UI under **Settings > Disable IPv6**, and in the iOS and Android apps under **Advanced Settings**. + +## How It Works + +### Address Assignment + +Each peer receives at most one IPv4 and one IPv6 overlay address. Management assigns the IPv6 address when the peer first connects with a client that supports IPv6 and belongs to an IPv6-enabled group. + +![Peer detail page showing both IPv4 and IPv6 overlay addresses](/docs-static/img/manage/settings/ipv6/ipv6-peer-page.png) + +### DNS + +Resolving a peer name returns both its IPv4 and IPv6 addresses, so any client can reach a dual-stack peer over either family. Under the hood, peers with IPv6 addresses get AAAA records alongside their A records, served from the same NetBird DNS zone. + +Reverse DNS works for IPv6 too. PTR records for overlay IPv6 addresses are served from the standard `ip6.arpa` nibble zone alongside the existing `in-addr.arpa` zone for IPv4, so reverse lookups return the peer name in logs and tooling. + +### Firewall Rules + +Access control policies apply to both IPv4 and IPv6 traffic. When a peer has an IPv6 address, the management server generates firewall rules for both address families. + +### Exit Nodes + +When an exit node route (`0.0.0.0/0`) is configured and the peer supports IPv6, management automatically creates a matching `::/0` route. See [Exit Nodes](/manage/network-routes/use-cases/by-scenario/exit-nodes#ipv6-support) for details. + +### Network Routes + +[Network routes](/manage/network-routes) accept IPv6 CIDRs (for example `fd11:2::/64`) the same way as IPv4 subnets. When a route has masquerade enabled, the routing peer SNATs IPv6 egress traffic to its backend-side address, matching the IPv4 behavior. + +### Domain Routes + +Domain-based network resources resolve both A and AAAA records. The client allocates a fake IPv4 from `240.0.0.0/8` and a fake IPv6 from `0100::/64` for each resolved target. This keeps v4-only and v6-only domains routable through the tunnel without address collisions. + +## CLI Status + +When IPv6 is enabled, `netbird status` shows the IPv6 address: + +```bash +$ netbird status +... +NetBird IP: 100.64.114.31/16 +NetBird IPv6: fd00:1234:5678::1f/64 +... +``` + +Use `--ipv6` to show only the IPv6 address: + +```bash +$ netbird status --ipv6 +fd00:1234:5678::1f/64 +``` + +![NetBird client status showing IPv6 address and exit-node usage](/docs-static/img/manage/settings/ipv6/ipv6-status-client-exit-node.png) + +## API + +The following API fields relate to IPv6: + +- **Account settings**: `ipv6_enabled_groups` (list of group IDs) and `network_range_v6` (CIDR string). See [Update an Account](/api/accounts#update-an-account). +- **Peer**: `ipv6` (read-only, the assigned IPv6 address). See [Retrieve a Peer](/api/peers#retrieve-a-peer). + +## Limitations + +- IPv6 overlay addresses are not routable on the public internet + +## Troubleshooting + +### Peers report no IPv6 address after enabling the setting + +Peers only get an IPv6 address if they belong to at least one group listed in **IPv6 Enabled Groups** and if the client version supports the IPv6 overlay capability (v0.71.0+). Older agents don't advertise the capability and management skips IPv6 assignment for them. + +### Routing peer has an IPv6 address but traffic doesn't reach the backend + + +On a regular Linux host NetBird enables `net.ipv6.conf.all.forwarding=1` on startup. In constrained environments where that sysctl is read-only (unprivileged containers, locked-down Kubernetes pods), the write fails silently and IPv6 forwarding stays off. + + +Enable it at the orchestrator layer when running a routing peer as a container: + +```yaml +# Docker / Podman compose +sysctls: + - net.ipv6.conf.all.forwarding=1 +``` + +```yaml +# Kubernetes pod spec +securityContext: + sysctls: + - name: net.ipv6.conf.all.forwarding + value: "1" +```