docs: Update UDP broadcast relay page to VyOS 1.5 standards (#2115)

* docs: Update UDP broadcast relay page to VyOS 1.5 standards

* Remove the implication that something other than IPv4 supports broadcast

---------

Co-authored-by: Daniil Baturin <daniil@baturin.org>

1 files changed, 109 insertions, 36 deletions

diff --git a/docs/configuration/service/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md
index 4202ad6b..20978aa3 100644
--- a/docs/configuration/service/broadcast-relay.md
+++ b/docs/configuration/service/broadcast-relay.md
@@ -1,70 +1,143 @@
+---
+myst:
+  html_meta:
+    description: |
+      UDP broadcast relay is a VyOS service that forwards UDP broadcast
+      packets between subnets. It enables applications that rely on
+      broadcast-based peer or service discovery to operate across
+      Layer 3 boundaries.
+    keywords: udp broadcast relay, broadcast forwarding, service discovery
+---
+
 (udp-broadcast-relay)=
 
-# UDP Broadcast Relay
+# UDP broadcast relay
+
+Certain applications use UDP broadcasts to discover peers or services
+within a local subnet. Since IP routers do not forward broadcast packets
+between subnets, applications in different subnets cannot use broadcast
+discovery.
+
+The UDP broadcast relay service bridges this gap. When an application
+sends a UDP broadcast packet to discover peers or services, the relay
+listens for that message on any of its configured interfaces and
+rebroadcasts it on the others, reaching the subnets they connect to.
 
-Certain vendors use broadcasts to identify their equipment within one ethernet
-segment. Unfortunately if you split your network with multiple VLANs you loose
-the ability of identifying your equipment.
+The unit of configuration is a UDP relay instance. Each instance is
+defined by the following settings:
 
-This is where "UDP broadcast relay" comes into play! It will forward received
-broadcasts to other configured networks.
+- a numeric ID in the range 1–99 that identifies the instance
+- a single UDP port number that the instance relays
+- two or more interfaces across which the instance operates
 
-Every UDP port which will be forward requires one unique ID. Currently we
-support 99 IDs!
+Every interface in the instance must be assigned an IPv4 address.
+
+```{note}
+Multiple routers may run UDP broadcast relay on a shared subnet,
+provided that any routers relaying the same UDP port use the same
+instance ID. Multiple routers relaying the same UDP port with different
+instance IDs will produce a relay loop and a packet storm.
+```
 
 ## Configuration
 
-```{cfgcmd} set service broadcast-relay id \<n\> description \<description\>
+```{cfgcmd} set service broadcast-relay id \<1-99\> description \<description\>
 
-A description can be added for each and every unique relay ID. This is
-useful to distinguish between multiple different ports/applications.
+**Configure a description for the specified relay instance.**
 ```
 
-```{cfgcmd} set service broadcast-relay id \<n\> interface \<interface\>
+Example:
 
-The interface used to receive and relay individual broadcast packets. If you
-want to receive/relay packets on both `eth1` and `eth2` both interfaces need
-to be added.
+```none
+set service broadcast-relay id 1 description 'SONOS discovery'
 ```
 
-```{cfgcmd} set service broadcast-relay id \<n\> address \<ipv4-address\>
+```{cfgcmd} set service broadcast-relay id \<1-99\> interface \<interface\>
+
+**Add an interface to the specified relay instance.**
 
-Set the source IP of forwarded packets, otherwise original senders address
-is used.
+Repeat the command to add additional interfaces.
 ```
 
-```{cfgcmd} set service broadcast-relay id \<n\> port \<port\>
+```{note}
+At least two interfaces must be configured per instance, and each
+interface must be assigned an IPv4 address.
+```
 
-The UDP port number used by your application. It is mandatory for this kind
-of operation.
+Example:
+
+```none
+set service broadcast-relay id 1 interface eth1
+set service broadcast-relay id 1 interface eth2
 ```
 
-```{cfgcmd} set service broadcast-relay id \<n\> disable
+```{cfgcmd} set service broadcast-relay id \<1-99\> address \<ipv4-address\>
+
+**Configure the source IPv4 address used in forwarded packets.**
+
+If unset, the original sender's source IP address is preserved.
+```
+
+Example:
+
+```none
+set service broadcast-relay id 1 address 192.0.2.1
+```
+
+```{cfgcmd} set service broadcast-relay id \<1-99\> port \<1-65535\>
+
+**Configure the UDP destination port for the specified relay instance.**
 
-Each broadcast relay instance can be individually disabled without deleting
-the configured node by using the following command:
+The relay listens for broadcasts on this port on any of the instance's
+interfaces and forwards them to the same port on the others.
+```
+
+```{note}
+This setting is mandatory for each relay instance. Otherwise, the
+commit is rejected.
+```
+
+Example:
+
+```none
+set service broadcast-relay id 1 port 1900
+```
+
+```{cfgcmd} set service broadcast-relay id \<1-99\> disable
+
+**Administratively disable the specified relay instance while preserving
+its configuration.**
+```
+
+Example:
+
+```none
+set service broadcast-relay id 1 disable
 ```
 
 ```{cfgcmd} set service broadcast-relay disable
 
-In addition you can also disable the whole service without the need to remove
-it from the current configuration.
+**Administratively disable the UDP broadcast relay service on the router
+without removing its configured instances.**
 ```
 
-:::{note}
-You can run the UDP broadcast relay service on multiple routers
-connected to a subnet. There is **NO** UDP broadcast relay packet storm!
-:::
+Example:
+
+```none
+set service broadcast-relay disable
+```
 
 ## Example
 
-To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4`
-or `eth5` to all other interfaces in this configuration.
+The following example shows how to configure the UDP broadcast relay to
+forward broadcasts on UDP port 1900 between `eth1`, `eth2`, and `eth3`.
+A broadcast received on any of these interfaces is forwarded to the
+other two. Each interface must already have an IPv4 address configured.
 
 ```none
-set service broadcast-relay id 1 description 'SONOS'
-set service broadcast-relay id 1 interface 'eth3'
-set service broadcast-relay id 1 interface 'eth4'
-set service broadcast-relay id 1 interface 'eth5'
+set service broadcast-relay id 1 description 'SONOS discovery'
 set service broadcast-relay id 1 port '1900'
+set service broadcast-relay id 1 interface 'eth1'
+set service broadcast-relay id 1 interface 'eth2'
+set service broadcast-relay id 1 interface 'eth3'
 ```