From b1cb71c71935ad6b0a7d9effe8f4dc4467de2175 Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 30 Nov 2020 21:15:16 +0100 Subject: arrange: system configration --- docs/configuration/system/lcd.rst | 45 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/configuration/system/lcd.rst (limited to 'docs/configuration/system/lcd.rst') diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst new file mode 100644 index 00000000..2509946e --- /dev/null +++ b/docs/configuration/system/lcd.rst @@ -0,0 +1,45 @@ +.. _system-display: + +******************** +System Display (LCD) +******************** + +The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(`ttySxx`) or serial via USB or even old parallel port interfaces. + +Configuration +============= + +.. cfgcmd:: set system lcd device + + This is the name of the physical interface used to connect to your LCD + display. Tab completion is supported and it will list you all available + serial interface. + + For serial via USB port information please refor to: :ref:`hardware_usb`. + +.. cfgcmd:: set system lcd model + + This is the LCD model used in your system. + + At the time of this writing the following displays are supported: + + * Crystalfontz CFA-533 + + * Crystalfontz CFA-631 + + * Crystalfontz CFA-633 + + * Crystalfontz CFA-635 + + .. note:: We can't support all displays from the beginning. If your display + type is missing, please create a feature request via Phabricator_. + +.. include:: /common-references.rst + -- cgit v1.2.3 From ce090a4ced7fccce3fdc70142e22fa0009fae12b Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 6 Dec 2020 21:41:10 +0100 Subject: arrange examples --- docs/_include/common-references.txt | 6 + docs/_include/interface-vlan-8021ad.txt | 2 +- docs/_include/interface-vlan-8021q.txt | 2 +- docs/appendix/examples/azure-vpn-bgp.rst | 130 ---- docs/appendix/examples/azure-vpn-dual-bgp.rst | 155 ----- docs/appendix/examples/bgp-ipv6-unnumbered.rst | 172 ----- .../examples/dhcp-relay-through-gre-bridge.rst | 77 --- docs/appendix/examples/ha.rst | 580 ---------------- docs/appendix/examples/index.rst | 19 - docs/appendix/examples/ospf-unnumbered.rst | 118 ---- docs/appendix/examples/tunnelbroker-ipv6.rst | 169 ----- docs/appendix/examples/wan-load-balancing.rst | 170 ----- docs/appendix/examples/zone-policy.rst | 415 ------------ docs/cli.rst | 733 +++++++++++++++++++++ docs/command-list-configuration.rst | 7 - docs/command-list-operation.rst | 7 - docs/common-references.rst | 6 - docs/configexamples/azure-vpn-bgp.rst | 130 ++++ docs/configexamples/azure-vpn-dual-bgp.rst | 155 +++++ docs/configexamples/bgp-ipv6-unnumbered.rst | 172 +++++ .../dhcp-relay-through-gre-bridge.rst | 77 +++ docs/configexamples/ha.rst | 580 ++++++++++++++++ docs/configexamples/index.rst | 19 + docs/configexamples/ospf-unnumbered.rst | 118 ++++ docs/configexamples/tunnelbroker-ipv6.rst | 169 +++++ docs/configexamples/wan-load-balancing.rst | 170 +++++ docs/configexamples/zone-policy.rst | 415 ++++++++++++ docs/configuration-overview.rst | 730 -------------------- docs/configuration/interfaces/openvpn.rst | 2 +- docs/configuration/nat/index.rst | 2 +- docs/configuration/policy/index.rst | 2 +- docs/configuration/service/ipoe-server.rst | 2 +- docs/configuration/service/pppoe-server.rst | 2 +- docs/configuration/system/lcd.rst | 2 +- docs/configuration/vpn/dmvpn.rst | 335 ++++++++++ docs/configuration/vpn/index.rst | 15 + docs/configuration/vpn/ipsec.rst | 192 ++++++ docs/configuration/vpn/l2tp.rst | 235 +++++++ docs/configuration/vpn/openconnect.rst | 95 +++ docs/configuration/vpn/pptp.rst | 47 ++ docs/configuration/vpn/site2site_ipsec.rst | 298 +++++++++ docs/configuration/vpn/sstp.rst | 347 ++++++++++ docs/configuration/vrf/index.rst | 307 +++++++++ docs/configuration/zonepolicy/index.rst | 8 + docs/contributing/debugging.rst | 2 +- docs/contributing/development.rst | 2 +- docs/contributing/documentation.rst | 2 +- docs/contributing/issues-features.rst | 2 +- docs/coverage.rst | 2 - docs/index.rst | 3 +- docs/installation/upate.rst | 79 --- docs/installation/update.rst | 79 +++ docs/operation/index.rst | 3 +- docs/vpn/dmvpn.rst | 335 ---------- docs/vpn/index.rst | 18 - docs/vpn/ipsec.rst | 192 ------ docs/vpn/l2tp.rst | 235 ------- docs/vpn/openconnect.rst | 95 --- docs/vpn/pptp.rst | 47 -- docs/vpn/site2site_ipsec.rst | 298 --------- docs/vpn/sstp.rst | 347 ---------- docs/vrf.rst | 307 --------- 62 files changed, 4718 insertions(+), 4724 deletions(-) create mode 100644 docs/_include/common-references.txt delete mode 100644 docs/appendix/examples/azure-vpn-bgp.rst delete mode 100644 docs/appendix/examples/azure-vpn-dual-bgp.rst delete mode 100644 docs/appendix/examples/bgp-ipv6-unnumbered.rst delete mode 100644 docs/appendix/examples/dhcp-relay-through-gre-bridge.rst delete mode 100644 docs/appendix/examples/ha.rst delete mode 100644 docs/appendix/examples/index.rst delete mode 100644 docs/appendix/examples/ospf-unnumbered.rst delete mode 100644 docs/appendix/examples/tunnelbroker-ipv6.rst delete mode 100644 docs/appendix/examples/wan-load-balancing.rst delete mode 100644 docs/appendix/examples/zone-policy.rst delete mode 100644 docs/command-list-configuration.rst delete mode 100644 docs/command-list-operation.rst delete mode 100644 docs/common-references.rst create mode 100644 docs/configexamples/azure-vpn-bgp.rst create mode 100644 docs/configexamples/azure-vpn-dual-bgp.rst create mode 100644 docs/configexamples/bgp-ipv6-unnumbered.rst create mode 100644 docs/configexamples/dhcp-relay-through-gre-bridge.rst create mode 100644 docs/configexamples/ha.rst create mode 100644 docs/configexamples/index.rst create mode 100644 docs/configexamples/ospf-unnumbered.rst create mode 100644 docs/configexamples/tunnelbroker-ipv6.rst create mode 100644 docs/configexamples/wan-load-balancing.rst create mode 100644 docs/configexamples/zone-policy.rst delete mode 100644 docs/configuration-overview.rst create mode 100644 docs/configuration/vpn/dmvpn.rst create mode 100644 docs/configuration/vpn/index.rst create mode 100644 docs/configuration/vpn/ipsec.rst create mode 100644 docs/configuration/vpn/l2tp.rst create mode 100644 docs/configuration/vpn/openconnect.rst create mode 100644 docs/configuration/vpn/pptp.rst create mode 100644 docs/configuration/vpn/site2site_ipsec.rst create mode 100644 docs/configuration/vpn/sstp.rst create mode 100644 docs/configuration/vrf/index.rst create mode 100644 docs/configuration/zonepolicy/index.rst delete mode 100644 docs/installation/upate.rst create mode 100644 docs/installation/update.rst delete mode 100644 docs/vpn/dmvpn.rst delete mode 100644 docs/vpn/index.rst delete mode 100644 docs/vpn/ipsec.rst delete mode 100644 docs/vpn/l2tp.rst delete mode 100644 docs/vpn/openconnect.rst delete mode 100644 docs/vpn/pptp.rst delete mode 100644 docs/vpn/site2site_ipsec.rst delete mode 100644 docs/vpn/sstp.rst delete mode 100644 docs/vrf.rst (limited to 'docs/configuration/system/lcd.rst') diff --git a/docs/_include/common-references.txt b/docs/_include/common-references.txt new file mode 100644 index 00000000..79881972 --- /dev/null +++ b/docs/_include/common-references.txt @@ -0,0 +1,6 @@ +.. _`accel-ppp`: https://accel-ppp.org/ +.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol +.. _Phabricator: https://phabricator.vyos.net/ + +.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad +.. _802.1q: https://en.wikipedia.org/wiki/IEEE_802.1Q diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt index 12925ad4..74bc2080 100644 --- a/docs/_include/interface-vlan-8021ad.txt +++ b/docs/_include/interface-vlan-8021ad.txt @@ -140,4 +140,4 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. include:: /common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt index 37f652f3..db22a1ce 100644 --- a/docs/_include/interface-vlan-8021q.txt +++ b/docs/_include/interface-vlan-8021q.txt @@ -108,4 +108,4 @@ term used for this is ``vif``. :var3: :var4: 10 -.. include:: /common-references.rst \ No newline at end of file +.. include:: /_include/common-references.txt \ No newline at end of file diff --git a/docs/appendix/examples/azure-vpn-bgp.rst b/docs/appendix/examples/azure-vpn-bgp.rst deleted file mode 100644 index 176e0ae0..00000000 --- a/docs/appendix/examples/azure-vpn-bgp.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. _examples-azure-vpn-bgp: - -Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ------------------------------------------------------------- - -This guide shows an example of a route-based IKEv2 site-to-site VPN to -Azure using VTI and BGP for dynamic routing updates. - -For redundant / active-active configurations see `Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) `_ - -Prerequisites -^^^^^^^^^^^^^ - -- A pair of Azure VNet Gateways deployed in active-passive - configuration with BGP enabled. - -- A local network gateway deployed in Azure representing - the Vyos device, matching the below Vyos settings except for - address space, which only requires the Vyos private IP, in - this example 10.10.0.5/32 - -- A connection resource deployed in Azure linking the - Azure VNet gateway and the local network gateway representing - the Vyos device. - -Example -^^^^^^^ - -+---------------------------------------+---------------------+ -| WAN Interface | eth0 | -+---------------------------------------+---------------------+ -| On-premises address space | 10.10.0.0/16 | -+---------------------------------------+---------------------+ -| Azure address space | 10.0.0.0/16 | -+---------------------------------------+---------------------+ -| Vyos public IP | 198.51.100.3 | -+---------------------------------------+---------------------+ -| Vyos private IP | 10.10.0.5 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway public IP | 203.0.113.2 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway BGP IP | 10.0.0.4 | -+---------------------------------------+---------------------+ -| Pre-shared key | ch00s3-4-s3cur3-psk | -+---------------------------------------+---------------------+ -| Vyos ASN | 64499 | -+---------------------------------------+---------------------+ -| Azure ASN | 65540 | -+---------------------------------------+---------------------+ - -Vyos configuration -^^^^^^^^^^^^^^^^^^ - -- Configure the IKE and ESP settings to match a subset - of those supported by Azure: - -.. code-block:: none - - set vpn ipsec esp-group AZURE compression 'disable' - set vpn ipsec esp-group AZURE lifetime '3600' - set vpn ipsec esp-group AZURE mode 'tunnel' - set vpn ipsec esp-group AZURE pfs 'dh-group2' - set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' - set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' - - set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' - set vpn ipsec ike-group AZURE dead-peer-detection interval '15' - set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' - set vpn ipsec ike-group AZURE ikev2-reauth 'yes' - set vpn ipsec ike-group AZURE key-exchange 'ikev2' - set vpn ipsec ike-group AZURE lifetime '28800' - set vpn ipsec ike-group AZURE proposal 1 dh-group '2' - set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' - set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' - -- Enable IPsec on eth0 - -.. code-block:: none - - set vpn ipsec ipsec-interfaces interface 'eth0' - -- Configure a VTI with a dummy IP address - -.. code-block:: none - - set interfaces vti vti1 address '10.10.1.5/32' - set interfaces vti vti1 description 'Azure Tunnel' - -- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. - -.. code-block:: none - - set firewall options interface vti1 adjust-mss 1350 - -- Configure the VPN tunnel - -.. code-block:: none - - set vpn ipsec site-to-site peer 203.0.113.2 authentication id '198.51.100.3' - set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' - set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' - set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' - set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' - set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' - set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' - set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' - set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' - -- **Important**: Add an interface route to reach Azure's BGP listener - -.. code-block:: none - - set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 - -- Configure your BGP settings - -.. code-block:: none - - set protocols bgp 64499 neighbor 10.0.0.4 remote-as '65540' - set protocols bgp 64499 neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' - set protocols bgp 64499 neighbor 10.0.0.4 timers holdtime '30' - set protocols bgp 64499 neighbor 10.0.0.4 timers keepalive '10' - -- **Important**: Disable connected check \ - -.. code-block:: none - - set protocols bgp 64499 neighbor 10.0.0.4 disable-connected-check diff --git a/docs/appendix/examples/azure-vpn-dual-bgp.rst b/docs/appendix/examples/azure-vpn-dual-bgp.rst deleted file mode 100644 index 13d4b5a2..00000000 --- a/docs/appendix/examples/azure-vpn-dual-bgp.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. _examples-azure-vpn-dual-bgp: - -Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ----------------------------------------------------------------------- - -This guide shows an example of a redundant (active-active) route-based IKEv2 -site-to-site VPN to Azure using VTI -and BGP for dynamic routing updates. - -Prerequisites -^^^^^^^^^^^^^ - -- A pair of Azure VNet Gateways deployed in active-active - configuration with BGP enabled. - -- A local network gateway deployed in Azure representing - the Vyos device, matching the below Vyos settings except for - address space, which only requires the Vyos private IP, in - this example 10.10.0.5/32 - -- A connection resource deployed in Azure linking the - Azure VNet gateway and the local network gateway representing - the Vyos device. - -Example -^^^^^^^ - -+---------------------------------------+---------------------+ -| WAN Interface | eth0 | -+---------------------------------------+---------------------+ -| On-premises address space | 10.10.0.0/16 | -+---------------------------------------+---------------------+ -| Azure address space | 10.0.0.0/16 | -+---------------------------------------+---------------------+ -| Vyos public IP | 198.51.100.3 | -+---------------------------------------+---------------------+ -| Vyos private IP | 10.10.0.5 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway 1 public IP | 203.0.113.2 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway 2 public IP | 203.0.113.3 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway BGP IP | 10.0.0.4,10.0.0.5 | -+---------------------------------------+---------------------+ -| Pre-shared key | ch00s3-4-s3cur3-psk | -+---------------------------------------+---------------------+ -| Vyos ASN | 64499 | -+---------------------------------------+---------------------+ -| Azure ASN | 65540 | -+---------------------------------------+---------------------+ - -Vyos configuration -^^^^^^^^^^^^^^^^^^ - -- Configure the IKE and ESP settings to match a subset - of those supported by Azure: - -.. code-block:: none - - set vpn ipsec esp-group AZURE compression 'disable' - set vpn ipsec esp-group AZURE lifetime '3600' - set vpn ipsec esp-group AZURE mode 'tunnel' - set vpn ipsec esp-group AZURE pfs 'dh-group2' - set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' - set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' - - set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' - set vpn ipsec ike-group AZURE dead-peer-detection interval '15' - set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' - set vpn ipsec ike-group AZURE ikev2-reauth 'yes' - set vpn ipsec ike-group AZURE key-exchange 'ikev2' - set vpn ipsec ike-group AZURE lifetime '28800' - set vpn ipsec ike-group AZURE proposal 1 dh-group '2' - set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' - set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' - -- Enable IPsec on eth0 - -.. code-block:: none - - set vpn ipsec ipsec-interfaces interface 'eth0' - -- Configure two VTIs with a dummy IP address each - -.. code-block:: none - - set interfaces vti vti1 address '10.10.1.5/32' - set interfaces vti vti1 description 'Azure Primary Tunnel' - - set interfaces vti vti2 address '10.10.1.6/32' - set interfaces vti vti2 description 'Azure Secondary Tunnel' - -- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. - -.. code-block:: none - - set firewall options interface vti1 adjust-mss 1350 - set firewall options interface vti2 adjust-mss 1350 - -- Configure the VPN tunnels - -.. code-block:: none - - set vpn ipsec site-to-site peer 203.0.113.2 authentication id '198.51.100.3' - set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' - set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' - set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' - set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' - set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' - set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' - set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' - set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' - - set vpn ipsec site-to-site peer 203.0.113.3 authentication id '198.51.100.3' - set vpn ipsec site-to-site peer 203.0.113.3 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 203.0.113.3 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' - set vpn ipsec site-to-site peer 203.0.113.3 authentication remote-id '203.0.113.3' - set vpn ipsec site-to-site peer 203.0.113.3 connection-type 'respond' - set vpn ipsec site-to-site peer 203.0.113.3 description 'AZURE SECONDARY TUNNEL' - set vpn ipsec site-to-site peer 203.0.113.3 ike-group 'AZURE' - set vpn ipsec site-to-site peer 203.0.113.3 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 203.0.113.3 local-address '10.10.0.5' - set vpn ipsec site-to-site peer 203.0.113.3 vti bind 'vti2' - set vpn ipsec site-to-site peer 203.0.113.3 vti esp-group 'AZURE' - -- **Important**: Add an interface route to reach both Azure's BGP listeners - -.. code-block:: none - - set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 - set protocols static interface-route 10.0.0.5/32 next-hop-interface vti2 - -- Configure your BGP settings - -.. code-block:: none - - set protocols bgp 64499 neighbor 10.0.0.4 remote-as '65540' - set protocols bgp 64499 neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' - set protocols bgp 64499 neighbor 10.0.0.4 timers holdtime '30' - set protocols bgp 64499 neighbor 10.0.0.4 timers keepalive '10' - - set protocols bgp 64499 neighbor 10.0.0.5 remote-as '65540' - set protocols bgp 64499 neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' - set protocols bgp 64499 neighbor 10.0.0.5 timers holdtime '30' - set protocols bgp 64499 neighbor 10.0.0.5 timers keepalive '10' - -- **Important**: Disable connected check, otherwise the routes learned - from Azure will not be imported into the routing table. - -.. code-block:: none - - set protocols bgp 64499 neighbor 10.0.0.4 disable-connected-check - set protocols bgp 64499 neighbor 10.0.0.5 disable-connected-check diff --git a/docs/appendix/examples/bgp-ipv6-unnumbered.rst b/docs/appendix/examples/bgp-ipv6-unnumbered.rst deleted file mode 100644 index ccc1f69a..00000000 --- a/docs/appendix/examples/bgp-ipv6-unnumbered.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _examples-bgp-ipv6-unnumbered: - -######################################### -BGP IPv6 unnumbered with extended nexthop -######################################### - -General information can be found in the :ref:`bgp` chapter. - -Configuration -============= - -- Router A: - -.. code-block:: none - - set protocols bgp 64496 address-family ipv4-unicast redistribute connected - set protocols bgp 64496 address-family ipv6-unicast redistribute connected - set protocols bgp 64496 neighbor eth1 interface v6only - set protocols bgp 64496 neighbor eth1 interface v6only peer-group 'fabric' - set protocols bgp 64496 neighbor eth2 interface v6only - set protocols bgp 64496 neighbor eth2 interface v6only peer-group 'fabric' - set protocols bgp 64496 parameters bestpath as-path multipath-relax - set protocols bgp 64496 parameters bestpath compare-routerid - set protocols bgp 64496 parameters default no-ipv4-unicast - set protocols bgp 64496 parameters router-id '192.168.0.1' - set protocols bgp 64496 peer-group fabric address-family ipv4-unicast - set protocols bgp 64496 peer-group fabric address-family ipv6-unicast - set protocols bgp 64496 peer-group fabric capability extended-nexthop - set protocols bgp 64496 peer-group fabric remote-as 'external' - -- Router B: - -.. code-block:: none - - set protocols bgp 64499 address-family ipv4-unicast redistribute connected - set protocols bgp 64499 address-family ipv6-unicast redistribute connected - set protocols bgp 64499 neighbor eth1 interface v6only - set protocols bgp 64499 neighbor eth1 interface v6only peer-group 'fabric' - set protocols bgp 64499 neighbor eth2 interface v6only - set protocols bgp 64499 neighbor eth2 interface v6only peer-group 'fabric' - set protocols bgp 64499 parameters bestpath as-path multipath-relax - set protocols bgp 64499 parameters bestpath compare-routerid - set protocols bgp 64499 parameters default no-ipv4-unicast - set protocols bgp 64499 parameters router-id '192.168.0.2' - set protocols bgp 64499 peer-group fabric address-family ipv4-unicast - set protocols bgp 64499 peer-group fabric address-family ipv6-unicast - set protocols bgp 64499 peer-group fabric capability extended-nexthop - set protocols bgp 64499 peer-group fabric remote-as 'external' - -Results -======= - -- Router A: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 198.51.100.34/24 u/u - eth1 - u/u - eth2 - u/u - lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 - -.. code-block:: none - - vyos@vyos:~$ show ip route - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - - S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 - C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 - C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 - B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 - * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 - -.. code-block:: none - - vyos@vyos:~$ ping 192.168.0.2 - PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. - 64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms - 64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms - 64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms - 64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms - 64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms - - --- 192.168.0.2 ping statistics --- - 5 packets transmitted, 5 received, 0% packet loss, time 4086ms - rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms - -.. code-block:: none - - vyos@vyos:~$ show ip bgp summary - - IPv4 Unicast Summary: - BGP router identifier 192.168.0.1, local AS number 65020 vrf-id 0 - BGP table version 4 - RIB entries 5, using 800 bytes of memory - Peers 2, using 41 KiB of memory - Peer groups 1, using 64 bytes of memory - - Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd - eth1 4 64499 13 13 0 0 0 00:05:33 2 - eth2 4 64499 13 14 0 0 0 00:05:29 2 - - Total number of neighbors 2 - -- Router B: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 198.51.100.33/24 u/u - eth1 - u/u - eth2 - u/u - lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 - -.. code-block:: none - - vyos@vyos:~$ show ip route - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - - S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 - C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 - B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 - * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 - C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 - -.. code-block:: none - - vyos@vyos:~$ ping 192.168.0.1 - PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. - 64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms - 64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms - 64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms - 64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms - - --- 192.168.0.1 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3051ms - rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms - -.. code-block:: none - - vyos@vyos:~$ show ip bgp summary - IPv4 Unicast Summary: - BGP router identifier 192.168.0.2, local AS number 65021 vrf-id 0 - BGP table version 4 - RIB entries 5, using 800 bytes of memory - Peers 2, using 41 KiB of memory - Peer groups 1, using 64 bytes of memory - - Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd - eth1 4 64496 14 14 0 0 0 00:06:40 2 - eth2 4 64496 14 14 0 0 0 00:06:37 2 - - Total number of neighbors 2 - diff --git a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst b/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst deleted file mode 100644 index f94eb67f..00000000 --- a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. _examples-dhcp-relay-through-gre-bridge: - - -DHCP Relay through GRE-Bridge ------------------------------ - -Diagram -^^^^^^^ - -.. image:: /_static/images/dhcp-relay-through-gre-bridge.png - :width: 80% - :align: center - :alt: Network Topology Diagram - -Configuration -^^^^^^^^^^^^^ - -DHCP Server -""""""""""" - -.. code-block:: none - - set interfaces ethernet eth0 address '10.0.2.1/24' - set interfaces loopback lo address '3.3.3.3/24' - set interfaces tunnel tun100 address '172.16.0.2/30' - set interfaces tunnel tun100 encapsulation 'gre-bridge' - set interfaces tunnel tun100 local-ip '10.0.2.1' - set interfaces tunnel tun100 remote-ip '192.168.0.1' - set protocols ospf area 0 network '3.3.3.0/24' - set protocols ospf area 0 network '10.0.2.0/24' - set protocols ospf parameters router-id '3.3.3.3' - set protocols static interface-route 10.0.1.2/32 next-hop-interface tun100 - set service dhcp-server shared-network-name asdf authoritative - set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 start '3.3.3.30' - set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 stop '3.3.3.40' - set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 default-router '10.0.1.2' - set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 start '10.0.1.200' - set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 stop '10.0.1.210' - set service dhcp-server shared-network-name asdf subnet 10.2.1.0/24 range 0 start '10.2.1.222' - set service dhcp-server shared-network-name asdf subnet 10.2.1.0/24 range 0 stop '10.2.1.233' - set service dhcp-server shared-network-name asdf subnet 172.16.0.0/30 range 0 start '172.16.0.1' - set service dhcp-server shared-network-name asdf subnet 172.16.0.0/30 range 0 stop '172.16.0.2' - - -In-Between Router -""""""""""""""""" - -.. code-block:: none - - set interfaces ethernet eth0 address '192.168.0.2/24' - set interfaces ethernet eth1 address '10.0.2.2/24' - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '10.0.2.0/24' - set protocols ospf parameters router-id '192.168.0.2' - - -DHCP Relay -"""""""""" - -.. code-block:: none - - set interfaces ethernet eth0 address '10.0.1.2/24' - set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces loopback lo address '1.1.1.1' - set interfaces tunnel tun100 address '172.16.0.1/30' - set interfaces tunnel tun100 encapsulation 'gre-bridge' - set interfaces tunnel tun100 local-ip '192.168.0.1' - set interfaces tunnel tun100 remote-ip '10.0.2.1' - set protocols ospf area 0 network '10.0.1.0/24' - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '1.1.1.0/24' - set protocols ospf parameters router-id '1.1.1.1' - set protocols static interface-route 3.3.3.3/32 next-hop-interface tun100 - set service dhcp-relay interface 'eth0' - set service dhcp-relay interface 'tun100' - set service dhcp-relay server '3.3.3.3' - diff --git a/docs/appendix/examples/ha.rst b/docs/appendix/examples/ha.rst deleted file mode 100644 index 702cb2b2..00000000 --- a/docs/appendix/examples/ha.rst +++ /dev/null @@ -1,580 +0,0 @@ -############################# -High Availability Walkthrough -############################# - -This document walks you through a complete HA setup of two VyOS machines. This -design is based on a VM as the primary router, and a physical machine as a -backup, using VRRP, BGP, OSPF and conntrack sharing. - -The aim of this document is to walk you through setting everything up so you -and up at a point where you can reboot any machine and not lose more than a few -seconds worth of connectivity. - -Design -====== - -This is based on a real life, in production design. One of the complex issues -is ensuring you have redundant data INTO your network. We do this with a pair -of Cisco Nexus switches, and using Virtual PortChannels that are spanned across -them. This as an added bonus, also allows for complete switch failure without -an outage. How you achieve this yourself is left as an exercise to the reader -but our setup is documented here. - -Walkthrough suggestion ----------------------- - -The ``commit`` command is implied after every section. If you make an error, -``commit`` will warn you and you can fix it before getting too far into things. -Please ensure you commit early and commit often. - -If you are following through this document, it is strongly suggested you -complete the entire document, ONLY doing the virtual router1 steps, and then -come back and walk through it AGAIN on the backup hardware router. - -This ensures you don't go to fast, or miss a step. However, it will make your -life easier to configure the fixed IP address and default route now on the -hardware router. - -Example Network ---------------- - -In this document, we have been allocated 203.0.113.0/24 by our upstream -provider, which we are publishing on VLAN100. - -They want us to establish a BGP session to their routers on 192.0.2.11 and -192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and -we are AS65551. - -Our routers are going to have a floating IP address of 203.0.113.1, and use -.2 and .3 as their fixed IPs. - -We are going to use 10.200.201.0/24 for an 'internal' network on VLAN201. - -When traffic is originated from the 10.200.201.0/24 network, it will be -masqueraded to 203.0.113.1 - -For connection between sites, we are running a WireGuard link to two REMOTE -routers, and using OSPF over those links to distribute routes. That remote -site is expected to send traffic from anything in 10.201.0.0/16 - -VLANs ------ - -These are the vlans we wll be using: - -* 50: Upstream, using the 192.0.2.0/24 network allocated by them. -* 100: 'Public' network, using our 203.0.113.0/24 network. -* 201: 'Internal' network, using 10.200.201.0/24 - -Hardware --------- - -* switch1 (Nexus 10gb Switch) -* switch2 (Nexus 10gb Switch) -* compute1 (VMware ESXi 6.5) -* compute2 (VMware ESXi 6.5) -* compute3 (VMware ESXi 6.5) -* router2 (Random 1RU machine with 4 NICs) - -Note that router1 is a VM that runs on one of the compute nodes. - -Network Cabling ---------------- - -* From Datacenter - This connects into port 1 on both switches, and is tagged - as VLAN 50 -* Cisco VPC Crossconnect - Ports 39 and 40 bonded between each switch -* Hardware Router - Port 8 of each switch -* compute1 - Port 9 of each switch -* compute2 - Port 10 of each switch -* compute3 - Port 11 of each switch - -This is ignoring the extra Out-of-band management networking, which should be -on totally different switches, and a different feed into the rack, and is out -of scope of this. - -.. note:: Our implementation uses VMware's Distributed Port Groups, which allows - VMware to use LACP. This is a part of the ENTERPRISE licence, and is not - available on a Free licence. If you are implementing this and do not have - access to DPGs, you should not use VMware, and use some other virtualization - platform instead. - - -Basic Setup (via console) -========================= - -Create your router1 VM so it is able to withstand a VM Host failing, or a -network link failing. Using VMware, this is achieved by enabling vSphere DRS, -vSphere Availability, and creating a Distributed Port Group that uses LACP. - -Many other Hypervisors do this, and I'm hoping that this document will be -expanded to document how to do this for others. - -Create an 'All VLANs' network group, that passes all trunked traffic through -to the VM. Attach this network group to router1 as eth0. - -.. note:: VMware: You must DISABLE SECURITY on this Port group. Make sure that - ``Promiscuous Mode``\ , ``MAC address changes`` and ``Forged transmits`` are - enabled. All of these will be done as part of failover. - -Bonding on Hardware Router --------------------------- - -Create a LACP bond on the hardware router. We are assuming that eth0 and eth1 -are connected to port 8 on both switches, and that those ports are configured -as a Port-Channel. - -.. code-block:: none - - set interfaces bonding bond0 description 'Switch Port-Channel' - set interfaces bonding bond0 hash-policy 'layer2' - set interfaces bonding bond0 member interface 'eth0' - set interfaces bonding bond0 member interface 'eth1' - set interfaces bonding bond0 mode '802.3ad' - - -Assign external IP addresses ----------------------------- - -VLAN 100 and 201 will have floating IP addresses, but VLAN50 does not, as this -is talking directly to upstream. Create our IP address on vlan50. - -For the hardware router, replace ``eth0`` with ``bond0``. As (almost) every -command is identical, this will not be specified unless different things need -to be performed on different hosts. - -.. code-block:: none - - set interfaces ethernet eth0 vif 50 address '192.0.2.21/24' - -In this case, the hardware router has a different IP, so it would be - -.. code-block:: none - - set interfaces ethernet bond0 vif 50 address '192.0.2.22/24' - -Add (temporary) default route ------------------------------ - -It is assumed that the routers provided by upstream are capable of acting as a -default router, add that as a static route. - -.. code-block:: none - - set protocols static route 0.0.0.0/0 next-hop 192.0.2.11 - commit - save - - -Enable SSH ----------- - -Enable SSH so you can now SSH into the routers, rather than using the console. - -.. code-block:: none - - set service ssh - commit - save - -At this point you should be able to SSH into both of them, and will no longer -need access to the console (unless you break something!) - - -VRRP Configuration -================== - -We are setting up VRRP so that it does NOT fail back when a machine returns into -service, and it prioritizes router1 over router2. - -Internal Network ----------------- - -This has a floating IP address of 10.200.201.1/24, using virtual router ID 201. -The difference between them is the interface name, hello-source-address, and -peer-address. - -**router1** - -.. code-block:: none - - set interfaces ethernet eth0 vif 201 address 10.200.201.2/24 - set high-availability vrrp group int hello-source-address '10.200.201.2' - set high-availability vrrp group int interface 'eth0.201' - set high-availability vrrp group int peer-address '10.200.201.3' - set high-availability vrrp group int no-preempt - set high-availability vrrp group int priority '200' - set high-availability vrrp group int virtual-address '10.200.201.1/24' - set high-availability vrrp group int vrid '201' - - -**router2** - -.. code-block:: none - - set interfaces ethernet bond0 vif 201 address 10.200.201.3/24 - set high-availability vrrp group int hello-source-address '10.200.201.3' - set high-availability vrrp group int interface 'bond0.201' - set high-availability vrrp group int peer-address '10.200.201.2' - set high-availability vrrp group int no-preempt - set high-availability vrrp group int priority '100' - set high-availability vrrp group int virtual-address '10.200.201.1/24' - set high-availability vrrp group int vrid '201' - - -Public Network --------------- - -This has a floating IP address of 203.0.113.1/24, using virtual router ID 113. -The virtual router ID is just a random number between 1 and 254, and can be set -to whatever you want. Best practices suggest you try to keep them unique -enterprise-wide. - -**router1** - -.. code-block:: none - - set interfaces ethernet eth0 vif 100 address 203.0.113.2/24 - set high-availability vrrp group public hello-source-address '203.0.113.2' - set high-availability vrrp group public interface 'eth0.100' - set high-availability vrrp group public peer-address '203.0.113.3' - set high-availability vrrp group public no-preempt - set high-availability vrrp group public priority '200' - set high-availability vrrp group public virtual-address '203.0.113.1/24' - set high-availability vrrp group public vrid '113' - -**router2** - -.. code-block:: none - - set interfaces ethernet bond0 vif 100 address 203.0.113.3/24 - set high-availability vrrp group public hello-source-address '203.0.113.3' - set high-availability vrrp group public interface 'bond0.100' - set high-availability vrrp group public peer-address '203.0.113.2' - set high-availability vrrp group public no-preempt - set high-availability vrrp group public priority '100' - set high-availability vrrp group public virtual-address '203.0.113.1/24' - set high-availability vrrp group public vrid '113' - - -Create VRRP sync-group ----------------------- - -The sync group is used to replicate connection tracking. It needs to be assigned -to a random VRRP group, and we are creating a sync group called ``sync`` using -the vrrp group ``int``. - -.. code-block:: none - - set high-availability vrrp sync-group sync member 'int' - -Testing -------- - -At this point, you should be able to see both IP addresses when you run -``show interfaces``\ , and ``show vrrp`` should show both interfaces in MASTER -state (and SLAVE state on router2). - -.. code-block:: none - - vyos@router1:~$ show vrrp - Name Interface VRID State Last Transition - -------- ----------- ------ ------- ----------------- - int eth0.201 201 MASTER 100s - public eth0.100 113 MASTER 200s - vyos@router1:~$ - - -You should be able to ping to and from all the IPs you have allocated. - -NAT and conntrack-sync -====================== - -Masquerade Traffic originating from 10.200.201.0/24 that is heading out the -public interface. - -.. note:: We explicitly exclude the primary upstream network so that BGP or - OSPF traffic doesn't accidentally get NAT'ed. - -.. code-block:: none - - set nat source rule 10 destination address '!192.0.2.0/24' - set nat source rule 10 outbound-interface 'eth0.50' - set nat source rule 10 source address '10.200.201.0/24' - set nat source rule 10 translation address '203.0.113.1' - - -Configure conntrack-sync and disable helpers --------------------------------------------- - -Most conntrack modules cause more problems than they're worth, especially in a -complex network. Turn them off by default, and if you need to turn them on -later, you can do so. - -.. code-block:: none - - set system conntrack modules ftp disable - set system conntrack modules gre disable - set system conntrack modules nfs disable - set system conntrack modules pptp disable - set system conntrack modules sip disable - set system conntrack modules tftp disable - -Now enable replication between nodes. Replace eth0.201 with bond0.201 on the -hardware router. - -.. code-block:: none - - set service conntrack-sync accept-protocol 'tcp,udp,icmp' - set service conntrack-sync event-listen-queue-size '8' - set service conntrack-sync failover-mechanism vrrp sync-group 'sync' - set service conntrack-sync interface eth0.201 - set service conntrack-sync mcast-group '224.0.0.50' - set service conntrack-sync sync-queue-size '8' - -Testing -------- - -The simplest way to test is to look at the connection tracking stats on the -standby hardware router with the command ``show conntrack-sync statistics``. -The numbers should be very close to the numbers on the primary router. - -When you have both routers up, you should be able to establish a connection -from a NAT'ed machine out to the internet, reboot the active machine, and that -connection should be preserved, and will not drop out. - -OSPF Over WireGuard -=================== - -Wireguard doesn't have the concept of an up or down link, due to its design. -This complicates AND simplifies using it for network transport, as for reliable -state detection you need to use SOMETHING to detect when the link is down. - -If you use a routing protocol itself, you solve two problems at once. This is -only a basic example, and is provided as a starting point. - -Configure Wireguard -------------------- - -There is plenty of instructions and documentation on setting up Wireguard. The -only important thing you need to remember is to only use one WireGuard -interface per OSPF connection. - -We use small /30's from 10.254.60/24 for the point-to-point links. - -**router1** - -Replace the 203.0.113.3 with whatever the other router's IP address is. - -.. code-block:: none - - set interfaces wireguard wg01 address '10.254.60.1/30' - set interfaces wireguard wg01 description 'router1-to-offsite1' - set interfaces wireguard wg01 ip ospf authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' - set interfaces wireguard wg01 ip ospf cost '11' - set interfaces wireguard wg01 ip ospf dead-interval '5' - set interfaces wireguard wg01 ip ospf hello-interval '1' - set interfaces wireguard wg01 ip ospf network 'point-to-point' - set interfaces wireguard wg01 ip ospf priority '1' - set interfaces wireguard wg01 ip ospf retransmit-interval '5' - set interfaces wireguard wg01 ip ospf transmit-delay '1' - set interfaces wireguard wg01 peer OFFSITE1 allowed-ips '0.0.0.0/0' - set interfaces wireguard wg01 peer OFFSITE1 endpoint '203.0.113.3:50001' - set interfaces wireguard wg01 peer OFFSITE1 persistent-keepalive '15' - set interfaces wireguard wg01 peer OFFSITE1 pubkey 'GEFMOWzAyau42/HwdwfXnrfHdIISQF8YHj35rOgSZ0o=' - set interfaces wireguard wg01 port '50001' - - -**offsite1** - -This is connecting back to the STATIC IP of router1, not the floating. - -.. code-block:: none - - set interfaces wireguard wg01 address '10.254.60.2/30' - set interfaces wireguard wg01 description 'offsite1-to-router1' - set interfaces wireguard wg01 ip ospf authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' - set interfaces wireguard wg01 ip ospf cost '11' - set interfaces wireguard wg01 ip ospf dead-interval '5' - set interfaces wireguard wg01 ip ospf hello-interval '1' - set interfaces wireguard wg01 ip ospf network 'point-to-point' - set interfaces wireguard wg01 ip ospf priority '1' - set interfaces wireguard wg01 ip ospf retransmit-interval '5' - set interfaces wireguard wg01 ip ospf transmit-delay '1' - set interfaces wireguard wg01 peer ROUTER1 allowed-ips '0.0.0.0/0' - set interfaces wireguard wg01 peer ROUTER1 endpoint '192.0.2.21:50001' - set interfaces wireguard wg01 peer ROUTER1 persistent-keepalive '15' - set interfaces wireguard wg01 peer ROUTER1 pubkey 'CKwMV3ZaLntMule2Kd3G7UyVBR7zE8/qoZgLb82EE2Q=' - set interfaces wireguard wg01 port '50001' - -Test WireGuard --------------- - -Make sure you can ping 10.254.60.1 and .2 from both routers. - -Create Export Filter --------------------- - -We only want to export the networks we know we should be exporting. Always -whitelist your route filters, both importing and exporting. A good rule of -thumb is **'If you are not the default router for a network, don't advertise -it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 -network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE -the default route for). This filter is applied to ``redistribute connected``. -If we WERE to advertise it, the remote machines would see 192.0.2.21 available -via their default route, establish the connection, and then OSPF would say -'192.0.2.0/24 is available via this tunnel', at which point the tunnel would -break, OSPF would drop the routes, and then 192.0.2.0/24 would be reachable via -default again. This is called 'flapping'. - -.. code-block:: none - - set policy access-list 150 description 'Outbound OSPF Redistribution' - set policy access-list 150 rule 10 action 'permit' - set policy access-list 150 rule 10 destination any - set policy access-list 150 rule 10 source inverse-mask '0.0.0.255' - set policy access-list 150 rule 10 source network '10.200.201.0' - set policy access-list 150 rule 20 action 'permit' - set policy access-list 150 rule 20 destination any - set policy access-list 150 rule 20 source inverse-mask '0.0.0.255' - set policy access-list 150 rule 20 source network '203.0.113.0' - set policy access-list 150 rule 100 action 'deny' - set policy access-list 150 rule 100 destination any - set policy access-list 150 rule 100 source any - - -Create Import Filter --------------------- - -We only want to import networks we know about. Our OSPF peer should only be -advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE -MATCH. You deny in access-list 100 to accept the route. - -.. code-block:: none - - set policy access-list 100 description 'Inbound OSPF Routes from Peers' - set policy access-list 100 rule 10 action 'deny' - set policy access-list 100 rule 10 destination any - set policy access-list 100 rule 10 source inverse-mask '0.0.255.255' - set policy access-list 100 rule 10 source network '10.201.0.0' - set policy access-list 100 rule 100 action 'permit' - set policy access-list 100 rule 100 destination any - set policy access-list 100 rule 100 source any - set policy route-map PUBOSPF rule 100 action 'deny' - set policy route-map PUBOSPF rule 100 match ip address access-list '100' - set policy route-map PUBOSPF rule 500 action 'permit' - - -Enable OSPF ------------ - -Every router **must** have a unique router-id. -The 'reference-bandwidth' is used because when OSPF was originally designed, -the idea of a link faster than 1gbit was unheard of, and it does not scale -correctly. - -.. code-block:: none - - set protocols ospf area 0.0.0.0 authentication 'md5' - set protocols ospf area 0.0.0.0 network '10.254.60.0/24' - set protocols ospf auto-cost reference-bandwidth '10000' - set protocols ospf log-adjacency-changes - set protocols ospf parameters abr-type 'cisco' - set protocols ospf parameters router-id '10.254.60.2' - set protocols ospf route-map PUBOSPF - - -Test OSPF ---------- - -When you have enabled OSPF on both routers, you should be able to see each -other with the command ``show ip ospf neighbour``. The state must be 'Full' -or '2-Way', if it is not then there is a network connectivity issue between the -hosts. This is often caused by NAT or MTU issues. You should not see any new -routes (unless this is the second pass) in the output of ``show ip route`` - -Advertise connected routes -========================== - -As a reminder, only advertise routes that you are the default router for. This -is why we are NOT announcing the 192.0.2.0/24 network, because if that was -announced into OSPF, the other routers would try to connect to that network -over a tunnel that connects to that network! - -.. code-block:: none - - set protocols ospf access-list 150 export 'connected' - set protocols ospf redistribute connected - - -You should now be able to see the advertised network on the other host. - -Duplicate configuration ------------------------ - -At this pont you now need to create the X link between all four routers. Use a -different /30 for each link. - -Priorities ----------- - -Set the cost on the secondary links to be 200. This means that they will not -be used unless the primary links are down. - -.. code-block:: none - - set interfaces wireguard wg01 ip ospf cost '10' - set interfaces wireguard wg02 ip ospf cost '200' - - -This will be visible in 'show ip route'. - -BGP -=== - -BGP is an extremely complex network protocol. An example is provided here. - -.. note:: Router id's must be unique. - -**router1** - - -The ``redistribute ospf`` command is there purely as an example of how this can -be expanded. In this walkthrough, it will be filtered by BGPOUT rule 10000, as -it is not 203.0.113.0/24. - -.. code-block:: none - - set policy prefix-list BGPOUT description 'BGP Export List' - set policy prefix-list BGPOUT rule 10 action 'deny' - set policy prefix-list BGPOUT rule 10 description 'Do not advertise short masks' - set policy prefix-list BGPOUT rule 10 ge '25' - set policy prefix-list BGPOUT rule 10 prefix '0.0.0.0/0' - set policy prefix-list BGPOUT rule 100 action 'permit' - set policy prefix-list BGPOUT rule 100 description 'Our network' - set policy prefix-list BGPOUT rule 100 prefix '203.0.113.0/24' - set policy prefix-list BGPOUT rule 10000 action 'deny' - set policy prefix-list BGPOUT rule 10000 prefix '0.0.0.0/0' - set policy route-map BGPOUT description 'BGP Export Filter' - set policy route-map BGPOUT rule 10 action 'permit' - set policy route-map BGPOUT rule 10 match ip address prefix-list 'BGPOUT' - set policy route-map BGPOUT rule 10000 action 'deny' - set policy route-map BGPPREPENDOUT description 'BGP Export Filter' - set policy route-map BGPPREPENDOUT rule 10 action 'permit' - set policy route-map BGPPREPENDOUT rule 10 set as-path-prepend '65551 65551 65551' - set policy route-map BGPPREPENDOUT rule 10 match ip address prefix-list 'BGPOUT' - set policy route-map BGPPREPENDOUT rule 10000 action 'deny' - set protocols bgp 65551 address-family ipv4-unicast network 192.0.2.0/24 - set protocols bgp 65551 address-family ipv4-unicast redistribute connected metric '50' - set protocols bgp 65551 address-family ipv4-unicast redistribute ospf metric '50' - set protocols bgp 65551 neighbor 192.0.2.11 address-family ipv4-unicast route-map export 'BGPOUT' - set protocols bgp 65551 neighbor 192.0.2.11 address-family ipv4-unicast soft-reconfiguration inbound - set protocols bgp 65551 neighbor 192.0.2.11 remote-as '65550' - set protocols bgp 65551 neighbor 192.0.2.11 update-source '192.0.2.21' - set protocols bgp 65551 parameters router-id '192.0.2.21' - - -**router2** - -This is identical, but you use the BGPPREPENDOUT route-map to advertise the -route with a longer path. diff --git a/docs/appendix/examples/index.rst b/docs/appendix/examples/index.rst deleted file mode 100644 index b2f7bfde..00000000 --- a/docs/appendix/examples/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _examples: - -Configuration Blueprints -======================== - -This chapter contains various configuration examples: - -.. toctree:: - :maxdepth: 2 - - dhcp-relay-through-gre-bridge - zone-policy - bgp-ipv6-unnumbered - ospf-unnumbered - azure-vpn-bgp - azure-vpn-dual-bgp - tunnelbroker-ipv6 - ha - wan-load-balancing diff --git a/docs/appendix/examples/ospf-unnumbered.rst b/docs/appendix/examples/ospf-unnumbered.rst deleted file mode 100644 index 39f8f69a..00000000 --- a/docs/appendix/examples/ospf-unnumbered.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _examples-ospf-unnumbered: - -######################### -OSPF unnumbered with ECMP -######################### - -General infomration can be found in the :ref:`routing-ospf` chapter. - -Configuration -============= - -- Router A: - -.. code-block:: none - - set interfaces ethernet eth0 address '10.0.0.1/24' - set interfaces ethernet eth1 address '192.168.0.1/32' - set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' - set interfaces ethernet eth1 ip ospf network 'point-to-point' - set interfaces ethernet eth2 address '192.168.0.1/32' - set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' - set interfaces ethernet eth2 ip ospf network 'point-to-point' - set interfaces loopback lo address '192.168.0.1/32' - set protocols ospf area 0.0.0.0 authentication 'md5' - set protocols ospf area 0.0.0.0 network '192.168.0.1/32' - set protocols ospf parameters router-id '192.168.0.1' - set protocols ospf redistribute connected - -- Router B: - -.. code-block:: none - - set interfaces ethernet eth0 address '10.0.0.2/24' - set interfaces ethernet eth1 address '192.168.0.2/32' - set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' - set interfaces ethernet eth1 ip ospf network 'point-to-point' - set interfaces ethernet eth2 address '192.168.0.2/32' - set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' - set interfaces ethernet eth2 ip ospf network 'point-to-point' - set interfaces loopback lo address '192.168.0.2/32' - set protocols ospf area 0.0.0.0 authentication 'md5' - set protocols ospf area 0.0.0.0 network '192.168.0.2/32' - set protocols ospf parameters router-id '192.168.0.2' - set protocols ospf redistribute connected - - -Results -======= - -- Router A: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 10.0.0.1/24 u/u - eth1 192.168.0.1/32 u/u - eth2 192.168.0.1/32 u/u - lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 - -.. code-block:: none - - vyos@vyos:~$ show ip route - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - - S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 - O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 - via 192.168.0.2, eth2 onlink, 00:13:21 - C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 - O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 - C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 - C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 - C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 - O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 - * via 192.168.0.2, eth2 onlink, 00:29:03 - -- Router B: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 10.0.0.2/24 u/u - eth1 192.168.0.2/32 u/u - eth2 192.168.0.2/32 u/u - lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 - -.. code-block:: none - - vyos@vyos:~$ show ip route - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - - S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 - O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 - via 192.168.0.1, eth2 onlink, 00:13:21 - C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 - O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 - C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 - C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 - C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 - O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 - * via 192.168.0.1, eth2 onlink, 00:29:03 diff --git a/docs/appendix/examples/tunnelbroker-ipv6.rst b/docs/appendix/examples/tunnelbroker-ipv6.rst deleted file mode 100644 index 868b225f..00000000 --- a/docs/appendix/examples/tunnelbroker-ipv6.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. _examples-tunnelbroker-ipv6: - -####################### -Tunnelbroker.net (IPv6) -####################### - -This guides walks through the setup of https://www.tunnelbroker.net/ for an -IPv6 Tunnel. - -Prerequisites -============= - -- A public, routable IPv4 address. This does not necessarily need to be static, - but you will need to update the tunnel endpoint when/if your IP address - changes, which can be done with a script and a scheduled task. -- Account at https://www.tunnelbroker.net/ -- Requested a "Regular Tunnel". You want to choose a location that is closest - to your physical location for the best response time. - -Setup initial tunnel -==================== - -Set up initial IPv6 tunnel. Replace the field below from the fields on the -tunnel information page. - -.. code-block:: none - - conf - set interfaces tunnel tun0 address Client_IPv6_from_Tunnelbroker # This will be your VyOS install's public IPv6 address - set interfaces tunnel tun0 description 'HE.NET IPv6 Tunnel' - set interfaces tunnel tun0 encapsulation 'sit' - set interfaces tunnel tun0 local-ip Client_IPv4_from_Tunnelbroker # This is your public IP - set interfaces tunnel tun0 mtu '1472' - set interfaces tunnel tun0 multicast 'disable' - set interfaces tunnel tun0 remote-ip Server_IPv4_from_Tunnelbroker # This is the IP of the Tunnelbroker server - set protocols static interface-route6 ::/0 next-hop-interface tun0 # Tell all traffic to go over this tunnel - commit - -If your WAN connection is over PPPoE, you may need to set the MTU on the above -tunnel lower than 1472. - -At this point you should be able to ping an IPv6 address, try pinging Google: - -.. code-block:: none - - ping6 -c2 2001:4860:4860::8888 - - 64 bytes from 2001:4860:4860::8888: icmp_seq=1 ttl=57 time=21.7 ms - 64 bytes from 2001:4860:4860::8888: icmp_seq=2 ttl=57 time=21.1 ms - - --- 2001:4860:4860::8888 ping statistics --- - 2 packets transmitted, 2 received, 0% packet loss, time 1001ms - rtt min/avg/max/mdev = 21.193/21.459/21.726/0.304 ms - -Assuming the pings are successful, you need to add some DNS servers. -Some options: - -.. code-block:: none - - set system name-server 2001:4860:4860::8888 # Google - set system name-server 2001:4860:4860::8844 # Google - set system name-server 2606:4700:4700::1111 # Cloudflare - set system name-server 2606:4700:4700::1001 # Cloudflare - commit - -You should now be able to ping something by IPv6 DNS name: - -.. code-block:: none - - # ping6 -c2 one.one.one.one - PING one.one.one.one(one.one.one.one) 56 data bytes - 64 bytes from one.one.one.one: icmp_seq=1 ttl=58 time=16.8 ms - 64 bytes from one.one.one.one: icmp_seq=2 ttl=58 time=17.4 ms - - --- one.one.one.one ping statistics --- - 2 packets transmitted, 2 received, 0% packet loss, time 1001ms - rtt min/avg/max/mdev = 16.880/17.153/17.426/0.273 ms - -Assuming everything works, you can proceed to client configuration - -LAN Configuration -================= - -At this point your VyOS install should have full IPv6, but now your LAN devices -need access. - -With Tunnelbroker.net, you have two options: - -- Routed /64. This is the default assignment. In IPv6-land, it's good for a - single "LAN", and is somewhat equivalent to a /24. - Example: `2001:470:xxxx:xxxx::/64` -- Routed /48. This is something you can request by clicking the "Assign /48" - link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k - LANs. Example: `2001:470:xxxx::/48` - -Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So -if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore -the assigned /64, and request the /48 and use that. - -Single LAN Setup -================ - -Single LAN setup where eth1 is your LAN interface. Use the /64 (all the xxxx -should be replaced with the information from your `Routed /64` tunnel): - -.. code-block:: none - - set interfaces ethernet eth1 address '2001:470:xxxx:xxxx::1/64' - set service router-advert interface eth1 name-server '2001:4860:4860::8888' - set service router-advert interface eth1 name-server '2001:4860:4860::8844' - set service router-advert interface eth1 prefix 2001:470:xxxx:xxxx::/64 - -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, 'valid-lifetime' and 'preferred-lifetime' are set to default values of 30 days and 4 hours respectively. - -This accomplishes a few things: - -- Sets your LAN interface's IP address -- Enables router advertisements. This is an IPv6 alternative for DHCP (though - DHCPv6 can still be used). With RAs, Your devices will automatically find the - information they need for routing and DNS. - -Multiple LAN/DMZ Setup -====================== - -In this, you use the `Routed /48` information. This allows you to assign a -different /64 to every interface, LAN, or even device. Or you could break your -network into smaller chunks like /56 or /60. - -The format of these addresses: - -- `2001:470:xxxx::/48`: The whole subnet. xxxx should come from Tunnelbroker. -- `2001:470:xxxx:1::/64`: A subnet suitable for a LAN -- `2001:470:xxxx:2::/64`: Another subnet -- `2001:470:xxxx:ffff:/64`: The last usable /64 subnet. - -In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff -(1-65535). - -So, when your LAN is eth1, your DMZ is eth2, your cameras live on eth3, etc: - -.. code-block:: none - - set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' - set service router-advert interface eth1 name-server '2001:4860:4860::8888' - set service router-advert interface eth1 name-server '2001:4860:4860::8844' - set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64 - - set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' - set service router-advert interface eth2 name-server '2001:4860:4860::8888' - set service router-advert interface eth2 name-server '2001:4860:4860::8844' - set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64 - - set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' - set service router-advert interface eth3 name-server '2001:4860:4860::8888' - set service router-advert interface eth3 name-server '2001:4860:4860::8844' - set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 - -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, 'valid-lifetime' and 'preferred-lifetime' are set to default values of 30 days and 4 hours respectively. - -Firewall -======== - -Finally, don't forget the :ref:`firewall`. The usage is identical, except for -instead of `set firewall name NAME`, you would use `set firewall ipv6-name -NAME`. - -Similarly, to attach the firewall, you would use `set interfaces ethernet eth0 -firewall in ipv6-name` or `set zone-policy zone LOCAL from WAN firewall -ipv6-name`. diff --git a/docs/appendix/examples/wan-load-balancing.rst b/docs/appendix/examples/wan-load-balancing.rst deleted file mode 100644 index 7093defe..00000000 --- a/docs/appendix/examples/wan-load-balancing.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. _wan-load-balancing: - -WAN Load Balancer examples -========================== - - -Example 1: Distributing load evenly ------------------------------------ - -The setup used in this example is shown in the following diagram: - -.. image:: /_static/images/Wan_load_balancing1.png - :width: 80% - :align: center - :alt: Network Topology Diagram - - -Overview -^^^^^^^^ - * All traffic coming in trough eth2 is balanced between eth0 and eth1 - on the router. - * Pings will be sent to four targets for health testing (33.44.55.66, - 44.55.66.77, 55.66.77.88 and 66.77.88.99). - * All outgoing packets are assigned the source address of the assigned - interface (SNAT). - * eth0 is set to be removed from the load balancer's interface pool - after 5 ping failures, eth1 will be removed after 4 ping failures. - -Create static routes to ping targets -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Create static routes through the two ISPs towards the ping targets and -commit the changes: - -.. code-block:: none - - set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 - set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 - set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 - set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 - -Configure the load balancer -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Configure the WAN load balancer with the parameters described above: - -.. code-block:: none - - set load-balancing wan interface-health eth0 failure-count 5 - set load-balancing wan interface-health eth0 nexthop 11.22.33.1 - set load-balancing wan interface-health eth0 test 10 type ping - set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 - set load-balancing wan interface-health eth0 test 20 type ping - set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 - set load-balancing wan interface-health eth1 failure-count 4 - set load-balancing wan interface-health eth1 nexthop 22.33.44.1 - set load-balancing wan interface-health eth1 test 10 type ping - set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 - set load-balancing wan interface-health eth1 test 20 type ping - set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 - set load-balancing wan rule 10 inbound-interface eth2 - set load-balancing wan rule 10 interface eth0 - set load-balancing wan rule 10 interface eth1 - -Example 2: Failover based on interface weights ----------------------------------------------- - -This examples uses the failover mode. - -Overview -^^^^^^^^ -In this example eth0 is the primary interface and eth1 is the secondary -interface to provide simple failover functionality. If eth0 fails, eth1 -takes over. - -Create interface weight based configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The configuration steps are the same as in the previous example, except -rule 10 so we keep the configuration, remove rule 10 and add a new rule -for the failover mode: - -.. code-block:: none - - delete load-balancing wan rule 10 - set load-balancing wan rule 10 failover - set load-balancing wan rule 10 inbound-interface eth2 - set load-balancing wan rule 10 interface eth0 weight 10 - set load-balancing wan rule 10 interface eth1 weight 1 - -Example 3: Failover based on rule order ---------------------------------------- - -The previous example used the failover command to send traffic thorugh -eth1 if eth0 fails. In this example failover functionality is provided -by rule order. - -Overview -^^^^^^^^ -Two rules will be created, the first rule directs traffic coming in -from eth2 to eth0 and the second rule directs the traffic to eth1. If -eth0 fails the first rule is bypassed and the second rule matches, -directing traffic to eth1. - -Create rule order based configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We keep the configurtation from the previous example, delete rule 10 -and create the two new rules as described: - -.. code-block:: none - - delete load-balancing wan rule 10 - set load-balancing wan rule 10 inbound-interface eth2 - set load-balancing wan rule 10 interface eth0 - set load-balancing wan rule 20 inbound-interface eth2 - set load-balancing wan rule 20 interface eth1 - -Example 4: Failover based on rule order - priority traffic ----------------------------------------------------------- - -A rule order for prioritising traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritise VoIP traffic. - -Overview -^^^^^^^^ -A rule order for prioritising traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritise VoIP traffic. - -Create rule order based configuration with low speed secondary link -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We keep the configuration from the previous example, delete rule 20 and -create a new rule as described: - -.. code-block:: none - - delete load-balancing wan rule 20 - set load-balancing wan rule 20 inbound-interface eth2 - set load-balancing wan rule 20 interface eth1 - set load-balancing wan rule 20 destination port sip - set load-balancing wan rule 20 protocol tcp - set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 - -Example 5: Exclude traffic from load balancing ----------------------------------------------- - -In this example two LAN interfaces exist in different subnets instead -of one like in the previous examples: - -.. image:: /_static/images/Wan_load_balancing_exclude1.png - :width: 80% - :align: center - :alt: Network Topology Diagram - -Adding a rule for the second interface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Based on the previous example, another rule for traffic from the second -interface eth3 can be added to the load balancer. However, traffic meant -to flow between the LAN subnets will be sent to eth0 and eth1 as well. -To prevent this, another rule is required. This rule excludes traffic -between the local subnets from the load balancer. It also excludes -locally-sources packets (required for web caching with load balancing). -eth+ is used as an alias that refers to all ethernet interfaces: - -.. code-block:: none - - set load-balancing wan rule 5 exclude - set load-balancing wan rule 5 inbound-interface eth+ - set load-balancing wan rule 5 destination address 10.0.0.0/8 diff --git a/docs/appendix/examples/zone-policy.rst b/docs/appendix/examples/zone-policy.rst deleted file mode 100644 index bfe77c2e..00000000 --- a/docs/appendix/examples/zone-policy.rst +++ /dev/null @@ -1,415 +0,0 @@ -.. _examples-zone-policy: - -Zone-Policy example -------------------- - -Native IPv4 and IPv6 -^^^^^^^^^^^^^^^^^^^^ - -We have three networks. - -.. code-block:: none - - WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 - LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 - DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 - - -**This specific example is for a router on a stick, but is very easily -adapted for however many NICs you have**: - - -* Internet - 192.168.200.100 - TCP/80 -* Internet - 192.168.200.100 - TCP/443 -* Internet - 192.168.200.100 - TCP/25 -* Internet - 192.168.200.100 - TCP/53 -* VyOS actis as DHCP, DNS forwarder, NAT, router and firewall. -* 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web - and mail (SMTP/IMAP) server. -* 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It - can SSH to VyOS. -* LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. -* LAN can access DMZ resources. -* DMZ cannot access LAN resources. -* Inbound WAN connect to DMZ host. - -.. image:: /_static/images/zone-policy-diagram.png - :width: 80% - :align: center - :alt: Network Topology Diagram - -The VyOS interface is assigned the .1/:1 address of their respective -networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. - -It will look something like this: - -.. code-block:: none - - interfaces { - ethernet eth0 { - duplex auto - hw-id 00:53:ed:6e:2a:92 - smp_affinity auto - speed auto - vif 10 { - address 172.16.10.1/24 - address 2001:db8:0:9999::1/64 - } - vif 20 { - address 192.168.100.1/24 - address 2001:db8:0:AAAA::1/64 - } - vif 30 { - address 192.168.200.1/24 - address 2001:db8:0:BBBB::1/64 - } - } - loopback lo { - } - } - - -Zones Basics -^^^^^^^^^^^^ - -Each interface is assigned to a zone. The interface can be physical or -virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly -the same. - -Traffic flows from zone A to zone B. That flow is what I refer to as a -zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. - -Ruleset are created per zone-pair-direction. - -I name rule sets to indicate which zone-pair-direction they represent. -eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. - -In VyOS, you have to have unique Ruleset names. In the event of overlap, -I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This -allows for each auto-completion and uniqueness. - -In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is -the firewall itself. - -If your computer is on the LAN and you need to SSH into your VyOS box, -you would need a rule to allow it in the LAN-Local ruleset. If you want -to access a webpage from your VyOS box, you need a rule to allow it in -the Local-LAN ruleset. - -In rules, it is good to keep them named consistently. As the number of -rules you have grows, the more consistency you have, the easier your -life will be. - -.. code-block:: none - - Rule 1 - State Established, Related - Rule 2 - State Invalid - Rule 100 - ICMP - Rule 200 - Web - Rule 300 - FTP - Rule 400 - NTP - Rule 500 - SMTP - Rule 600 - DNS - Rule 700 - DHCP - Rule 800 - SSH - Rule 900 - IMAPS - -The first two rules are to deal with the idiosyncrasies of VyOS and -iptables. - -Zones and Rulesets both have a default action statement. When using -Zone-Policies, the default action is set by the zone-policy statement -and is represented by rule 10000. - -It is good practice to log both accepted and denied traffic. It can save -you significant headaches when trying to troubleshoot a connectivity -issue. - -To add logging to the default rule, do: - -.. code-block:: none - - set firewall name enable-default-log - - -By default, iptables does not allow traffic for established session to -return, so you must explicitly allow this. I do this by adding two rules -to every ruleset. 1 allows established and related state packets through -and rule 2 drops and logs invalid state packets. We place the -established/related rule at the top because the vast majority of traffic -on a network is established and the invalid rule to prevent invalid -state packets from mistakenly being matched against other rules. Having -the most matched rule listed first reduces CPU load in high volume -environments. Note: I have filed a bug to have this added as a default -action as well. - -''It is important to note, that you do not want to add logging to the -established state rule as you will be logging both the inbound and -outbound packets for each session instead of just the initiation of the -session. Your logs will be massive in a very short period of time.'' - -In VyOS you must have the interfaces created before you can apply it to -the zone and the rulesets must be created prior to applying it to a -zone-policy. - -I create/configure the interfaces first. Build out the rulesets for each -zone-pair-direction which includes at least the three state rules. Then -I setup the zone-policies. - -Zones do not allow for a default action of accept; either drop or -reject. It is important to remember this because if you apply an -interface to a zone and commit, any active connections will be dropped. -Specifically, if you are SSH’d into VyOS and add local or the interface -you are connecting through to a zone and do not have rulesets in place -to allow SSH and established sessions, you will not be able to connect. - -The following are the rules that were created for this example (may not -be complete), both in IPv4 and IPv6. If there is no IP specified, then -the source/destination address is not explicit. - -.. code-block:: none - - WAN – DMZ:192.168.200.200 – tcp/80 - WAN – DMZ:192.168.200.200 – tcp/443 - WAN – DMZ:192.168.200.200 – tcp/25 - WAN – DMZ:192.168.200.200 – tcp/53 - WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/80 - WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/443 - WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/25 - WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/53 - - DMZ - Local - tcp/53 - DMZ - Local - tcp/123 - DMZ - Local - tcp/67,68 - - LAN - Local - tcp/53 - LAN - Local - tcp/123 - LAN - Local - tcp/67,68 - LAN:192.168.100.10 - Local - tcp/22 - LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 - - LAN - WAN - tcp/80 - LAN - WAN - tcp/443 - LAN - WAN - tcp/22 - LAN - WAN - tcp/20,21 - - DMZ - WAN - tcp/80 - DMZ - WAN - tcp/443 - DMZ - WAN - tcp/22 - DMZ - WAN - tcp/20,21 - DMZ - WAN - tcp/53 - DMZ - WAN - udp/53 - - Local - WAN - tcp/80 - Local - WAN - tcp/443 - Local - WAN - tcp/20,21 - - Local - DMZ - tcp/25 - Local - DMZ - tcp/67,68 - Local - DMZ - tcp/53 - Local - DMZ - udp/53 - - Local - LAN - tcp/67,68 - - LAN - DMZ - tcp/80 - LAN - DMZ - tcp/443 - LAN - DMZ - tcp/993 - LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 - LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 - -Since we have 4 zones, we need to setup the following rulesets. - -.. code-block:: none - - Lan-wan - Lan-local - Lan-dmz - Wan-lan - Wan-local - Wan-dmz - Local-lan - Local-wan - Local-dmz - Dmz-lan - Dmz-wan - Dmz-local - -Even if the two zones will never communicate, it is a good idea to -create the zone-pair-direction rulesets and set enable-default-log. This -will allow you to log attempts to access the networks. Without it, you -will never see the connection attempts. - -This is an example of the three base rules. - -.. code-block:: none - - name wan-lan { - default-action drop - enable-default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - } - } - - -Here is an example of an IPv6 DMZ-WAN ruleset. - -.. code-block:: none - - ipv6-name dmz-wan-6 { - default-action drop - enable-default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - rule 100 { - action accept - log enable - protocol ipv6-icmp - } - rule 200 { - action accept - destination { - port 80,443 - } - log enable - protocol tcp - } - rule 300 { - action accept - destination { - port 20,21 - } - log enable - protocol tcp - } - rule 500 { - action accept - destination { - port 25 - } - log enable - protocol tcp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 600 { - action accept - destination { - port 53 - } - log enable - protocol tcp_udp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 800 { - action accept - destination { - port 22 - } - log enable - protocol tcp - } - } - -Once you have all of your rulesets built, then you need to create your -zone-policy. - -Start by setting the interface and default action for each zone. - -.. code-block:: none - - set zone-policy zone dmz default-action drop - set zone-policy zone dmz interface eth0.30 - -In this case, we are setting the v6 ruleset that represents traffic -sourced from the LAN, destined for the DMZ. Because the zone-policy -firewall syntax is a little awkward, I keep it straight by thinking of -it backwards. - -.. code-block:: none - - set zone-policy zone dmz from lan firewall ipv6-name lan-dmz-6 - -DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out -a bunch at one time. - -In the end, you will end up with something like this config. I took out -everything but the Firewall, Interfaces, and zone-policy sections. It is -long enough as is. - - -IPv6 Tunnel -^^^^^^^^^^^ - -If you are using a IPv6 tunnel from HE.net or someone else, the basis is -the same except you have two WAN interface. One for v4 and one for v6. - -You would have 5 zones instead of just 4 and you would configure your v6 -ruleset between your tunnel interface and your LAN/DMZ zones instead of -to the WAN. - -LAN, WAN, DMZ, local and TUN (tunnel) - -v6 pairs would be: - -.. code-block:: none - - lan-tun - lan-local - lan-dmz - tun-lan - tun-local - tun-dmz - local-lan - local-tun - local-dmz - dmz-lan - dmz-tun - dmz-local - -Notice, none go to WAN since WAN wouldn't have a v6 address on it. - -You would have to add a couple of rules on your wan-local ruleset to -allow protocol 41 in. - -Something like: - -.. code-block:: none - - rule 400 { - action accept - destination { - address 172.16.10.1 - } - log enable - protocol 41 - source { - address ip.of.tunnel.broker - } - } - diff --git a/docs/cli.rst b/docs/cli.rst index b138b18b..34ab3df6 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -97,3 +97,736 @@ To enter configuration mode use the ``configure`` command: See the configuration section of this document for more information on configuration mode. + + +.. _configuration-overview: + +###################### +Configuration Overview +###################### + +VyOS makes use of a unified configuration file for the entire system's +configuration: ``/config/config.boot``. This allows easy template +creation, backup, and replication of system configuration. A system can +thus also be easily cloned by simply copying the required configuration +files. + +Terminology +=========== +live +A VyOS system has three major types of configurations: + +* **Active** or **running configuration** is the system configuration + that is loaded and currently active (used by VyOS). Any change in + the configuration will have to be committed to belong to the + active/running configuration. + +* **Working configuration** is the one that is currently being modified + in configuration mode. Changes made to the working configuration do + not go into effect until the changes are committed with the + :cfgcmd:`commit` command. At which time the working configuration will + become the active or running configuration. + +* **Saved configuration** is the one saved to a file using the + :cfgcmd:`save` command. It allows you to keep safe a configuration for + future uses. There can be multiple configuration files. The default or + "boot" configuration is saved and loaded from the file + ``/config/config.boot``. + +Seeing and navigating the configuration +======================================= + +.. opcmd:: show configuration + + View the current active configuration, also known as the running + configuration, from the operational mode. + + .. code-block:: none + + vyos@vyos:~$ show configuration + interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } + } + service { + ssh { + port 22 + } + } + system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } + } + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the +configuration. When the configuration is generated and the device is +configured, changes are added through a collection of :cfgcmd:`set` and +:cfgcmd:`delete` commands. + +.. opcmd:: show configuration commands + + Get a collection of all the set commands required which led to the + running configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration commands + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' + set interfaces loopback 'lo' + set service ssh port '22' + set system config-management commit-revisions '20' + set system console device ttyS0 speed '9600' + set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' + set system login user vyos level 'admin' + set system ntp server '0.pool.ntp.org' + set system ntp server '1.pool.ntp.org' + set system ntp server '2.pool.ntp.org' + set system syslog global facility all level 'notice' + set system syslog global facility protocols level 'debug' + +Both these ``show`` commands should be executed when in operational +mode, they do not work directly in configuration mode. There is a +special way on how to :ref:`run_opmode_from_config_mode`. + +.. hint:: Use the ``show configuration commands | strip-private`` + command when you want to hide private data. You may want to do so if + you want to share your configuration on the `forum`_. + +.. _`forum`: https://forum.vyos.io + + +The config mode +--------------- + +When entering the configuration mode you are navigating inside a tree +structure, to enter configuration mode enter the command +:opcmd:`configure` when in operational mode. + +.. code-block:: none + + vyos@vyos$ configure + [edit] + vyos@vyos# + + +.. note:: When going into configuration mode, prompt changes from + ``$`` to ``#``. + + +All commands executed here are relative to the configuration level you +have entered. You can do everything from the top level, but commands +will be quite lengthy when manually typing them. + +The current hierarchy level can be changed by the :cfgcmd:`edit` +command. + +.. code-block:: none + + [edit] + vyos@vyos# edit interfaces ethernet eth0 + + [edit interfaces ethernet eth0] + vyos@vyos# + +You are now in a sublevel relative to ``interfaces ethernet eth0``, all +commands executed from this point on are relative to this sublevel. Use +eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top +of the hierarchy. You can also use the :cfgcmd:`up` command to move only +one level up at a time. + +.. cfgcmd:: show + +The :cfgcmd:`show` command within configuration mode will show the +working configuration indicating line changes with ``+`` for additions, +``>`` for replacements and ``-`` for deletions. + +**Example:** + +.. code-block:: none + + vyos@vyos:~$ configure + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + description MY_OLD_DESCRIPTION + disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } + [edit] + vyos@vyos# set interfaces ethernet eth0 address dhcp + [edit] + vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION + [edit] + vyos@vyos# delete interfaces ethernet eth0 disable + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + + address dhcp + > description MY_NEW_DESCRIPTION + - disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } + +It is also possible to display all `set` commands within configuration +mode using :cfgcmd:`show | commands` + +.. code-block:: none + + vyos@vyos# show interfaces ethernet eth0 | commands + set address dhcp + set hw-id 00:53:ad:44:3b:03 + +These commands are also relative to the level you are inside and only +relevant configuration blocks will be displayed when entering a +sub-level. + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# show + address dhcp + hw-id 00:53:ad:44:3b:03 + +Exiting from the configuration mode is done via the :cfgcmd:`exit` +command from the top level, executing :cfgcmd:`exit` from within a +sub-level takes you back to the top level. + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# exit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + + +Editing the configuration +========================= + +The configuration can be edited by the use of :cfgcmd:`set` and +:cfgcmd:`delete` commands from within configuration mode. + +.. cfgcmd:: set + + Use this command to set the value of a parameter or to create a new + element. + +Configuration commands are flattened from the tree into 'one-liner' +commands shown in :opcmd:`show configuration commands` from operation +mode. Commands are relative to the level where they are executed and all +redundant information from the current level is removed from the command +entered. + +.. code-block:: none + + [edit] + vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 + + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# set address 203.0.113.6/24 + + +These two commands above are essentially the same, just executed from +different levels in the hierarchy. + +.. cfgcmd:: delete + + To delete a configuration entry use the :cfgcmd:`delete` command, + this also deletes all sub-levels under the current level you've + specified in the :cfgcmd:`delete` command. Deleting an entry will + also result in the element reverting back to its default value if one + exists. + + .. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# delete address 192.0.2.100/24 + +.. cfgcmd:: commit + + Any change you do on the configuration, will not take effect until + committed using the :cfgcmd:`commit` command in configuration mode. + + .. code-block:: none + + vyos@vyos# commit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ + +.. _save: + +.. cfgcmd:: save + + Use this command to preserve configuration changes upon reboot. By + default it is stored at */config/config.boot*. In the case you want + to store the configuration file somewhere else, you can add a local + path, an SCP address, an FTP address or a TFTP address. + + .. code-block:: none + + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + + .. code-block:: none + + vyos@vyos# save [tab] + Possible completions: + Save to system config file + Save to file on local machine + scp://:@:/ Save to file on remote machine + ftp://:@/ Save to file on remote machine + tftp:/// Save to file on remote machine + vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot + Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... + ######################################################################## 100.0% + Done + +.. cfgcmd:: exit [discard] + + Configuration mode can not be exited while uncommitted changes exist. + To exit configuration mode without applying changes, the + :cfgcmd:`exit discard` command must be used. + + All changes in the working config will thus be lost. + + .. code-block:: none + + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# exit discard + + +.. cfgcmd:: commit-confirm + + Use this command to temporarily commit your changes and set the + number of minutes available for validation. ``confirm`` must + be entered within those minutes, otherwise the system will reboot + into the previous configuration. The default value is 10 minutes. + + + What if you are doing something dangerous? Suppose you want to setup + a firewall, and you are not sure there are no mistakes that will lock + you out of your system. You can use confirmed commit. If you issue + the ``commit-confirm`` command, your changes will be commited, and if + you don't issue issue the ``confirm`` command in 10 minutes, your + system will reboot into previous config revision. + + .. code-block:: none + + vyos@router# set interfaces ethernet eth0 firewall local name FromWorld + vyos@router# commit-confirm + commit confirm will be automatically reboot in 10 minutes unless confirmed + Proceed? [confirm]y + [edit] + vyos@router# confirm + [edit] + + + .. note:: A reboot because you did not enter ``confirm`` will not + take you necessarily to the *saved configuration*, but to the + point before the unfortunate commit. + + +.. cfgcmd:: copy + + Copy a configuration element. + + You can copy and remove configuration subtrees. Suppose you set up a + firewall ruleset ``FromWorld`` with one rule that allows traffic from + specific subnet. Now you want to setup a similar rule, but for + different subnet. Change your edit level to + ``firewall name FromWorld`` and use ``copy rule 10 to rule 20``, then + modify rule 20. + + + .. code-block:: none + + vyos@router# show firewall name FromWorld + default-action drop + rule 10 { + action accept + source { + address 203.0.113.0/24 + } + } + [edit] + vyos@router# edit firewall name FromWorld + [edit firewall name FromWorld] + vyos@router# copy rule 10 to rule 20 + [edit firewall name FromWorld] + vyos@router# set rule 20 source address 198.51.100.0/24 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + +.. cfgcmd:: rename + + Rename a configuration element. + + You can also rename config subtrees: + + .. code-block:: none + + vyos@router# rename rule 10 to rule 5 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + Note that ``show`` command respects your edit level and from this + level you can view the modified firewall ruleset with just ``show`` + with no parameters. + + .. code-block:: none + + vyos@router# show + default-action drop + rule 5 { + action accept + source { + address 203.0.113.0/24 + } + } + rule 20 { + action accept + source { + address 198.51.100.0/24 + } + } + + +.. cfgcmd:: comment "comment text" + + Add comment as an annotation to a configuration node. + + The ``comment`` command allows you to insert a comment above the + ```` configuration section. When shown, comments are + enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments + need to be commited, just like other config changes. + + To remove an existing comment from your current configuration, + specify an empty string enclosed in double quote marks (``""``) as + the comment text. + + Example: + + .. code-block:: none + + vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" + vyos@vyos# commit + vyos@vyos# show + firewall { + /* Yes I know this VyOS is cool */ + all-ping enable + broadcast-ping disable + ... + } + + .. note:: An important thing to note is that since the comment is + added on top of the section, it will not appear if the ``show +
`` command is used. With the above example, the `show + firewall` command would return starting after the ``firewall + {`` line, hiding the comment. + + + + + + +.. _run_opmode_from_config_mode: + +Access opmode from config mode +============================== + +When inside configuration mode you are not directly able to execute +operational commands. + +.. cfgcmd:: run + + Access to these commands are possible through the use of the + ``run [command]`` command. From this command you will have access to + everything accessible from operational mode. + + Command completion and syntax help with ``?`` and ``[tab]`` will also + work. + + .. code-block:: none + + [edit] + vyos@vyos# run show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 0.0.0.0/0 u/u + +Managing configurations +======================= + +VyOS comes with an integrated versioning system for the system +configuration. It automatically maintains a backup of every previous +configuration which has been committed to the system. The configurations +are versioned locally for rollback but they can also be stored on a +remote host for archiving/backup reasons. + +Local Archive +------------- + +Revisions are stored on disk. You can view, compare and rollback them to +any previous revisions if something goes wrong. + +.. opcmd:: show system commit + + View all existing revisions on the local system. + + .. code-block:: none + + vyos@vyos:~$ show system commit + 0 2015-03-30 08:53:03 by vyos via cli + 1 2015-03-30 08:52:20 by vyos via cli + 2 2015-03-26 21:26:01 by root via boot-config-loader + 3 2015-03-26 20:43:18 by root via boot-config-loader + 4 2015-03-25 11:06:14 by root via boot-config-loader + 5 2015-03-25 01:04:28 by root via boot-config-loader + 6 2015-03-25 00:16:47 by vyos via cli + 7 2015-03-24 23:43:45 by root via boot-config-loader + + +.. cfgcmd:: set system config-management commit-revisions + + You can specify the number of revisions stored on disk. N can be in + the range of 0 - 65535. When the number of revisions exceeds the + configured value, the oldest revision is removed. The default setting + for this value is to store 100 revisions locally. + + +Compare configurations +---------------------- + +VyOS lets you compare different configurations. + +.. cfgcmd:: compare + + Use this command to spot what the differences are between different + configurations. + + .. code-block:: none + + vyos@vyos# compare [tab] + Possible completions: + Compare working & active configurations + saved Compare working & saved configurations + Compare working with revision N + Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init + + The command :cfgcmd:`compare` allows you to compare different type of + configurations. It also lets you compare different revisions through + the :cfgcmd:`compare N M` command, where N and M are revision + numbers. The output will describe how the configuration N is when + compared to M indicating with a plus sign (``+``) the additional + parts N has when compared to M, and indicating with a minus sign + (``-``) the lacking parts N misses when compared to M. + + .. code-block:: none + + vyos@vyos# compare 0 6 + [edit interfaces] + +dummy dum1 { + + address 10.189.0.1/31 + +} + [edit interfaces ethernet eth0] + +vif 99 { + + address 10.199.0.1/31 + +} + -vif 900 { + - address 192.0.2.4/24 + -} + + +.. opcmd:: show system commit diff + + Show commit revision difference. + + +The command above also lets you see the difference between two commits. +By default the difference with the running config is shown. + +.. code-block:: none + + vyos@router# run show system commit diff 4 + [edit system] + +ipv6 { + + disable-forwarding + +} + +This means four commits ago we did ``set system ipv6 disable-forwarding``. + + +Rollback Changes +---------------- + +You can rollback configuration changes using the rollback command. This +will apply the selected revision and trigger a system reboot. + +.. cfgcmd:: rollback + + Rollback to revision N (currently requires reboot) + + .. code-block:: none + + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] + + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): + The system is going down for reboot NOW! + +Remote Archive +-------------- + +VyOS can upload the configuration to a remote location after each call +to :cfgcmd:`commit`. You will have to set the commit-archive location. +TFTP, FTP, SCP and SFTP servers are supported. Every time a +:cfgcmd:`commit` is successfull the ``config.boot`` file will be copied +to the defined destination(s). The filename used on the remote host will +be ``config.boot-hostname.YYYYMMDD_HHMMSS``. + +.. cfgcmd:: set system config-management commit-archive location + + Specify remote location of commit archive as any of the below + :abbr:`URI (Uniform Resource Identifier)` + + * ``scp://:@:/`` + * ``sftp://:@/`` + * ``ftp://:@/`` + * ``tftp:///`` + +.. note:: The number of revisions don't affect the commit-archive. + +.. note:: You may find VyOS not allowing the secure connection because + it cannot verify the legitimacy of the remote server. You can use + the workaround below to quickly add the remote host's SSH + fingerprint to your ``~/.ssh/known_hosts`` file: + + .. code-block:: none + + vyos@vyos# ssh-keyscan >> ~/.ssh/known_hosts + +Saving and loading manually +--------------------------- + +You can use the ``save`` and ``load`` commands if you want to manually +manage specific configuration files. + +When using the save_ command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the ``load`` command: + +.. cfgcmd:: load + + Use this command to load a configuration which will replace the + running configuration. Define the location of the configuration file + to be loaded. You can use a path to a local file, an SCP address, an + SFTP address, an FTP address, an HTTP address, an HTTPS address or a + TFTP address. + + .. code-block:: none + + vyos@vyos# load + Possible completions: + Load from system config file + Load from file on local machine + scp://:@:/ Load from file on remote machine + sftp://:@/ Load from file on remote machine + ftp://:@/ Load from file on remote machine + http:/// Load from file on remote machine + https:/// Load from file on remote machine + tftp:/// Load from file on remote machine + + + +Restore Default +--------------- + +In the case you want to completely delete your configuration and restore +the default one, you can enter the following command in configuration +mode: + +.. code-block:: none + + load /opt/vyatta/etc/config.boot.default + +You will be asked if you want to continue. If you accept, you will have +to use :cfgcmd:`commit` if you want to make the changes active. + +Then you may want to :cfgcmd:`save` in order to delete the saved +configuration too. + +.. note:: If you are remotely connected, you will lose your connection. + You may want to copy first the config, edit it to ensure + connectivity, and load the edited config. + diff --git a/docs/command-list-configuration.rst b/docs/command-list-configuration.rst deleted file mode 100644 index 7b981518..00000000 --- a/docs/command-list-configuration.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _configuration_level_commands: - -******************************** -Configuration Level Command List -******************************** - -.. cfgcmdlist:: diff --git a/docs/command-list-operation.rst b/docs/command-list-operation.rst deleted file mode 100644 index bbb0298c..00000000 --- a/docs/command-list-operation.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _operational_level_commands: - -****************************** -Operational Level Command List -****************************** - -.. opcmdlist:: diff --git a/docs/common-references.rst b/docs/common-references.rst deleted file mode 100644 index 79881972..00000000 --- a/docs/common-references.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _`accel-ppp`: https://accel-ppp.org/ -.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol -.. _Phabricator: https://phabricator.vyos.net/ - -.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad -.. _802.1q: https://en.wikipedia.org/wiki/IEEE_802.1Q diff --git a/docs/configexamples/azure-vpn-bgp.rst b/docs/configexamples/azure-vpn-bgp.rst new file mode 100644 index 00000000..176e0ae0 --- /dev/null +++ b/docs/configexamples/azure-vpn-bgp.rst @@ -0,0 +1,130 @@ +.. _examples-azure-vpn-bgp: + +Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) +------------------------------------------------------------ + +This guide shows an example of a route-based IKEv2 site-to-site VPN to +Azure using VTI and BGP for dynamic routing updates. + +For redundant / active-active configurations see `Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) `_ + +Prerequisites +^^^^^^^^^^^^^ + +- A pair of Azure VNet Gateways deployed in active-passive + configuration with BGP enabled. + +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 + +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +Example +^^^^^^^ + ++---------------------------------------+---------------------+ +| WAN Interface | eth0 | ++---------------------------------------+---------------------+ +| On-premises address space | 10.10.0.0/16 | ++---------------------------------------+---------------------+ +| Azure address space | 10.0.0.0/16 | ++---------------------------------------+---------------------+ +| Vyos public IP | 198.51.100.3 | ++---------------------------------------+---------------------+ +| Vyos private IP | 10.10.0.5 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway public IP | 203.0.113.2 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway BGP IP | 10.0.0.4 | ++---------------------------------------+---------------------+ +| Pre-shared key | ch00s3-4-s3cur3-psk | ++---------------------------------------+---------------------+ +| Vyos ASN | 64499 | ++---------------------------------------+---------------------+ +| Azure ASN | 65540 | ++---------------------------------------+---------------------+ + +Vyos configuration +^^^^^^^^^^^^^^^^^^ + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +.. code-block:: none + + set vpn ipsec esp-group AZURE compression 'disable' + set vpn ipsec esp-group AZURE lifetime '3600' + set vpn ipsec esp-group AZURE mode 'tunnel' + set vpn ipsec esp-group AZURE pfs 'dh-group2' + set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + + set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' + set vpn ipsec ike-group AZURE dead-peer-detection interval '15' + set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' + set vpn ipsec ike-group AZURE ikev2-reauth 'yes' + set vpn ipsec ike-group AZURE key-exchange 'ikev2' + set vpn ipsec ike-group AZURE lifetime '28800' + set vpn ipsec ike-group AZURE proposal 1 dh-group '2' + set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' + +- Enable IPsec on eth0 + +.. code-block:: none + + set vpn ipsec ipsec-interfaces interface 'eth0' + +- Configure a VTI with a dummy IP address + +.. code-block:: none + + set interfaces vti vti1 address '10.10.1.5/32' + set interfaces vti vti1 description 'Azure Tunnel' + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +.. code-block:: none + + set firewall options interface vti1 adjust-mss 1350 + +- Configure the VPN tunnel + +.. code-block:: none + + set vpn ipsec site-to-site peer 203.0.113.2 authentication id '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' + set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' + set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' + set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' + set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' + set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' + set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' + +- **Important**: Add an interface route to reach Azure's BGP listener + +.. code-block:: none + + set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 + +- Configure your BGP settings + +.. code-block:: none + + set protocols bgp 64499 neighbor 10.0.0.4 remote-as '65540' + set protocols bgp 64499 neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' + set protocols bgp 64499 neighbor 10.0.0.4 timers holdtime '30' + set protocols bgp 64499 neighbor 10.0.0.4 timers keepalive '10' + +- **Important**: Disable connected check \ + +.. code-block:: none + + set protocols bgp 64499 neighbor 10.0.0.4 disable-connected-check diff --git a/docs/configexamples/azure-vpn-dual-bgp.rst b/docs/configexamples/azure-vpn-dual-bgp.rst new file mode 100644 index 00000000..13d4b5a2 --- /dev/null +++ b/docs/configexamples/azure-vpn-dual-bgp.rst @@ -0,0 +1,155 @@ +.. _examples-azure-vpn-dual-bgp: + +Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) +---------------------------------------------------------------------- + +This guide shows an example of a redundant (active-active) route-based IKEv2 +site-to-site VPN to Azure using VTI +and BGP for dynamic routing updates. + +Prerequisites +^^^^^^^^^^^^^ + +- A pair of Azure VNet Gateways deployed in active-active + configuration with BGP enabled. + +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 + +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +Example +^^^^^^^ + ++---------------------------------------+---------------------+ +| WAN Interface | eth0 | ++---------------------------------------+---------------------+ +| On-premises address space | 10.10.0.0/16 | ++---------------------------------------+---------------------+ +| Azure address space | 10.0.0.0/16 | ++---------------------------------------+---------------------+ +| Vyos public IP | 198.51.100.3 | ++---------------------------------------+---------------------+ +| Vyos private IP | 10.10.0.5 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway 1 public IP | 203.0.113.2 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway 2 public IP | 203.0.113.3 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway BGP IP | 10.0.0.4,10.0.0.5 | ++---------------------------------------+---------------------+ +| Pre-shared key | ch00s3-4-s3cur3-psk | ++---------------------------------------+---------------------+ +| Vyos ASN | 64499 | ++---------------------------------------+---------------------+ +| Azure ASN | 65540 | ++---------------------------------------+---------------------+ + +Vyos configuration +^^^^^^^^^^^^^^^^^^ + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +.. code-block:: none + + set vpn ipsec esp-group AZURE compression 'disable' + set vpn ipsec esp-group AZURE lifetime '3600' + set vpn ipsec esp-group AZURE mode 'tunnel' + set vpn ipsec esp-group AZURE pfs 'dh-group2' + set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + + set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' + set vpn ipsec ike-group AZURE dead-peer-detection interval '15' + set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' + set vpn ipsec ike-group AZURE ikev2-reauth 'yes' + set vpn ipsec ike-group AZURE key-exchange 'ikev2' + set vpn ipsec ike-group AZURE lifetime '28800' + set vpn ipsec ike-group AZURE proposal 1 dh-group '2' + set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' + +- Enable IPsec on eth0 + +.. code-block:: none + + set vpn ipsec ipsec-interfaces interface 'eth0' + +- Configure two VTIs with a dummy IP address each + +.. code-block:: none + + set interfaces vti vti1 address '10.10.1.5/32' + set interfaces vti vti1 description 'Azure Primary Tunnel' + + set interfaces vti vti2 address '10.10.1.6/32' + set interfaces vti vti2 description 'Azure Secondary Tunnel' + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +.. code-block:: none + + set firewall options interface vti1 adjust-mss 1350 + set firewall options interface vti2 adjust-mss 1350 + +- Configure the VPN tunnels + +.. code-block:: none + + set vpn ipsec site-to-site peer 203.0.113.2 authentication id '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' + set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' + set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' + set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' + set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' + set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' + set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' + + set vpn ipsec site-to-site peer 203.0.113.3 authentication id '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.3 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.3 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' + set vpn ipsec site-to-site peer 203.0.113.3 authentication remote-id '203.0.113.3' + set vpn ipsec site-to-site peer 203.0.113.3 connection-type 'respond' + set vpn ipsec site-to-site peer 203.0.113.3 description 'AZURE SECONDARY TUNNEL' + set vpn ipsec site-to-site peer 203.0.113.3 ike-group 'AZURE' + set vpn ipsec site-to-site peer 203.0.113.3 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 203.0.113.3 local-address '10.10.0.5' + set vpn ipsec site-to-site peer 203.0.113.3 vti bind 'vti2' + set vpn ipsec site-to-site peer 203.0.113.3 vti esp-group 'AZURE' + +- **Important**: Add an interface route to reach both Azure's BGP listeners + +.. code-block:: none + + set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 + set protocols static interface-route 10.0.0.5/32 next-hop-interface vti2 + +- Configure your BGP settings + +.. code-block:: none + + set protocols bgp 64499 neighbor 10.0.0.4 remote-as '65540' + set protocols bgp 64499 neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' + set protocols bgp 64499 neighbor 10.0.0.4 timers holdtime '30' + set protocols bgp 64499 neighbor 10.0.0.4 timers keepalive '10' + + set protocols bgp 64499 neighbor 10.0.0.5 remote-as '65540' + set protocols bgp 64499 neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' + set protocols bgp 64499 neighbor 10.0.0.5 timers holdtime '30' + set protocols bgp 64499 neighbor 10.0.0.5 timers keepalive '10' + +- **Important**: Disable connected check, otherwise the routes learned + from Azure will not be imported into the routing table. + +.. code-block:: none + + set protocols bgp 64499 neighbor 10.0.0.4 disable-connected-check + set protocols bgp 64499 neighbor 10.0.0.5 disable-connected-check diff --git a/docs/configexamples/bgp-ipv6-unnumbered.rst b/docs/configexamples/bgp-ipv6-unnumbered.rst new file mode 100644 index 00000000..ccc1f69a --- /dev/null +++ b/docs/configexamples/bgp-ipv6-unnumbered.rst @@ -0,0 +1,172 @@ +.. _examples-bgp-ipv6-unnumbered: + +######################################### +BGP IPv6 unnumbered with extended nexthop +######################################### + +General information can be found in the :ref:`bgp` chapter. + +Configuration +============= + +- Router A: + +.. code-block:: none + + set protocols bgp 64496 address-family ipv4-unicast redistribute connected + set protocols bgp 64496 address-family ipv6-unicast redistribute connected + set protocols bgp 64496 neighbor eth1 interface v6only + set protocols bgp 64496 neighbor eth1 interface v6only peer-group 'fabric' + set protocols bgp 64496 neighbor eth2 interface v6only + set protocols bgp 64496 neighbor eth2 interface v6only peer-group 'fabric' + set protocols bgp 64496 parameters bestpath as-path multipath-relax + set protocols bgp 64496 parameters bestpath compare-routerid + set protocols bgp 64496 parameters default no-ipv4-unicast + set protocols bgp 64496 parameters router-id '192.168.0.1' + set protocols bgp 64496 peer-group fabric address-family ipv4-unicast + set protocols bgp 64496 peer-group fabric address-family ipv6-unicast + set protocols bgp 64496 peer-group fabric capability extended-nexthop + set protocols bgp 64496 peer-group fabric remote-as 'external' + +- Router B: + +.. code-block:: none + + set protocols bgp 64499 address-family ipv4-unicast redistribute connected + set protocols bgp 64499 address-family ipv6-unicast redistribute connected + set protocols bgp 64499 neighbor eth1 interface v6only + set protocols bgp 64499 neighbor eth1 interface v6only peer-group 'fabric' + set protocols bgp 64499 neighbor eth2 interface v6only + set protocols bgp 64499 neighbor eth2 interface v6only peer-group 'fabric' + set protocols bgp 64499 parameters bestpath as-path multipath-relax + set protocols bgp 64499 parameters bestpath compare-routerid + set protocols bgp 64499 parameters default no-ipv4-unicast + set protocols bgp 64499 parameters router-id '192.168.0.2' + set protocols bgp 64499 peer-group fabric address-family ipv4-unicast + set protocols bgp 64499 peer-group fabric address-family ipv6-unicast + set protocols bgp 64499 peer-group fabric capability extended-nexthop + set protocols bgp 64499 peer-group fabric remote-as 'external' + +Results +======= + +- Router A: + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 198.51.100.34/24 u/u + eth1 - u/u + eth2 - u/u + lo 127.0.0.1/8 u/u + 192.168.0.1/32 + ::1/128 + +.. code-block:: none + + vyos@vyos:~$ show ip route + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route + + S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 + C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 + C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 + B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 + * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 + +.. code-block:: none + + vyos@vyos:~$ ping 192.168.0.2 + PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. + 64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms + 64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms + 64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms + 64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms + 64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms + + --- 192.168.0.2 ping statistics --- + 5 packets transmitted, 5 received, 0% packet loss, time 4086ms + rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms + +.. code-block:: none + + vyos@vyos:~$ show ip bgp summary + + IPv4 Unicast Summary: + BGP router identifier 192.168.0.1, local AS number 65020 vrf-id 0 + BGP table version 4 + RIB entries 5, using 800 bytes of memory + Peers 2, using 41 KiB of memory + Peer groups 1, using 64 bytes of memory + + Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd + eth1 4 64499 13 13 0 0 0 00:05:33 2 + eth2 4 64499 13 14 0 0 0 00:05:29 2 + + Total number of neighbors 2 + +- Router B: + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 198.51.100.33/24 u/u + eth1 - u/u + eth2 - u/u + lo 127.0.0.1/8 u/u + 192.168.0.2/32 + ::1/128 + +.. code-block:: none + + vyos@vyos:~$ show ip route + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route + + S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 + C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 + B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 + * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 + C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 + +.. code-block:: none + + vyos@vyos:~$ ping 192.168.0.1 + PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. + 64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms + 64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms + 64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms + 64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms + + --- 192.168.0.1 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3051ms + rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms + +.. code-block:: none + + vyos@vyos:~$ show ip bgp summary + IPv4 Unicast Summary: + BGP router identifier 192.168.0.2, local AS number 65021 vrf-id 0 + BGP table version 4 + RIB entries 5, using 800 bytes of memory + Peers 2, using 41 KiB of memory + Peer groups 1, using 64 bytes of memory + + Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd + eth1 4 64496 14 14 0 0 0 00:06:40 2 + eth2 4 64496 14 14 0 0 0 00:06:37 2 + + Total number of neighbors 2 + diff --git a/docs/configexamples/dhcp-relay-through-gre-bridge.rst b/docs/configexamples/dhcp-relay-through-gre-bridge.rst new file mode 100644 index 00000000..f94eb67f --- /dev/null +++ b/docs/configexamples/dhcp-relay-through-gre-bridge.rst @@ -0,0 +1,77 @@ +.. _examples-dhcp-relay-through-gre-bridge: + + +DHCP Relay through GRE-Bridge +----------------------------- + +Diagram +^^^^^^^ + +.. image:: /_static/images/dhcp-relay-through-gre-bridge.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +Configuration +^^^^^^^^^^^^^ + +DHCP Server +""""""""""" + +.. code-block:: none + + set interfaces ethernet eth0 address '10.0.2.1/24' + set interfaces loopback lo address '3.3.3.3/24' + set interfaces tunnel tun100 address '172.16.0.2/30' + set interfaces tunnel tun100 encapsulation 'gre-bridge' + set interfaces tunnel tun100 local-ip '10.0.2.1' + set interfaces tunnel tun100 remote-ip '192.168.0.1' + set protocols ospf area 0 network '3.3.3.0/24' + set protocols ospf area 0 network '10.0.2.0/24' + set protocols ospf parameters router-id '3.3.3.3' + set protocols static interface-route 10.0.1.2/32 next-hop-interface tun100 + set service dhcp-server shared-network-name asdf authoritative + set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 start '3.3.3.30' + set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 stop '3.3.3.40' + set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 default-router '10.0.1.2' + set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 start '10.0.1.200' + set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 stop '10.0.1.210' + set service dhcp-server shared-network-name asdf subnet 10.2.1.0/24 range 0 start '10.2.1.222' + set service dhcp-server shared-network-name asdf subnet 10.2.1.0/24 range 0 stop '10.2.1.233' + set service dhcp-server shared-network-name asdf subnet 172.16.0.0/30 range 0 start '172.16.0.1' + set service dhcp-server shared-network-name asdf subnet 172.16.0.0/30 range 0 stop '172.16.0.2' + + +In-Between Router +""""""""""""""""" + +.. code-block:: none + + set interfaces ethernet eth0 address '192.168.0.2/24' + set interfaces ethernet eth1 address '10.0.2.2/24' + set protocols ospf area 0 network '192.168.0.0/24' + set protocols ospf area 0 network '10.0.2.0/24' + set protocols ospf parameters router-id '192.168.0.2' + + +DHCP Relay +"""""""""" + +.. code-block:: none + + set interfaces ethernet eth0 address '10.0.1.2/24' + set interfaces ethernet eth1 address '192.168.0.1/24' + set interfaces loopback lo address '1.1.1.1' + set interfaces tunnel tun100 address '172.16.0.1/30' + set interfaces tunnel tun100 encapsulation 'gre-bridge' + set interfaces tunnel tun100 local-ip '192.168.0.1' + set interfaces tunnel tun100 remote-ip '10.0.2.1' + set protocols ospf area 0 network '10.0.1.0/24' + set protocols ospf area 0 network '192.168.0.0/24' + set protocols ospf area 0 network '1.1.1.0/24' + set protocols ospf parameters router-id '1.1.1.1' + set protocols static interface-route 3.3.3.3/32 next-hop-interface tun100 + set service dhcp-relay interface 'eth0' + set service dhcp-relay interface 'tun100' + set service dhcp-relay server '3.3.3.3' + diff --git a/docs/configexamples/ha.rst b/docs/configexamples/ha.rst new file mode 100644 index 00000000..702cb2b2 --- /dev/null +++ b/docs/configexamples/ha.rst @@ -0,0 +1,580 @@ +############################# +High Availability Walkthrough +############################# + +This document walks you through a complete HA setup of two VyOS machines. This +design is based on a VM as the primary router, and a physical machine as a +backup, using VRRP, BGP, OSPF and conntrack sharing. + +The aim of this document is to walk you through setting everything up so you +and up at a point where you can reboot any machine and not lose more than a few +seconds worth of connectivity. + +Design +====== + +This is based on a real life, in production design. One of the complex issues +is ensuring you have redundant data INTO your network. We do this with a pair +of Cisco Nexus switches, and using Virtual PortChannels that are spanned across +them. This as an added bonus, also allows for complete switch failure without +an outage. How you achieve this yourself is left as an exercise to the reader +but our setup is documented here. + +Walkthrough suggestion +---------------------- + +The ``commit`` command is implied after every section. If you make an error, +``commit`` will warn you and you can fix it before getting too far into things. +Please ensure you commit early and commit often. + +If you are following through this document, it is strongly suggested you +complete the entire document, ONLY doing the virtual router1 steps, and then +come back and walk through it AGAIN on the backup hardware router. + +This ensures you don't go to fast, or miss a step. However, it will make your +life easier to configure the fixed IP address and default route now on the +hardware router. + +Example Network +--------------- + +In this document, we have been allocated 203.0.113.0/24 by our upstream +provider, which we are publishing on VLAN100. + +They want us to establish a BGP session to their routers on 192.0.2.11 and +192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and +we are AS65551. + +Our routers are going to have a floating IP address of 203.0.113.1, and use +.2 and .3 as their fixed IPs. + +We are going to use 10.200.201.0/24 for an 'internal' network on VLAN201. + +When traffic is originated from the 10.200.201.0/24 network, it will be +masqueraded to 203.0.113.1 + +For connection between sites, we are running a WireGuard link to two REMOTE +routers, and using OSPF over those links to distribute routes. That remote +site is expected to send traffic from anything in 10.201.0.0/16 + +VLANs +----- + +These are the vlans we wll be using: + +* 50: Upstream, using the 192.0.2.0/24 network allocated by them. +* 100: 'Public' network, using our 203.0.113.0/24 network. +* 201: 'Internal' network, using 10.200.201.0/24 + +Hardware +-------- + +* switch1 (Nexus 10gb Switch) +* switch2 (Nexus 10gb Switch) +* compute1 (VMware ESXi 6.5) +* compute2 (VMware ESXi 6.5) +* compute3 (VMware ESXi 6.5) +* router2 (Random 1RU machine with 4 NICs) + +Note that router1 is a VM that runs on one of the compute nodes. + +Network Cabling +--------------- + +* From Datacenter - This connects into port 1 on both switches, and is tagged + as VLAN 50 +* Cisco VPC Crossconnect - Ports 39 and 40 bonded between each switch +* Hardware Router - Port 8 of each switch +* compute1 - Port 9 of each switch +* compute2 - Port 10 of each switch +* compute3 - Port 11 of each switch + +This is ignoring the extra Out-of-band management networking, which should be +on totally different switches, and a different feed into the rack, and is out +of scope of this. + +.. note:: Our implementation uses VMware's Distributed Port Groups, which allows + VMware to use LACP. This is a part of the ENTERPRISE licence, and is not + available on a Free licence. If you are implementing this and do not have + access to DPGs, you should not use VMware, and use some other virtualization + platform instead. + + +Basic Setup (via console) +========================= + +Create your router1 VM so it is able to withstand a VM Host failing, or a +network link failing. Using VMware, this is achieved by enabling vSphere DRS, +vSphere Availability, and creating a Distributed Port Group that uses LACP. + +Many other Hypervisors do this, and I'm hoping that this document will be +expanded to document how to do this for others. + +Create an 'All VLANs' network group, that passes all trunked traffic through +to the VM. Attach this network group to router1 as eth0. + +.. note:: VMware: You must DISABLE SECURITY on this Port group. Make sure that + ``Promiscuous Mode``\ , ``MAC address changes`` and ``Forged transmits`` are + enabled. All of these will be done as part of failover. + +Bonding on Hardware Router +-------------------------- + +Create a LACP bond on the hardware router. We are assuming that eth0 and eth1 +are connected to port 8 on both switches, and that those ports are configured +as a Port-Channel. + +.. code-block:: none + + set interfaces bonding bond0 description 'Switch Port-Channel' + set interfaces bonding bond0 hash-policy 'layer2' + set interfaces bonding bond0 member interface 'eth0' + set interfaces bonding bond0 member interface 'eth1' + set interfaces bonding bond0 mode '802.3ad' + + +Assign external IP addresses +---------------------------- + +VLAN 100 and 201 will have floating IP addresses, but VLAN50 does not, as this +is talking directly to upstream. Create our IP address on vlan50. + +For the hardware router, replace ``eth0`` with ``bond0``. As (almost) every +command is identical, this will not be specified unless different things need +to be performed on different hosts. + +.. code-block:: none + + set interfaces ethernet eth0 vif 50 address '192.0.2.21/24' + +In this case, the hardware router has a different IP, so it would be + +.. code-block:: none + + set interfaces ethernet bond0 vif 50 address '192.0.2.22/24' + +Add (temporary) default route +----------------------------- + +It is assumed that the routers provided by upstream are capable of acting as a +default router, add that as a static route. + +.. code-block:: none + + set protocols static route 0.0.0.0/0 next-hop 192.0.2.11 + commit + save + + +Enable SSH +---------- + +Enable SSH so you can now SSH into the routers, rather than using the console. + +.. code-block:: none + + set service ssh + commit + save + +At this point you should be able to SSH into both of them, and will no longer +need access to the console (unless you break something!) + + +VRRP Configuration +================== + +We are setting up VRRP so that it does NOT fail back when a machine returns into +service, and it prioritizes router1 over router2. + +Internal Network +---------------- + +This has a floating IP address of 10.200.201.1/24, using virtual router ID 201. +The difference between them is the interface name, hello-source-address, and +peer-address. + +**router1** + +.. code-block:: none + + set interfaces ethernet eth0 vif 201 address 10.200.201.2/24 + set high-availability vrrp group int hello-source-address '10.200.201.2' + set high-availability vrrp group int interface 'eth0.201' + set high-availability vrrp group int peer-address '10.200.201.3' + set high-availability vrrp group int no-preempt + set high-availability vrrp group int priority '200' + set high-availability vrrp group int virtual-address '10.200.201.1/24' + set high-availability vrrp group int vrid '201' + + +**router2** + +.. code-block:: none + + set interfaces ethernet bond0 vif 201 address 10.200.201.3/24 + set high-availability vrrp group int hello-source-address '10.200.201.3' + set high-availability vrrp group int interface 'bond0.201' + set high-availability vrrp group int peer-address '10.200.201.2' + set high-availability vrrp group int no-preempt + set high-availability vrrp group int priority '100' + set high-availability vrrp group int virtual-address '10.200.201.1/24' + set high-availability vrrp group int vrid '201' + + +Public Network +-------------- + +This has a floating IP address of 203.0.113.1/24, using virtual router ID 113. +The virtual router ID is just a random number between 1 and 254, and can be set +to whatever you want. Best practices suggest you try to keep them unique +enterprise-wide. + +**router1** + +.. code-block:: none + + set interfaces ethernet eth0 vif 100 address 203.0.113.2/24 + set high-availability vrrp group public hello-source-address '203.0.113.2' + set high-availability vrrp group public interface 'eth0.100' + set high-availability vrrp group public peer-address '203.0.113.3' + set high-availability vrrp group public no-preempt + set high-availability vrrp group public priority '200' + set high-availability vrrp group public virtual-address '203.0.113.1/24' + set high-availability vrrp group public vrid '113' + +**router2** + +.. code-block:: none + + set interfaces ethernet bond0 vif 100 address 203.0.113.3/24 + set high-availability vrrp group public hello-source-address '203.0.113.3' + set high-availability vrrp group public interface 'bond0.100' + set high-availability vrrp group public peer-address '203.0.113.2' + set high-availability vrrp group public no-preempt + set high-availability vrrp group public priority '100' + set high-availability vrrp group public virtual-address '203.0.113.1/24' + set high-availability vrrp group public vrid '113' + + +Create VRRP sync-group +---------------------- + +The sync group is used to replicate connection tracking. It needs to be assigned +to a random VRRP group, and we are creating a sync group called ``sync`` using +the vrrp group ``int``. + +.. code-block:: none + + set high-availability vrrp sync-group sync member 'int' + +Testing +------- + +At this point, you should be able to see both IP addresses when you run +``show interfaces``\ , and ``show vrrp`` should show both interfaces in MASTER +state (and SLAVE state on router2). + +.. code-block:: none + + vyos@router1:~$ show vrrp + Name Interface VRID State Last Transition + -------- ----------- ------ ------- ----------------- + int eth0.201 201 MASTER 100s + public eth0.100 113 MASTER 200s + vyos@router1:~$ + + +You should be able to ping to and from all the IPs you have allocated. + +NAT and conntrack-sync +====================== + +Masquerade Traffic originating from 10.200.201.0/24 that is heading out the +public interface. + +.. note:: We explicitly exclude the primary upstream network so that BGP or + OSPF traffic doesn't accidentally get NAT'ed. + +.. code-block:: none + + set nat source rule 10 destination address '!192.0.2.0/24' + set nat source rule 10 outbound-interface 'eth0.50' + set nat source rule 10 source address '10.200.201.0/24' + set nat source rule 10 translation address '203.0.113.1' + + +Configure conntrack-sync and disable helpers +-------------------------------------------- + +Most conntrack modules cause more problems than they're worth, especially in a +complex network. Turn them off by default, and if you need to turn them on +later, you can do so. + +.. code-block:: none + + set system conntrack modules ftp disable + set system conntrack modules gre disable + set system conntrack modules nfs disable + set system conntrack modules pptp disable + set system conntrack modules sip disable + set system conntrack modules tftp disable + +Now enable replication between nodes. Replace eth0.201 with bond0.201 on the +hardware router. + +.. code-block:: none + + set service conntrack-sync accept-protocol 'tcp,udp,icmp' + set service conntrack-sync event-listen-queue-size '8' + set service conntrack-sync failover-mechanism vrrp sync-group 'sync' + set service conntrack-sync interface eth0.201 + set service conntrack-sync mcast-group '224.0.0.50' + set service conntrack-sync sync-queue-size '8' + +Testing +------- + +The simplest way to test is to look at the connection tracking stats on the +standby hardware router with the command ``show conntrack-sync statistics``. +The numbers should be very close to the numbers on the primary router. + +When you have both routers up, you should be able to establish a connection +from a NAT'ed machine out to the internet, reboot the active machine, and that +connection should be preserved, and will not drop out. + +OSPF Over WireGuard +=================== + +Wireguard doesn't have the concept of an up or down link, due to its design. +This complicates AND simplifies using it for network transport, as for reliable +state detection you need to use SOMETHING to detect when the link is down. + +If you use a routing protocol itself, you solve two problems at once. This is +only a basic example, and is provided as a starting point. + +Configure Wireguard +------------------- + +There is plenty of instructions and documentation on setting up Wireguard. The +only important thing you need to remember is to only use one WireGuard +interface per OSPF connection. + +We use small /30's from 10.254.60/24 for the point-to-point links. + +**router1** + +Replace the 203.0.113.3 with whatever the other router's IP address is. + +.. code-block:: none + + set interfaces wireguard wg01 address '10.254.60.1/30' + set interfaces wireguard wg01 description 'router1-to-offsite1' + set interfaces wireguard wg01 ip ospf authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' + set interfaces wireguard wg01 ip ospf cost '11' + set interfaces wireguard wg01 ip ospf dead-interval '5' + set interfaces wireguard wg01 ip ospf hello-interval '1' + set interfaces wireguard wg01 ip ospf network 'point-to-point' + set interfaces wireguard wg01 ip ospf priority '1' + set interfaces wireguard wg01 ip ospf retransmit-interval '5' + set interfaces wireguard wg01 ip ospf transmit-delay '1' + set interfaces wireguard wg01 peer OFFSITE1 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer OFFSITE1 endpoint '203.0.113.3:50001' + set interfaces wireguard wg01 peer OFFSITE1 persistent-keepalive '15' + set interfaces wireguard wg01 peer OFFSITE1 pubkey 'GEFMOWzAyau42/HwdwfXnrfHdIISQF8YHj35rOgSZ0o=' + set interfaces wireguard wg01 port '50001' + + +**offsite1** + +This is connecting back to the STATIC IP of router1, not the floating. + +.. code-block:: none + + set interfaces wireguard wg01 address '10.254.60.2/30' + set interfaces wireguard wg01 description 'offsite1-to-router1' + set interfaces wireguard wg01 ip ospf authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' + set interfaces wireguard wg01 ip ospf cost '11' + set interfaces wireguard wg01 ip ospf dead-interval '5' + set interfaces wireguard wg01 ip ospf hello-interval '1' + set interfaces wireguard wg01 ip ospf network 'point-to-point' + set interfaces wireguard wg01 ip ospf priority '1' + set interfaces wireguard wg01 ip ospf retransmit-interval '5' + set interfaces wireguard wg01 ip ospf transmit-delay '1' + set interfaces wireguard wg01 peer ROUTER1 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ROUTER1 endpoint '192.0.2.21:50001' + set interfaces wireguard wg01 peer ROUTER1 persistent-keepalive '15' + set interfaces wireguard wg01 peer ROUTER1 pubkey 'CKwMV3ZaLntMule2Kd3G7UyVBR7zE8/qoZgLb82EE2Q=' + set interfaces wireguard wg01 port '50001' + +Test WireGuard +-------------- + +Make sure you can ping 10.254.60.1 and .2 from both routers. + +Create Export Filter +-------------------- + +We only want to export the networks we know we should be exporting. Always +whitelist your route filters, both importing and exporting. A good rule of +thumb is **'If you are not the default router for a network, don't advertise +it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 +network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE +the default route for). This filter is applied to ``redistribute connected``. +If we WERE to advertise it, the remote machines would see 192.0.2.21 available +via their default route, establish the connection, and then OSPF would say +'192.0.2.0/24 is available via this tunnel', at which point the tunnel would +break, OSPF would drop the routes, and then 192.0.2.0/24 would be reachable via +default again. This is called 'flapping'. + +.. code-block:: none + + set policy access-list 150 description 'Outbound OSPF Redistribution' + set policy access-list 150 rule 10 action 'permit' + set policy access-list 150 rule 10 destination any + set policy access-list 150 rule 10 source inverse-mask '0.0.0.255' + set policy access-list 150 rule 10 source network '10.200.201.0' + set policy access-list 150 rule 20 action 'permit' + set policy access-list 150 rule 20 destination any + set policy access-list 150 rule 20 source inverse-mask '0.0.0.255' + set policy access-list 150 rule 20 source network '203.0.113.0' + set policy access-list 150 rule 100 action 'deny' + set policy access-list 150 rule 100 destination any + set policy access-list 150 rule 100 source any + + +Create Import Filter +-------------------- + +We only want to import networks we know about. Our OSPF peer should only be +advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE +MATCH. You deny in access-list 100 to accept the route. + +.. code-block:: none + + set policy access-list 100 description 'Inbound OSPF Routes from Peers' + set policy access-list 100 rule 10 action 'deny' + set policy access-list 100 rule 10 destination any + set policy access-list 100 rule 10 source inverse-mask '0.0.255.255' + set policy access-list 100 rule 10 source network '10.201.0.0' + set policy access-list 100 rule 100 action 'permit' + set policy access-list 100 rule 100 destination any + set policy access-list 100 rule 100 source any + set policy route-map PUBOSPF rule 100 action 'deny' + set policy route-map PUBOSPF rule 100 match ip address access-list '100' + set policy route-map PUBOSPF rule 500 action 'permit' + + +Enable OSPF +----------- + +Every router **must** have a unique router-id. +The 'reference-bandwidth' is used because when OSPF was originally designed, +the idea of a link faster than 1gbit was unheard of, and it does not scale +correctly. + +.. code-block:: none + + set protocols ospf area 0.0.0.0 authentication 'md5' + set protocols ospf area 0.0.0.0 network '10.254.60.0/24' + set protocols ospf auto-cost reference-bandwidth '10000' + set protocols ospf log-adjacency-changes + set protocols ospf parameters abr-type 'cisco' + set protocols ospf parameters router-id '10.254.60.2' + set protocols ospf route-map PUBOSPF + + +Test OSPF +--------- + +When you have enabled OSPF on both routers, you should be able to see each +other with the command ``show ip ospf neighbour``. The state must be 'Full' +or '2-Way', if it is not then there is a network connectivity issue between the +hosts. This is often caused by NAT or MTU issues. You should not see any new +routes (unless this is the second pass) in the output of ``show ip route`` + +Advertise connected routes +========================== + +As a reminder, only advertise routes that you are the default router for. This +is why we are NOT announcing the 192.0.2.0/24 network, because if that was +announced into OSPF, the other routers would try to connect to that network +over a tunnel that connects to that network! + +.. code-block:: none + + set protocols ospf access-list 150 export 'connected' + set protocols ospf redistribute connected + + +You should now be able to see the advertised network on the other host. + +Duplicate configuration +----------------------- + +At this pont you now need to create the X link between all four routers. Use a +different /30 for each link. + +Priorities +---------- + +Set the cost on the secondary links to be 200. This means that they will not +be used unless the primary links are down. + +.. code-block:: none + + set interfaces wireguard wg01 ip ospf cost '10' + set interfaces wireguard wg02 ip ospf cost '200' + + +This will be visible in 'show ip route'. + +BGP +=== + +BGP is an extremely complex network protocol. An example is provided here. + +.. note:: Router id's must be unique. + +**router1** + + +The ``redistribute ospf`` command is there purely as an example of how this can +be expanded. In this walkthrough, it will be filtered by BGPOUT rule 10000, as +it is not 203.0.113.0/24. + +.. code-block:: none + + set policy prefix-list BGPOUT description 'BGP Export List' + set policy prefix-list BGPOUT rule 10 action 'deny' + set policy prefix-list BGPOUT rule 10 description 'Do not advertise short masks' + set policy prefix-list BGPOUT rule 10 ge '25' + set policy prefix-list BGPOUT rule 10 prefix '0.0.0.0/0' + set policy prefix-list BGPOUT rule 100 action 'permit' + set policy prefix-list BGPOUT rule 100 description 'Our network' + set policy prefix-list BGPOUT rule 100 prefix '203.0.113.0/24' + set policy prefix-list BGPOUT rule 10000 action 'deny' + set policy prefix-list BGPOUT rule 10000 prefix '0.0.0.0/0' + set policy route-map BGPOUT description 'BGP Export Filter' + set policy route-map BGPOUT rule 10 action 'permit' + set policy route-map BGPOUT rule 10 match ip address prefix-list 'BGPOUT' + set policy route-map BGPOUT rule 10000 action 'deny' + set policy route-map BGPPREPENDOUT description 'BGP Export Filter' + set policy route-map BGPPREPENDOUT rule 10 action 'permit' + set policy route-map BGPPREPENDOUT rule 10 set as-path-prepend '65551 65551 65551' + set policy route-map BGPPREPENDOUT rule 10 match ip address prefix-list 'BGPOUT' + set policy route-map BGPPREPENDOUT rule 10000 action 'deny' + set protocols bgp 65551 address-family ipv4-unicast network 192.0.2.0/24 + set protocols bgp 65551 address-family ipv4-unicast redistribute connected metric '50' + set protocols bgp 65551 address-family ipv4-unicast redistribute ospf metric '50' + set protocols bgp 65551 neighbor 192.0.2.11 address-family ipv4-unicast route-map export 'BGPOUT' + set protocols bgp 65551 neighbor 192.0.2.11 address-family ipv4-unicast soft-reconfiguration inbound + set protocols bgp 65551 neighbor 192.0.2.11 remote-as '65550' + set protocols bgp 65551 neighbor 192.0.2.11 update-source '192.0.2.21' + set protocols bgp 65551 parameters router-id '192.0.2.21' + + +**router2** + +This is identical, but you use the BGPPREPENDOUT route-map to advertise the +route with a longer path. diff --git a/docs/configexamples/index.rst b/docs/configexamples/index.rst new file mode 100644 index 00000000..b2f7bfde --- /dev/null +++ b/docs/configexamples/index.rst @@ -0,0 +1,19 @@ +.. _examples: + +Configuration Blueprints +======================== + +This chapter contains various configuration examples: + +.. toctree:: + :maxdepth: 2 + + dhcp-relay-through-gre-bridge + zone-policy + bgp-ipv6-unnumbered + ospf-unnumbered + azure-vpn-bgp + azure-vpn-dual-bgp + tunnelbroker-ipv6 + ha + wan-load-balancing diff --git a/docs/configexamples/ospf-unnumbered.rst b/docs/configexamples/ospf-unnumbered.rst new file mode 100644 index 00000000..39f8f69a --- /dev/null +++ b/docs/configexamples/ospf-unnumbered.rst @@ -0,0 +1,118 @@ +.. _examples-ospf-unnumbered: + +######################### +OSPF unnumbered with ECMP +######################### + +General infomration can be found in the :ref:`routing-ospf` chapter. + +Configuration +============= + +- Router A: + +.. code-block:: none + + set interfaces ethernet eth0 address '10.0.0.1/24' + set interfaces ethernet eth1 address '192.168.0.1/32' + set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' + set interfaces ethernet eth1 ip ospf network 'point-to-point' + set interfaces ethernet eth2 address '192.168.0.1/32' + set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' + set interfaces ethernet eth2 ip ospf network 'point-to-point' + set interfaces loopback lo address '192.168.0.1/32' + set protocols ospf area 0.0.0.0 authentication 'md5' + set protocols ospf area 0.0.0.0 network '192.168.0.1/32' + set protocols ospf parameters router-id '192.168.0.1' + set protocols ospf redistribute connected + +- Router B: + +.. code-block:: none + + set interfaces ethernet eth0 address '10.0.0.2/24' + set interfaces ethernet eth1 address '192.168.0.2/32' + set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' + set interfaces ethernet eth1 ip ospf network 'point-to-point' + set interfaces ethernet eth2 address '192.168.0.2/32' + set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' + set interfaces ethernet eth2 ip ospf network 'point-to-point' + set interfaces loopback lo address '192.168.0.2/32' + set protocols ospf area 0.0.0.0 authentication 'md5' + set protocols ospf area 0.0.0.0 network '192.168.0.2/32' + set protocols ospf parameters router-id '192.168.0.2' + set protocols ospf redistribute connected + + +Results +======= + +- Router A: + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 10.0.0.1/24 u/u + eth1 192.168.0.1/32 u/u + eth2 192.168.0.1/32 u/u + lo 127.0.0.1/8 u/u + 192.168.0.1/32 + ::1/128 + +.. code-block:: none + + vyos@vyos:~$ show ip route + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 + O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 + via 192.168.0.2, eth2 onlink, 00:13:21 + C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 + O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 + C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 + C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 + C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 + O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 + * via 192.168.0.2, eth2 onlink, 00:29:03 + +- Router B: + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 10.0.0.2/24 u/u + eth1 192.168.0.2/32 u/u + eth2 192.168.0.2/32 u/u + lo 127.0.0.1/8 u/u + 192.168.0.2/32 + ::1/128 + +.. code-block:: none + + vyos@vyos:~$ show ip route + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 + O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 + via 192.168.0.1, eth2 onlink, 00:13:21 + C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 + O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 + C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 + C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 + C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 + O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 + * via 192.168.0.1, eth2 onlink, 00:29:03 diff --git a/docs/configexamples/tunnelbroker-ipv6.rst b/docs/configexamples/tunnelbroker-ipv6.rst new file mode 100644 index 00000000..868b225f --- /dev/null +++ b/docs/configexamples/tunnelbroker-ipv6.rst @@ -0,0 +1,169 @@ +.. _examples-tunnelbroker-ipv6: + +####################### +Tunnelbroker.net (IPv6) +####################### + +This guides walks through the setup of https://www.tunnelbroker.net/ for an +IPv6 Tunnel. + +Prerequisites +============= + +- A public, routable IPv4 address. This does not necessarily need to be static, + but you will need to update the tunnel endpoint when/if your IP address + changes, which can be done with a script and a scheduled task. +- Account at https://www.tunnelbroker.net/ +- Requested a "Regular Tunnel". You want to choose a location that is closest + to your physical location for the best response time. + +Setup initial tunnel +==================== + +Set up initial IPv6 tunnel. Replace the field below from the fields on the +tunnel information page. + +.. code-block:: none + + conf + set interfaces tunnel tun0 address Client_IPv6_from_Tunnelbroker # This will be your VyOS install's public IPv6 address + set interfaces tunnel tun0 description 'HE.NET IPv6 Tunnel' + set interfaces tunnel tun0 encapsulation 'sit' + set interfaces tunnel tun0 local-ip Client_IPv4_from_Tunnelbroker # This is your public IP + set interfaces tunnel tun0 mtu '1472' + set interfaces tunnel tun0 multicast 'disable' + set interfaces tunnel tun0 remote-ip Server_IPv4_from_Tunnelbroker # This is the IP of the Tunnelbroker server + set protocols static interface-route6 ::/0 next-hop-interface tun0 # Tell all traffic to go over this tunnel + commit + +If your WAN connection is over PPPoE, you may need to set the MTU on the above +tunnel lower than 1472. + +At this point you should be able to ping an IPv6 address, try pinging Google: + +.. code-block:: none + + ping6 -c2 2001:4860:4860::8888 + + 64 bytes from 2001:4860:4860::8888: icmp_seq=1 ttl=57 time=21.7 ms + 64 bytes from 2001:4860:4860::8888: icmp_seq=2 ttl=57 time=21.1 ms + + --- 2001:4860:4860::8888 ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 1001ms + rtt min/avg/max/mdev = 21.193/21.459/21.726/0.304 ms + +Assuming the pings are successful, you need to add some DNS servers. +Some options: + +.. code-block:: none + + set system name-server 2001:4860:4860::8888 # Google + set system name-server 2001:4860:4860::8844 # Google + set system name-server 2606:4700:4700::1111 # Cloudflare + set system name-server 2606:4700:4700::1001 # Cloudflare + commit + +You should now be able to ping something by IPv6 DNS name: + +.. code-block:: none + + # ping6 -c2 one.one.one.one + PING one.one.one.one(one.one.one.one) 56 data bytes + 64 bytes from one.one.one.one: icmp_seq=1 ttl=58 time=16.8 ms + 64 bytes from one.one.one.one: icmp_seq=2 ttl=58 time=17.4 ms + + --- one.one.one.one ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 1001ms + rtt min/avg/max/mdev = 16.880/17.153/17.426/0.273 ms + +Assuming everything works, you can proceed to client configuration + +LAN Configuration +================= + +At this point your VyOS install should have full IPv6, but now your LAN devices +need access. + +With Tunnelbroker.net, you have two options: + +- Routed /64. This is the default assignment. In IPv6-land, it's good for a + single "LAN", and is somewhat equivalent to a /24. + Example: `2001:470:xxxx:xxxx::/64` +- Routed /48. This is something you can request by clicking the "Assign /48" + link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k + LANs. Example: `2001:470:xxxx::/48` + +Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So +if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore +the assigned /64, and request the /48 and use that. + +Single LAN Setup +================ + +Single LAN setup where eth1 is your LAN interface. Use the /64 (all the xxxx +should be replaced with the information from your `Routed /64` tunnel): + +.. code-block:: none + + set interfaces ethernet eth1 address '2001:470:xxxx:xxxx::1/64' + set service router-advert interface eth1 name-server '2001:4860:4860::8888' + set service router-advert interface eth1 name-server '2001:4860:4860::8844' + set service router-advert interface eth1 prefix 2001:470:xxxx:xxxx::/64 + +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, 'valid-lifetime' and 'preferred-lifetime' are set to default values of 30 days and 4 hours respectively. + +This accomplishes a few things: + +- Sets your LAN interface's IP address +- Enables router advertisements. This is an IPv6 alternative for DHCP (though + DHCPv6 can still be used). With RAs, Your devices will automatically find the + information they need for routing and DNS. + +Multiple LAN/DMZ Setup +====================== + +In this, you use the `Routed /48` information. This allows you to assign a +different /64 to every interface, LAN, or even device. Or you could break your +network into smaller chunks like /56 or /60. + +The format of these addresses: + +- `2001:470:xxxx::/48`: The whole subnet. xxxx should come from Tunnelbroker. +- `2001:470:xxxx:1::/64`: A subnet suitable for a LAN +- `2001:470:xxxx:2::/64`: Another subnet +- `2001:470:xxxx:ffff:/64`: The last usable /64 subnet. + +In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff +(1-65535). + +So, when your LAN is eth1, your DMZ is eth2, your cameras live on eth3, etc: + +.. code-block:: none + + set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' + set service router-advert interface eth1 name-server '2001:4860:4860::8888' + set service router-advert interface eth1 name-server '2001:4860:4860::8844' + set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64 + + set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' + set service router-advert interface eth2 name-server '2001:4860:4860::8888' + set service router-advert interface eth2 name-server '2001:4860:4860::8844' + set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64 + + set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' + set service router-advert interface eth3 name-server '2001:4860:4860::8888' + set service router-advert interface eth3 name-server '2001:4860:4860::8844' + set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 + +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, 'valid-lifetime' and 'preferred-lifetime' are set to default values of 30 days and 4 hours respectively. + +Firewall +======== + +Finally, don't forget the :ref:`firewall`. The usage is identical, except for +instead of `set firewall name NAME`, you would use `set firewall ipv6-name +NAME`. + +Similarly, to attach the firewall, you would use `set interfaces ethernet eth0 +firewall in ipv6-name` or `set zone-policy zone LOCAL from WAN firewall +ipv6-name`. diff --git a/docs/configexamples/wan-load-balancing.rst b/docs/configexamples/wan-load-balancing.rst new file mode 100644 index 00000000..7093defe --- /dev/null +++ b/docs/configexamples/wan-load-balancing.rst @@ -0,0 +1,170 @@ +.. _wan-load-balancing: + +WAN Load Balancer examples +========================== + + +Example 1: Distributing load evenly +----------------------------------- + +The setup used in this example is shown in the following diagram: + +.. image:: /_static/images/Wan_load_balancing1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + + +Overview +^^^^^^^^ + * All traffic coming in trough eth2 is balanced between eth0 and eth1 + on the router. + * Pings will be sent to four targets for health testing (33.44.55.66, + 44.55.66.77, 55.66.77.88 and 66.77.88.99). + * All outgoing packets are assigned the source address of the assigned + interface (SNAT). + * eth0 is set to be removed from the load balancer's interface pool + after 5 ping failures, eth1 will be removed after 4 ping failures. + +Create static routes to ping targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create static routes through the two ISPs towards the ping targets and +commit the changes: + +.. code-block:: none + + set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 + set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 + set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 + set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 + +Configure the load balancer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure the WAN load balancer with the parameters described above: + +.. code-block:: none + + set load-balancing wan interface-health eth0 failure-count 5 + set load-balancing wan interface-health eth0 nexthop 11.22.33.1 + set load-balancing wan interface-health eth0 test 10 type ping + set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 + set load-balancing wan interface-health eth0 test 20 type ping + set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 + set load-balancing wan interface-health eth1 failure-count 4 + set load-balancing wan interface-health eth1 nexthop 22.33.44.1 + set load-balancing wan interface-health eth1 test 10 type ping + set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 + set load-balancing wan interface-health eth1 test 20 type ping + set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 10 interface eth1 + +Example 2: Failover based on interface weights +---------------------------------------------- + +This examples uses the failover mode. + +Overview +^^^^^^^^ +In this example eth0 is the primary interface and eth1 is the secondary +interface to provide simple failover functionality. If eth0 fails, eth1 +takes over. + +Create interface weight based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The configuration steps are the same as in the previous example, except +rule 10 so we keep the configuration, remove rule 10 and add a new rule +for the failover mode: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 failover + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 weight 10 + set load-balancing wan rule 10 interface eth1 weight 1 + +Example 3: Failover based on rule order +--------------------------------------- + +The previous example used the failover command to send traffic thorugh +eth1 if eth0 fails. In this example failover functionality is provided +by rule order. + +Overview +^^^^^^^^ +Two rules will be created, the first rule directs traffic coming in +from eth2 to eth0 and the second rule directs the traffic to eth1. If +eth0 fails the first rule is bypassed and the second rule matches, +directing traffic to eth1. + +Create rule order based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configurtation from the previous example, delete rule 10 +and create the two new rules as described: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + +Example 4: Failover based on rule order - priority traffic +---------------------------------------------------------- + +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Overview +^^^^^^^^ +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Create rule order based configuration with low speed secondary link +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configuration from the previous example, delete rule 20 and +create a new rule as described: + +.. code-block:: none + + delete load-balancing wan rule 20 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + set load-balancing wan rule 20 destination port sip + set load-balancing wan rule 20 protocol tcp + set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 + +Example 5: Exclude traffic from load balancing +---------------------------------------------- + +In this example two LAN interfaces exist in different subnets instead +of one like in the previous examples: + +.. image:: /_static/images/Wan_load_balancing_exclude1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +Adding a rule for the second interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Based on the previous example, another rule for traffic from the second +interface eth3 can be added to the load balancer. However, traffic meant +to flow between the LAN subnets will be sent to eth0 and eth1 as well. +To prevent this, another rule is required. This rule excludes traffic +between the local subnets from the load balancer. It also excludes +locally-sources packets (required for web caching with load balancing). +eth+ is used as an alias that refers to all ethernet interfaces: + +.. code-block:: none + + set load-balancing wan rule 5 exclude + set load-balancing wan rule 5 inbound-interface eth+ + set load-balancing wan rule 5 destination address 10.0.0.0/8 diff --git a/docs/configexamples/zone-policy.rst b/docs/configexamples/zone-policy.rst new file mode 100644 index 00000000..bfe77c2e --- /dev/null +++ b/docs/configexamples/zone-policy.rst @@ -0,0 +1,415 @@ +.. _examples-zone-policy: + +Zone-Policy example +------------------- + +Native IPv4 and IPv6 +^^^^^^^^^^^^^^^^^^^^ + +We have three networks. + +.. code-block:: none + + WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 + LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 + DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 + + +**This specific example is for a router on a stick, but is very easily +adapted for however many NICs you have**: + + +* Internet - 192.168.200.100 - TCP/80 +* Internet - 192.168.200.100 - TCP/443 +* Internet - 192.168.200.100 - TCP/25 +* Internet - 192.168.200.100 - TCP/53 +* VyOS actis as DHCP, DNS forwarder, NAT, router and firewall. +* 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web + and mail (SMTP/IMAP) server. +* 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It + can SSH to VyOS. +* LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. +* LAN can access DMZ resources. +* DMZ cannot access LAN resources. +* Inbound WAN connect to DMZ host. + +.. image:: /_static/images/zone-policy-diagram.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +The VyOS interface is assigned the .1/:1 address of their respective +networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. + +It will look something like this: + +.. code-block:: none + + interfaces { + ethernet eth0 { + duplex auto + hw-id 00:53:ed:6e:2a:92 + smp_affinity auto + speed auto + vif 10 { + address 172.16.10.1/24 + address 2001:db8:0:9999::1/64 + } + vif 20 { + address 192.168.100.1/24 + address 2001:db8:0:AAAA::1/64 + } + vif 30 { + address 192.168.200.1/24 + address 2001:db8:0:BBBB::1/64 + } + } + loopback lo { + } + } + + +Zones Basics +^^^^^^^^^^^^ + +Each interface is assigned to a zone. The interface can be physical or +virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly +the same. + +Traffic flows from zone A to zone B. That flow is what I refer to as a +zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. + +Ruleset are created per zone-pair-direction. + +I name rule sets to indicate which zone-pair-direction they represent. +eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. + +In VyOS, you have to have unique Ruleset names. In the event of overlap, +I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This +allows for each auto-completion and uniqueness. + +In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is +the firewall itself. + +If your computer is on the LAN and you need to SSH into your VyOS box, +you would need a rule to allow it in the LAN-Local ruleset. If you want +to access a webpage from your VyOS box, you need a rule to allow it in +the Local-LAN ruleset. + +In rules, it is good to keep them named consistently. As the number of +rules you have grows, the more consistency you have, the easier your +life will be. + +.. code-block:: none + + Rule 1 - State Established, Related + Rule 2 - State Invalid + Rule 100 - ICMP + Rule 200 - Web + Rule 300 - FTP + Rule 400 - NTP + Rule 500 - SMTP + Rule 600 - DNS + Rule 700 - DHCP + Rule 800 - SSH + Rule 900 - IMAPS + +The first two rules are to deal with the idiosyncrasies of VyOS and +iptables. + +Zones and Rulesets both have a default action statement. When using +Zone-Policies, the default action is set by the zone-policy statement +and is represented by rule 10000. + +It is good practice to log both accepted and denied traffic. It can save +you significant headaches when trying to troubleshoot a connectivity +issue. + +To add logging to the default rule, do: + +.. code-block:: none + + set firewall name enable-default-log + + +By default, iptables does not allow traffic for established session to +return, so you must explicitly allow this. I do this by adding two rules +to every ruleset. 1 allows established and related state packets through +and rule 2 drops and logs invalid state packets. We place the +established/related rule at the top because the vast majority of traffic +on a network is established and the invalid rule to prevent invalid +state packets from mistakenly being matched against other rules. Having +the most matched rule listed first reduces CPU load in high volume +environments. Note: I have filed a bug to have this added as a default +action as well. + +''It is important to note, that you do not want to add logging to the +established state rule as you will be logging both the inbound and +outbound packets for each session instead of just the initiation of the +session. Your logs will be massive in a very short period of time.'' + +In VyOS you must have the interfaces created before you can apply it to +the zone and the rulesets must be created prior to applying it to a +zone-policy. + +I create/configure the interfaces first. Build out the rulesets for each +zone-pair-direction which includes at least the three state rules. Then +I setup the zone-policies. + +Zones do not allow for a default action of accept; either drop or +reject. It is important to remember this because if you apply an +interface to a zone and commit, any active connections will be dropped. +Specifically, if you are SSH’d into VyOS and add local or the interface +you are connecting through to a zone and do not have rulesets in place +to allow SSH and established sessions, you will not be able to connect. + +The following are the rules that were created for this example (may not +be complete), both in IPv4 and IPv6. If there is no IP specified, then +the source/destination address is not explicit. + +.. code-block:: none + + WAN – DMZ:192.168.200.200 – tcp/80 + WAN – DMZ:192.168.200.200 – tcp/443 + WAN – DMZ:192.168.200.200 – tcp/25 + WAN – DMZ:192.168.200.200 – tcp/53 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/80 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/443 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/25 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/53 + + DMZ - Local - tcp/53 + DMZ - Local - tcp/123 + DMZ - Local - tcp/67,68 + + LAN - Local - tcp/53 + LAN - Local - tcp/123 + LAN - Local - tcp/67,68 + LAN:192.168.100.10 - Local - tcp/22 + LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 + + LAN - WAN - tcp/80 + LAN - WAN - tcp/443 + LAN - WAN - tcp/22 + LAN - WAN - tcp/20,21 + + DMZ - WAN - tcp/80 + DMZ - WAN - tcp/443 + DMZ - WAN - tcp/22 + DMZ - WAN - tcp/20,21 + DMZ - WAN - tcp/53 + DMZ - WAN - udp/53 + + Local - WAN - tcp/80 + Local - WAN - tcp/443 + Local - WAN - tcp/20,21 + + Local - DMZ - tcp/25 + Local - DMZ - tcp/67,68 + Local - DMZ - tcp/53 + Local - DMZ - udp/53 + + Local - LAN - tcp/67,68 + + LAN - DMZ - tcp/80 + LAN - DMZ - tcp/443 + LAN - DMZ - tcp/993 + LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 + LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 + +Since we have 4 zones, we need to setup the following rulesets. + +.. code-block:: none + + Lan-wan + Lan-local + Lan-dmz + Wan-lan + Wan-local + Wan-dmz + Local-lan + Local-wan + Local-dmz + Dmz-lan + Dmz-wan + Dmz-local + +Even if the two zones will never communicate, it is a good idea to +create the zone-pair-direction rulesets and set enable-default-log. This +will allow you to log attempts to access the networks. Without it, you +will never see the connection attempts. + +This is an example of the three base rules. + +.. code-block:: none + + name wan-lan { + default-action drop + enable-default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + } + } + + +Here is an example of an IPv6 DMZ-WAN ruleset. + +.. code-block:: none + + ipv6-name dmz-wan-6 { + default-action drop + enable-default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + rule 100 { + action accept + log enable + protocol ipv6-icmp + } + rule 200 { + action accept + destination { + port 80,443 + } + log enable + protocol tcp + } + rule 300 { + action accept + destination { + port 20,21 + } + log enable + protocol tcp + } + rule 500 { + action accept + destination { + port 25 + } + log enable + protocol tcp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 600 { + action accept + destination { + port 53 + } + log enable + protocol tcp_udp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 800 { + action accept + destination { + port 22 + } + log enable + protocol tcp + } + } + +Once you have all of your rulesets built, then you need to create your +zone-policy. + +Start by setting the interface and default action for each zone. + +.. code-block:: none + + set zone-policy zone dmz default-action drop + set zone-policy zone dmz interface eth0.30 + +In this case, we are setting the v6 ruleset that represents traffic +sourced from the LAN, destined for the DMZ. Because the zone-policy +firewall syntax is a little awkward, I keep it straight by thinking of +it backwards. + +.. code-block:: none + + set zone-policy zone dmz from lan firewall ipv6-name lan-dmz-6 + +DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out +a bunch at one time. + +In the end, you will end up with something like this config. I took out +everything but the Firewall, Interfaces, and zone-policy sections. It is +long enough as is. + + +IPv6 Tunnel +^^^^^^^^^^^ + +If you are using a IPv6 tunnel from HE.net or someone else, the basis is +the same except you have two WAN interface. One for v4 and one for v6. + +You would have 5 zones instead of just 4 and you would configure your v6 +ruleset between your tunnel interface and your LAN/DMZ zones instead of +to the WAN. + +LAN, WAN, DMZ, local and TUN (tunnel) + +v6 pairs would be: + +.. code-block:: none + + lan-tun + lan-local + lan-dmz + tun-lan + tun-local + tun-dmz + local-lan + local-tun + local-dmz + dmz-lan + dmz-tun + dmz-local + +Notice, none go to WAN since WAN wouldn't have a v6 address on it. + +You would have to add a couple of rules on your wan-local ruleset to +allow protocol 41 in. + +Something like: + +.. code-block:: none + + rule 400 { + action accept + destination { + address 172.16.10.1 + } + log enable + protocol 41 + source { + address ip.of.tunnel.broker + } + } + diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst deleted file mode 100644 index 5658cdbb..00000000 --- a/docs/configuration-overview.rst +++ /dev/null @@ -1,730 +0,0 @@ -.. _configuration-overview: - -###################### -Configuration Overview -###################### - -VyOS makes use of a unified configuration file for the entire system's -configuration: ``/config/config.boot``. This allows easy template -creation, backup, and replication of system configuration. A system can -thus also be easily cloned by simply copying the required configuration -files. - -Terminology -=========== -live -A VyOS system has three major types of configurations: - -* **Active** or **running configuration** is the system configuration - that is loaded and currently active (used by VyOS). Any change in - the configuration will have to be committed to belong to the - active/running configuration. - -* **Working configuration** is the one that is currently being modified - in configuration mode. Changes made to the working configuration do - not go into effect until the changes are committed with the - :cfgcmd:`commit` command. At which time the working configuration will - become the active or running configuration. - -* **Saved configuration** is the one saved to a file using the - :cfgcmd:`save` command. It allows you to keep safe a configuration for - future uses. There can be multiple configuration files. The default or - "boot" configuration is saved and loaded from the file - ``/config/config.boot``. - -Seeing and navigating the configuration -======================================= - -.. opcmd:: show configuration - - View the current active configuration, also known as the running - configuration, from the operational mode. - - .. code-block:: none - - vyos@vyos:~$ show configuration - interfaces { - ethernet eth0 { - address dhcp - hw-id 00:53:00:00:aa:01 - } - loopback lo { - } - } - service { - ssh { - port 22 - } - } - system { - config-management { - commit-revisions 20 - } - console { - device ttyS0 { - speed 9600 - } - } - login { - user vyos { - authentication { - encrypted-password **************** - } - level admin - } - } - ntp { - server 0.pool.ntp.org { - } - server 1.pool.ntp.org { - } - server 2.pool.ntp.org { - } - } - syslog { - global { - facility all { - level notice - } - facility protocols { - level debug - } - } - } - } - -By default, the configuration is displayed in a hierarchy like the above -example, this is only one of the possible ways to display the -configuration. When the configuration is generated and the device is -configured, changes are added through a collection of :cfgcmd:`set` and -:cfgcmd:`delete` commands. - -.. opcmd:: show configuration commands - - Get a collection of all the set commands required which led to the - running configuration. - - .. code-block:: none - - vyos@vyos:~$ show configuration commands - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' - set interfaces loopback 'lo' - set service ssh port '22' - set system config-management commit-revisions '20' - set system console device ttyS0 speed '9600' - set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' - set system login user vyos level 'admin' - set system ntp server '0.pool.ntp.org' - set system ntp server '1.pool.ntp.org' - set system ntp server '2.pool.ntp.org' - set system syslog global facility all level 'notice' - set system syslog global facility protocols level 'debug' - -Both these ``show`` commands should be executed when in operational -mode, they do not work directly in configuration mode. There is a -special way on how to :ref:`run_opmode_from_config_mode`. - -.. hint:: Use the ``show configuration commands | strip-private`` - command when you want to hide private data. You may want to do so if - you want to share your configuration on the `forum`_. - -.. _`forum`: https://forum.vyos.io - - -The config mode ---------------- - -When entering the configuration mode you are navigating inside a tree -structure, to enter configuration mode enter the command -:opcmd:`configure` when in operational mode. - -.. code-block:: none - - vyos@vyos$ configure - [edit] - vyos@vyos# - - -.. note:: When going into configuration mode, prompt changes from - ``$`` to ``#``. - - -All commands executed here are relative to the configuration level you -have entered. You can do everything from the top level, but commands -will be quite lengthy when manually typing them. - -The current hierarchy level can be changed by the :cfgcmd:`edit` -command. - -.. code-block:: none - - [edit] - vyos@vyos# edit interfaces ethernet eth0 - - [edit interfaces ethernet eth0] - vyos@vyos# - -You are now in a sublevel relative to ``interfaces ethernet eth0``, all -commands executed from this point on are relative to this sublevel. Use -eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top -of the hierarchy. You can also use the :cfgcmd:`up` command to move only -one level up at a time. - -.. cfgcmd:: show - -The :cfgcmd:`show` command within configuration mode will show the -working configuration indicating line changes with ``+`` for additions, -``>`` for replacements and ``-`` for deletions. - -**Example:** - -.. code-block:: none - - vyos@vyos:~$ configure - [edit] - vyos@vyos# show interfaces - ethernet eth0 { - description MY_OLD_DESCRIPTION - disable - hw-id 00:53:dd:44:3b:03 - } - loopback lo { - } - [edit] - vyos@vyos# set interfaces ethernet eth0 address dhcp - [edit] - vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION - [edit] - vyos@vyos# delete interfaces ethernet eth0 disable - [edit] - vyos@vyos# show interfaces - ethernet eth0 { - + address dhcp - > description MY_NEW_DESCRIPTION - - disable - hw-id 00:53:dd:44:3b:03 - } - loopback lo { - } - -It is also possible to display all `set` commands within configuration -mode using :cfgcmd:`show | commands` - -.. code-block:: none - - vyos@vyos# show interfaces ethernet eth0 | commands - set address dhcp - set hw-id 00:53:ad:44:3b:03 - -These commands are also relative to the level you are inside and only -relevant configuration blocks will be displayed when entering a -sub-level. - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# show - address dhcp - hw-id 00:53:ad:44:3b:03 - -Exiting from the configuration mode is done via the :cfgcmd:`exit` -command from the top level, executing :cfgcmd:`exit` from within a -sub-level takes you back to the top level. - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# exit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - - -Editing the configuration -========================= - -The configuration can be edited by the use of :cfgcmd:`set` and -:cfgcmd:`delete` commands from within configuration mode. - -.. cfgcmd:: set - - Use this command to set the value of a parameter or to create a new - element. - -Configuration commands are flattened from the tree into 'one-liner' -commands shown in :opcmd:`show configuration commands` from operation -mode. Commands are relative to the level where they are executed and all -redundant information from the current level is removed from the command -entered. - -.. code-block:: none - - [edit] - vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 - - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# set address 203.0.113.6/24 - - -These two commands above are essentially the same, just executed from -different levels in the hierarchy. - -.. cfgcmd:: delete - - To delete a configuration entry use the :cfgcmd:`delete` command, - this also deletes all sub-levels under the current level you've - specified in the :cfgcmd:`delete` command. Deleting an entry will - also result in the element reverting back to its default value if one - exists. - - .. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# delete address 192.0.2.100/24 - -.. cfgcmd:: commit - - Any change you do on the configuration, will not take effect until - committed using the :cfgcmd:`commit` command in configuration mode. - - .. code-block:: none - - vyos@vyos# commit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - vyos@vyos:~$ - -.. _save: - -.. cfgcmd:: save - - Use this command to preserve configuration changes upon reboot. By - default it is stored at */config/config.boot*. In the case you want - to store the configuration file somewhere else, you can add a local - path, an SCP address, an FTP address or a TFTP address. - - .. code-block:: none - - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done - - .. code-block:: none - - vyos@vyos# save [tab] - Possible completions: - Save to system config file - Save to file on local machine - scp://:@:/ Save to file on remote machine - ftp://:@/ Save to file on remote machine - tftp:/// Save to file on remote machine - vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot - Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... - ######################################################################## 100.0% - Done - -.. cfgcmd:: exit [discard] - - Configuration mode can not be exited while uncommitted changes exist. - To exit configuration mode without applying changes, the - :cfgcmd:`exit discard` command must be used. - - All changes in the working config will thus be lost. - - .. code-block:: none - - vyos@vyos# exit - Cannot exit: configuration modified. - Use 'exit discard' to discard the changes and exit. - [edit] - vyos@vyos# exit discard - - -.. cfgcmd:: commit-confirm - - Use this command to temporarily commit your changes and set the - number of minutes available for validation. ``confirm`` must - be entered within those minutes, otherwise the system will reboot - into the previous configuration. The default value is 10 minutes. - - - What if you are doing something dangerous? Suppose you want to setup - a firewall, and you are not sure there are no mistakes that will lock - you out of your system. You can use confirmed commit. If you issue - the ``commit-confirm`` command, your changes will be commited, and if - you don't issue issue the ``confirm`` command in 10 minutes, your - system will reboot into previous config revision. - - .. code-block:: none - - vyos@router# set interfaces ethernet eth0 firewall local name FromWorld - vyos@router# commit-confirm - commit confirm will be automatically reboot in 10 minutes unless confirmed - Proceed? [confirm]y - [edit] - vyos@router# confirm - [edit] - - - .. note:: A reboot because you did not enter ``confirm`` will not - take you necessarily to the *saved configuration*, but to the - point before the unfortunate commit. - - -.. cfgcmd:: copy - - Copy a configuration element. - - You can copy and remove configuration subtrees. Suppose you set up a - firewall ruleset ``FromWorld`` with one rule that allows traffic from - specific subnet. Now you want to setup a similar rule, but for - different subnet. Change your edit level to - ``firewall name FromWorld`` and use ``copy rule 10 to rule 20``, then - modify rule 20. - - - .. code-block:: none - - vyos@router# show firewall name FromWorld - default-action drop - rule 10 { - action accept - source { - address 203.0.113.0/24 - } - } - [edit] - vyos@router# edit firewall name FromWorld - [edit firewall name FromWorld] - vyos@router# copy rule 10 to rule 20 - [edit firewall name FromWorld] - vyos@router# set rule 20 source address 198.51.100.0/24 - [edit firewall name FromWorld] - vyos@router# commit - [edit firewall name FromWorld] - - -.. cfgcmd:: rename - - Rename a configuration element. - - You can also rename config subtrees: - - .. code-block:: none - - vyos@router# rename rule 10 to rule 5 - [edit firewall name FromWorld] - vyos@router# commit - [edit firewall name FromWorld] - - Note that ``show`` command respects your edit level and from this - level you can view the modified firewall ruleset with just ``show`` - with no parameters. - - .. code-block:: none - - vyos@router# show - default-action drop - rule 5 { - action accept - source { - address 203.0.113.0/24 - } - } - rule 20 { - action accept - source { - address 198.51.100.0/24 - } - } - - -.. cfgcmd:: comment "comment text" - - Add comment as an annotation to a configuration node. - - The ``comment`` command allows you to insert a comment above the - ```` configuration section. When shown, comments are - enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments - need to be commited, just like other config changes. - - To remove an existing comment from your current configuration, - specify an empty string enclosed in double quote marks (``""``) as - the comment text. - - Example: - - .. code-block:: none - - vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" - vyos@vyos# commit - vyos@vyos# show - firewall { - /* Yes I know this VyOS is cool */ - all-ping enable - broadcast-ping disable - ... - } - - .. note:: An important thing to note is that since the comment is - added on top of the section, it will not appear if the ``show -
`` command is used. With the above example, the `show - firewall` command would return starting after the ``firewall - {`` line, hiding the comment. - - - - - - -.. _run_opmode_from_config_mode: - -Access opmode from config mode -============================== - -When inside configuration mode you are not directly able to execute -operational commands. - -.. cfgcmd:: run - - Access to these commands are possible through the use of the - ``run [command]`` command. From this command you will have access to - everything accessible from operational mode. - - Command completion and syntax help with ``?`` and ``[tab]`` will also - work. - - .. code-block:: none - - [edit] - vyos@vyos# run show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 0.0.0.0/0 u/u - -Managing configurations -======================= - -VyOS comes with an integrated versioning system for the system -configuration. It automatically maintains a backup of every previous -configuration which has been committed to the system. The configurations -are versioned locally for rollback but they can also be stored on a -remote host for archiving/backup reasons. - -Local Archive -------------- - -Revisions are stored on disk. You can view, compare and rollback them to -any previous revisions if something goes wrong. - -.. opcmd:: show system commit - - View all existing revisions on the local system. - - .. code-block:: none - - vyos@vyos:~$ show system commit - 0 2015-03-30 08:53:03 by vyos via cli - 1 2015-03-30 08:52:20 by vyos via cli - 2 2015-03-26 21:26:01 by root via boot-config-loader - 3 2015-03-26 20:43:18 by root via boot-config-loader - 4 2015-03-25 11:06:14 by root via boot-config-loader - 5 2015-03-25 01:04:28 by root via boot-config-loader - 6 2015-03-25 00:16:47 by vyos via cli - 7 2015-03-24 23:43:45 by root via boot-config-loader - - -.. cfgcmd:: set system config-management commit-revisions - - You can specify the number of revisions stored on disk. N can be in - the range of 0 - 65535. When the number of revisions exceeds the - configured value, the oldest revision is removed. The default setting - for this value is to store 100 revisions locally. - - -Compare configurations ----------------------- - -VyOS lets you compare different configurations. - -.. cfgcmd:: compare - - Use this command to spot what the differences are between different - configurations. - - .. code-block:: none - - vyos@vyos# compare [tab] - Possible completions: - Compare working & active configurations - saved Compare working & saved configurations - Compare working with revision N - Compare revision N with M - Revisions: - 0 2013-12-17 20:01:37 root by boot-config-loader - 1 2013-12-13 15:59:31 root by boot-config-loader - 2 2013-12-12 21:56:22 vyos by cli - 3 2013-12-12 21:55:11 vyos by cli - 4 2013-12-12 21:27:54 vyos by cli - 5 2013-12-12 21:23:29 vyos by cli - 6 2013-12-12 21:13:59 root by boot-config-loader - 7 2013-12-12 16:25:19 vyos by cli - 8 2013-12-12 15:44:36 vyos by cli - 9 2013-12-12 15:42:07 root by boot-config-loader - 10 2013-12-12 15:42:06 root by init - - The command :cfgcmd:`compare` allows you to compare different type of - configurations. It also lets you compare different revisions through - the :cfgcmd:`compare N M` command, where N and M are revision - numbers. The output will describe how the configuration N is when - compared to M indicating with a plus sign (``+``) the additional - parts N has when compared to M, and indicating with a minus sign - (``-``) the lacking parts N misses when compared to M. - - .. code-block:: none - - vyos@vyos# compare 0 6 - [edit interfaces] - +dummy dum1 { - + address 10.189.0.1/31 - +} - [edit interfaces ethernet eth0] - +vif 99 { - + address 10.199.0.1/31 - +} - -vif 900 { - - address 192.0.2.4/24 - -} - - -.. opcmd:: show system commit diff - - Show commit revision difference. - - -The command above also lets you see the difference between two commits. -By default the difference with the running config is shown. - -.. code-block:: none - - vyos@router# run show system commit diff 4 - [edit system] - +ipv6 { - + disable-forwarding - +} - -This means four commits ago we did ``set system ipv6 disable-forwarding``. - - -Rollback Changes ----------------- - -You can rollback configuration changes using the rollback command. This -will apply the selected revision and trigger a system reboot. - -.. cfgcmd:: rollback - - Rollback to revision N (currently requires reboot) - - .. code-block:: none - - vyos@vyos# compare 1 - [edit system] - >host-name vyos-1 - [edit] - - vyos@vyos# rollback 1 - Proceed with reboot? [confirm][y] - Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): - The system is going down for reboot NOW! - -Remote Archive --------------- - -VyOS can upload the configuration to a remote location after each call -to :cfgcmd:`commit`. You will have to set the commit-archive location. -TFTP, FTP, SCP and SFTP servers are supported. Every time a -:cfgcmd:`commit` is successfull the ``config.boot`` file will be copied -to the defined destination(s). The filename used on the remote host will -be ``config.boot-hostname.YYYYMMDD_HHMMSS``. - -.. cfgcmd:: set system config-management commit-archive location - - Specify remote location of commit archive as any of the below - :abbr:`URI (Uniform Resource Identifier)` - - * ``scp://:@:/`` - * ``sftp://:@/`` - * ``ftp://:@/`` - * ``tftp:///`` - -.. note:: The number of revisions don't affect the commit-archive. - -.. note:: You may find VyOS not allowing the secure connection because - it cannot verify the legitimacy of the remote server. You can use - the workaround below to quickly add the remote host's SSH - fingerprint to your ``~/.ssh/known_hosts`` file: - - .. code-block:: none - - vyos@vyos# ssh-keyscan >> ~/.ssh/known_hosts - -Saving and loading manually ---------------------------- - -You can use the ``save`` and ``load`` commands if you want to manually -manage specific configuration files. - -When using the save_ command, you can add a specific location where -to store your configuration file. And, when needed it, you will be able -to load it with the ``load`` command: - -.. cfgcmd:: load - - Use this command to load a configuration which will replace the - running configuration. Define the location of the configuration file - to be loaded. You can use a path to a local file, an SCP address, an - SFTP address, an FTP address, an HTTP address, an HTTPS address or a - TFTP address. - - .. code-block:: none - - vyos@vyos# load - Possible completions: - Load from system config file - Load from file on local machine - scp://:@:/ Load from file on remote machine - sftp://:@/ Load from file on remote machine - ftp://:@/ Load from file on remote machine - http:/// Load from file on remote machine - https:/// Load from file on remote machine - tftp:/// Load from file on remote machine - - - -Restore Default ---------------- - -In the case you want to completely delete your configuration and restore -the default one, you can enter the following command in configuration -mode: - -.. code-block:: none - - load /opt/vyatta/etc/config.boot.default - -You will be asked if you want to continue. If you accept, you will have -to use :cfgcmd:`commit` if you want to make the changes active. - -Then you may want to :cfgcmd:`save` in order to delete the saved -configuration too. - -.. note:: If you are remotely connected, you will lose your connection. - You may want to copy first the config, edit it to ensure - connectivity, and load the edited config. diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 7646959c..f503ae84 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -581,4 +581,4 @@ The following commands let you reset OpenVPN. -.. include:: /common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst index 85bd41d5..5aeffb63 100644 --- a/docs/configuration/nat/index.rst +++ b/docs/configuration/nat/index.rst @@ -606,7 +606,7 @@ The ASP requests that all connections from this company should come from 172.29.41.89 - an address that is assigned by the ASP and not in use at the customer site. -.. figure:: _static/images/nat_before_vpn_topology.png +.. figure:: /_static/images/nat_before_vpn_topology.png :scale: 100 % :alt: NAT before VPN Topology diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst index 557911d9..4b7d48ee 100644 --- a/docs/configuration/policy/index.rst +++ b/docs/configuration/policy/index.rst @@ -125,7 +125,7 @@ Routing tables that will be used in this example are: * ``main`` Routing table used by VyOS and other interfaces not participating in PBR -.. figure:: ../_static/images/pbr_example_1.png +.. figure:: /_static/images/pbr_example_1.png :scale: 80 % :alt: PBR multiple uplinks diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index 279f0c6d..3f794af8 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -146,4 +146,4 @@ The rate-limit is set in kbit/sec. -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb -.. include:: /common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 4deb6c7e..28d1f097 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -394,4 +394,4 @@ a /56 subnet for the clients internal use. --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB -.. include:: /common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst index 2509946e..808d45a2 100644 --- a/docs/configuration/system/lcd.rst +++ b/docs/configuration/system/lcd.rst @@ -41,5 +41,5 @@ Configuration .. note:: We can't support all displays from the beginning. If your display type is missing, please create a feature request via Phabricator_. -.. include:: /common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst new file mode 100644 index 00000000..d6706421 --- /dev/null +++ b/docs/configuration/vpn/dmvpn.rst @@ -0,0 +1,335 @@ +.. _vpn-dmvpn: + +##### +DMVPN +##### + +:abbr:`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +:abbr:`VPN (Virtual Private Network)` technology originally developed by Cisco. +While their implementation was somewhat proprietary, the underlying +technologies are actually standards based. The three technologies are: + +* :abbr:`NHRP (Next Hop Resolution Protocol)` :rfc:`2332` +* :abbr:`mGRE (Multipoint Generic Routing Encapsulation)` :rfc:`1702` +* :abbr:`IPSec (IP Security)` - too many RFCs to list, but start with :rfc:`4301` + +NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint +registration, and endpoint discovery/lookup), mGRE provides the tunnel +encapsulation itself, and the IPSec protocols handle the key exchange, and +crypto mechanism. + +In short, DMVPN provides the capability for creating a dynamic-mesh VPN +network without having to pre-configure (static) all possible tunnel end-point +peers. + +.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A + complete solution also incorporates the use of a routing protocol. BGP is + particularly well suited for use with DMVPN. + +.. figure:: /_static/images/vpn_dmvpn_topology01.png + :scale: 40 % + :alt: Baseline DMVPN topology + + Baseline DMVPN topology + +************* +Configuration +************* + +* Please refer to the :ref:`tunnel-interface` documentation for the individual + tunnel related options. + +* Please refer to the :ref:`ipsec` documentation for the individual IPSec + related options. + +.. cfgcmd:: set protocols nhrp tunnel cisco-authentication + + Enables Cisco style authentication on NHRP packets. This embeds the secret + plaintext password to the outgoing NHRP packets. Incoming NHRP packets on + this interface are discarded unless the secret password is present. Maximum + length of the secret is 8 characters. + +.. cfgcmd:: set protocols nhrp tunnel dynamic-map
+ nbma-domain-name + + Specifies that the :abbr:`NBMA (Non-broadcast multiple-access network)` + addresses of the next hop servers are defined in the domain name + nbma-domain-name. For each A record opennhrp creates a dynamic NHS entry. + + Each dynamic NHS will get a peer entry with the configured network address + and the discovered NBMA address. + + The first registration request is sent to the protocol broadcast address, and + the server's real protocol address is dynamically detected from the first + registration reply. + +.. cfgcmd:: set protocols nhrp tunnel holding-time + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. + +.. cfgcmd:: set protocols nhrp tunnel map cisco + + If the statically mapped peer is running Cisco IOS, specify the cisco keyword. + It is used to fix statically the Registration Request ID so that a matching + Purge Request can be sent if NBMA address has changed. This is to work around + broken IOS which requires Purge Request ID to match the original Registration + Request ID. + +.. cfgcmd:: set protocols nhrp tunnel map nbma-address
+ + Creates static peer mapping of protocol-address to :abbr:`NBMA (Non-broadcast + multiple-access network)` address. + + If the IP prefix mask is present, it directs opennhrp to use this peer as a + next hop server when sending Resolution Requests matching this subnet. + + This is also known as the HUBs IP address or FQDN. + +.. cfgcmd:: set protocols nhrp tunnel map register + + The optional parameter register specifies that Registration Request should be + sent to this peer on startup. + + This option is required when running a DMVPN spoke. + +.. cfgcmd:: set protocols nhrp tunnel multicast + + Determines how opennhrp daemon should soft switch the multicast traffic. + Currently, multicast traffic is captured by opennhrp daemon using a packet + socket, and resent back to proper destinations. This means that multicast + packet sending is CPU intensive. + + Specfying nhs makes all multicast packets to be repeated to each statically + configured next hop. + + Synamic instructs to forward to all peers which we have a direct connection + with. Alternatively, you can specify the directive multiple times for each + protocol-address the multicast traffic should be sent to. + + .. warning:: It is very easy to misconfigure multicast repeating if you have + multiple NHSes. + +.. cfgcmd:: set protocols nhrp tunnel non-caching + + Disables caching of peer information from forwarded NHRP Resolution Reply + packets. This can be used to reduce memory consumption on big NBMA subnets. + + .. note:: Currently does not do much as caching is not implemented. + +.. cfgcmd:: set protocols nhrp tunnel redirect + + Enable sending of Cisco style NHRP Traffic Indication packets. If this is + enabled and opennhrp detects a forwarded packet, it will send a message to + the original sender of the packet instructing it to create a direct connection + with the destination. This is basically a protocol independent equivalent of + ICMP redirect. + +.. cfgcmd:: set protocols nhrp tunnel shortcut + + Enable creation of shortcut routes. + + A received NHRP Traffic Indication will trigger the resolution and + establishment of a shortcut route. + +.. cfgcmd:: set protocols nhrp tunnel shortcut-destination + + This instructs opennhrp to reply with authorative answers on NHRP Resolution + Requests destinied to addresses in this interface (instead of forwarding the + packets). This effectively allows the creation of shortcut routes to subnets + located on the interface. + + When specified, this should be the only keyword for the interface. + +.. cfgcmd:: set protocols nhrp tunnel shortcut-target
+ + Defines an off-NBMA network prefix for which the GRE interface will act as a + gateway. This an alternative to defining local interfaces with + shortcut-destination flag. + +.. cfgcmd:: set protocols nhrp tunnel shortcut-target
+ holding-time + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. + +******* +Example +******* + + +This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as +multiple spoke sites. The lab was build using :abbr:`EVE-NG (Emulated Virtual +Environment NG)`. + +.. figure:: /_static/images/blueprint-dmvpn.png + :alt: DMVPN network + + DMVPN example network + +Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29. + +The below referenced IP address `192.0.2.1` is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. + +Configuration +============= + +Hub +--- + +.. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + + set interfaces tunnel tun100 address '172.16.253.134/29' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '192.0.2.1' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication 'secret' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 multicast 'dynamic' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'tunnel' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + +.. note:: Setting this up on AWS will require a "Custom Protocol Rule" for + protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC + Network ACL, and secondly on the security group network ACL attached to the + EC2 instance. This has been tested as working for the official AMI image on + the AWS Marketplace. (Locate the correct VPC and security group by navigating + through the details pane below your EC2 instance in the AWS console). + +Spoke +----- + +The individual spoke configurations only differ in the local IP address on the +``tun10`` interface. See the above diagram for the individual IP addresses. + +spoke01-spoke04 +^^^^^^^^^^^^^^^ + +.. code-block:: none + + crypto keyring DMVPN + pre-shared-key address 192.0.2.1 key secret + ! + crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 + crypto isakmp invalid-spi-recovery + crypto isakmp keepalive 30 30 periodic + crypto isakmp profile DMVPN + keyring DMVPN + match identity address 192.0.2.1 255.255.255.255 + ! + crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport + ! + crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + set isakmp-profile DMVPN + ! + interface Tunnel10 + ! individual spoke tunnel IP must change + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication secret + ip nhrp map 172.16.253.134 192.0.2.1 + ip nhrp map multicast 192.0.2.1 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source FastEthernet0/0 + tunnel mode gre multipoint + tunnel key 1 + ! + interface FastEthernet0/0 + ip address dhcp + duplex half + + +spoke05 +^^^^^^^ + +VyOS can also run in DMVPN spoke mode. + +.. code-block:: none + + set interfaces ethernet eth0 address 'dhcp' + + set interfaces tunnel tun100 address '172.16.253.133/29' + set interfaces tunnel tun100 local-ip 0.0.0.0 + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication 'secret' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 map 172.16.253.134/29 nbma-address '192.0.2.1' + set protocols nhrp tunnel tun100 map 172.16.253.134/29 register + set protocols nhrp tunnel tun100 multicast 'nhs' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'tunnel' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB close-action 'none' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + + diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst new file mode 100644 index 00000000..397093c2 --- /dev/null +++ b/docs/configuration/vpn/index.rst @@ -0,0 +1,15 @@ +### +VPN +### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + ipsec + l2tp + openconnect + pptp + rsa-keys + sstp \ No newline at end of file diff --git a/docs/configuration/vpn/ipsec.rst b/docs/configuration/vpn/ipsec.rst new file mode 100644 index 00000000..647f3753 --- /dev/null +++ b/docs/configuration/vpn/ipsec.rst @@ -0,0 +1,192 @@ +.. _ipsec: + +##### +IPsec +##### + +:abbr:`GRE (Generic Routing Encapsulation)`, GRE/IPsec (or IPIP/IPsec, +SIT/IPsec, or any other stateless tunnel protocol over IPsec) is the usual way +to protect the traffic inside a tunnel. + +An advantage of this scheme is that you get a real interface with its own +address, which makes it easier to setup static routes or use dynamic routing +protocols without having to modify IPsec policies. The other advantage is that +it greatly simplifies router to router communication, which can be tricky with +plain IPsec because the external outgoing address of the router usually doesn't +match the IPsec policy of typical site-to-site setup and you need to add special +configuration for it, or adjust the source address for outgoing traffic of your +applications. GRE/IPsec has no such problem and is completely transparent for +the applications. + +GRE/IPIP/SIT and IPsec are widely accepted standards, which make this scheme +easy to implement between VyOS and virtually any other router. + +For simplicity we'll assume that the protocol is GRE, it's not hard to guess +what needs to be changed to make it work with a different protocol. We assume +that IPsec will use pre-shared secret authentication and will use AES128/SHA1 +for the cipher and hash. Adjust this as necessary. + +.. NOTE:: VMware users should ensure that a VMXNET3 adapter is used. E1000 + adapters have known issues with GRE processing. + +************************* +IPsec policy matching GRE +************************* + +The first and arguably cleaner option is to make your IPsec policy match GRE +packets between external addresses of your routers. This is the best option if +both routers have static external addresses. + +Suppose the LEFT router has external address 192.0.2.10 on its eth0 interface, +and the RIGHT router is 203.0.113.45 + +On the LEFT: + +.. code-block:: none + + # GRE tunnel + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.45 + set interfaces tunnel tun0 address 10.10.10.1/30 + + ## IPsec + set vpn ipsec ipsec-interfaces interface eth0 + + # IKE group + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '2' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes128' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha1' + + # ESP group + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes128' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha1' + + # IPsec tunnel + set vpn ipsec site-to-site peer 203.0.113.45 authentication mode pre-shared-secret + set vpn ipsec site-to-site peer 203.0.113.45 authentication pre-shared-secret MYSECRETKEY + + set vpn ipsec site-to-site peer 203.0.113.45 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 203.0.113.45 default-esp-group MyESPGroup + + set vpn ipsec site-to-site peer 203.0.113.45 local-address 192.0.2.10 + + # This will match all GRE traffic to the peer + set vpn ipsec site-to-site peer 203.0.113.45 tunnel 1 protocol gre + +On the RIGHT, setup by analogy and swap local and remote addresses. + + +Source tunnel from loopbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scheme above doesn't work when one of the routers has a dynamic external +address though. The classic workaround for this is to setup an address on a +loopback interface and use it as a source address for the GRE tunnel, then setup +an IPsec policy to match those loopback addresses. + +We assume that the LEFT router has static 192.0.2.10 address on eth0, and the +RIGHT router has a dynamic address on eth0. + +**Setting up the GRE tunnel** + +On the LEFT: + +.. code-block:: none + + set interfaces loopback lo address 192.168.99.1/32 + + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 address 10.10.10.1/30 + set interfaces tunnel tun0 local-ip 192.168.99.1 + set interfaces tunnel tun0 remote-ip 192.168.99.2 + +On the RIGHT: + +.. code-block:: none + + set interfaces loopback lo address 192.168.99.2/32 + + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 address 10.10.10.2/30 + set interfaces tunnel tun0 local-ip 192.168.99.2 + set interfaces tunnel tun0 remote-ip 192.168.99.1 + +**Setting up IPSec** + +However, now you need to make IPsec work with dynamic address on one side. The +tricky part is that pre-shared secret authentication doesn't work with dynamic +address, so we'll have to use RSA keys. + +First, on both routers run the operational command "generate vpn rsa-key bits +2048". You may choose different length than 2048 of course. + +.. code-block:: none + + vyos@left# run generate vpn rsa-key bits 2048 + Generating rsa-key to /config/ipsec.d/rsa-keys/localhost.key + + Your new local RSA key has been generated + The public portion of the key is: + + 0sAQO2335[long string here] + +Then on the opposite router, add the RSA key to your config. + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key KEYGOESHERE + +Now you are ready to setup IPsec. You'll need to use an ID instead of address +for the peer on the dynamic side. + +On the LEFT (static address): + +.. code-block:: none + + set vpn rsa-keys rsa-key-name RIGHT rsa-key + + set vpn ipsec ipsec-interfaces interface eth0 + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer @RIGHT authentication mode rsa + set vpn ipsec site-to-site peer @RIGHT authentication rsa-key-name RIGHT + set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup + set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 + set vpn ipsec site-to-site peer @RIGHT connection-type respond + set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote + + +On the RIGHT (dynamic address): + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key + + set vpn ipsec ipsec-interfaces interface eth0 + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer 192.0.2.10 authentication id @RIGHT + set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa + set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa-key-name LEFT + set vpn ipsec site-to-site peer 192.0.2.10 remote-id @LEFT + set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate + set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 192.0.2.10 local-address any + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst new file mode 100644 index 00000000..0d8dde08 --- /dev/null +++ b/docs/configuration/vpn/l2tp.rst @@ -0,0 +1,235 @@ +.. _l2tp: + +L2TP +---- + +VyOS utilizes accel-ppp_ to provide L2TP server functionality. It can be used +with local authentication or a connected RADIUS server. + +L2TP over IPsec +=============== + +Example for configuring a simple L2TP over IPsec VPN for remote access (works +with native Windows and Mac VPN clients): + +.. code-block:: none + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal enable + set vpn ipsec nat-networks allowed-network 0.0.0.0/0 + + set vpn l2tp remote-access outside-address 192.0.2.2 + set vpn l2tp remote-access client-ip-pool start 192.168.255.2 + set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret + set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username test password 'test' + +In the example above an external IP of 192.0.2.2 is assumed. + +If a local firewall policy is in place on your external interface you will need +to allow the ports below: + +* UDP port 500 (IKE) +* IP protocol number 50 (ESP) +* UDP port 1701 for IPsec + +As well as the below to allow NAT-traversal (when NAT is detected by the +VPN client, ESP is encapsulated in UDP for NAT-traversal): + +* UDP port 4500 (NAT-T) + +Example: + +.. code-block:: none + + set firewall name OUTSIDE-LOCAL rule 40 action 'accept' + set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp' + set firewall name OUTSIDE-LOCAL rule 41 action 'accept' + set firewall name OUTSIDE-LOCAL rule 41 destination port '500' + set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp' + set firewall name OUTSIDE-LOCAL rule 42 action 'accept' + set firewall name OUTSIDE-LOCAL rule 42 destination port '4500' + set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp' + set firewall name OUTSIDE-LOCAL rule 43 action 'accept' + set firewall name OUTSIDE-LOCAL rule 43 destination port '1701' + set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' + set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp' + +To allow VPN-clients access via your external address, a NAT rule is required: + + +.. code-block:: none + + set nat source rule 110 outbound-interface 'eth0' + set nat source rule 110 source address '192.168.255.0/24' + set nat source rule 110 translation address masquerade + + +VPN-clients will request configuration parameters, optionally you can DNS +parameter to the client. + +.. code-block:: none + + set vpn l2tp remote-access dns-servers server-1 '8.8.8.8' + set vpn l2tp remote-access dns-servers server-2 '8.8.4.4' + +.. note:: Those are the `Google public DNS`_ servers, but you can choose + any public available servers, like Quad9_ (9.9.9.9), Cloudflare_ (1.1.1.1) + or OpenNIC_. + +Established sessions can be viewed using the **show vpn remote-access** +operational command, or **show l2tp-server sessions** + +.. code-block:: none + + vyos@vyos:~$ show vpn remote-access + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + --------+----------+--------------+---------------+------------+------+------+--------+---------- + ppp0 | vyos | 192.168.0.36 | 192.168.255.1 | | l2tp | | active | 00:06:13 + + +LNS (L2TP Network Server) +========================= + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +Below is an example to configure a LNS: + +.. code-block:: none + + set vpn l2tp remote-access outside-address 192.0.2.2 + set vpn l2tp remote-access client-ip-pool start 192.168.255.2 + set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access lns shared-secret 'secret' + set vpn l2tp remote-access ccp-disable + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username test password 'test' + +The example above uses 192.0.2.2 as external IP address. A LAC normally +requires an authentication password, which is set in the example configuration +to ``lns shared-secret 'secret'``. This setup requires the Compression Control +Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access ccp-disable`` +accomplishes that. + + +Bandwidth Shaping +================= + +Bandwidth rate limits can be set for local users or via RADIUS based attributes. + +Bandwidth Shaping for local users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The rate-limit is set in kbit/sec. + +.. code-block:: none + + set vpn l2tp remote-access outside-address 192.0.2.2 + set vpn l2tp remote-access client-ip-pool start 192.168.255.2 + set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username test password test + set vpn l2tp remote-access authentication local-users username test rate-limit download 20480 + set vpn l2tp remote-access authentication local-users username test rate-limit upload 10240 + + vyos@vyos:~$ show vpn remote-access + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + -------+----------+--------------+---------------+-------------+------+------+--------+----------- + ppp0 | test | 192.168.0.36 | 192.168.255.2 | 20480/10240 | l2tp | | active | 00:06:30 + +RADIUS authentication +====================== + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +.. code-block:: none + + set vpn l2tp remote-access authentication mode + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' + set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' + +.. note:: Some RADIUS_ severs use an access control list which allows or denies + queries, make sure to add your VyOS router to the allowed client list. + +RADIUS source address +^^^^^^^^^^^^^^^^^^^^^ + +If you are using OSPF as IGP always the closets interface connected to the RADIUS +server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests to a +single source IP e.g. the loopback interface. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius source-address 10.0.0.3 + +Above command will use `10.0.0.3` as source IPv4 address for all RADIUS queries +on this NAS. + +.. note:: The ``source-address`` must be configured on one of VyOS interface. + Best proctice would be a loopback or dummy interface. + +RADIUS bandwidth shaping attribute +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To enable bandwidth shaping via RADIUS, the option rate-limit needs to be enabled. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius rate-limit enable + +The default RADIUS attribute for rate limiting is ``Filter-Id``, but you may also +redefine it. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius rate-limit attribute Download-Speed + +.. note:: If you set a custom RADIUS attribute you must define it on both + dictionaries at RADIUS server and client, which is the vyos router in our + example. + +The RADIUS dictionaries in VyOS are located at ``/usr/share/accel-ppp/radius/`` + +RADIUS advanced features +^^^^^^^^^^^^^^^^^^^^^^^^ + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +Allocation clients ip addresses by RADIUS +***************************************** + +If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP +address will be allocated to the client and the option ip-pool within the CLI +config is being ignored. + +Renaming clients interfaces by RADIUS +************************************* + +If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be +renamed. + +.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 + characters, otherwise the interface won't be renamed. + + +.. _`Google Public DNS`: https://developers.google.com/speed/public-dns +.. _Quad9: https://quad9.net +.. _CloudFlare: https://blog.cloudflare.com/announcing-1111 +.. _OpenNIC: https://www.opennic.org/ +.. _RADIUS: https://en.wikipedia.org/wiki/RADIUS +.. _FreeRADIUS: https://freeradius.org +.. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server +.. _accel-ppp: https://accel-ppp.org/ diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst new file mode 100644 index 00000000..a409ed9d --- /dev/null +++ b/docs/configuration/vpn/openconnect.rst @@ -0,0 +1,95 @@ +.. _vpn-openconnect: + +########### +OpenConnect +########### + +OpenConnect-compatible server feature is available from this release. +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. + +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the network. + +.. note:: All certificates should be stored on VyOS under /config/auth. If + certificates are not stored in the /config directory they will not be + migrated during a software update. + +************* +Configuration +************* + +SSL Certificates +================ + +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following command +will create a self signed certificates and will be stored in the file path +`/config/auth`. + +.. code-block:: none + + openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt + openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt + +We can also create the certificates using Cerbort which is an easy-to-use client +that fetches a certificate from Let's Encrypt an open certificate authority +launched by the EFF, Mozilla, and others and deploys it to a web server. + +.. code-block:: none + + sudo certbot certonly --standalone --preferred-challenges http -d + +Server Configuration +==================== + +.. code-block:: none + + set vpn openconnect authentication local-users username password + set vpn openconnect authentication mode + set vpn opneconnect network-settings client-ip-settings subnet + set vpn openconnect network-settings name-server
+ set vpn openconnect network-settings name-server
+ set vpn openconnect ssl ca-cert-file + set vpn openconnect ssl cert-file + set vpn openconnect ssl key-file + + +******* +Example +******* + +Use local user name "user4" with password "SecretPassword" +Client IP addresses will be provided from pool 100.64.0.0/24 +The Gateway IP Address must be in one of the router´s interfaces. + +.. code-block:: none + + set vpn openconnect authentication local-users username user4 password 'SecretPassword' + set vpn openconnect authentication mode 'local' + set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' + set vpn openconnect network-settings name-server '1.1.1.1' + set vpn openconnect network-settings name-server '8.8.8.8' + set vpn openconnect ssl ca-cert-file '/config/auth/fullchain.pem' + set vpn openconnect ssl cert-file '/config/auth/cert.pem' + set vpn openconnect ssl key-file '/config/auth/privkey.pem' + + +************ +Verification +************ + +.. code-block:: none + + + vyos@RTR1:~$ show openconnect-server sessions + + interface username ip remote IP RX TX state uptime + ----------- ---------- ------------ ------------- -------- -------- --------- -------- + sslvpn0 user4 100.64.0.105 xx.xxx.49.253 127.3 KB 160.0 KB connected 12m:28s + +.. note:: It is compatible with Cisco (R) AnyConnect (R) clients. diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst new file mode 100644 index 00000000..72b3feb0 --- /dev/null +++ b/docs/configuration/vpn/pptp.rst @@ -0,0 +1,47 @@ +.. _pptp: + +PPTP-Server +----------- + +The Point-to-Point Tunneling Protocol (PPTP_) has been implemented in VyOS only for backwards compatibility. +PPTP has many well known security issues and you should use one of the many other new VPN implementations. + +As per default and if not otherwise defined, mschap-v2 is being used for authentication and mppe 128-bit (stateless) for encryption. +If no gateway-address is set within the configuration, the lowest IP out of the /24 client-ip-pool is being used. For instance, in the example below it would be 192.168.0.1. + +server example +^^^^^^^^^^^^^^ + +.. code-block:: none + + set vpn pptp remote-access authentication local-users username test password 'test' + set vpn pptp remote-access authentication mode 'local' + set vpn pptp remote-access client-ip-pool start '192.168.0.10' + set vpn pptp remote-access client-ip-pool stop '192.168.0.15' + set vpn pptp remote-access gateway-address '10.100.100.1' + set vpn pptp remote-access outside-address '10.1.1.120' + + +client example (debian 9) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Install the client software via apt and execute pptpsetup to generate the configuration. + + +.. code-block:: none + + apt-get install pptp-linux + pptpsetup --create TESTTUNNEL --server 10.1.1.120 --username test --password test --encrypt + pon TESTTUNNEL + +The command pon TESTUNNEL establishes the PPTP tunnel to the remote system. + + +All tunnel sessions can be checked via: + +.. code-block:: none + + run sh pptp-server sessions + ifname | username | calling-sid | ip | type | comp | state | uptime + --------+----------+-------------+--------------+------+------+--------+---------- + ppp0 | test | 10.1.1.99 | 192.168.0.10 | pptp | mppe | active | 00:00:58 diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst new file mode 100644 index 00000000..97f27b43 --- /dev/null +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -0,0 +1,298 @@ +.. _size2site_ipsec: + +Site-to-Site +============ + +Site-to-site mode provides a way to add remote peers, which could be configured to exchange encrypted information between them and VyOS itself or connected/routed networks. + +To configure site-to-site connection you need to add peers with the ``set vpn ipsec site-to-site`` command. + +You can identify a remote peer with: + +* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used when a peer has a public static IP address; +* Hostname. This mode is similar to IP address, only you define DNS name instead of an IP. Could be used when a peer has a public IP address and DNS name, but an IP address could be changed from time to time; +* Remote ID of the peer. In this mode, there is no predefined remote address nor DNS name of the peer. This mode is useful when a peer doesn't have a publicly available IP address (NAT between it and VyOS), or IP address could be changed. + +Each site-to-site peer has the next options: + +* ``authentication`` - configure authentication between VyOS and a remote peer. Suboptions: + + * ``id`` - ID for the local VyOS router. If defined, during the authentication it will be send to remote peer; + + * ``mode`` - mode for authentication between VyOS and remote peer: + + * ``pre-shared-secret`` - use predefined shared secret phrase, must be the same for local and remote side; + + * ``rsa`` - use simple shared RSA key. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``x509`` - use certificates infrastructure for authentication. + + * ``pre-shared-secret`` - predefined shared secret. Used if configured ``mode pre-shared-secret``; + + * ``remote-id`` - define an ID for remote peer, instead of using peer name or address. Useful in case if the remote peer is behind NAT or if ``mode x509`` is used; + + * ``rsa-key-name`` - shared RSA key for authentication. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when ``id`` is defined; + + * ``x509`` - options for x509 authentication mode: + + * ``ca-cert-file`` - CA certificate file. Using for authenticating remote peer; + + * ``cert-file`` - certificate file, which will be used for authenticating local router on remote peer; + + * ``crl-file`` - file with the Certificate Revocation List. Using to check if a certificate for the remote peer is valid or revoked; + + * ``key`` - a private key, which will be used for authenticating local router on remote peer: + + * ``file`` - path to the key file; + + * ``password`` - passphrase private key, if needed. + +* ``connection-type`` - how to handle this connection process. Possible variants: + + * ``initiate`` - do initial connection to remote peer immediately after configuring and after boot. In this mode the connection will not be restarted in case of disconnection, therefore should be used only together with DPD or another session tracking methods; + + * ``respond`` - do not try to initiate a connection to a remote peer. In this mode, the IPSec session will be established only after initiation from a remote peer. Could be useful when there is no direct connectivity to the peer due to firewall or NAT in the middle of the local and remote side. + +* ``default-esp-group`` - ESP group to use by default for traffic encryption. Might be overwritten by individual settings for tunnel or VTI interface binding; + +* ``description`` - description for this peer; + +* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec connection with this peer, instead of ``local-address``; + +* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. Useful in case if between local and remote side is firewall or NAT, which not allows passing plain ESP packets between them; + +* ``ike-group`` - IKE group to use for key exchanges; + +* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. Can be used only with IKEv2: + + * ``yes`` - create a new IKE_SA from the scratch and try to recreate all IPsec SAs; + + * ``no`` - rekey without uninstalling the IPsec SAs; + + * ``inherit`` - use default behavior for the used IKE group. + +* ``local-address`` - local IP address for IPSec connection with this peer. If defined ``any``, then an IP address which configured on interface with default route will be used; + +* ``tunnel`` - define criteria for traffic to be matched for encrypting and send it to a peer: + + * ``disable`` - disable this tunnel; + + * ``esp-group`` - define ESP group for encrypt traffic, defined by this tunnel; + + * ``local`` - define a local source for match traffic, which should be encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at local side. + + * ``protocol`` - define the protocol for match traffic, which should be encrypted and send to this peer; + + * ``remote`` - define the remote destination for match traffic, which should be encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at remote side. + +* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will be send to VTI interface will be encrypted and send to this peer. Using VTI makes IPSec configuration much flexible and easier in complex situation, and allows to dynamically add/delete remote networks, reachable via a peer, as in this mode router don't need to create additional SA/policy for each remote network: + + * ``bind`` - select a VTI interface to bind to this peer; + + * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI interface. + +Examples: +------------------ + +IKEv1 +^^^^^ + +Example: + +* WAN interface on `eth1` +* left subnet: `192.168.0.0/24` site1, server side (i.e. locality, actually + there is no client or server roles) +* left local_ip: `198.51.100.3` # server side WAN IP +* right subnet: `10.0.0.0/24` site2,remote office side +* right local_ip: `203.0.113.2` # remote office side WAN IP + +.. code-block:: none + + # server config + set vpn ipsec esp-group office-srv-esp compression 'disable' + set vpn ipsec esp-group office-srv-esp lifetime '1800' + set vpn ipsec esp-group office-srv-esp mode 'tunnel' + set vpn ipsec esp-group office-srv-esp pfs 'enable' + set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' + set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no' + set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' + set vpn ipsec ike-group office-srv-ike lifetime '3600' + set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' + set vpn ipsec ipsec-interfaces interface 'eth1' + set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-public-networks 'disable' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 local prefix '192.168.0.0/24' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 remote prefix '10.0.0.0/21' + + # remote office config + set vpn ipsec esp-group office-srv-esp compression 'disable' + set vpn ipsec esp-group office-srv-esp lifetime '1800' + set vpn ipsec esp-group office-srv-esp mode 'tunnel' + set vpn ipsec esp-group office-srv-esp pfs 'enable' + set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' + set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no' + set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' + set vpn ipsec ike-group office-srv-ike lifetime '3600' + set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' + set vpn ipsec ipsec-interfaces interface 'eth1' + set vpn ipsec site-to-site peer 198.51.100.3 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.3 authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer 198.51.100.3 ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer 198.51.100.3 local-address '203.0.113.2' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-public-networks 'disable' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 local prefix '10.0.0.0/21' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 remote prefix '192.168.0.0/24' + +Show status of new setup: + +.. code-block:: none + + vyos@srv-gw0:~$ show vpn ike sa + Peer ID / IP Local ID / IP + ------------ ------------- + 203.0.113.2 198.51.100.3 + State Encrypt Hash D-H Grp NAT-T A-Time L-Time + ----- ------- ---- ------- ----- ------ ------ + up aes256 sha1 5 no 734 3600 + + vyos@srv-gw0:~$ show vpn ipsec sa + Peer ID / IP Local ID / IP + ------------ ------------- + 203.0.113.2 198.51.100.3 + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 7.5M/230.6K aes256 sha1 no 567 1800 all + +If there is SNAT rules on eth1, need to add exclude rule + +.. code-block:: none + + # server side + set nat source rule 10 destination address '10.0.0.0/24' + set nat source rule 10 'exclude' + set nat source rule 10 outbound-interface 'eth1' + set nat source rule 10 source address '192.168.0.0/24' + + # remote office side + set nat source rule 10 destination address '192.168.0.0/24' + set nat source rule 10 'exclude' + set nat source rule 10 outbound-interface 'eth1' + set nat source rule 10 source address '10.0.0.0/24' + +To allow traffic to pass through to clients, you need to add the following +rules. (if you used the default configuration at the top of this page) + +.. code-block:: none + + # server side + set firewall name OUTSIDE-LOCAL rule 32 action 'accept' + set firewall name OUTSIDE-LOCAL rule 32 source address '10.0.0.0/24' + + # remote office side + set firewall name OUTSIDE-LOCAL rule 32 action 'accept' + set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24' + +IKEv2 +^^^^^ + +Imagine the following topology + +.. figure:: /_static/images/vpn_s2s_ikev2.png + :scale: 50 % + :alt: IPSec IKEv2 site2site VPN + + IPSec IKEv2 site2site VPN (source ./draw.io/vpn_s2s_ikev2.drawio) + + +.. note:: Don't get confused about the used /31 tunnel subnet. :rfc:`3021` + gives you additional information for using /31 subnets on point-to-point + links. + +**left** + +.. code-block:: none + + set interfaces vti vti10 address '10.0.0.2/31' + + set vpn ipsec esp-group ESP_DEFAULT compression 'disable' + set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' + set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' + set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'hold' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' + set vpn ipsec ike-group IKEv2_DEFAULT ikev2-reauth 'no' + set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' + set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' + set vpn ipsec ike-group IKEv2_DEFAULT mobike 'disable' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ipsec-interfaces interface 'eth0.201' + set vpn ipsec site-to-site peer 172.18.202.10 authentication id '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.202.10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 172.18.202.10 authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer 172.18.202.10 authentication remote-id '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.202.10 connection-type 'initiate' + set vpn ipsec site-to-site peer 172.18.202.10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer 172.18.202.10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 172.18.202.10 local-address '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.202.10 vti bind 'vti10' + set vpn ipsec site-to-site peer 172.18.202.10 vti esp-group 'ESP_DEFAULT' + +**right** + +.. code-block:: none + + set interfaces vti vti10 address '10.0.0.3/31' + + set vpn ipsec esp-group ESP_DEFAULT compression 'disable' + set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' + set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' + set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'hold' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' + set vpn ipsec ike-group IKEv2_DEFAULT ikev2-reauth 'no' + set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' + set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' + set vpn ipsec ike-group IKEv2_DEFAULT mobike 'disable' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ipsec-interfaces interface 'eth0.202' + set vpn ipsec site-to-site peer 172.18.201.10 authentication id '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.201.10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 172.18.201.10 authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer 172.18.201.10 authentication remote-id '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.201.10 connection-type 'initiate' + set vpn ipsec site-to-site peer 172.18.201.10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer 172.18.201.10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 172.18.201.10 local-address '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.201.10 vti bind 'vti10' + set vpn ipsec site-to-site peer 172.18.201.10 vti esp-group 'ESP_DEFAULT' diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst new file mode 100644 index 00000000..dbaa41c0 --- /dev/null +++ b/docs/configuration/vpn/sstp.rst @@ -0,0 +1,347 @@ +.. _sstp: + +#### +SSTP +#### + +:abbr:`SSTP (Secure Socket Tunneling Protocol)` is a form of :abbr:`VPN +(Virtual Private Network)` tunnel that provides a mechanism to transport PPP +traffic through an SSL/TLS channel. SSL/TLS provides transport-level security +with key negotiation, encryption and traffic integrity checking. The use of +SSL/TLS over TCP port 443 allows SSTP to pass through virtually all firewalls +and proxy servers except for authenticated web proxies. + +SSTP is available for Linux, BSD, and Windows. + +VyOS utilizes accel-ppp_ to provide SSTP server functionality. We support both +local and RADIUS authentication. + +As SSTP provides PPP via a SSL/TLS channel the use of either publically signed +certificates as well as a private PKI is required. + +.. note:: All certificates should be stored on VyOS under ``/config/auth``. If + certificates are not stored in the ``/config`` directory they will not be + migrated during a software update. + +Certificates +============ + +Self Signed CA +-------------- + +To generate the CA, the server private key and certificates the following +commands can be used. + +.. code-block:: none + + vyos@vyos:~$ mkdir -p /config/user-data/sstp + vyos@vyos:~$ openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/user-data/sstp/server.key -out /config/user-data/sstp/server.crt + + Generating a 4096 bit RSA private key + .........................++ + ...............................................................++ + writing new private key to 'server.key' + [...] + Country Name (2 letter code) [AU]: + State or Province Name (full name) [Some-State]: + Locality Name (eg, city) []: + Organization Name (eg, company) [Internet Widgits Pty Ltd]: + Organizational Unit Name (eg, section) []: + Common Name (e.g. server FQDN or YOUR name) []: + Email Address []: + + vyos@vyos:~$ openssl req -new -x509 -key /config/user-data/sstp/server.key -out /config/user-data/sstp/ca.crt + [...] + Country Name (2 letter code) [AU]: + State or Province Name (full name) [Some-State]: + Locality Name (eg, city) []: + Organization Name (eg, company) [Internet Widgits Pty Ltd]: + Organizational Unit Name (eg, section) []: + Common Name (e.g. server FQDN or YOUR name) []: + Email Address []: + + +Configuration +============= + +.. cfgcmd:: set vpn sstp authentication local-users username password + + Create `` for local authentication on this system. The users password + will be set to ``. + +.. cfgcmd:: set vpn sstp authentication local-users username disable + + Disable `` account. + +.. cfgcmd:: set vpn sstp authentication local-users username static-ip
+ + Assign static IP address to `` account. + +.. cfgcmd:: set vpn sstp authentication local-users username rate-limit download + + Download bandwidth limit in kbit/s for ``. + +.. cfgcmd:: set vpn sstp authentication local-users username rate-limit upload + + Upload bandwidth limit in kbit/s for ``. + +.. cfgcmd:: set vpn sstp authentication protocols + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. + +.. cfgcmd:: set vpn sstp authentication mode + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + + +.. cfgcmd:: set vpn sstp gateway-address + + Specifies single `` IP address to be used as local address of PPP + interfaces. + + +.. cfgcmd:: set vpn sstp client-ip-pool subnet + + Use `` as the IP pool for all connecting clients. + + +.. cfgcmd:: set vpn sstp client-ipv6-pool prefix
mask + + Use this comand to set the IPv6 address pool from which an SSTP client + will get an IPv6 prefix of your defined length (mask) to terminate the + SSTP endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. + + +.. cfgcmd:: set vpn sstp client-ipv6-pool delegate
delegation-prefix + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + SSTP. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. + + +.. cfgcmd:: set vpn sstp name-server
+ + Connected client should use `
` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. + +Maximum number of IPv4 nameservers + +SSL Certificates +---------------- + +.. cfgcmd:: set vpn sstp ssl ca-cert-file + + Path to `` pointing to the certificate authority certificate. + +.. cfgcmd:: set vpn sstp ssl cert-file + + Path to `` pointing to the servers certificate (public portion). + +.. cfgcmd:: set vpn sstp ssl key-file + + Path to `` pointing to the servers certificate (private portion). + +PPP Settings +------------ + +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure + + Defines the maximum `` of unanswered echo requests. Upon reaching the + value ``, the session will be reset. + +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval + + If this option is specified and is greater than 0, then the PPP module will + send LCP pings of the echo request every `` seconds. + +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. + +.. cfgcmd:: set vpn sstp ppp-options mppe + + Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotioation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail + * **deny** - deny mppe + + Default behavior - don't ask client for mppe, but allow it if client wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. + + +RADIUS +------ + +Server +^^^^^^ + +.. cfgcmd:: set vpn sstp authentication radius server port + + Configure RADIUS `` and its required port for authentication requests. + +.. cfgcmd:: set vpn sstp authentication radius server key + + Configure RADIUS `` and its required shared `` for + communicating with the RADIUS server. + +.. cfgcmd:: set vpn sstp authentication radius server fail-time