summaryrefslogtreecommitdiff
path: root/docs/configuration
diff options
context:
space:
mode:
Diffstat (limited to 'docs/configuration')
-rw-r--r--docs/configuration/firewall/flowtables.rst2
-rw-r--r--docs/configuration/protocols/igmp-proxy.rst77
-rw-r--r--docs/configuration/protocols/igmp.rst249
-rw-r--r--docs/configuration/protocols/index.rst4
-rw-r--r--docs/configuration/protocols/pim.disable2
-rw-r--r--docs/configuration/protocols/pim.rst264
-rw-r--r--docs/configuration/protocols/pim6.rst6
7 files changed, 347 insertions, 257 deletions
diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst
index 05122c24..8b44a9b9 100644
--- a/docs/configuration/firewall/flowtables.rst
+++ b/docs/configuration/firewall/flowtables.rst
@@ -2,7 +2,7 @@
.. _firewall-flowtables-configuration:
-###################ä#############
+#################################
Flowtables Firewall Configuration
#################################
diff --git a/docs/configuration/protocols/igmp-proxy.rst b/docs/configuration/protocols/igmp-proxy.rst
new file mode 100644
index 00000000..f62a289e
--- /dev/null
+++ b/docs/configuration/protocols/igmp-proxy.rst
@@ -0,0 +1,77 @@
+:lastproofread: 2023-11-13
+
+.. _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.
+
+Configuration
+=============
+
+.. cfgcmd:: set protocols igmp-proxy interface <interface> role
+ <upstream | downstream>
+
+ * **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.
+
+ * **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.
+
+.. cfgcmd:: set protocols igmp-proxy interface <interface> alt-subnet <network>
+
+ 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.
+
+ This is especially useful for the upstream interface, since the source for
+ multicast traffic is often from a remote location.
+
+ This option can be supplied multiple times.
+
+.. 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.
+
+ If it's vital that the daemon should act exactly like a real multicast client
+ on the upstream interface, this function should be enabled.
+
+ Enabling this function increases the risk of bandwidth saturation.
+
+.. cfgcmd:: set protocols igmp-proxy disable
+
+ Disable this service.
+
+.. _igmp:proxy_example:
+
+Example
+-------
+
+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.
+
+.. code-block:: 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
+
+Operation
+=========
+
+.. opcmd:: restart igmp-proxy
+
+ Restart the IGMP proxy process.
diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst
deleted file mode 100644
index d3492632..00000000
--- a/docs/configuration/protocols/igmp.rst
+++ /dev/null
@@ -1,249 +0,0 @@
-:lastproofread: 2023-01-27
-
-.. _multicast:
-
-#########
-Multicast
-#########
-
-VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**,
-**IGMP** and **IGMP-Proxy**.
-
-************
-PIM and IGMP
-************
-
-PIM (Protocol Independent Multicast) must be configured in every
-interface of every participating router. Every router must also have the
-location of the Rendevouz Point manually configured. Then,
-unidirectional shared trees rooted at the Rendevouz Point will
-automatically be built for multicast distribution.
-
-Traffic from multicast sources will go to the Rendezvous Point, and
-receivers will pull it from a shared tree using IGMP (Internet Group
-Management Protocol).
-
-Multicast receivers will talk IGMP to their local router, so, besides
-having PIM configured in every router, IGMP must also be configured in
-any router where there could be a multicast receiver locally connected.
-
-VyOS supports both IGMP version 2 and version 3 (which allows
-source-specific multicast).
-
-
-Example
-=======
-
-In the following example we can see a basic multicast setup:
-
-.. image:: /_static/images/multicast-basic.png
- :width: 90%
- :align: center
- :alt: Network Topology Diagram
-
-
-
-**Router 1**
-
-.. code-block:: none
-
- set interfaces ethernet eth2 address '172.16.0.2/24'
- set interfaces ethernet eth1 address '100.64.0.1/24'
- set protocols ospf area 0 network '172.16.0.0/24'
- set protocols ospf area 0 network '100.64.0.0/24'
- set protocols igmp interface eth1
- set protocols pim interface eth1
- set protocols pim interface eth2
- set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
-
-**Router 3**
-
-.. code-block:: none
-
- set interfaces dummy dum0 address '172.16.255.1/24'
- set interfaces ethernet eth0 address '172.16.0.1/24'
- set interfaces ethernet eth1 address '172.16.1.1/24'
- set protocols ospf area 0 network '172.16.0.0/24'
- set protocols ospf area 0 network '172.16.255.0/24'
- set protocols ospf area 0 network '172.16.1.0/24'
- set protocols pim interface dum0
- set protocols pim interface eth0
- set protocols pim interface eth1
- set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
-
-**Router 2**
-
-.. code-block:: none
-
- set interfaces ethernet eth1 address '10.0.0.1/24'
- set interfaces ethernet eth2 address '172.16.1.2/24'
- set protocols ospf area 0 network '10.0.0.0/24'
- set protocols ospf area 0 network '172.16.1.0/24'
- set protocols pim interface eth1
- set protocols pim interface eth2
- set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
-
-
-
-
-
-Basic commands
-==============
-
-These are the commands for a basic setup.
-
-.. cfgcmd:: set protocols pim interface <interface-name>
-
- Use this command to enable PIM in the selected interface so that it
- can communicate with PIM neighbors.
-
-
-.. cfgcmd:: set protocols pim rp address <address> group
- <multicast-address/mask-bits>
-
- Use this command to manually configure a Rendezvous Point for PIM so
- that join messages can be sent there. Set the Rendevouz Point address
- and the matching prefix of group ranges covered. These values must
- be shared with every router participating in the PIM network.
-
-
-.. cfgcmd:: set protocols igmp interface eth1
-
- Use this command to configure an interface with IGMP so that PIM can
- receive IGMP reports and query on the selected interface. By default
- IGMP version 3 will be used.
-
-
-
-Tuning commands
-===============
-
-You can also tune multicast with the following commands.
-
-.. cfgcmd:: set protocols pim interface <interface> dr-priority <value>
-
- Use this PIM command in the selected interface to set the priority
- (1-4294967295) you want to influence in the election of a node to
- become the Designated Router for a LAN segment. The default priority
- is 1, set a higher value to give the router more preference in the
- DR election process.
-
-
-.. cfgcmd:: set protocols pim int <interface> hello <seconds>
-
- Use this command to configure the PIM hello interval in seconds
- (1-180) for the selected interface.
-
-
-.. cfgcmd:: set protocols pim rp keep-alive-timer <seconds>
-
- Use this PIM command to modify the time out value (31-60000
- seconds) for an `(S,G) <https://tools.ietf.org/html/rfc7761#section-4.1>`_
- flow. 31 seconds is chosen for a lower bound as some hardware
- platforms cannot see data flowing in better than 30 seconds chunks.
-
-
-.. cfgcmd:: set protocols igmp interface <interface> join <multicast-address>
- source <IP-address>
-
- Use this command to allow the selected interface to join a multicast
- group defining the multicast address you want to join and the source
- IP address too.
-
-
-.. cfgcmd:: set protocols igmp interface <interface> query-interval <seconds>
-
- Use this command to configure in the selected interface the IGMP
- host query interval (1-1800) in seconds that PIM will use.
-
-
-.. cfgcmd:: set protocols igmp interface <interface> query-max-response-time
- <deciseconds>
-
- Use this command to configure in the selected interface the IGMP
- query response timeout value (10-250) in deciseconds. If a report is
- not returned in the specified time, it will be assumed the `(S,G) or
- (*,G) state <https://tools.ietf.org/html/rfc7761#section-4.1>`_ has
- timed out.
-
-
-.. cfgcmd:: set protocols igmp interface <interface> version <version-number>
-
- Use this command to define in the selected interface whether you
- choose IGMP version 2 or 3. The default value is 3.
-
-
-
-**********
-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.
-
-Configuration
-=============
-
-.. cfgcmd:: set protocols igmp-proxy interface <interface> role
- <upstream | downstream>
-
- * **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.
-
- * **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.
-
-.. cfgcmd:: set protocols igmp-proxy interface <interface> alt-subnet <network>
-
- 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.
-
- This is especially useful for the upstream interface, since the source for
- multicast traffic is often from a remote location.
-
- This option can be supplied multiple times.
-
-.. 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.
-
- If it's vital that the daemon should act exactly like a real multicast client
- on the upstream interface, this function should be enabled.
-
- Enabling this function increases the risk of bandwidth saturation.
-
-.. cfgcmd:: set protocols igmp-proxy disable
-
- Disable this service.
-
-.. _igmp:proxy_example:
-
-Example
--------
-
-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.
-
-.. code-block:: 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
-
-Operation
-=========
-
-.. opcmd:: restart igmp-proxy
-
- Restart the IGMP proxy process.
diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst
index 237608a1..ea217d3c 100644
--- a/docs/configuration/protocols/index.rst
+++ b/docs/configuration/protocols/index.rst
@@ -2,7 +2,6 @@
Protocols
#########
-
.. toctree::
:maxdepth: 1
:includehidden:
@@ -11,11 +10,12 @@ Protocols
bfd
bgp
failover
- igmp
+ igmp-proxy
isis
mpls
segment-routing
ospf
+ pim
pim6
rip
rpki
diff --git a/docs/configuration/protocols/pim.disable b/docs/configuration/protocols/pim.disable
deleted file mode 100644
index 1dd373d8..00000000
--- a/docs/configuration/protocols/pim.disable
+++ /dev/null
@@ -1,2 +0,0 @@
-PIM
-### \ No newline at end of file
diff --git a/docs/configuration/protocols/pim.rst b/docs/configuration/protocols/pim.rst
new file mode 100644
index 00000000..1b97697d
--- /dev/null
+++ b/docs/configuration/protocols/pim.rst
@@ -0,0 +1,264 @@
+:lastproofread: 2023-11-13
+
+.. _pim:
+
+####################################
+PIM – Protocol Independent Multicast
+####################################
+
+VyOS supports :abbr:`PIM-SM (PIM Sparse Mode)` as well as
+:abbr:`IGMP (Internet Group Management Protocol)` v2 and v3
+
+:abbr:`PIM (Protocol Independent Multicast)` must be configured in every
+interface of every participating router. Every router must also have the
+location of the Rendevouz Point manually configured. Then, unidirectional
+shared trees rooted at the Rendevouz Point will automatically be built
+for multicast distribution.
+
+Traffic from multicast sources will go to the Rendezvous Point, and
+receivers will pull it from a shared tree using :abbr:`IGMP (Internet
+Group Management Protocol)`.
+
+Multicast receivers will talk IGMP to their local router, so, besides
+having PIM configured in every router, IGMP must also be configured in
+any router where there could be a multicast receiver locally connected.
+
+VyOS supports both IGMP version 2 and version 3 (which allows
+source-specific multicast).
+
+************************
+PIM-SM - PIM Sparse Mode
+************************
+
+.. cfgcmd:: set protocols pim ecmp
+
+ If PIM has the a choice of ECMP nexthops for a particular
+ :abbr:`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be
+ spread out amongst the nexthops. If this command is not specified then
+ the first nexthop found will be used.
+
+.. cfgcmd:: set protocols pim ecmp rebalance
+
+ If PIM is using ECMP and an interface goes down, cause PIM to rebalance all
+ S,G flows across the remaining nexthops. If this command is not configured
+ PIM only modifies those S,G flows that were using the interface that went
+ down.
+
+.. cfgcmd:: set protocols pim join-prune-interval <n>
+
+ Modify the join/prune interval that PIM uses to the new value. Time is
+ specified in seconds.
+
+ The default time is 60 seconds.
+
+ If you enter a value smaller than 60 seconds be aware that this can and
+ will affect convergence at scale.
+
+.. cfgcmd:: set protocols pim keep-alive-timer <n>
+
+ Modify the time out value for a S,G flow from 1-65535 seconds. If choosing
+ a value below 31 seconds be aware that some hardware platforms cannot see
+ data flowing in better than 30 second chunks.
+
+.. cfgcmd:: set protocols pim packets <n>
+
+ When processing packets from a neighbor process the number of packets
+ incoming at one time before moving on to the next task.
+
+ The default value is 3 packets.
+
+ This command is only useful at scale when you can possibly have a large
+ number of PIM control packets flowing.
+
+.. cfgcmd:: set protocols pim register-accept-list <prefix-list>
+
+ When PIM receives a register packet the source of the packet will be compared
+ to the prefix-list specified, and if a permit is received normal processing
+ continues. If a deny is returned for the source address of the register packet
+ a register stop message is sent to the source.
+
+.. cfgcmd:: set protocols pim register-suppress-time <n>
+
+ Modify the time that pim will register suppress a FHR will send register
+ notifications to the kernel.
+
+.. cfgcmd:: set protocols pim rp <address> group <group>
+
+ In order to use PIM, it is necessary to configure a :abbr:`RP (Rendezvous Point)`
+ for join messages to be sent to. Currently the only methodology to do this is
+ via static rendezvous point commands.
+
+ All routers in the PIM network must agree on these values.
+
+ The first ip address is the RP's address and the second value is the matching
+ prefix of group ranges covered.
+
+.. cfgcmd:: set protocols pim rp keep-alive-timer <n>
+
+ Modify the time out value for a S,G flow from 1-65535 seconds at
+ :abbr:`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G)
+ defaults to 210 seconds. However, at the :abbr:`RP (Rendezvous Point)`, the
+ keepalive period must be at least the Register_Suppression_Time, or the RP
+ may time out the (S,G) state before the next Null-Register arrives.
+ Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period)
+ when a Register-Stop is sent.
+
+ If choosing a value below 31 seconds be aware that some hardware platforms
+ cannot see data flowing in better than 30 second chunks.
+
+ See :rfc:`7761#section-4.1` for details.
+
+.. cfgcmd:: set protocols pim no-v6-secondary
+
+ When sending PIM hello packets tell PIM to not send any v6 secondary
+ addresses on the interface. This information is used to allow PIM to use v6
+ nexthops in it's decision for :abbr:`RPF (Reverse Path Forwarding)` lookup
+ if this option is not set (default).
+
+.. cfgcmd:: set protocols pim spt-switchover infinity-and-beyond [prefix-list <list>]
+
+ On the last hop router if it is desired to not switch over to the SPT tree
+ configure this command.
+
+ Optional parameter prefix-list can be use to control which groups to switch or
+ not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover
+ does not happen for it and if it is DENY, then the SPT switchover happens.
+
+.. cfgcmd:: set protocols pim ssm prefix-list <list>
+
+ Specify a range of group addresses via a prefix-list that forces PIM to never
+ do :abbr:`SSM (Source-Specific Multicast)` over.
+
+Interface specific commands
+===========================
+
+.. cfgcmd:: set protocols pim interface <interface> bfd [profile <name>]
+
+ Automatically create BFD session for each RIP peer discovered in this
+ interface. When the BFD session monitor signalize that the link is down
+ the RIP peer is removed and all the learned routes associated with that
+ peer are removed.
+
+ If optional profile parameter is used, select a BFD profile for the BFD
+ sessions created via this interface.
+
+.. cfgcmd:: set protocols pim interface <interface> dr-priority <n>
+
+ Set the :abbr:`DR (Designated Router)` Priority for the interface.
+ This command is useful to allow the user to influence what node becomes
+ the DR for a LAN segment.
+
+.. cfgcmd:: set protocols pim interface <interface> hello <n>
+
+ Set the PIM hello and hold interval for a interface.
+
+.. cfgcmd:: set protocols pim interface <interface> no-bsm
+
+ Tell PIM that we would not like to use this interface to process
+ bootstrap messages.
+
+.. cfgcmd:: set protocols pim interface <interface> no-unicast-bsm
+
+ Tell PIM that we would not like to use this interface to process
+ unicast bootstrap messages.
+
+.. cfgcmd:: set protocols pim interface <interface> passive
+
+ Disable sending and receiving PIM control packets on the interface.
+
+ .. cfgcmd:: set protocols pim interface <interface> source-address <ip-address>
+
+ If you have multiple addresses configured on a particular interface and would
+ like PIM to use a specific source address associated with that interface.
+
+******************************************
+IGMP - Internet Group Management Protocol)
+******************************************
+
+.. cfgcmd:: set protocols pim igmp watermark-warning <n>
+
+ Configure watermark warning generation for an IGMP group limit. Generates
+ warning once the configured group limit is reached while adding new groups.
+
+Interface specific commands
+===========================
+
+.. cfgcmd:: set protocols pim interface <interface> igmp
+ join <multicast-address> source-address <IP-address>
+
+ Use this command to allow the selected interface to join a multicast
+ group defining the multicast address you want to join and the source
+ IP address too.
+
+.. cfgcmd:: set protocols pim interface <interface> igmp
+ query-interval <seconds>
+
+ Use this command to configure in the selected interface the IGMP
+ host query interval (1-1800) in seconds that PIM will use.
+
+.. cfgcmd:: set protocols pim interface <interface> igmp
+ query-max-response-time <n>
+
+ Use this command to configure in the selected interface the IGMP
+ query response timeout value (10-250) in deciseconds. If a report is
+ not returned in the specified time, it will be assumed the (S,G) or
+ (*,G) state :rfc:`7761#section-4.1` has timed out.
+
+.. cfgcmd:: set protocols pim interface <interface> igmp version <version-number>
+
+ Use this command to define in the selected interface whether you
+ choose IGMP version 2 or 3.
+
+ The default value is 3.
+
+Example
+-------
+
+In the following example we can see a basic multicast setup:
+
+.. image:: /_static/images/multicast-basic.png
+ :width: 90%
+ :align: center
+ :alt: Network Topology Diagram
+
+
+
+**Router 1**
+
+.. code-block:: none
+
+ set interfaces ethernet eth2 address '172.16.0.2/24'
+ set interfaces ethernet eth1 address '100.64.0.1/24'
+ set protocols ospf area 0 network '172.16.0.0/24'
+ set protocols ospf area 0 network '100.64.0.0/24'
+ set protocols igmp interface eth1
+ set protocols pim interface eth1
+ set protocols pim interface eth2
+ set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
+
+**Router 3**
+
+.. code-block:: none
+
+ set interfaces dummy dum0 address '172.16.255.1/24'
+ set interfaces ethernet eth0 address '172.16.0.1/24'
+ set interfaces ethernet eth1 address '172.16.1.1/24'
+ set protocols ospf area 0 network '172.16.0.0/24'
+ set protocols ospf area 0 network '172.16.255.0/24'
+ set protocols ospf area 0 network '172.16.1.0/24'
+ set protocols pim interface dum0
+ set protocols pim interface eth0
+ set protocols pim interface eth1
+ set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
+
+**Router 2**
+
+.. code-block:: none
+
+ set interfaces ethernet eth1 address '10.0.0.1/24'
+ set interfaces ethernet eth2 address '172.16.1.2/24'
+ set protocols ospf area 0 network '10.0.0.0/24'
+ set protocols ospf area 0 network '172.16.1.0/24'
+ set protocols pim interface eth1
+ set protocols pim interface eth2
+ set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
diff --git a/docs/configuration/protocols/pim6.rst b/docs/configuration/protocols/pim6.rst
index 1d316cfb..2b2276a7 100644
--- a/docs/configuration/protocols/pim6.rst
+++ b/docs/configuration/protocols/pim6.rst
@@ -1,8 +1,8 @@
.. _pim6:
-##############
-IPv6 Multicast
-##############
+##############################################
+PIM6 - Protocol Independent Multicast for IPv6
+##############################################
VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**.