From bf60fed7e344fc7ec170fe655d0d0f98fd66425a Mon Sep 17 00:00:00 2001 From: "JR L." Date: Fri, 14 Aug 2026 11:45:04 -0300 Subject: docs: igmp-proxy: document firewall requirements and operational commands (#2174) Co-authored-by: JR Lanteigne (cherry picked from commit dad7649352c22260e00ea5dbbe8a8b18642ace7a) # Conflicts: # docs/configuration/protocols/igmp-proxy.md --- docs/configuration/protocols/igmp-proxy.md | 122 ++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration/protocols/igmp-proxy.md b/docs/configuration/protocols/igmp-proxy.md index 961f921b..02d072ee 100644 --- a/docs/configuration/protocols/igmp-proxy.md +++ b/docs/configuration/protocols/igmp-proxy.md @@ -35,7 +35,57 @@ traffic should be accepted. This is especially useful for the upstream interface, since the source for multicast traffic is often from a remote location. +<<<<<<< HEAD This option can be supplied multiple times. +======= +You can configure multiple remote subnets for an **upstream** IGMP proxy +interface. + +Upstream interfaces frequently require this configuration because multicast +sources typically reside on external subnets. ISPs frequently send IPTV +streams from remote private subnets. The set of source subnets can change +without notice. +``` + +Example: + +```none +set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/8 +``` + +```{cfgcmd} set protocols igmp-proxy interface \ whitelist \ + +**Configure a permitted destination network for multicast traffic requests +on the specified IGMP proxy interface.** + +By default, the IGMP proxy accepts requests for all multicast destination +networks. When you define a whitelist, the IGMP proxy forwards requests only +for the specified multicast networks. + +You can configure multiple whitelist entries per **downstream** IGMP proxy +interface. +``` + +Example: + +```none +set protocols igmp-proxy interface eth1 whitelist 239.0.0.0/8 +``` + +```{cfgcmd} set protocols igmp-proxy interface \ threshold \<1-255\> + +**Configure the Time-to-Live (TTL) threshold for the specified IGMP proxy +interface.** + +The IGMP proxy drops any multicast packet with a TTL value lower than the +configured threshold. +``` + +Example: + +```none +set protocols igmp-proxy interface eth0 threshold 5 +>>>>>>> dad76493 (docs: igmp-proxy: document firewall requirements and operational commands (#2174)) ``` ```{cfgcmd} set protocols igmp-proxy disable-quickleave @@ -76,4 +126,74 @@ set protocols igmp-proxy interface eth1 role downstream ```{opcmd} restart igmp-proxy Restart the IGMP proxy process. -``` \ No newline at end of file +<<<<<<< HEAD +``` +======= +``` + +```{opcmd} show ip multicast interface + +Display per-interface multicast packet and byte counters. + +~~~none +vyos@vyos:~$ show ip multicast interface +Interface PktsIn PktsOut BytesIn BytesOut Local +----------- -------- --------- --------- ---------- -------------- +eth0 11528936 0 14.54 GB 0 B 10.222.175.251 +eth1 0 11528936 0 B 14.54 GB 192.168.0.1 +~~~ + +On a healthy proxy, the upstream and downstream counters increase +together. If the proxy replicates traffic to multiple downstream +interfaces, the output counters can exceed the input counters. If the +upstream counters increase but the downstream counters do not, the +router receives the streams but does not forward them. A missing +``forward`` firewall rule or the absence of downstream membership +causes this condition. +``` + +```{opcmd} show log igmp-proxy + +Display the log messages of the IGMP proxy process. Common messages: + +- ``No interfaces found for source 0.0.0.0``: This message is harmless. + General membership queries use an unspecified source address. +- ``Too many origins for route 239.192.0.2; replacing 10.237.1.165 + with 10.237.1.168``: This message is harmless. The multicast source + uses more origin servers than the IGMP proxy tracks for one route. + The IGMP proxy replaces the oldest entry and does not interrupt the + stream. +``` + +## Firewall considerations + +The IGMP proxy joins the requested multicast groups. The router +therefore receives the IGMP signaling and the multicast streams +locally. Multicast traffic traverses the ``input`` hook, not only the +``forward`` hook. A firewall with a default-drop ``input`` chain must +accept this traffic: + +- IGMP (protocol ``igmp``) on the upstream interface and on each + downstream interface, in the ``input`` hook. Downstream clients + address membership reports to multicast groups, not to the router. + The proxy must receive these reports to learn which streams to join. +- Traffic to multicast destinations (``224.0.0.0/4``) that arrives on + the upstream interface, in the ``input`` hook. +- Traffic to multicast destinations (``224.0.0.0/4``) from the + upstream interface to the downstream networks, in the ``forward`` + hook. + +## Example + +In this example, the local LAN on interface eth1 operates behind NAT. To allow +local clients to receive multicast traffic originating from the 198.51.100.0/24 +source network on the WAN interface (eth0), configure the IGMP proxy as +follows: + +```none +set protocols igmp-proxy interface eth0 role upstream +set protocols igmp-proxy interface eth0 alt-subnet 198.51.100.0/24 +set protocols igmp-proxy interface eth1 role downstream +``` + +>>>>>>> dad76493 (docs: igmp-proxy: document firewall requirements and operational commands (#2174)) -- cgit v1.2.3 From fd450159221e9abbf9d12aa6f3ff3f954da8b03e Mon Sep 17 00:00:00 2001 From: "JR L." Date: Fri, 14 Aug 2026 11:45:04 -0300 Subject: docs: igmp-proxy: document firewall requirements and operational commands (#2174) Co-authored-by: JR Lanteigne --- docs/configuration/protocols/igmp-proxy.md | 105 ++++++++++++++++------------- 1 file changed, 60 insertions(+), 45 deletions(-) (limited to 'docs') diff --git a/docs/configuration/protocols/igmp-proxy.md b/docs/configuration/protocols/igmp-proxy.md index 02d072ee..f4af94b4 100644 --- a/docs/configuration/protocols/igmp-proxy.md +++ b/docs/configuration/protocols/igmp-proxy.md @@ -1,43 +1,57 @@ --- -lastproofread: '2023-11-13' +myst: + html_meta: + description: | + The IGMP proxy enables routers to forward multicast traffic, such as + IPTV or video streams, between different networks like home networks + and ISPs. + keywords: igmp, igmp-proxy, multicast, iptv, quickleave, alt-subnet --- (igmp-proxy)= -# IGMP Proxy +# IGMP proxy -{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages -on behalf of a connected client. The configuration must define one, and only one -upstream interface, and one or more downstream interfaces. +The {abbr}`IGMP (Internet Group Management Protocol)` proxy enables routers to +forward multicast traffic, such as IPTV or video streams, between different +networks, such as home networks and ISPs. The IGMP proxy relies on an upstream +interface that faces upstream multicast sources, and one or more downstream +interfaces that face local networks or hosts and forward traffic to requesting +clients. + +IGMP proxy configuration requires exactly one upstream interface and at least +one downstream interface. ## Configuration ```{cfgcmd} set protocols igmp-proxy interface \ role \ -* **upstream:** The upstream network interface is the outgoing interface -which is responsible for communicating to available multicast data sources. -There can only be one upstream interface. +**Configure the operational role for the specified IGMP proxy interface.** -* **downstream:** Downstream network interfaces are the distribution -interfaces to the destination networks, where multicast clients can join -groups and receive multicast data. One or more downstream interfaces must -be configured. +- ``upstream``: Communicates with upstream multicast sources to retrieve the + multicast traffic. A valid configuration requires exactly one upstream + interface. +- ``downstream``: Communicates with downstream local subnets or hosts to + distribute the requested traffic. A valid configuration requires at least + one downstream interface. +``` + +Example: + +```none +set protocols igmp-proxy interface eth0 role upstream +set protocols igmp-proxy interface eth1 role downstream ``` ```{cfgcmd} set protocols igmp-proxy interface \ alt-subnet \ -Defines alternate sources for multicasting and IGMP data. The network address -must be on the following format 'a.b.c.d/n'. By default, the router will -accept data from sources on the same network as configured on an interface. -If the multicast source lies on a remote network, one must define from where -traffic should be accepted. +**Configure an allowed remote subnet for incoming multicast traffic +on the specified IGMP proxy interface** -This is especially useful for the upstream interface, since the source for -multicast traffic is often from a remote location. +By default, the IGMP proxy accepts multicast traffic only from directly +connected subnets. If a multicast source resides on a remote network, you +must explicitly define the allowed remote subnet to permit the traffic. -<<<<<<< HEAD -This option can be supplied multiple times. -======= You can configure multiple remote subnets for an **upstream** IGMP proxy interface. @@ -85,50 +99,52 @@ Example: ```none set protocols igmp-proxy interface eth0 threshold 5 ->>>>>>> dad76493 (docs: igmp-proxy: document firewall requirements and operational commands (#2174)) ``` ```{cfgcmd} set protocols igmp-proxy disable-quickleave -Disables quickleave mode. In this mode the daemon will not send a Leave IGMP -message upstream as soon as it receives a Leave message for any downstream -interface. The daemon will not ask for Membership reports on the downstream -interfaces, and if a report is received the group is not joined again the -upstream. +**Disable quickleave mode for the IGMP proxy.** -If it's vital that the daemon should act exactly like a real multicast client -on the upstream interface, this function should be enabled. +If disabled, the IGMP proxy does not send an upstream Leave message upon +receiving a downstream Leave message, preventing the immediate termination +of upstream multicast traffic. The IGMP proxy also stops querying downstream +interfaces for membership reports. If a downstream client submits a new +report, the IGMP proxy discards the message and does not resume the delivery +of requested traffic. +``` -Enabling this function increases the risk of bandwidth saturation. +```{note} +Disabling quickleave mode forces the IGMP proxy to act exactly like a +standard multicast client on the upstream interface. ``` -```{cfgcmd} set protocols igmp-proxy disable +```{note} +Disabling quickleave mode increases the risk of network bandwidth +saturation. +``` -Disable this service. +Example: + +```none +set protocols igmp-proxy disable-quickleave ``` -(igmp-proxy-example)= +```{cfgcmd} set protocols igmp-proxy disable -### Example +**Disable the IGMP proxy on the router.** +``` -Interface eth1 LAN is behind NAT. In order to subscribe 10.0.0.0/23 subnet -multicast which is in eth0 WAN we need to configure igmp-proxy. +Example: ```none -set protocols igmp-proxy interface eth0 role upstream -set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 -set protocols igmp-proxy interface eth1 role downstream +set protocols igmp-proxy disable ``` - ## Operation ```{opcmd} restart igmp-proxy Restart the IGMP proxy process. -<<<<<<< HEAD -``` -======= ``` ```{opcmd} show ip multicast interface @@ -196,4 +212,3 @@ set protocols igmp-proxy interface eth0 alt-subnet 198.51.100.0/24 set protocols igmp-proxy interface eth1 role downstream ``` ->>>>>>> dad76493 (docs: igmp-proxy: document firewall requirements and operational commands (#2174)) -- cgit v1.2.3