docs: igmp-proxy: document firewall requirements and operational commands (#2174)mergify/bp/circinus/pr-2174

Co-authored-by: JR Lanteigne <dniminenn@users.noreply.github.com>
(cherry picked from commit dad7649352c22260e00ea5dbbe8a8b18642ace7a)

# Conflicts:
#	docs/configuration/protocols/igmp-proxy.md

1 files changed, 121 insertions, 1 deletions

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 \<interface\> whitelist \<network\>
+
+**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 \<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))