docs: peer with BIRD over ::1 on the router; explain the multihop requirement

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs/lab/prod/on-router/05-lab-lo.network

@@ -4,12 +4,15 @@
 [Match]
 Name=lo
 
-# One address each for BIRD and ferrix to peer over.
+# BIRD and ferrix peer over ::1, which needs no configuration. Should BIRD
-[Address]
+# object to identical local and neighbour addresses, give them one each
-Address=fd00:179::1/128
+# instead (and use those in bird.conf and ferrix.textpb):
-
+#
-[Address]
+#   [Address]
-Address=fd00:179::2/128
+#   Address=fd00:179::1/128
+#
+#   [Address]
+#   Address=fd00:179::2/128
 
 # AnyIP: the router answers ping for every address in the lab space.
 [Route]

docs/lab/prod/on-router/README.md

@@ -1,7 +1,6 @@
 # Running ferrix_bgp on the production router
 
-ferrix and BIRD run side by side on pr01 and peer over two loopback
+ferrix and BIRD run side by side on pr01 and peer over `::1`. Students reach the status page through a reverse proxy that adds
-addresses. Students reach the status page through a reverse proxy that adds
 TLS and a password. Nothing here has been run on the router; treat each step
 as something to check.
 
@@ -24,10 +23,11 @@ Check the router really is x86-64 first (`uname -m`).
     install -m 0644 ferrix.textpb /etc/ferrix-bgp/ferrix.textpb
     install -m 0644 ferrix-bgp.service /etc/systemd/system/ferrix-bgp.service
 
-## 3. Loopback addresses
+## 3. Loopback
 
-Merge `05-lab-lo.network` into the networkd file that matches `lo`, then
+Peering over `::1` needs no address setup. `05-lab-lo.network` only carries
-`networkctl reload` and confirm with `ip -6 addr show dev lo`.
+the AnyIP route for the lab space; merge it into the networkd file that
+matches `lo` if it is not there already, then `networkctl reload`.
 
 ## 4. BIRD
 

docs/lab/prod/on-router/bird-ferrix-local.conf

@@ -1,13 +1,18 @@
 # Replaces "protocol bgp ferrix" in bird.conf when ferrix runs on this host.
 # Only the addresses and "multihop" differ from the WireGuard version; the
 # import filter and everything about export control stay as they are.
+#
+# Without "multihop" BIRD looks for the neighbour on a directly connected
+# network, cannot find ::1 there, and disables the protocol with
+# "Error: Invalid next hop". After fixing that, `birdc enable ferrix` if a
+# reconfigure does not bring it back by itself.
 protocol bgp ferrix
 {
     description "ferrix_bgp teaching lab (announce only, same host)";
-    local fd00:179::1 as 210036;
+    local ::1 as 210036;
-    neighbor fd00:179::2 as FERRIX_ASN;
+    neighbor ::1 as FERRIX_ASN;
-    # Both ends are addresses of this machine, so there is no directly
+    # Both ends are this machine, so there is no directly connected
-    # connected neighbour for "direct" to find.
+    # neighbour for "direct" (the eBGP default) to find.
     multihop;
     passive on;
     ipv6 {

docs/lab/prod/on-router/ferrix.textpb

@@ -4,14 +4,13 @@ local_asn: 4200000001
 
 # Unused in practice (BIRD is passive and we dial it), but a listener is
 # required. 179 belongs to BIRD, so take another port on our own address.
-listen_endpoints { address: "fd00:179::2" port: 9179 }
+listen_endpoints { address: "::1" port: 9179 }
 
 peers {
     name: "pr01-bird"
-    endpoint { address: "fd00:179::1" port: 179 }
+    endpoint { address: "::1" port: 179 }
-    # BIRD recognises its neighbour by source address. Both addresses live on
+    # BIRD recognises its neighbour by source address, so pin ours.
-    # this host, so say which one is ours.
+    local_address: "::1"
-    local_address: "fd00:179::2"
     remote_asn: 210036
     hold_time_seconds: 90
 }