diff options
| -rw-r--r-- | docs/404.rst | 3 | ||||
| -rw-r--r-- | docs/_templates/layout.html | 2 | ||||
| -rw-r--r-- | docs/conf.py | 6 | ||||
| -rw-r--r-- | docs/configuration/firewall/flowtables.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/protocols/igmp-proxy.rst | 77 | ||||
| -rw-r--r-- | docs/configuration/protocols/igmp.rst | 249 | ||||
| -rw-r--r-- | docs/configuration/protocols/index.rst | 4 | ||||
| -rw-r--r-- | docs/configuration/protocols/pim.disable | 2 | ||||
| -rw-r--r-- | docs/configuration/protocols/pim.rst | 264 | ||||
| -rw-r--r-- | docs/configuration/protocols/pim6.rst | 6 |
10 files changed, 353 insertions, 262 deletions
diff --git a/docs/404.rst b/docs/404.rst index 5073773a..2ae79f2e 100644 --- a/docs/404.rst +++ b/docs/404.rst @@ -8,4 +8,5 @@ Try using the search box or go to the release homepage: * `1.2.x (crux) <https://docs.vyos.io/en/crux/>`_ * `1.3.x (equuleus) <https://docs.vyos.io/en/equuleus/>`_ - * `rolling release (sagitta) <https://docs.vyos.io/en/latest/>`_ + * `1.4.x (sagitta) <https://docs.vyos.io/en/sagitta/>`_ + * `rolling release (circinus) <https://docs.vyos.io/en/latest/>`_ diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index e7ede58c..6cb68508 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -1,5 +1,5 @@ {% extends "!layout.html" %} -{%- set current_version = "1.4.x sagitta" %} +{%- set current_version = "1.5.x circinus" %} {% block extrahead %} <link href="{{ pathto("_static/css/custom.css", True) }}" rel="stylesheet" type="text/css"> <link href="{{ pathto("_static/css/datatables.css", True) }}" rel="stylesheet" type="text/css"> diff --git a/docs/conf.py b/docs/conf.py index 4807472e..3fe1c6e1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,14 +22,14 @@ from docutils.parsers.rst.roles import set_classes # -- Project information ----------------------------------------------------- project = u'VyOS' -copyright = u'2021, VyOS maintainers and contributors' +copyright = u'2023, VyOS maintainers and contributors' author = u'VyOS maintainers and contributors' # The short X.Y version -version = u'1.4' +version = u'1.5' # The full version, including alpha/beta/rc tags -release = u'1.4.x (sagitta)' +release = u'1.5.x (circinus)' # -- General configuration --------------------------------------------------- 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**. |