diff options
Diffstat (limited to 'docs/configuration/protocols')
| -rw-r--r-- | docs/configuration/protocols/bgp.rst | 144 | ||||
| -rw-r--r-- | docs/configuration/protocols/igmp.rst | 246 | ||||
| -rw-r--r-- | docs/configuration/protocols/index.rst | 18 | ||||
| -rw-r--r-- | docs/configuration/protocols/ospf.rst | 139 | ||||
| -rw-r--r-- | docs/configuration/protocols/rip.rst | 22 | ||||
| -rw-r--r-- | docs/configuration/protocols/static.rst | 66 |
6 files changed, 635 insertions, 0 deletions
diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst new file mode 100644 index 00000000..f0550fd4 --- /dev/null +++ b/docs/configuration/protocols/bgp.rst @@ -0,0 +1,144 @@ +.. _routing-bgp: + +Border Gateway Protocol (BGP) +----------------------------- + +IPv4 +^^^^ + +A simple eBGP configuration: + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' + set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' + set protocols bgp 65534 address-family ipv4-unicast network '172.16.0.0/16' + set protocols bgp 65534 parameters router-id '192.168.0.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' + set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' + set protocols bgp 65535 address-family ipv4-unicast network '172.17.0.0/16' + set protocols bgp 65535 parameters router-id '192.168.0.2' + + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route 172.16.0.0/16 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route 172.17.0.0/16 blackhole distance '254' + + +IPv6 +^^^^ + +A simple BGP configuration via IPv6. + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' + set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast + set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' + set protocols bgp 65534 parameters router-id '10.1.1.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' + set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast + set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' + set protocols bgp 65535 parameters router-id '10.1.1.2' + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route6 2001:db8:1::/48 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route6 2001:db8:2::/48 blackhole distance '254' + +Route Filter +^^^^^^^^^^^^ + +Route filter can be applied using a route-map: + +**Node1:** + +.. code-block:: none + + set policy prefix-list AS65535-IN rule 10 action 'permit' + set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' + set policy prefix-list AS65535-OUT rule 10 action 'deny' + set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' + set policy prefix-list6 AS65535-IN rule 10 action 'permit' + set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' + set policy prefix-list6 AS65535-OUT rule 10 action 'deny' + set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + set policy route-map AS65535-IN rule 10 action 'permit' + set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 20 action 'deny' + set policy route-map AS65535-OUT rule 10 action 'deny' + set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 20 action 'permit' + set protocols bgp 65534 neighbor 2001:db8::2 route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 route-map import 'AS65535-IN' + +**Node2:** + +.. code-block:: none + + set policy prefix-list AS65534-IN rule 10 action 'permit' + set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' + set policy prefix-list AS65534-OUT rule 10 action 'deny' + set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' + set policy prefix-list6 AS65534-IN rule 10 action 'permit' + set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' + set policy prefix-list6 AS65534-OUT rule 10 action 'deny' + set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + set policy route-map AS65534-IN rule 10 action 'permit' + set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 20 action 'deny' + set policy route-map AS65534-OUT rule 10 action 'deny' + set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 20 action 'permit' + set protocols bgp 65535 neighbor 2001:db8::1 route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 route-map import 'AS65534-IN' + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst new file mode 100644 index 00000000..421c9f0f --- /dev/null +++ b/docs/configuration/protocols/igmp.rst @@ -0,0 +1,246 @@ +.. _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 comand to manually configure a Rendevouz 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 defaul + 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 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 second chunks. + + +.. cfgcmd:: set protocols igmp interface <interface> join <multicast-address> source <IP-address> + + Use this command to allow the selected interface 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 asumed 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 + upstream. + + If it's vital that the daemon should act exactly as 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. + +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 new file mode 100644 index 00000000..a737a026 --- /dev/null +++ b/docs/configuration/protocols/index.rst @@ -0,0 +1,18 @@ +.. _routing: + +######### +Protocols +######### + +VyOS is a "router first" network operating system. It supports static routing, +policy routing, and dynamic routing using standard protocols (RIP, OSPF, and +BGP). + +.. toctree:: + :maxdepth: 1 + + bgp + igmp + ospf + rip + static diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst new file mode 100644 index 00000000..1e70f644 --- /dev/null +++ b/docs/configuration/protocols/ospf.rst @@ -0,0 +1,139 @@ +.. _routing-ospf: + +Open Shortest Path First (OSPF) +------------------------------- + +Open Shortest Path First (OSPF) is a routing protocol for Internet Protocol +(IP) networks. It uses a link state routing (LSR) algorithm and falls into the +group of interior gateway protocols (IGPs), operating within a single autonomous +system (AS). It is defined as OSPF Version 2 in RFC2328_ (1998) for IPv4. Updates +for IPv6 are specified as OSPF Version 3 in RFC5340_ (2008). OSPF supports the +Classless Inter-Domain Routing (CIDR) addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +OSPFv2 (IPv4) +^^^^^^^^^^^^^ + +In order to have a VyOS system exchanging routes with OSPF neighbors, you will at least need to configure the area and a network, + +.. code-block:: none + + set protocols ospf area 0 network 192.168.0.0/24 + +as well as the router ID. + +.. code-block:: none + + set protocols ospf parameters router-id 10.1.1.1 + +That is the minimum configuration you will need. + +Below you can see a typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route: + +**Node 1** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.1/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf default-information originate always + set protocols ospf default-information originate metric 10 + set protocols ospf default-information originate metric-type 2 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.1.1.1 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + +**Node 2** + +.. code-block:: none + + set interfaces loopback lo address 10.2.2.2/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.2.2.2 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + +OSPFv3 (IPv6) +^^^^^^^^^^^^^ + +A typical configuration using 2 nodes. + +**Node 1:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 redistribute connected + +**Node 2:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 + set protocols ospfv3 parameters router-id 192.168.2.1 + set protocols ospfv3 redistribute connected + +.. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard + interface link. This requires you to configure link-local addresses manually + on the WireGuard interfaces, see Phabricator task T1483_. + +Example configuration for WireGuard interfaces: + +**Node 1** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' + set interfaces wireguard wg01 address '192.168.0.1/24' + set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' + set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Node 2** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' + set interfaces wireguard wg01 address '192.168.0.2/24' + set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' + set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.2 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Status** + +.. code-block:: none + + vyos@ospf01:~$ sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + + vyos@ospf02# run sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] + +.. _RFC2328: https://tools.ietf.org/html/rfc2328 +.. _RFC5340: https://tools.ietf.org/html/rfc2340 +.. _T1483: https://phabricator.vyos.net/T1483 + diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rip.rst new file mode 100644 index 00000000..da00e7b1 --- /dev/null +++ b/docs/configuration/protocols/rip.rst @@ -0,0 +1,22 @@ +.. _routing-rip: + +Routing Information Protocol (RIP) +---------------------------------- + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +.. code-block:: none + + set interfaces loopback address 10.1.1.1/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected + +**Node 2:** + +.. code-block:: none + + set interfaces loopback address 10.2.2.2/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst new file mode 100644 index 00000000..8415981b --- /dev/null +++ b/docs/configuration/protocols/static.rst @@ -0,0 +1,66 @@ +.. _routing-static: + +###### +Static +###### + +Static routes are manually configured network routes. + +A typical use for a static route is a static default route for systems that do +not make use of DHCP or dynamic routing protocols: + +.. code-block:: none + + set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1' + +Another common use of static routes is to blackhole (drop) traffic. In the +example below, RFC1918_ networks are set as blackhole routes. + +This prevents these networks leaking out public interfaces, but it does not prevent +them from being used as the most specific route has the highest priority. + +.. code-block:: none + + set protocols static route 10.0.0.0/8 blackhole distance '254' + set protocols static route 172.16.0.0/12 blackhole distance '254' + set protocols static route 192.168.0.0/16 blackhole distance '254' + +.. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 + +.. _routing-arp: + +Address Resolution Protocol (ARP) +--------------------------------- + +To manipulate or display ARP_ table entries, the following commands are implemented. + +adding a static arp entry +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + set protocols static arp 10.1.1.100 hwaddr 08:00:27:de:23:aa + commit + +display arp table entries +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + show protocols static arp + + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 08:00:27:de:23:2e C eth1 + 10.1.1.100 ether 08:00:27:de:23:aa CM eth1 + +.. code-block:: none + + show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 08:00:27:de:23:2e C eth1 + 10.1.1.100 ether 08:00:27:de:23:aa CM eth1 + +.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol |