diff options
Diffstat (limited to 'docs/appendix')
20 files changed, 0 insertions, 3861 deletions
diff --git a/docs/appendix/command-scripting.rst b/docs/appendix/command-scripting.rst deleted file mode 100644 index 7d0ab6c5..00000000 --- a/docs/appendix/command-scripting.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _command-scripting: - -Command Scripting -================= - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS specific functions and aliases you need to ``source -/opt/vyatta/etc/functions/script-template`` files at the top of your script. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - exit - -Run configuration commands --------------------------- - -Configuration commands are executed just like from a normal config session. For -example, if you want to disable a BGP peer on VRRP transition to backup: - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - set protocols bgp 65536 neighbor 192.168.2.1 shutdown - commit - exit - -Run operational commands ------------------------- - -Unlike a normal configuration sessions, all operational commands must be -prepended with ``run``, even if you haven't created a session with configure. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - run show interfaces - exit - -Other script language ---------------------- - -If you want to script the configs in a language other than bash you can have -your script output commands and then source them in a bash script. - -Here is a simple example: - -.. code-block:: python - - #!/usr/bin/env python - print "delete firewall group address-group somehosts" - print "set firewall group address-group somehosts address '192.0.2.3'" - print "set firewall group address-group somehosts address '203.0.113.55'" - - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - source < /config/scripts/setfirewallgroup.py - commit - - -Executing Configuration Scripts -------------------------------- - -There is a pitfall when working with configuration scripts. It is tempting to -call configuration scripts with "sudo" (i.e., temporary root permissions), -because that's the common way on most Linux platforms to call system commands. - -On VyOS this will cause the following problem: After modifying the configuration -via script like this once, it is not possible to manually modify the config -anymore: - -.. code-block:: none - - sudo ./myscript.sh # Modifies config - configure - set ... # Any configuration parameter - -This will result in the following error message: ``Set failed`` If this happens, -a reboot is required to be able to edit the config manually again. - -To avoid these problems, the proper way is to call a script with the -``vyattacfg`` group, e.g., by using the ``sg`` (switch group) command: - -.. code-block:: none - - sg vyattacfg -c ./myscript.sh - -To make sure that a script is not accidentally called without the ``vyattacfg`` -group, the script can be safeguarded like this: - -.. code-block:: none - - if [ "$(id -g -n)" != 'vyattacfg' ] ; then - exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" - fi - -Postconfig on boot ------------------- - -The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot -after the VyOS configuration is fully applied. - -Any modifications done to work around unfixed bugs and implement enhancements -which are not complete in the VyOS system can be placed here. - -The default file looks like this: - -.. code-block:: none - - #!/bin/sh - # This script is executed at boot time after VyOS configuration is fully - # applied. Any modifications required to work around unfixed bugs or use - # services not available through the VyOS CLI system can be placed here. - -.. hint:: For configuration/upgrade management issues, modification of this - script should be the last option. Always try to find solutions based on CLI - commands first. 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) <https://docs.vyos.io/en/crux/appendix/examples/azure-vpn-dual-bgp.html>`_ - -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 <ruleSet> 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/appendix/http-api.rst b/docs/appendix/http-api.rst deleted file mode 100644 index 49f2dbd9..00000000 --- a/docs/appendix/http-api.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _http-api: - -######## -HTTP-API -######## - -Enabling HTTP-API ------------------ - -VyOS HTTP API can be enabled through the ``set service https api`` command. - -.. code-block:: none - - set service https api debug - set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY - -The local API process listens on localhost:8080, and nginx exposes it on all -virtual servers, by default. For the purpose of illustration below, we will -assume nginx is running at https://192.168.122.127. - -One can limit proxying to specific listen addresses/ports/server-names by -defining a ``service https virtual-host <id>``, and setting ``service https -api-restrict virtual-host <id>``. - -.. code-block:: none - - set service https virtual-host example listen-address 192.168.122.127 - set service https virtual-host example listen-port 44302 - set service https virtual-host example server-name example.net - - set service https api-restrict virtual-host example - -In this example, nginx will proxy only those requests to -192.168.122.127:44302 or example.net:44302 (assuming the DNS record is -viable). Omitting any of listen-address, listen-port, or server-name, will -leave appropriate defaults in the nginx directive. Multiple instances of -``service https api-restrict virtual-host`` may be set. - -Configuration mode requests ---------------------------- - -In our example, we are creating a dummy interface and assigning an address to it: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure - -The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP method it uses is POST. Request data is passed in the ``data=`` field and the API key is passed in the ``key=`` field. Key identifiers from the config are purely informational and the application doesn't need to know them, they only appear in the server logs to avoid exposing keys in log files, you only need the key itself. - -Since internally there is no distinction between a path and a value, you can omit the value field and include the value in the path like it's done in the shell commands: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure - -Separate value field make the semantics more clear though, and also makes it easier to create a command template once and update it with different values as needed. - -You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit. - -To retrieve a value: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -Use ``returnValues`` for multi-valued nodes. - - -Show config -""""""""""" - -To retrieve the full config under a path: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -It will return: - -.. code-block:: none - - {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} - -Passing an empty path will return the full config: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - - -Configuration management requests ---------------------------------- - -When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command. - -If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example: - -.. code-block:: none - - # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file - -Image management requests -------------------------- - -One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples: - -``add`` from ``url``. Here we use the URL of the latest rolling release: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image - -``delete`` by image ``name``. For example: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image - -To list the available system images by name, one may use the operational mode request ``show`` discussed in the next section; in this setting it would be: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Operational mode requests -------------------------- - -It is possible to run ``show`` and ``generate`` commands: - - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate - -Response: - -.. code-block:: none - - {"success": true, "data": "", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "<some pubkey>=\n", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} - diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/appendix/migrate-from-vyatta.rst deleted file mode 100644 index f15c3d5a..00000000 --- a/docs/appendix/migrate-from-vyatta.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _migrate_from_vyatta: - -Migrate from Vyatta Core -======================== - -VyOS 1.x line aims to preserve backward compatibility and provide a safe -upgrade path for existing Vyatta Core users. You may think of VyOS 1.0.0 as -VC7.0. - -Vyatta release compatibility ----------------------------- - -Vyatta Core releases from 6.5 to 6.6 should be 100% compatible. - -Vyatta Core 6.4 and earlier may have incompatibilities. In Vyatta 6.5 the -"modify" firewall was removed and replaced with the ``set policy route`` -command family, old configs can not be automatically converted. You will have -to adapt it to post-6.5 Vyatta syntax manually. - -.. note:: Also, in Vyatta Core 6.5 remote access VPN interfaces have been - renamed from ``pppX`` to ``l2tpX`` and ``pptpX``. If you are using - zone based firewalling in Vyatta Core pre-6.5 versions, make sure to change - interface names in rules for remote access VPN. - -Upgrade procedure ------------------ - -You just use ``add system image``, as if it was a new VC release (see -:ref:`update_vyos` for additional information). The only thing you want to do -is to verify the new images digital signature. You will have to add the public -key manually once as it is not shipped the first time. - -.. code-block:: none - - vyatta@vyatta:~$ wget http://wiki.vyos.net/so3group_maintainers.key - Connecting to vyos.net (x.x.x.x:80) - so3group_maintainers 100% |*************************| 3125 --:--:-- ETA - vyatta@vyatta:~$ sudo apt-key add so3group_maintainers.key - OK - vyatta@vyatta:~$ - -For completion the key below corresponds to the key listed in the URL above. - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - mQINBFIIUZwBEADGl+wkZpYytQxd6LnjDZZScziBKYJbjInetYeS0SUrgpqnPkzL - 2CiGfPczLwpYY0zWxpUhTvqjFsE5yDpgs0sPXIgUTFE1qfZQE+WD1I1EUM6sp/38 - 2xKQ9QaNc8oHuYINLYYmNYra6ZjIGtQP9WOX//IDYB3fhdwlmiW2z0hux2OnPWdh - hPZAmSrx5AiXFEEREJ1cAQyvYk7hgIRvM/rdQMUm+u4/z+S4mxCHE10KzlqOGhRv - hA8WQxHCVusMFGwXoKHxYf9OQpV7lsfOCODfXOMP/L9kHQ5/gBsLL5hHst+o/3VG - ec0QuVrVkBBehgrqhfJW2noq+9gTooURGImQHEOyE0xpJdFrrgk5Ii9RqQwdVRzI - ZPbqbo8uuldZIRJRGnfx+vAR9812yo38NVZ/X0P/hkkrx+UeGVgpC/ao5XLRiOzL - 7ZBMWLA6FVmZ7mkpqdzuMXX5548ApACm6EKErULIhTYDGDzFxA3cf6gr5VVi4usD - wglVs+FHuiLehmuuPTMoVcT2R6+Ht44hG3BmQmKzh/SSEa1g9gKgrhZrMdIyK4hu - GvMqLw9z9BgJbWB3BgXOUdlkXLDwBvVpEcWsPJgxSjAvjAbLLE4YkKAdYU8bQ0Pd - JuN485tcXxgQCadFZB0gcipQAvVf4b810HrY88g6FldfauHxiACOlXscZwARAQAB - tDBTTzMgR3JvdXAgTWFpbnRhaW5lcnMgPG1haW50YWluZXJzQHNvM2dyb3VwLm5l - dD6JAjgEEwECACIFAlIIUZwCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJ - ELdE4lqkQubp8GsQAKntoRFG6bWX/4WPw7Vo7kIF5kWcmv3lVb0AQkacscWope7T - Iq0VcgpAycJue2bSS9LAsvNtpVkQmFawbwFjqB3CC5NbPNQ4Kf+gswKa+yaHwejo - 7dkslAwxgXHe5g76DG7CVLMsMg6zVDFYuzeksPywls/OJBIpkuGqeXy9tAHjQzjA - SlZV3Gsx7azESjiVQ73EUBt2OXkwN4TN9TEHAnVsrNIXHwFl1VfFsSG1Q6uZDtkk - CB4DZJKN4RzCY2QSwMAqRRC2OXdwk5IAk8wwCGoFpp0UV6CO9YCeOaqJderEcBA4 - MGHqdiPDIbH5wvckjZzFznU/Paz3MwPwBdtN+WSKvwf+JItSiUqm8Dy2Pl/1cnux - 1g1I4WQlXUVaS/MDusqL7tbS8k5A5a2+YVMxShWH9BhXZwNXzEihl4sm8Hrg5SvZ - givJj2y93WoL69Wq0/86wkkH2xcrz4gsiUcQf5YXU/RHXOLnPR29/pg8TS0L7sST - dv0X23C2IpfqYoqN7YZ3K0Wczhi0yLPCrc27IczuHgjt/8ICda11xhB1t/pUbvnX - oksehaLp8O3uU8GyAsTfUgpijZFc/3jIadOl0L9NGUbYYgPzFeaZTa/njeEbz3wX - PZMn278sbL9UhupI5Hx7eREbKzV4VPVKz81ndKNMXyuJHXv2R0xou3nvuo1WuQIN - BFIIUZwBEADAhoYPDCSogG41Naq+wFkG+IPszqe0dW/UWg0xrZDT0UblwDSd4OGY - 7FATMIhjOUyFxk6+XKA5CDCWP8Npkl0modTL59uVWNxU1vUKincc/j4ipHQeAhE6 - fvZkrprvADD8TYIGesl/3EGNc7bzc5ZqX71hKPHG+autRtgFSOR2PSXD9MlJXIBb - RzHAXxlh72zvsGadcxLJm4pSWXitkR/5Wc3e0IippKdzGwZnCDpNmcBGtSTFgixP - JqyRZFVCPWs7jr/oQeZnq65wJp1KD2HvhhKHJfsPrnNjLSm1SQVh8hXzE9odcv6N - mJB7tNXywuROBt6a01ojBa9J3zuMYQj3iQl2MhxtHylKVBjr7NjZ4evZbLsRMxY1 - hYk7sl+ZxCPFeOZ9D2ppU/CUDXCS095I1x+s+VuiUNf/3yd8ahCWDXVp9nsXyYjm - 2pHIxb2F6r8Vd4AjlD2MQwszECS88INF3l/9ksIHEMKuuW+JAC9FiZ7k4IGcIltv - If/V2TgE6t6qoWIlmLhMTjOyJpwnokY1nIuXHH7yp+HsuqnYnf/dgLnt4czPLeHO - +TdIDHhUym0AKlCcbdgn0C6EJVTnA8BFgFjiIOMAeT0rhATg0W/cND8KQcX4V9wM - nHSEsgSEuP9H+67xuRx5Imuh5ntecrcuCYSNuOneUXWPThDKQPO9lQARAQABiQIf - BBgBAgAJBQJSCFGcAhsMAAoJELdE4lqkQubpc+0P/0IzUx8nTpF0/ii2TA0YCOgj - tviM6PRTVPrFcxijNeXiIMHZYrALYUvXxXGp1IZBP3IcOyuZNp2WLqF/f9a3cIr1 - 9b/LJPrwopGqV3K30lormk7hH0s3IXbhd0ZYWvRj+5kQ8TFRAFfPwjlItzjYJmYX - AGJmM9PxJID/4LgWSfQ/ZfNu7MJ7+2goQLu9b6x7UC1FlE4q1lcjBvHjVPM//S9G - lGAHaysyTjVu88W2wwBpBrO1MQnDvqFRddXPOIWp0jecBMUd4E0fB36yuStsXZT3 - RN4V8vKRBYXuqHhiTwZeh153cHZk2EZBwz5A6DJubMaGdJTesHW5Qf2goph0pmjC - +XuXn8J6tc5nFDf8DP4AFVMtqa3Brj2fodWd0Zzxq3AVsbX144c1oqJUhO4t3+ie - 8fD/6/jx4iuPCQTfyhHG+zGfyUb2LQ+OVLW1WYTxH5tzHaZUmZFdV2I1kuhuvZ1t - WRlmTnHZOnEb3+t8KCRWzRMfweTzXfRRKBC0/QpeX1r5pbaMHH8zF/J5PKmL0+jg - +DS8JSbSfv7Ke6rplf7lHYaDumAFZfxXuQkajzLZbX0E5Xu5BNz4Vq6LGBj7LDXL - gswIK8FFgZB+W8zwOqUV1vjIr9wkdLifXXezKpTeYpFDGLdfsK+uNAtGyvI61TDi - Pr6fWpIruuc7Gg9rUF0L - =VQTr - -----END PGP PUBLIC KEY BLOCK----- - -Next add the VyOS image. - -This example uses VyOS 1.0.0, however, it's better to install the latest -release. - -.. code-block:: none - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - 1: VC6.6R1 (default boot) (running image) - - vyatta@vyatta:~$ add system image https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 223M 100 223M 0 0 960k 0 0:03:57 0:03:57 --:--:-- 657k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 836 100 836 0 0 4197 0 --:--:-- --:--:-- --:--:-- 4287 - Found it. Checking digital signature... - gpg: directory `/root/.gnupg' created - gpg: new configuration file `/root/.gnupg/gpg.conf' created - gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run - gpg: keyring `/root/.gnupg/pubring.gpg' created - gpg: Signature made Sun Dec 22 16:51:42 2013 GMT using RSA key ID A442E6E9 - gpg: /root/.gnupg/trustdb.gpg: trustdb created - gpg: Good signature from "SO3 Group Maintainers <maintainers@so3group.net>" - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - Primary key fingerprint: DD5B B405 35E7 F6E3 4278 1ABF B744 E25A A442 E6E9 - Digital signature is valid. - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [1.0.0]: [return] - OK. This image will be named: 1.0.0 - Installing "1.0.0" image. - Copying new release files... - - Would you like to save the current configuration - directory and config file? (Yes/No) [Yes]: [return] - Copying current configuration... - - Would you like to save the SSH host keys from your - current configuration? (Yes/No) [Yes]: [return] - Copying SSH keys... - Setting up grub configuration... - Done. - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.0.0 (default boot) - 2: VC6.6R1 (running image) - -Upon reboot, you should have a working installation of VyOS. - -You can go back to your Vyatta install using the ``set system image -default-boot`` command and selecting the your previous Vyatta Core image. - -.. note:: Future releases of VyOS will break the direct upgrade path from - Vyatta core. Please upgrade through an intermediate VyOS version e.g. VyOS - 1.2. After this you can continue upgrading to newer releases once you bootet - into VyOS 1.2 once. diff --git a/docs/appendix/release-notes.rst b/docs/appendix/release-notes.rst deleted file mode 100644 index 7ba8baaf..00000000 --- a/docs/appendix/release-notes.rst +++ /dev/null @@ -1,435 +0,0 @@ -.. _release-notes: - -############# -Release Notes -############# - -****************** -Version 1.2 - Crux -****************** - -1.2.6-S1 -======== - -1.2.6-S1 is a security release release made in September 2020. - -Resolved issues ---------------- - -VyOS 1.2.6 release was found to be suspectible to CVE-2020-10995. It's a low- -impact vulnerability in the PowerDNS recursor that allows an attacker to cause -performance degradation via a specially crafted authoritative DNS server reply. - -* :vytask:`2899` remote syslog server migration error on update - -1.2.6 -===== - -1.2.6 is a maintenance release made in September 2020. - -Resolved issues ---------------- - -* :vytask:`103` DHCP server prepends shared network name to hostnames -* :vytask:`125` Missing PPPoE interfaces in l2tp configuration -* :vytask:`1194` cronjob is being setup even if not saved -* :vytask:`1205` module pcspkr missing -* :vytask:`1219` Redundant active-active configuration, asymmetric routing and - conntrack-sync cache -* :vytask:`1220` Show transceiver information from plugin modules, e.g SFP+, - QSFP -* :vytask:`1221` BGP - Default route injection is not processed by the specific - route-map -* :vytask:`1241` Remove of policy route throws CLI error -* :vytask:`1291` Under certain conditions the VTI will stay forever down -* :vytask:`1463` Missing command `show ip bgp scan` appears in command - completion -* :vytask:`1575` `show snmp mib ifmib` crashes with IndexError -* :vytask:`1699` Default net.ipv6.route.max_size 32768 is too low -* :vytask:`1729` PIM (Protocol Independent Multicast) implementation -* :vytask:`1901` Semicolon in values is interpreted as a part of the shell - command by validators -* :vytask:`1934` Change default hostname when deploy from OVA without params. -* :vytask:`1938` syslog doesn't start automatically -* :vytask:`1949` Multihop IPv6 BFD is unconfigurable -* :vytask:`1953` DDNS service name validation rejects valid service names -* :vytask:`1956` PPPoE server: support PADO-delay -* :vytask:`1973` Allow route-map to match on BGP local preference value -* :vytask:`1974` Allow route-map to set administrative distance -* :vytask:`1982` Increase rotation for atop.acct -* :vytask:`1983` Expose route-map when BGP routes are programmed in to FIB -* :vytask:`1985` pppoe: Enable ipv6 modules without configured ipv6 pools -* :vytask:`2000` strongSwan does not install routes to table 220 in certain - cases -* :vytask:`2021` OSPFv3 doesn't support decimal area syntax -* :vytask:`2062` Wrong dhcp-server static route subnet bytes -* :vytask:`2091` swanctl.conf file is not generated properly is more than one - IPsec profile is used -* :vytask:`2131` Improve syslog remote host CLI definition -* :vytask:`2224` Update Linux Kernel to v4.19.114 -* :vytask:`2286` IPoE server vulnerability -* :vytask:`2303` Unable to delete the image version that came from OVA -* :vytask:`2305` Add release name to "show version" command -* :vytask:`2311` Statically configured name servers may not take precedence - over ones from DHCP -* :vytask:`2327` Unable to create syslog server entry with different port -* :vytask:`2332` Backport node option for a syslog server -* :vytask:`2342` Bridge l2tpv3 + ethX errors -* :vytask:`2344` PPPoE server client static IP assignment silently fails -* :vytask:`2385` salt-minion: improve completion helpers -* :vytask:`2389` BGP community-list unknown command -* :vytask:`2398` op-mode "dhcp client leases interface" completion helper - misses interfaces -* :vytask:`2402` Live ISO should warn when configuring that changes won't - persist -* :vytask:`2443` NHRP: Add debugging information to syslog -* :vytask:`2448` `monitor protocol bgp` subcommands fail with 'command - incomplete' -* :vytask:`2458` Update FRR to 7.3.1 -* :vytask:`2476` Bond member description change leads to network outage -* :vytask:`2478` login radius: use NAS-IP-Address if defined source address -* :vytask:`2482` Update PowerDNS recursor to 4.3.1 for CVE-2020-10995 -* :vytask:`2517` vyos-container: link_filter: No such file or directory -* :vytask:`2526` Wake-On-Lan CLI implementation -* :vytask:`2528` "update dns dynamic" throws FileNotFoundError excepton -* :vytask:`2536` "show log dns forwarding" still refers to dnsmasq -* :vytask:`2538` Update Intel NIC drivers to recent release (preparation for - Kernel >=5.4) -* :vytask:`2545` Show physical device offloading capabilities for specified - ethernet interface -* :vytask:`2563` Wrong interface binding for Dell VEP 1445 -* :vytask:`2605` SNMP service is not disabled by default -* :vytask:`2625` Provide generic Library for package builds -* :vytask:`2686` FRR: BGP: large-community configuration is not applied - properly after upgrading FRR to 7.3.x series -* :vytask:`2701` `vpn ipsec pfs enable` doesn't work with IKE groups -* :vytask:`2728` Protocol option ignored for IPSec peers in transport mode -* :vytask:`2734` WireGuard: fwmark CLI definition is inconsistent -* :vytask:`2757` "show system image version" contains additional new-line - character breaking output -* :vytask:`2797` Update Linux Kernel to v4.19.139 -* :vytask:`2822` Update Linux Kernel to v4.19.141 -* :vytask:`2829` PPPoE server: mppe setting is implemented as node instead of - leafNode -* :vytask:`2831` Update Linux Kernel to v4.19.142 -* :vytask:`2852` rename dynamic dns interface breaks ddclient.cache permissions -* :vytask:`2853` Intel QAT acceleration does not work - -1.2.5 -===== - -1.2.5 is a maintenance release made in April 2020. - -Resolved issues ---------------- - -* :vytask:`1020` OSPF Stops distributing default route after a while -* :vytask:`1228` pppoe default-route force option not working (Rel 1.2.0-rc11) -* :vytask:`1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. -* :vytask:`1341` Adding rate-limiter for pppoe server users -* :vytask:`1376` Incorrect DHCP lease counting -* :vytask:`1392` Large firewall rulesets cause the system to lose configuration - and crash at startup -* :vytask:`1416` 2 dhcp server run in failover mode can't sync hostname with - each other -* :vytask:`1452` accel-pppoe - add vendor option to shaper -* :vytask:`1490` BGP configuration (is lost|not applied) when updating 1.1.8 -> - 1.2.1 -* :vytask:`1780` Adding ipsec ike closeaction -* :vytask:`1803` Unbind NTP while it's not requested... -* :vytask:`1821` "authentication mode radius" has no effect for PPPoE server -* :vytask:`1827` Increase default gc_thresh -* :vytask:`1828` Missing completion helper for "set system syslog host - 192.0.2.1 facility all protocol" -* :vytask:`1832` radvd adding feature DNSSL branch.example.com example.com to - existing package -* :vytask:`1837` PPPoE unrecognized option 'replacedefaultroute' -* :vytask:`1851` wireguard - changing the pubkey on an existing peer seems to - destroy the running config. -* :vytask:`1858` l2tp: Delete depricated outside-nexthop and add gateway-address -* :vytask:`1864` Lower IPSec DPD timeout lower limit from 10s -> 2s -* :vytask:`1879` Extend Dynamic DNS XML definition value help strings and - validators -* :vytask:`1881` Execute permissions are removed from custom SNMP scripts at - commit time -* :vytask:`1884` Keeping VRRP transition-script native behaviour and adding - stop-script -* :vytask:`1891` Router announcements broken on boot -* :vytask:`1900` Enable SNMP for VRRP. -* :vytask:`1902` Add redistribute non main table in bgp -* :vytask:`1909` Incorrect behaviour of static routes with overlapping networks -* :vytask:`1913` "system ipv6 blacklist" command has no effect -* :vytask:`1914` IPv6 multipath hash policy does not apply -* :vytask:`1917` Update WireGuard to Debian release 0.0.20191219-1 -* :vytask:`1934` Change default hostname when deploy from OVA without params. -* :vytask:`1935` NIC identification and usage problem in Hyper-V environments -* :vytask:`1936` pppoe-server CLI control features -* :vytask:`1964` SNMP Script-extensions allows names with spaces, but commit - fails -* :vytask:`1967` BGP parameter "enforce-first-as" does not work anymore -* :vytask:`1970` Correct adding interfaces on boot -* :vytask:`1971` Missing modules in initrd.img for PXE boot -* :vytask:`1998` Update FRR to 7.3 -* :vytask:`2001` Error when router reboot -* :vytask:`2032` Monitor bandwidth bits -* :vytask:`2059` Set source-validation on bond vif don't work -* :vytask:`2066` PPPoE interface can be created multiple times - last wins -* :vytask:`2069` PPPoE-client does not works with service-name option -* :vytask:`2077` ISO build from crux branch is failing -* :vytask:`2079` Update Linux Kernel to v4.19.106 -* :vytask:`2087` Add maxfail 0 option to pppoe configuration. -* :vytask:`2100` BGP route adverisement wih checks rib -* :vytask:`2120` "reset vpn ipsec-peer" doesn't work with named peers -* :vytask:`2197` Cant add vif-s interface into a bridge -* :vytask:`2228` WireGuard does not allow ports < 1024 to be used -* :vytask:`2252` HTTP API add system image can return '504 Gateway Time-out' -* :vytask:`2272` Set system flow-accounting disable-imt has syntax error -* :vytask:`2276` PPPoE server vulnerability - - -1.2.4 -===== - -1.2.4 is a maintenance release made in December 2019. - -Resolved issues ---------------- - -* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 -* :vytask:`T818` SNMP v3 - remove required engineid from user node -* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare - API v4) -* :vytask:`T1183` BFD Support via FRR -* :vytask:`T1299` Allow SNMPd to be extended with custom scripts -* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option -* :vytask:`T1391` In route-map set community additive -* :vytask:`T1394` syslog systemd and host_name.py race condition -* :vytask:`T1401` Copying files with the FTP protocol fails if the password - contains special characters -* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes - to fix -* :vytask:`T1430` Add options for custom DHCP client-id and hostname -* :vytask:`T1447` Python subprocess called without import in host_name.py -* :vytask:`T1470` improve output of "show dhcpv6 server leases" -* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf -* :vytask:`T1496` Separate rolling release and LTS kernel builds -* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevents - load balancing from starting -* :vytask:`T1568` strip-private command improvement for additional masking of - IPv6 and MAC address -* :vytask:`T1578` completion offers "show table", but show table does not exist -* :vytask:`T1593` Support ip6gre -* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" -* :vytask:`T1638` vyos-hostsd not setting system domain name -* :vytask:`T1678` hostfile-update missing line feed -* :vytask:`T1694` NTPd: Do not listen on all interfaces by default -* :vytask:`T1701` Delete domain-name and domain-search won't work -* :vytask:`T1705` High CPU usage by bgpd when snmp is active -* :vytask:`T1707` DHCP static mapping and exclude address not working -* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 -* :vytask:`T1709` Update WireGuard to 0.0.20190913 -* :vytask:`T1716` Update Intel NIC drivers to recent versions -* :vytask:`T1726` Update Linux Firmware binaries to a more recent version - 2019-03-14 -> 2019-10-07 -* :vytask:`T1728` Update Linux Kernel to 4.19.79 -* :vytask:`T1737` SNMP tab completion missing -* :vytask:`T1738` Copy SNMP configuration from node to node raises exception -* :vytask:`T1740` Broken OSPFv2 virtual-link authentication -* :vytask:`T1742` NHRP unable to commit. -* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address x must - be greater or equal to the range start address y!" when static mapping has - same IP as range stop -* :vytask:`T1749` numeric validator doesn't support multiple ranges -* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) -* :vytask:`T1772` <regex> constraints in XML are partially broken -* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR -* :vytask:`T1780` Adding ipsec ike closeaction -* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.py - implementation -* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation -* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 -* :vytask:`T1800` Update Linux Kernel to v4.19.84 -* :vytask:`T1809` Wireless: SSID scan does not work in AP mode -* :vytask:`T1811` Upgrade from 1.1.8: Config file migration failed: module=l2tp -* :vytask:`T1812` DHCP: hostnames of clients not resolving after update v1.2.3 - -> 1.2-rolling -* :vytask:`T1819` Reboot kills SNMPv3 configuration -* :vytask:`T1822` Priority inversion wireless interface dhcpv6 -* :vytask:`T1825` Improve DHCP configuration error message -* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails to create - an XML -* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" -* :vytask:`T1841` PPP ipv6-up.d direcotry missing -* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface -* :vytask:`T1903` Implementation udev predefined interface naming -* :vytask:`T1904` update eth1 and eth2 link files for the vep4600 - - -1.2.3 -===== - -1.2.3 is a maintenance and feature backport release made in September 2019. - -New features ------------- - -* HTTP API -* :vytask:`T1524` "set service dns forwarding allow-from <IPv4 net|IPv6 net>" - option for limiting queries to specific client networks -* :vytask:`T1503` Functions for checking if a commit is in progress -* :vytask:`T1543` "set system contig-mangement commit-archive source-address" - option -* :vytask:`T1554` Intel NIC drivers now support receive side scaling and - multiqueue - -Resolved issues ---------------- - -* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit - errors -* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive - lookups on domain specific forwarders -* :vytask:`T1362` Special characters in VRRP passwords are handled correctly -* :vytask:`T1377` BGP weight is applied properly -* :vytask:`T1420` Fixed permission for log files -* :vytask:`T1425` Wireguard interfaces now support /31 addresses -* :vytask:`T1428` Wireguard correctly handles firewall marks -* :vytask:`T1439` DHCPv6 static mappings now work correctly -* :vytask:`T1450` Flood ping commands now works correctly -* :vytask:`T1460` Op mode "show firewall" commands now support counters longer - than 8 digits (T1460) -* :vytask:`T1465` Fixed priority inversion in VTI commands -* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option -* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC - compatibility mode enabled -* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings -* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces -* :vytask:`T1530` Fixed "set system syslog global archive file" command -* :vytask:`T1531` Multiple fixes in cluster configuration scripts -* :vytask:`T1537` Fixed missing help text for "service dns" -* :vytask:`T1541` Fixed input validation in DHCPv6 relay options -* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall - assigned to it in one commit -* :vytask:`T1559` URL filtering now uses correct rule database path and works - again -* :vytask:`T1579` "show log vpn ipsec" command works again -* :vytask:`T1576` "show arp interface <intf>" command works again -* :vytask:`T1605` Fixed regression in L2TP/IPsec server -* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly -* :vytask:`T1616` "renew dhcpv6" command now works from op mode -* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works - correctly now -* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple - improvements in name servers and hosts configuration handling - -Internals ---------- - -``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the -*vyos-hostsd* service that listens on a ZMQ socket for update messages. - -1.2.2 -===== - -1.2.2 is a maintenance release made in July 2019. - -New features ------------- - -* Options for per-interface MSS clamping. -* BGP extended next-hop capability -* Relaxed BGP multipath option -* Internal and external options for "remote-as" (accept any AS as long as it's - the same to this router or different, respectively) -* "Unnumbered" (interface-based) BGP peers -* BGP no-prepend option -* Additive BGP community option -* OSPFv3 network type option -* Custom arguments for VRRP scripts -* A script for querying values from config files - -Resolved issues ---------------- - -* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability -* :vytask:`T1371` VRRP health-check scripts now can use arguments -* :vytask:`T1497` DNS server addresses coming from a DHCP server are now - correctly propagated to resolv.conf -* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used - for recursive queries -* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly -* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors -* :vytask:`T1458` Correct hostname is sent to remote syslog again -* :vytask:`T1438` Board serial number from DMI is correctly displayed in - ``show version`` -* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in - remote syslog config -* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` -* :vytask:`T1174` ``system domain-name`` is correctly included in - ``/etc/resolv.conf`` -* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` - settings -* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines -* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address -* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU -* :vytask:`T1505` vyos.config ``return_effective_values()`` function now - correctly returns a list rather than a string - -1.2.1 -===== - -VyOS 1.2.1 is a maintenance release made in April 2019. - -Resolved issues ---------------- - -* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers -* :vytask:`T1326` The kernel now includes drivers for various USB serial - adapters, which allows people to add a serial console to a machine without - onboard RS232, or connect to something else from the router -* The collection of network card firmware is now much more extensive -* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC - addresses in the RFC-compliant mode -* :vytask:`T1330` DHCP WPAD URL option works correctly again -* :vytask:`T1312` Many to many NAT rules now can use source/destination and - translation networks of non-matching size. If 1:1 network bits translation is - desired, it's now users responsibility to check if prefix length matches. -* :vytask:`T1290` IPv6 network prefix translation is fixed -* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely - used in PPPoE passwords -* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends - with a leaf node such as ``timezone`` in ``show system | commands`` -* :vytask:`T1235` ``show | commands`` correctly works in config mode now -* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option -* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest - Crux -* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses - other than loopback was fixed -* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to - start is fixed -* :vytask:`T1067` VXLAN value validation is improved -* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS - forwarding -* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with - more than one upstream interface -* :vytask:`T1234` ``relay-agents-packets`` option works correctly now -* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change -* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name -* :vytask:`T1279` ACPI power off works again -* :vytask:`T1247` Negation in WAN load balancing rules works again -* :vytask:`T1218` FRR staticd now starts on boot correctly -* :vytask:`T1296` The installer now correctly detects SD card devices -* :vytask:`T1225` Wireguard peers can be disabled now -* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete - is fixed -* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration -* :vytask:`T1060` It's now possible to exclude hosts from the transparent - web proxy -* :vytask:`T484` An issue with rules impossible to delete from the zone-based - firewall is fixed - -Earlier releases -================ - -Release notes for legacy versions (1.1.x, 1.0.x) can be found in the -`archived wiki <https://web.archive.org/web/20200212180711/https://wiki.vyos.net/wiki/Category:Release_notes>`_. diff --git a/docs/appendix/virtual/index.rst b/docs/appendix/virtual/index.rst deleted file mode 100644 index 7ede37b5..00000000 --- a/docs/appendix/virtual/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _virtual: - -Running on Virtual Environments -=============================== - - -.. toctree:: - :maxdepth: 2 - - libvirt - vyos-on-vmware - vyos-on-gns3 diff --git a/docs/appendix/virtual/libvirt.rst b/docs/appendix/virtual/libvirt.rst deleted file mode 100644 index 0d624b94..00000000 --- a/docs/appendix/virtual/libvirt.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _libvirt: - -*************************** -Running on Libvirt Qemu/KVM -*************************** - -Libvirt is an open-source API, daemon and management tool for managing platform virtualization. -There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. -In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. - -CLI -=== - -Deploy from ISO ---------------- - -Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. -The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. - -.. code-block:: none - - $ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom /var/lib/libvirt/images/vyos.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r1`` - -.. code-block:: none - - $ virsh console vyos_r1 - - Connected to domain vyos_r1 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ install image - -After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. - -Deploy from qcow2 ------------------ -The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: none - - $ virt-install -n vyos_r2 \ - --ram 4096 \ - --vcpus 2 \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r2`` - -.. code-block:: none - - $ virsh console vyos_r2 - - Connected to domain vyos_r2 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ - -The system is fully operational. - -Virt-manager -============ -The virt-manager application is a desktop user interface for managing virtual machines through libvirt. -On the linux open :abbr:`VMM (Virtual Machine Manager)`. - -Deploy from ISO ---------------- - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Local install media`` (ISO) - -.. figure:: /_static/images/virt-libvirt-01.png - -3. Choose path to iso vyos.iso. Operating System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.png - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -7. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.png - -Deploy from qcow2 ------------------ - -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Import existing disk`` image - -.. figure:: /_static/images/virt-libvirt-qc-01.png - -3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-qc-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -6. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.png - - - diff --git a/docs/appendix/virtual/vyos-on-gns3.rst b/docs/appendix/virtual/vyos-on-gns3.rst deleted file mode 100644 index 93ea9ae2..00000000 --- a/docs/appendix/virtual/vyos-on-gns3.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _vyos-on-gns3: - -############### -Running on GNS3 -############### - -Sometimes you may want to test VyOS in a lab environment. -`GNS3 <http://www.gns3.com>`__ is a network emulation software you -might use for it. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -Requirements ------------- - -The following items are required: - -* A VyOS installation image (.iso file). - `Here <https://docs.vyos.io/en/latest/install.html#download>`__ you - can find how to get it. - -* A working GNS3 installation. For further information see the - `GNS3 documentation <https://docs.gns3.com/>`__. - -.. _vm_setup: - -VM setup --------- - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template** and choose select -**Manually create a new Template**. - -.. figure:: /_static/images/gns3-01.png - -Select **Quemu VMs** and then click on the ``New`` button. - -.. figure:: /_static/images/gns3-02.png - -Write a name for your VM, for instance "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.png - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.png - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.png - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.png - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.png - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.png - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.png - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.png - -Now the VM settings have to be edited. - -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the ``Edit`` button. - -.. figure:: /_static/images/gns3-11.png - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -* Click on the ``Browse...`` button to choose the **Symbol** you want to - have representing your VM. -* In **Category** select in which group you want to find your VM. -* Set the **Boot priority** to **CD/DVD-ROM**. - -.. figure:: /_static/images/gns3-12.png - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.png - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.png - -.. note:: You probably will want to accept to copy the .iso file to your - default image directory when you are asked. - -In the **Network** tab, set **0** as the number of adapters, set the -**Name format** to **eth{0}** and the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -.. figure:: /_static/images/gns3-15.png - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click ``OK``, which will save and close the **QEMU VM template -configuration** window. - -.. figure:: /_static/images/gns3-16.png - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.png - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. -* `Install VyOS <https://docs.vyos.io/en/latest/install.html#install>`__ - as normal (that is, using the ``install image`` command). - -* After a successful installation, shutdown the VM with the ``poweroff`` - command. - -* **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -.. _vyos_vm_configuration: - -VyOS VM configuration ---------------------- - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -.. figure:: /_static/images/gns3-20.png - -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. - -.. figure:: /_static/images/gns3-21.png - -Set the number of required network adapters, for example **4**. - -.. figure:: /_static/images/gns3-215.png - -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.png - -The VyOS VM is now ready to be deployed. - diff --git a/docs/appendix/virtual/vyos-on-vmware.rst b/docs/appendix/virtual/vyos-on-vmware.rst deleted file mode 100644 index c4299cbf..00000000 --- a/docs/appendix/virtual/vyos-on-vmware.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _vyosonvmware:
-
-Running on VMware ESXi
-######################
-
-ESXi 5.5 or later
-*****************
-
-.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO
-using the normal process around `install image`.
-
-.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised.
-
-Memory Contention Considerations
---------------------------------
-When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems.
-This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to
-force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of
-guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted
-lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel.
-
-It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests.
-
-
-
-
-
-References
-----------
-
-https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html
-
diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst deleted file mode 100644 index db618431..00000000 --- a/docs/appendix/vyos-on-baremetal.rst +++ /dev/null @@ -1,411 +0,0 @@ -.. _vyosonbaremetal: - -##################### -Running on Bare Metal -##################### - -Supermicro A2SDi (Atom C3000) -============================= - -I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. -Running VyOS on an UEFI only device is supported as of VyOS release 1.2. - -Shopping Cart -------------- - -* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) -* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) -* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN - with Intel C3000 SoC 1GbE) -* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) -* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) -* 1x Supermicro MCP-320-81302-0B (optional FAN tray) - -Optional (10GE) ---------------- -If you want to get additional ethernet ports or even 10GE connectivity -the following optional parts will be required: - -* 1x Supermicro RSC-RR1U-E8 (Riser Card) -* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) - -Latest VyOS rolling releases boot without any problem on this board. You also -receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no -information about `OpenBMC <https://www.openbmc.org/>`_ so far on this -motherboard). - -Pictures --------- - -.. figure:: /_static/images/1u_vyos_back.jpg - :scale: 25 % - :alt: CSE-505-203B Back - -.. figure:: /_static/images/1u_vyos_front.jpg - :scale: 25 % - :alt: CSE-505-203B Front - -.. figure:: /_static/images/1u_vyos_front_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B Open 1 - -.. figure:: /_static/images/1u_vyos_front_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B Open 2 - -.. figure:: /_static/images/1u_vyos_front_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 1 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 2 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open - - -.. _pc-engines-apu4: - -PC Engines APU4 -================ - -As this platform seems to be quite common in terms of noise, cost, power and -performance it makes sense to write a small installation manual. - -This guide was developed using an APU4C4 board with the following specs: - -* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI - support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. -* 4 GB DDR3-1333 DRAM, with optional ECC support -* About 6 to 10W of 12V DC power depending on CPU load -* 2 miniPCI express (one with SIM socket for 3G modem). -* 4 Gigabit Ethernet channels using Intel i211AT NICs - -The board can be powered via 12V from the front or via a 5V onboard connector. - -Shopping Cart -------------- - -* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM -* 1x Kingston SUV500MS/120G -* 1x VARIA Group Item 326745 19" dual rack for APU4 - -The 19" enclosure can accommodate up to two APU4 boards - there is a single and -dual front cover. - -Extension Modules -^^^^^^^^^^^^^^^^^ - -WiFi -"""" - -Refer to :ref:`wireless-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform: - -* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. - -WWAN -"""" - -Refer to :ref:`wwan-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform using VyOS 1.3 (equuleus): - -* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -* Huawei ME909u-521 miniPCIe card (LTE) - -VyOS 1.2 (crux) ---------------- - -Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (:vytask:`T1327`). - -Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. - -Connect serial port to a PC through null modem cable (RXD / TXD crossed over). -Set terminal emulator to 115200 8N1. - -.. code-block:: none - - PC Engines apu4 - coreboot build 20171130 - BIOS version v4.6.4 - 4080 MB ECC DRAM - SeaBIOS (version rel-1.11.0.1-0-g90da88d) - - Press F10 key now for boot menu: - - Select boot device: - - 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) - 2. USB MSC Drive Generic Flash Disk 8.07 - 3. Payload [memtest] - 4. Payload [setup] - -Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing -``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` -to continue. - -.. code-block:: none - - lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk - x VyOS - Boot Menu x - tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu - x Live (amd64-vyos) x - x Live (amd64-vyos failsafe) x - x x - mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj - -The image will be loaded and the last lines you will get will be: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - -The Kernel will now spin up using a different console setting. Set terminal -emulator to 9600 8N1 and after a while your console will show: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - Welcome to VyOS - vyos ttyS0 - - vyos login: - -You can now proceed with a regular image installation as described in -:ref:`installation`. - -As the APU board itself still used a serial setting of 115200 8N1 it is -strongly recommended that you change the VyOS serial interface settings after -your first successful boot. - -Use the following command to adjust the :ref:`serial-console` settings: - -.. code-block:: none - - set system console device ttyS0 speed 115200 - -.. note:: Once you ``commit`` the above changes access to the serial interface - is lost until you set your terminal emulator to 115200 8N1 again. - -.. code-block:: none - - vyos@vyos# show system console - device ttyS0 { - speed 115200 - } - -VyOS 1.2 (rolling) ------------------- - -Installing the rolling release on an APU2 board does not require any change -on the serial console from your host side as :vytask:`T1327` was successfully -implemented. - -Simply proceed with a regular image installation as described in -:ref:`installation`. - -Pictures --------- - -.. note:: Both device types operate without any moving parts and emit zero - noise. - -Rack Mount -^^^^^^^^^^ - -.. figure:: /_static/images/apu4_rack_1.jpg - :scale: 25 % - :alt: APU4 rack closed - -.. figure:: /_static/images/apu4_rack_2.jpg - :scale: 25 % - :alt: APU4 rack front - -.. figure:: /_static/images/apu4_rack_3.jpg - :scale: 25 % - :alt: APU4 rack module #1 - -.. figure:: /_static/images/apu4_rack_4.jpg - :scale: 25 % - :alt: APU4 rack module #2 - -.. figure:: /_static/images/apu4_rack_5.jpg - :scale: 25 % - :alt: APU4 rack module #3 with PSU - -VyOS custom print -""""""""""""""""" - -.. figure:: /_static/images/apu4_rack_vyos_print.jpg - :scale: 25 % - :alt: APU4 custom VyOS powder coat - -Desktop / Bench Top -^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/apu4_desk_1.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_2.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_3.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. figure:: /_static/images/apu4_desk_4.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. _Rufus: https://rufus.ie/ - -Qotom Q355G4 -============ - -The install on this Q355G4 box is pretty much plug and play. The port numbering -the OS does might differ from the labels on the outside, but the UEFI firmware -has a port blink test built in with MAC addresses so you can very quickly -identify which is which. MAC labels are on the inside as well, and this test -can be done from VyOS or plain Linux too. Default settings in the UEFI will -make it boot, but depending on your installation wishes (i.e. storage type, -boot type, console type) you might want to adjust them. This Qotom company -seems to be the real OEM/ODM for many other relabelling companies like -Protectli. - -Hardware --------- - -There are a number of other options, but they all seem to be close to Intel -reference designs, with added features like more serial ports, more network -interfaces and the likes. Because they don't deviate too much from standard -designs all the hardware is well-supported by mainline. It accepts one LPDDR3 -SO-DIMM, but chances are that if you need more than that, you'll also want -something even beefier than an i5. There are options for antenna holes, and SIM -slots, so you could in theory add an LTE/Cell modem (not tested so far). - -The chassis is a U-shaped alu extrusion with removable I/O plates and removable -bottom plate. Cooling is completely passive with a heatsink on the SoC with -internal and external fins, a flat interface surface, thermal pad on top of -that, which then directly attaches to the chassis, which has fins as well. It -comes with mounting hardware and rubber feet, so you could place it like a -desktop model or mount it on a VESA mount, or even wall mount it with the -provided mounting plate. The closing plate doubles as internal 2.5" mounting -place for an HDD or SSD, and comes supplied with a small SATA cable and SATA -power cable. - -Power supply is a 12VDC barrel jack, and included switching power supply, which -is why SATA power regulation is on-board. Internally it has a NUC-board-style -on-board 12V input header as well, the molex locking style. - -There are WDT options and auto-boot on power enable, which is great for remote -setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled -in enforcement mode, which is good but also means no coreboot option), yet has -most options available to configure (so it's not locked out like most firmwares -are). - -An external RS232 serial port is available, internally a GPIO header as well. -It does have Realtek based audio on board for some reason, but you can disable -that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS -mode and HDMI BIOS mode depends on what is connected at startup; it goes into -serial mode if you disconnect HDMI and plug in serial, in all other cases it's -HDMI mode. - -Partaker i5 -=========== - -.. figure:: ../_static/images/600px-Partaker-i5.jpg - -I believe this is actually the same hardware as the Protectli. I purchased it -in June 2018. It came pre-loaded with pfSense. - -`Manufacturer product page <http://www.inctel.com.cn/product/detail/338.html>`_. - -Installation ------------- - -* Write VyOS ISO to USB drive of some sort -* Plug in VGA, power, USB keyboard, and USB drive -* Press "SW" button on the front (this is the power button; I don't know what - "SW" is supposed to mean). -* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, - but with a few tries you should be able to get into the BIOS. -* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 - (EHCI) to Enabled. Without doing this, the USB drive won't boot. -* Boot to the VyOS installer and install as usual. - -Warning the interface labels on my device are backwards; the left-most "LAN4" -port is eth0 and the right-most "LAN1" port is eth3. - -Acrosser AND-J190N1 -=================== - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg - -This microbox network appliance was build to create OpenVPN bridges. It can -saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN -http://www.acrosser.com/upload/AND-J190_J180N1-2.pdf - -You may have to add your own RAM and HDD/SSD. There is no VGA connector. But -Acrosser provides a DB25 adapter for the VGA header on the motherboard (not -used). - -BIOS Settings: --------------- - -First thing you want to do is getting a more user friendly console to configure -BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. - -For practical issues change speed from 115200 to 9600. 9600 is the default -speed at which both linux kernel and VyOS will reconfigure the serial port -when loading. - -Connect to serial (115200bps). Power on the appliance and press Del in the -console when requested to enter BIOS settings. - -Advanced > Serial Port Console Redirection > Console Redirection Settings: - -* Terminal Type : VT100+ -* Bits per second : 9600 - -Save, reboot and change serial speed to 9600 on your client. - -Some options have to be changed for VyOS to boot correctly. With XHCI enabled -the installer can’t access the USB key. Enable EHCI instead. - -Reboot into BIOS, Chipset > South Bridge > USB Configuration: - -* Disable XHCI -* Enable USB 2.0 (EHCI) Support - -Install VyOS: -------------- - -Create a VyOS bootable USB key. I used the 64-bit ISO (VyOS 1.1.7) and -`LinuxLive USB Creator <http://www.linuxliveusb.com/>`_. - -I'm not sure if it helps the process but I changed default option to live-serial -(line “default xxxx”) on the USB key under syslinux/syslinux.cfg. - -I connected the key to one black USB port on the back and powered on. The first -VyOS screen has some readability issues. Press :kbd:`Enter` to continue. - -Then VyOS should boot and you can perform the ``install image`` diff --git a/docs/appendix/vyos-on-clouds.rst b/docs/appendix/vyos-on-clouds.rst deleted file mode 100644 index 33b7011e..00000000 --- a/docs/appendix/vyos-on-clouds.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. _vyos-on-clouds: - -Running on Clouds -################# - -Amazon AWS -********** - -Deploy VM ---------- - -Deploy VyOS on Amazon :abbr:`AWS (Amazon Web Services)` - -1. Click to ``Instances`` and ``Launch Instance`` - -.. figure:: /_static/images/cloud-aws-01.png - -2. On the marketplace search "VyOS" - -.. figure:: /_static/images/cloud-aws-02.png - -3. Choose the instance type. Minimum recommendation start from ``m3.medium`` - -.. figure:: /_static/images/cloud-aws-03.png - -4. Configure instance for your requirements. Select number of instances / network / subnet - -.. figure:: /_static/images/cloud-aws-04.png - -5. Additional storage. You can remove additional storage ``/dev/sdb``. First root device will be ``/dev/xvda``. You can skeep this step. - -.. figure:: /_static/images/cloud-aws-05.png - -6. Configure Security Group. It's recommended that you configure ssh access only from certain address sources. Or permit any (by default). - -.. figure:: /_static/images/cloud-aws-06.png - -7. Select SSH key pair and click ``Launch Instances`` - -.. figure:: /_static/images/cloud-aws-07.png - -8. Find out your public IP address. - -.. figure:: /_static/images/cloud-aws-08.png - -9. Connect to the instance by SSH key. - - .. code-block:: none - - ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 - vyos@ip-192-0-2-10:~$ - - - - -References ----------- -https://console.aws.amazon.com/ - -Azure -***** - -Deploy VM ---------- - -Deploy VyOS on Azure. - -1. Go to the Azure services and Click to **Add new Virtual machine** - -2. Choose vm name, resource group, region and click **Browse all public and private images** - -.. figure:: /_static/images/cloud-azure-01.png - -3. On the marketplace search ``VyOS`` - -.. figure:: /_static/images/cloud-azure-02.png - -4. Generate new SSH key pair or use existing. - -.. figure:: /_static/images/cloud-azure-03.png - -5. Define network, subnet, Public IP. Or it will be created by default. - -.. figure:: /_static/images/cloud-azure-04.png - -6. Click ``Review + create``. After fiew second your deployment will be complete - -.. figure:: /_static/images/cloud-azure-05.png - -7. Click to your new vm and find out your Public IP address. - -.. figure:: /_static/images/cloud-azure-06.png - -8. Connect to the instance by SSH key. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 - vyos@vyos-doc-r1:~$ - -Add interface -------------- - -If instance was deployed with one **eth0** ``WAN`` interface and want to add new one. -To add new interface an example **eth1** ``LAN`` you need shutdown the instance. Attach the interface in the Azure portal and then start the instance. - -.. NOTE:: Azure does not allow you attach interface when the instance in the **Running** state. - -References ----------- -https://azure.microsoft.com - -Google Cloud Platform -********************* - -Deploy VM ---------- - -To deploy VyOS on GCP (Google Cloud Platform) - -1. Generate SSH key pair type **ssh-rsa** from the host that will connect to VyOS. - - Example: - - .. code-block:: none - - ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" - - -.. NOTE:: In name "vyos@mypc" The first value must be "**vyos**". Because default user is vyos and google api uses this option. - - -2. Open GCP console and navigate to the menu **Metadata**. Choose **SSH Keys** and click ``edit``. - -.. figure:: /_static/images/cloud-gcp-01.png - - -Click **Add item** and paste your public ssh key. Click ``Save``. - -.. figure:: /_static/images/cloud-gcp-02.png - - -2. On marketplace search "VyOS" - -3. Change Deployment name/Zone/Machine type and click ``Deploy`` - -.. figure:: /_static/images/cloud-gcp-03.png - -4. After fiew seconds click to ``instance`` - -.. figure:: /_static/images/cloud-gcp-04.png - -5. Find out your external IP address - -.. figure:: /_static/images/cloud-gcp-05.png - -6. Connect to the instance. SSH key was generated in the first step. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 - vyos@vyos-r1-vm:~$ - -References ----------- -https://console.cloud.google.com/ - -Oracle -***************** - -References ----------- -https://www.oracle.com/cloud/ |