diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration/service/broadcast-relay.md | 145 |
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' ``` |