ipspace · jbemmel · Aug 28, 2022 · Aug 29, 2022 · Aug 29, 2022 · Aug 30, 2022
diff --git a/docs/addressing.md b/docs/addressing.md
@@ -98,6 +98,7 @@ addressing:
 * Management IP addresses are assigned from 192.168.121.0/24 CIDR block. The first IP address is 192.168.121.101 (*start* offset plus node ID)
 * MAC addresses of management interfaces start with 08-4F-A9. The last byte of the MAC address is the node ID.
 
+(addressing-unnumbered)=
 ## Unnumbered Interface Support
 
 *netlab* supports unnumbered IPv4 and IPv6 interfaces: 

diff --git a/docs/caveats.md b/docs/caveats.md
@@ -18,6 +18,28 @@
 * *netlab* uses Cumulus VX containers created by Michael Kashin and downloaded from his Docker Hub account. Once Nvidia releases an official container image, change the container name with **defaults.devices.cumulus.clab.image** parameter (or by editing the `topology-defaults.yml` file included with *netlab*).
 * The Cumulus VX 4.4.0 Vagrant box for VirtualBox is broken. *netlab* is using Cumulus VX 4.3.0 with *virtualbox* virtualization provider.
 
+(caveats-cumulus-nvue)=
+
+## Cumulus 5.0 with NVUE
+
+You could configure Cumulus Linux 5.0 with configuration templates developed for Cumulus Linux 4.0 (use device type **cumulus** and specify desired device image), or with NVUE.
+
+NVUE has several shortcomings that prevent *netlab* from configuring basic designs like IBGP on top of IGP. Don't be surprised if the labs that work with **cumulus** device don't work with **cumulus_nvue** device, and please create a GitHub issue whenever you find a glitch. We'd love to know (at least) what doesn't work as expected.
+
+To run Cumulus Linux 5.x with **cumulus** device type, add the following lines to your lab topology:
+
+```
+defaults.devices.cumulus.libvirt.image: CumulusCommunity/cumulus-vx:5.2.0
+defaults.devices.cumulus.libvirt.memory: 2048
+```
+
+Alternatively, you could add the following lines to your `~/.topology-defaults.yml` file:
+
+```
+devices.cumulus.libvirt.image: CumulusCommunity/cumulus-vx:5.2.0
+devices.cumulus.libvirt.memory: 2048
+```
+
 ## Fortinet FortiOS
 
 * *FortiOS* VM images by default have a 15 day evaluation license. The VM has [limited capabilities](https://docs.fortinet.com/document/fortigate-private-cloud/6.0.0/fortigate-vm-on-kvm/504166/fortigate-vm-virtual-appliance-evaluation-license) without a license file. It will work for 15 days from first boot, at which point you must install a license file or recreate the vagrant box completely from scratch.

diff --git a/docs/dev/config/vlan.md b/docs/dev/config/vlan.md
@@ -73,7 +73,7 @@ devices:
     features:
       vlan:
         model: router
-        svi_interface_name: "{ifname}.{vlan}"
+        svi_interface_name: "irb0.{vlan}"
         subif_name: "{ifname}.{subif_index}"
   vyos:
     features:

diff --git a/docs/dev/guidelines.md b/docs/dev/guidelines.md
@@ -20,6 +20,7 @@ The easiest way to get started is to [add support for a new platform for an exis
    device-box.md
    device-features.md
    devices.md
+   unnumbered.md
 ```
 
 ```eval_rst

diff --git a/docs/dev/unnumbered.md b/docs/dev/unnumbered.md
@@ -0,0 +1,80 @@
+# Unnumbered Interfaces
+
+*netlab* supports unnumbered IPv4, IPv6 (LLA) or dual-stack interfaces. There are two ways to create an unnumbered interface (or link):
+
+* Set **unnumbered: true** on interface[^NLA] or link.
+* Set **ipv4** and/or **ipv6** attribute to *True*.
+
+**unnumbered** attribute is translated into **ipv4** and/or **ipv6** attributes set to *True* based on address families configured on node's loopback interface. With the default addressing setup, **unnumbered: True** results in **ipv4: True**, to enable dual-stack unnumbered interfaces with **unnumbered** attribute, add **ipv6** prefix to the **loopback** addressing pool. For more details, see [unnumbered interfaces](addressing-unnumbered) part of [addressing](../addressing.md) document.
+
+## Implementing unnumbered interfaces
+
+There is no standard way of implementing IPv4 unnumbered interfaces, and they might not be available on all platforms. IPv4 implementations of unnumbered interfaces usually use the loopback IPv4 address as the interface IPv4 address. For more details, read the [unnumbered interfaces](https://blog.ipspace.net/series/unnumbered-interfaces.html) series of blog posts on ipSpace.net.
+
+Unnumbered IPv6 interfaces should use link-local addresses, a standard IPv6 feature.
+
+If your device supports IPv6 LLA-only interface, set `topology-defaults.yml` attribute **devices._name_.features.initial.ipv6.lla** to *True*.
+
+If your device supports IPv4 unnumbered interfaces, set `topology-defaults.yml` attribute **devices._name_.features.initial.ipv4.unnumbered** to *True*.
+
+## Integration with IGP routing protocols
+
+OSPF and IS-IS implementations might support unnumbered IPv4 interfaces[^OSPFv3]. The routing protocol configuration modules detect unnumbered IPv4 interfaces by checking the **unnumbered** and **ipv4** attributes -- if either one of them is set to *True*, the interface is an unnumbered IPv4 interface.
+
+OSPFv2 can use unnumbered IPv4 interfaces on point-to-point links. If your device supports this functionality, set `topology-defaults.yml` attribute **devices._name_.features.ospf.unnumbered** to *True*. OSPFv2 cannot run over multi-access unnumbered IPv4 links.
+
+Some IS-IS implementations support unnumbered IPv4 P2P links. If your device supports this, set `topology-defaults.yml` attribute **devices._name_.features.isis.unnumbered.ipv4** to *True*.
+
+Fewer IS-IS implementations support unnumbered multi-access IPv4 links. To indicate your device can do that, set `topology-defaults.yml` attribute **devices._name_.features.isis.unnumbered.network** to *True*.
+
+```{note}
+If you're unsure what your device can do, set all three feature flags to *True*, start a lab, and check whether the adjacency- and routing tables are populated as expected.
+```
+
+## Unnumbered EBGP sessions
+
+Several vendors implemented EBGP sessions between well-known IPv6 LLA addresses[^EBGP_LLA]. *netlab* does not support this half-baked attempt and implements IPv6 LLA sessions only for those devices that can configure EBGP session *on an interface*.
+
+Devices supporting interface-level EBGP sessions between auto-generated IPv6 LLA can use these sessions to:
+
+* Transport IPv6 prefixes with LLA next hop over IPv6 AF
+* Transport IPv4 prefixes with IPv6 LLA next hop according to RFC 8950.
+
+*netlab* core and BGP configuration module do not support:
+
+* Running IPv4 AF with IPv4 next hops over IPv6 transport session
+* Running IPv4 AF with RFC 8950-style IPv6 next hops over numbered IPv6 interfaces or over IBGP sessions.
+* Creating IBGP sessions between IPv6 LLA addresses
+
+```{note}
+You can always extend *netlab* functionality with plugins and custom configuration modules.
+```
+
+*netlab* will create an IPv6 LLA EBGP session whenever it finds a pair of devices connected to the same link if the devices:
+
+* Belong to different autonomous systems
+* Have **ipv6** interface attribute set to *True*.
+
+Whenever *netlab* encounters an EBGP session between IPv6 LLA interfaces, it sets **local_if** attribute in the neighbor data structure to simplify the device configuration templates.
+
+If your device supports EBGP sessions between auto-generated IPv6 link-local addresses, set `topology-defaults.yml` attribute **devices._name_.features.bgp.ipv6_lla** to *True*.
+
+*netlab* device configuration templates will enable RFC 8950-style IPv4-over-IPv6 address family on IPv6 LLA sessions if the interface has **ipv6** interface attribute set to *True* (indicating IPv6 LLA EBGP session) AND **ipv4** interface attribute set to *True*.
+
+RFC 8950-style IPv4 address family [REALLY SHOULD NOT](https://www.rfc-editor.org/rfc/rfc6919#section-3) be enabled for:
+
+* EBGP sessions running on numbered IPv6 interfaces
+* Interfaces with IPv4 addresses regardless of the state of **ipv6** attribute.
+
+BGP configuration module simplifies the device configuration templates conforming to the above restriction with the **ipv4_rfc8950** neighbor attribute which is set:
+
+* when link or interface **unnumbered** attribute is set to *True* on both EBGP neighbors or
+* when both IPv4 and IPv6 interface attributes are set to *True* on both EBGP neighbors.
+
+If your device supports RFC 8950 (IPv4 with IPv6 next hops) on EBGP sessions between auto-generated IPv6 link-local addresses, set `topology-defaults.yml` attribute **devices._name_.features.bgp.rfc8950** to *True*.
+
+[^NLA]: node-to-link attachment
+
+[^OSPFv3]: OSPFv3 runs over IPv6 LLA. Decent IS-IS implementations should support IPv6 LLA-only segments. *netlab* therefore does not check whether an implementation supports IPv6 LLA-only segments.
+
+[^EBGP_LLA]: An EBGP neighbor has to be configured using remote IPv6 LLA address and an interface name.