Rebuild the connecting-from-the-office guide on Networks

src/pages/manage/access-control/posture-checks/connecting-from-the-office.mdx

@@ -1,121 +1,130 @@
+import {Note, Warning} from "@/components/mdx";
+
+export const description = "Use a Peer Network Range posture check so devices in the office reach the LAN over their local link, and receive the NetBird route only when they are remote."
+
 # Connecting from the office
-A typical scenario administrators have is accessing their office networks remotely. With [Routes](https://docs.netbird.io/manage/network-routes), NetBird makes this easy. Still, administrators often want to avoid routing their users’ traffic via NetBird when they are in the office.
-To solve this, administrators can leverage the power of [Posture Checks](https://docs.netbird.io/manage/access-control/posture-checks) and create policies that allow connection to the routing peers only if they are outside the office by using
-a [Peer Network Range](/manage/access-control/posture-checks#peer-network-range) posture check with a block action.
 
-## Example
-In the following scenario, our office network is on the subnet `192.168.1.0/24`. Let's assume all users will be part of the group `route-users`, and the routing peer for our office will be inside the group `route-nodes`.
-With this in mind, the goal is to create a Posture Check, create a Policy and assign a Posture Check to it, and finally create a Network Route that will expose the office subnet.
+Remote access to an office network is straightforward with [Networks](/manage/networks): a routing peer inside the office opens the LAN to your overlay network. The awkward part is what happens when a user walks into that office. Their device is already on the LAN, but the route distributed by NetBird is still installed, so traffic to a machine one switch away can leave over the tunnel, reach the routing peer, and come back. You pay latency and bandwidth for a trip the device never needed to make.
+
+The fix is to stop distributing the route to devices that are already on site. A **Peer Network Range** posture check with the `Block` action, attached to the access policy that grants access to the resource, does exactly that: while the device's own address falls inside the office subnet, the policy does not apply to it, the route is not distributed, and the operating system uses its local link. When the user leaves, the route comes back on its own.
+
+## The scenario
 
-### Create a Posture Check
-To create a Posture Check, navigate to the `Access Control -> Posture Checks` section in the NetBird dashboard and click on **Add Posture Check**.
+One office LAN, `192.168.1.0/24`, reached through a routing peer named `router-01`. The users who need it are in the group `route-users`. Everything below is built around that example.
 
-Select `Peer Network Range`.
+Three things to create, in order:
+
+1. A posture check that recognizes the office subnet.
+2. A Network holding the office resource and the routing peer.
+3. An access policy from `route-users` to that resource, carrying the posture check.
+
+## Create the posture check
+
+Navigate to `Access Control` > `Posture Checks` in the NetBird dashboard and click `Add Posture Check`. Select `Peer Network Range`.
 
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/posture-check-new-block-network-range.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/posture-check-new-block-network-range.png" alt="Selecting the Peer Network Range posture check in the NetBird dashboard" className="imagewrapper"/>
 </p>
-Select the `Block` action and click on `Add Network Range` to input your office subbnet `192.168.1.0/24`.
+
+Select the `Block` action, then click `Add Network Range` and enter the office subnet `192.168.1.0/24`.
+
 <Note>
-Note that if you have multiple locations that you want to see excluded, you can add multiple network ranges.
+If you have several sites to exclude, add one network range per site to the same posture check.
 </Note>
+
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/posture-check-block-network-range.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/posture-check-block-network-range.png" alt="Peer Network Range posture check with the Block action and the office subnet 192.168.1.0/24" className="imagewrapper"/>
 </p>
-Click `Save`, then click `Continue` and fill out `Name of the Posture Check` with "Exclude Office subnet”.
 
-After we conclude this step, we are ready to create a policy and assign this posture check. 
-### Create a Policy
-We start by creating a simple policy that will allow access from group `route-users` to group `route-nodes`.
-This is needed to establish the connection between the users and the routing peer.
+Click `Save`, then `Continue`, and name the check "Exclude office subnet".
 
-Navigate to the `Access Control -> Policies` section in the NetBird dashboard and click on `Add Policy`.
+## Create the Network and its resource
 
-On the `Source` field, select the group `route-user`, and on the `Destination` field, select the group `route-nodes`.
-Choose `UDP` for the protocol and type `1`on Ports. Click `Continue`.
-<Note>
-    Note that the protocol and port are arbitrary and can be changed according to your needs. An usual choice is to allow ICMP traffic for troubleshooting purposes.
-</Note>
-<p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/policy-office-subnet-with-posturecheck.png" alt="high-level-dia" className="imagewrapper"/>
-</p>
-In this step, we'll click `Browse Checks` and select the posture check we created earlier, `Exclude Office subnet`.
+Create a Network for the office and add `router-01` as its routing peer, then add the office LAN as a resource. The full walkthrough is on the [Networks](/manage/networks) page.
 
-Click `Add Posture Checks` and then click `Continue`.
-<p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/policy-with-network-posturecheck-added.png" alt="high-level-dia" className="imagewrapper"/>
-</p>
-Give your policy the name "Allow users to route-nodes" and click on `Add Policy`.
+For this use case the resource is the office subnet `192.168.1.0/24`, because the whole point is to route that range only when the user is remote. Everywhere else, prefer single-host `/32` resources: a policy then grants access to one machine instead of a whole subnet.
 
-We are now ready for the final step of creating the office route.
+<Warning>
+Resources are not members of the built-in `All` group, so nothing behind the routing peer is reachable until a policy allows it. That policy is the next step, and it is where the posture check goes.
+</Warning>
 
-### Create a Network Route
+## Create the access policy and attach the check
 
-Now, let's create a [Network Route](https://docs.netbird.io/manage/network-routes) that will expose the local office subnet `192.168.1.0/24`,
-which will be distributed to all peers members of the group `route-users`. In this example, we will be using a routing peer named `router-01`,
-which is a member of the group `route-nodes`, this way, the policy we just created goes into effect, and all peers from the group `route-users` will be able to reach
-`router-01` only if they are not in the office network, due to our posture check.
+Navigate to `Access Control` > `Policies` and click `Add Policy`. Set the source to the group `route-users` and the destination to the office resource (or to a resource group that contains it), then choose the protocols and ports you want to allow.
+
+Click `Browse Checks`, select `Exclude office subnet`, and click `Add Posture Checks`.
 
-To get started navigate to the `Network Routing` → `Routes` menu on the NetBird dashboard and click on **Add Route**. Fill out the fields as shown in the image below, and click `Continue`:
-<p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/create-route-with-posturecheck.png" alt="high-level-dia" className="imagewrapper"/>
-</p>
-Next assign `route-users` do `Distribution Groups`.
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/distribute-to-groups-posturechecks.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/policy-with-network-posturecheck-added.png" alt="An access policy with the Exclude office subnet posture check attached" className="imagewrapper"/>
 </p>
-Click `Continue` and assign the name "Office network access" to `Network Identifier`, click `Continue` again and in the final step, finish this process by clicking `Add Route`.
-### Testing Posture Check
-Now that we have created the Posture Check, the Policy, and the Network Route, we can test this configuration. In the following example, we will be testing this Posture Check from a macOS client named `client-01`, and as stated earlier, it belongs to the group `route-users`.
 
-#### While connect from inside our office:
-Our local connection shows that we are connected to local office WiFi and and we are part of that subnet.
+Name the policy "Office network access" and save it. Peers in `route-users` now receive the office route only while they are outside `192.168.1.0/24`.
+
+## Verify it
+
+The example below uses a macOS client named `client-01` in the group `route-users`, so the NetBird interface appears as `utun100` and the local link as `en0`. On Windows and Linux the NetBird interface is `wt0` by default. The screenshots use the older `netbird routes list` alias of `netbird networks list`, which still works.
+
+**Inside the office.** The device holds an address inside the office subnet.
+
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/wifi-inside-office-subnet.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/wifi-inside-office-subnet.png" alt="macOS Wi-Fi details showing the client with the address 192.168.1.68 on the office network" className="imagewrapper"/>
 </p>
 
-When we are connected from inside the office, we can observe that the NetBird route is not available and that the subnet `192.168.1` is using local network interface `en0` to route traffic.
+`netbird networks list` does not show the office network, and the system route table sends `192.168.1.0/24` over the local interface `en0`.
 
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netbird-routes-list-local.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netbird-routes-list-local.png" alt="The NetBird client reporting no available routes while the device is on site" className="imagewrapper"/>
 </p>
 
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netstat-routes-grep-local.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netstat-routes-grep-local.png" alt="netstat output showing 192.168.1.0/24 reached over the local interface en0" className="imagewrapper"/>
 </p>
-#### When connected outside the office, we can observe: 
+
+**Outside the office.** The office network is distributed again and shows as selected, and the same destination now goes over the NetBird interface `utun100`.
 
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netbird-routes-list-external.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netbird-routes-list-external.png" alt="The NetBird client listing 192.168.1.0/24 as an available and selected route while the device is remote" className="imagewrapper"/>
 </p>
 
 <p>
-    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netstat-routes-grep-external.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/access-control/posture-checks/connecting-from-the-office/netstat-routes-grep-external.png" alt="netstat output showing 192.168.1.0/24 reached over the NetBird interface utun100" className="imagewrapper"/>
 </p>
 
-Notice that subnet `192.168.1.0/24` is routed through our Wireguard interface (`utun100`).
+## Limits worth knowing
+
+**Re-evaluation after a network change is automatic, but not immediate.** When a device switches network, for example from cellular to office Wi-Fi, the client reports its new addresses and the management server rebuilds the network map before the route is added or withdrawn. Expect a short gap during which the previous route set is still in place.
 
-As you can see, the Posture Check is working as expected, and the traffic is being routed through NetBird only when the client is outside the office network.
+**An IP range is not an identity.** The check can only compare addresses, so it cannot tell two networks apart that use the same range. An office on `192.168.1.0/24` and a home network on `192.168.1.0/24` look identical to it, and blocking one blocks the other. If your office range collides with the ranges your users have at home, match on the office public IP instead, as described below.
+
+**Platform coverage.** Matching a device's local interface addresses depends on the client reporting them. See [Peer Network Range Check on Android](/manage/access-control/posture-checks#peer-network-range-check-on-android) for the platform details.
 
 ## Matching by office public IP
-The example above relies on the office LAN subnet showing up on the peer's local network interface. In some deployments this isn't practical — for example, when the office hands out an opaque DHCP range that overlaps with common home-network subnets, or when peers connect through a guest network that doesn't expose the production LAN on the device.
 
-In these cases you can match the peer's **public egress IP** instead — the source IP the NetBird management server observes when the peer connects. The Peer Network Range posture check evaluates this IP automatically against any range in the list and matches when the IP is contained in the range, so you can use a single-host prefix for one address or a CIDR for a whole block.
+The example above relies on the office LAN subnet showing up on the peer's local network interface. In some deployments this isn't practical, for example when the office hands out an opaque DHCP range that overlaps with common home-network subnets, or when peers connect through a guest network that doesn't expose the production LAN on the device.
+
+In these cases you can match the peer's **public egress IP** instead: the source IP the NetBird management server observes when the peer connects. The Peer Network Range posture check evaluates this IP automatically against any range in the list and matches when the IP is contained in the range, so you can use a single-host prefix for one address or a CIDR for a whole block.
 
 ### IPv4 example
-If your office's public IPv4 address is `203.0.113.10`, create a Peer Network Range posture check with the `Block` action and add `203.0.113.10/32` to the list. Peers connecting from that egress IP will be blocked from the route, while peers connecting from anywhere else will reach it.
 
-If your office (or your ISP) hands out an entire public block, you can add the block directly — for example `1.0.0.0/24` or `3.0.0.0/23`. Any peer whose connection IP falls in that range will match.
+If your office's public IPv4 address is `203.0.113.10`, create a Peer Network Range posture check with the `Block` action and add `203.0.113.10/32` to the list. Peers connecting from that egress IP will be blocked from the resource, while peers connecting from anywhere else will reach it.
+
+If your office (or your ISP) hands out an entire public block, you can add the block directly, for example `198.51.100.0/24` or `203.0.113.0/24`. Any peer whose connection IP falls in that range will match.
 
 ### IPv6 example
+
 If your office also (or only) has an IPv6 egress, add the address as a `/128`, for example `2001:db8::1/128`, or a wider IPv6 prefix such as `2001:db8::/48`. You can include IPv4 and IPv6 entries in the same posture check; a peer matches if its connection IP falls into any of them.
 
 <Note>
-    For this to work, the NetBird management server must see the peer's real source IP. When running self-hosted behind a reverse proxy or load balancer, ensure the proxy is configured to forward the client IP (PROXY protocol or `X-Forwarded-For`). The country and city shown on the peer in the dashboard are a quick sanity check — if they reflect your proxy's datacenter rather than the peer's actual location, the source IP isn't being forwarded correctly.
+    For this to work, the NetBird management server must see the peer's real source IP. When running self-hosted behind a reverse proxy or load balancer, ensure the proxy is configured to forward the client IP (PROXY protocol or `X-Forwarded-For`). The country and city shown on the peer in the dashboard are a quick sanity check: if they reflect your proxy's datacenter rather than the peer's actual location, the source IP isn't being forwarded correctly.
 </Note>
 
 <Note>
-    Mobile peers connecting through cellular networks normally have a different egress IP than your office, so they will not be matched. However, if a phone joins the office Wi-Fi, its egress IP becomes the office IP and the block will apply — usually the desired behavior.
+    Mobile peers connecting through cellular networks normally have a different egress IP than your office, so they will not be matched. However, if a phone joins the office Wi-Fi, its egress IP becomes the office IP and the block will apply, which is usually the desired behavior.
 </Note>
 
-This concludes this Posture Check example.
+## Summary
+
+- A routing peer in the office publishes `192.168.1.0/24` as a resource in a Network.
+- One access policy grants `route-users` access to that resource.
+- A Peer Network Range posture check with the `Block` action for `192.168.1.0/24` is attached to that policy.
+- On site, the policy does not apply, so the route is never installed and the device reaches the LAN over its local link. Off site, the route returns and traffic takes the NetBird interface.