diff options
46 files changed, 1132 insertions, 211 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 496659bb..7390c11f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,17 @@ # Contributor's Guide 1. fork the project on GitHub https://github.com/vyos/vyos-documentation -2. clone the fork -3. create a a new branch for your work. You can use a name that describes what you do. +2. clone the fork to your local machine ```shell - git checkout -b fix-vxlan-typo + $ git clone https://github.com/YOUR_USERNAME/vyos-documentation +3. cd to your new local directory vyos-documentation +4. create a a new branch for your work. You can use a name that describes what you do. + ```shell + $ git checkout -b fix-vxlan-typo ``` -4. make your changes. +5. make your changes. - Please check the documation, if you don't familiar with [sphinx-doc](http://http://www.sphinx-doc.org) or [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) + Please check the documentation if you aren't familiar with [sphinx-doc](http://http://www.sphinx-doc.org) or [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) Note the following RFCs, which describe the reserved public IP addresses and autonomous system numbers for the documentation. [RFC5737](https://tools.ietf.org/html/rfc5737), [RFC3849](https://tools.ietf.org/html/rfc3849), [RFC5389](https://tools.ietf.org/html/rfc5398), [RFC7042](https://tools.ietf.org/html/rfc7042) @@ -23,25 +26,59 @@ Please don't use other public address space. +6. Check your changes by locally building the documentation + ```shell + $ cd docs + $ make html + ``` + Sphinx will build the html files in the docs/_build folder -5. add the modified files +7. add the modified files ```shell - git add path/to/filname + $ git add path/to/filname ``` or add all unstaged files ```shell - git add . + $ git add . ```` -6. commit your changes +8. commit your changes ```shell - git commit -m "rename vxlan set syntax" + $ git commit -m "rename vxlan set syntax" ``` -7. push your commits to your GitHub project: +9. push your commits to your GitHub project: ```shell - git push -u origin fix-vxlan-typo + $ git push -u origin fix-vxlan-typo ``` -8. Submit a pull request. +10. submit a pull request. In GitHub, visit the main repository and you should see a banner - suggesting to make a pull request. Fill out the form and describe what you do.
\ No newline at end of file + suggesting to make a pull request. Fill out the form and describe what you do. + +11. once pull resquests have been approved, you may want to locally update your forked repository too. First you'll have to add the remote upstream repository. + ```shell + $ git remote add upstream https://github.com/vyos/vyos-documentation.git + ``` + + Check your configured remote repositories. + ```shell + $ git remote -v + origin https://github.com/YOUR_USERNAME/vyos-documentation.git (fetch) + origin https://github.com/YOUR_USERNAME/vyos.documentation.git (push) + upstream https://github.com/vyos/vyos-documentation.git (fetch) + upstream https://github.com/vyos/vyos-documentation.git (push) + ``` + + Your remote repo on Github is called Origin, while the original repo you have forked is called Upstream. + + Now you can locally update your forked repo. + ```shell + $ git fetch upstream + $ git checkout master + $ git merge upstream/master + ``` + If you want to update your fork on Github too: + ```shell + $ git push origin master + ``` + diff --git a/docs/_static/images/apu4c4_rack_5.jpg b/docs/_static/images/apu4c4_rack_5.jpg Binary files differnew file mode 100644 index 00000000..534bbad6 --- /dev/null +++ b/docs/_static/images/apu4c4_rack_5.jpg diff --git a/docs/appendix/examples/azure-vpn-bgp.rst b/docs/appendix/examples/azure-vpn-bgp.rst new file mode 100644 index 00000000..818817ae --- /dev/null +++ b/docs/appendix/examples/azure-vpn-bgp.rst @@ -0,0 +1,128 @@ +.. _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. + +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:: sh + + 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:: sh + + set vpn ipsec ipsec-interfaces interface 'eth0' + +- Configure a VTI with a dummy IP address + +.. code-block:: sh + + 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:: sh + + set firewall options interface vti1 adjust-mss 1350 + +- Configure the VPN tunnel + +.. code-block:: sh + + 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:: sh + + set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 + +- Configure your BGP settings + +.. code-block:: sh + + 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:: sh + + 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 new file mode 100644 index 00000000..4cbcde3b --- /dev/null +++ b/docs/appendix/examples/azure-vpn-dual-bgp.rst @@ -0,0 +1,155 @@ +.. _examples-azure-vpn-dual-bgp: + +Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) +---------------------------------------------------------------------- + +This guide shows an example of a redundant (active-active) route-based IKEv2 +site-to-site VPN to Azure using VTI +and BGP for dynamic routing updates. + +Prerequisites +^^^^^^^^^^^^^ + +- A pair of Azure VNet Gateways deployed in active-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 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:: sh + + 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:: sh + + set vpn ipsec ipsec-interfaces interface 'eth0' + +- Configure two VTIs with a dummy IP address each + +.. code-block:: sh + + 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:: sh + + set firewall options interface vti1 adjust-mss 1350 + set firewall options interface vti2 adjust-mss 1350 + +- Configure the VPN tunnels + +.. code-block:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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/index.rst b/docs/appendix/examples/index.rst index a77ee380..0f4ba595 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/appendix/examples/index.rst @@ -13,3 +13,6 @@ This chapter contains various configuration Examples zone-policy bgp-ipv6-unnumbered ospf-unnumbered + azure-vpn-bgp + azure-vpn-dual-bgp + tunnelbroker-ipv6 diff --git a/docs/appendix/examples/tunnelbroker-ipv6.rst b/docs/appendix/examples/tunnelbroker-ipv6.rst new file mode 100644 index 00000000..e05d77a5 --- /dev/null +++ b/docs/appendix/examples/tunnelbroker-ipv6.rst @@ -0,0 +1,151 @@ +.. _examples-tunnelbroker-ipv6: + +VyOS Tunnelbroker.net IPv6 +-------------------------- + +This guides walks through the setup of `Tunnelbroker.net <https://www.tunnelbroker.net/>`_ for an IPv6 Tunnel. + +Prerequisites +^^^^^^^^^^^^^ + +- A public IP 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. +- An account at `Tunnelbroker.net <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. + +Setting up the initial tunnel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Set up the initial IPv6 tunnel. Replace the field below from the fields on the `Tunnelbroker.net <https://www.tunnelbroker.net/>`_ tunnel information page. + +.. code-block:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + # 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:: sh + + set interfaces ethernet eth1 address '2001:470:xxxx:xxxx::1/64' + set interfaces ethernet eth1 ipv6 router-advert name-server '2001:4860:4860::8888' + set interfaces ethernet eth1 ipv6 router-advert name-server '2001:4860:4860::8844' + set interfaces ethernet eth1 ipv6 router-advert prefix 2001:470:xxxx:xxxx::/64 autonomous-flag 'true' + set interfaces ethernet eth1 ipv6 router-advert prefix 2001:470:xxxx:xxxx::/64 on-link-flag 'true' + set interfaces ethernet eth1 ipv6 router-advert prefix 2001:470:xxxx:xxxx::/64 valid-lifetime '2592000' + + +- 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:: sh + + set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' + set interfaces ethernet eth1 ipv6 router-advert name-server '2001:4860:4860::8888' + set interfaces ethernet eth1 ipv6 router-advert name-server '2001:4860:4860::8844' + set interfaces ethernet eth1 ipv6 router-advert prefix 2001:470:xxxx:1::/64 autonomous-flag 'true' + set interfaces ethernet eth1 ipv6 router-advert prefix 2001:470:xxxx:1::/64 on-link-flag 'true' + set interfaces ethernet eth1 ipv6 router-advert prefix 2001:470:xxxx:1::/64 valid-lifetime '2592000' + + set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' + set interfaces ethernet eth2 ipv6 router-advert name-server '2001:4860:4860::8888' + set interfaces ethernet eth2 ipv6 router-advert name-server '2001:4860:4860::8844' + set interfaces ethernet eth2 ipv6 router-advert prefix 2001:470:xxxx:2::/64 autonomous-flag 'true' + set interfaces ethernet eth2 ipv6 router-advert prefix 2001:470:xxxx:2::/64 on-link-flag 'true' + set interfaces ethernet eth2 ipv6 router-advert prefix 2001:470:xxxx:2::/64 valid-lifetime '2592000' + + set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' + set interfaces ethernet eth3 ipv6 router-advert name-server '2001:4860:4860::8888' + set interfaces ethernet eth3 ipv6 router-advert name-server '2001:4860:4860::8844' + set interfaces ethernet eth3 ipv6 router-advert prefix 2001:470:xxxx:3::/64 autonomous-flag 'true' + set interfaces ethernet eth3 ipv6 router-advert prefix 2001:470:xxxx:3::/64 on-link-flag 'true' + set interfaces ethernet eth3 ipv6 router-advert prefix 2001:470:xxxx:3::/64 valid-lifetime '2592000' + +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/releasenotes.rst b/docs/appendix/releasenotes.rst index 933476eb..13e8fa1c 100644 --- a/docs/appendix/releasenotes.rst +++ b/docs/appendix/releasenotes.rst @@ -6,6 +6,57 @@ Release notes 1.2 (Crux) ========== +1.2.3 +----- + +1.2.3 is a maintenance and feature backport release made in September 2019. + +New features +^^^^^^^^^^^^ + +* HTTP API +* "set service dns forwarding allow-from <IPv4 net|IPv6 net>" option for limiting queries to specific client networks (T1524) +* Functions for checking if a commit is in progress (T1503) +* "set system contig-mangement commit-archive source-address" option (T1543) +* Intel NIC drivers now support receive side scaling and multiqueue (T1554) + +Resolved issues +^^^^^^^^^^^^^^^ + +* OSPF max-metric values over 100 no longer causes commit errors (T1209) +* Fixes issue with DNS forwarding not performing recursive lookups on domain specific forwarders (T1333) +* Special characters in VRRP passwords are handled correctly (T1362) +* BGP weight is applied properly (T1377) +* Fixed permission for log files (T1420) +* Wireguard interfaces now support /31 addresses (T1425) +* Wireguard correctly handles firewall marks (T1428) +* DHCPv6 static mappings now work correctly (T1439) +* Flood ping commands now works correctly (T1450) +* Op mode "show firewall" commands now support counters longer than 8 digits (T1460) +* Fixed priority inversion in VTI commands (T1465) +* Fixed remote-as check in the BGP route-reflector-client option (T1468) +* It's now possible to re-create VRRP groups with RFC compatibility mode enabled (T1472) +* Fixed a typo in DHCPv6 server help strings (T1527) +* Unnumbered BGP peers now support VLAN interfaces (T1529) +* Fixed "set system syslog global archive file" command (T1530) +* Multiple fixes in cluster configuration scripts (T1531) +* Fixed missing help text for "service dns" (T1537) +* Fixed input validation in DHCPv6 relay options (T1541) +* It's now possible to create a QinQ interface and a firewall assigned to it in one commit (T1551) +* URL filtering now uses correct rule database path and works again (T1559) +* "show log vpn ipsec" command works again (T1579) +* "show arp interface <intf>" command works again (T1576) +* Fixed regression in L2TP/IPsec server (T1605) +* Netflow/sFlow captures IPv6 traffic correctly (T1613) +* "renew dhcpv6" command now works from op mode (T1616) +* BGP remove-private-as option iBGP vs eBGP check works correctly now (T1642) +* Multiple improvements in name servers and hosts configuration handling (T1540, T1360, T1264, T1623) + +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 ----- diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 66b68c09..3d5814e4 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -30,7 +30,7 @@ the following optional parts will be required: 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. +about `OpenBMC <https://www.openbmc.org/>`_ so far on this motherboard). Pictures -------- @@ -94,10 +94,13 @@ 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 10" dual rack rack for APU4 +* 1x VARIA Group Item 326745 19" dual rack rack for APU4 +* 1x Compex WLE900VX (Optional mini PCIe WiFi module) -The 19" enclosure can accomodate two APU4 boards - there is a single and dual -cover. +The 19" enclosure can accomodate up to two APU4 boards - there is a single and +dual front cover. + +.. note:: Compex WLE900VX is only supported in mPCIe slot 1. VyOS 1.2 (crux) --------------- @@ -162,7 +165,7 @@ emulator to 9600 8N1 and after a while your console will show: 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 +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. @@ -215,6 +218,11 @@ Rack Mount :scale: 25 % :alt: APU4C4 rack module #2 +.. figure:: /_static/images/apu4c4_rack_5.jpg + :scale: 25 % + :alt: APU4C4 rack module #3 with PSU + + Desktop ^^^^^^^ @@ -360,13 +368,13 @@ Reboot into BIOS, Chipset > South Bridge > USB Configuration: Install VyOS: ------------- -Create a VyOS bootable USB key. I Used the 64bits iso (VyOS 1.1.7) and live USB -installer (http://www.linuxliveusb.com/) +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 enter to continue. +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-vmware.rst b/docs/appendix/vyos-on-vmware.rst new file mode 100644 index 00000000..6feb95ba --- /dev/null +++ b/docs/appendix/vyos-on-vmware.rst @@ -0,0 +1,32 @@ +.. _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 artifical 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/build-vyos.rst b/docs/build-vyos.rst index b5f10954..bcd32ecb 100644 --- a/docs/build-vyos.rst +++ b/docs/build-vyos.rst @@ -3,14 +3,17 @@ Building VyOS using Docker ========================== -This will guide you though the process of building a VyOS ISO yourself using Docker and works best on a fresh installation of Debain 9 (Stretch). +This will guide you though the process of building a VyOS ISO yourself using +Docker and works best on a fresh installation of Debain 8 (Jessie). -.. note:: Starting with VyOS 1.2 the developers have decided to change their release model. - VyOS is now **free as in speech, but not as in beer**, meaning that while VyOS is still an open source project, the release ISO's are no longer free and can only be obtained via subscription, or by contributing to the community. - Since the source code is still public you can build your own ISO using the process described here. - - -Installing Docker and it's prequisites +.. note:: Starting with VyOS 1.2 the developers have decided to change their + release model. VyOS is now **free as in speech, but not as in beer**, meaning + that while VyOS is still an open source project, the release ISO's are no + longer free and can only be obtained via subscription, or by contributing to + the community. Since the source code is still public you can build your own + ISO using the process described here. + +Installing Docker and it's prerequisites .. code-block:: sh @@ -20,16 +23,18 @@ Installing Docker and it's prequisites root@build:~$ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" root@build:~$ apt update root@build:~$ apt install docker-ce - -Adding you user to the docker group to be able to execute the docker command without sudo +Adding you user to the docker group to be able to execute the ``docker`` command +without sudo. .. code-block:: sh root@build:~$ usermod -aG docker user -.. note:: It is recommended to use a non-root user from here on out +.. note:: It is recommended to use a non-root user from here on out. +.. note:: The build process needs to be built on a local file system, building + on SMB or NFS shares is not supported! Cloning the vyos-build crux branch and creating the docker container @@ -38,21 +43,17 @@ Cloning the vyos-build crux branch and creating the docker container user@build:~$ git clone -b crux --single-branch https://github.com/vyos/vyos-build.git user@build:~$ cd vyos-build user@build:~/vyos-build$ docker build -t vyos-builder docker - - -Running the container and building the ISO +Running the container and building the ISO .. code-block:: sh user@build:~$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos-builder bash vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 --build-by "your@email.tld" --build-type release --version 1.2.0 vyos_bld@d4220bb519a0:/vyos# sudo make iso - - -You may use these options to customize you ISO -.. code-block:: sh +You may use these options to customize you ISO +code-block:: sh -h, --help show this help message and exit --architecture ARCHITECTURE @@ -76,5 +77,5 @@ You may use these options to customize you ISO Custom APT entry --custom-apt-key CUSTOM_APT_KEY Custom APT key file - + *Your freshly built ISO should now be in the build directory. Good luck!* diff --git a/docs/clustering.rst b/docs/clustering.rst index 74cfcf42..d51f0073 100644 --- a/docs/clustering.rst +++ b/docs/clustering.rst @@ -3,7 +3,7 @@ Clustering ========== -The cluster feature allows 2 vyos routers to share IP adresses and various services. +The cluster feature allows 2 vyos routers to share IP addresses and various services. VyOS supports multicast clustering. diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 67bc6316..7d0e8767 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -105,7 +105,7 @@ The working configuration is the configuration which is currently being modified Saved configuration ^^^^^^^^^^^^^^^^^^^ -A saved configuration is a configuration saved to a file using the `save` command. It allowes you to keep safe a configuration for future uses. There can be multiple configuration files. The default or "boot" configuration is saved and loaded from the file config.boot. +A saved configuration is a configuration saved to a file using the `save` command. It allows you to keep safe a configuration for future uses. There can be multiple configuration files. The default or "boot" configuration is saved and loaded from the file config.boot. Navigating in Configuration Mode @@ -117,7 +117,7 @@ to enter configuration mode enter the command `configure` when in operational mo vyos@vyos$ configure [edit] - cyos@vyos# + vyos@vyos# .. note:: When going into configuration mode, prompt changes from *$* to *#*. To exit configuration mode, type `exit`. @@ -135,8 +135,7 @@ To change the current hierarchy level use the command: `edit` You are now in a sublevel relative to `interfaces ethernet eth0`, all commands executed from this point on are relative to this sublevel. -Use either the `top` or `exit` command to go back to the top of the hierarchy. - +Use either the `top` or `exit` command to go back to the top of the hierarchy. You can also use the `up` command to move only one level up at a time. The `show` command within configuration mode will show the working configuration indicating line changes with `+` for additions, `>` for replacements and `-` for deletions. @@ -207,7 +206,7 @@ Managing the configuration -------------------------- The configuration is managed by the use of `set` and `delete` commands from within configuration mode. -Configuration commands are flattend from the tree into 'one-liner' commands shown in `show configuration commands` from operation mode. +Configuration commands are flattened from the tree into 'one-liner' commands shown in `show configuration commands` from operation mode. These commands are also relative to the level where they are executed and all redundant information from the current level is removed from the command entered. @@ -222,7 +221,7 @@ These commands are also relative to the level where they are executed and all re These two commands above are essentially the same, just executed from different levels in the hierarchy. To delete a configuration entry use the `delete` command, this also deletes all sub-levels under the current level you've specified in the `delete` command. -Deleting an entry could also mean to reset it back to its default value if the element is mandatory, in each case it will be removed from the configuration file. +Deleting an entry will also result in the element reverting back to its default value if one exists. .. code-block:: sh @@ -266,51 +265,7 @@ used. exit vyos@vyos:~$ -VyOS automatically maintains backups of previous configurations. To compare -configuration revisions in configuration mode, use the compare command: -.. code-block:: sh - - vyos@vyos# compare [tab] - Possible completions: - <Enter> Compare working & active configurations - saved Compare working & saved configurations - <N> Compare working with revision N - <N> <M> Compare revision N with M - Revisions: - 0 2013-12-17 20:01:37 root by boot-config-loader - 1 2013-12-13 15:59:31 root by boot-config-loader - 2 2013-12-12 21:56:22 vyos by cli - 3 2013-12-12 21:55:11 vyos by cli - 4 2013-12-12 21:27:54 vyos by cli - 5 2013-12-12 21:23:29 vyos by cli - 6 2013-12-12 21:13:59 root by boot-config-loader - 7 2013-12-12 16:25:19 vyos by cli - 8 2013-12-12 15:44:36 vyos by cli - 9 2013-12-12 15:42:07 root by boot-config-loader - 10 2013-12-12 15:42:06 root by init - - [edit] - vyos@vyos# - -You can rollback configuration using the rollback command, however this -command will currently trigger a system reboot. - -.. code-block:: sh - - vyos@vyos# compare 1 - [edit system] - >host-name vyos-1 - [edit] - vyos@vyos# rollback 1 - Proceed with reboot? [confirm][y] - Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): - The system is going down for reboot NOW! - [edit] - vyos@vyos# - -VyOS also supports saving and loading configuration remotely using SCP, FTP, -or TFTP. .. code-block:: sh @@ -329,9 +284,11 @@ or TFTP. Operational info from config mode --------------------------------- -When inside configuration mode you are not directly able to execute operational commands, -access to these commands are possible trough the use of the `run [command]` command. +When inside configuration mode you are not directly able to execute operational commands. + +Access to these commands are possible through the use of the `run [command]` command. From this command you will have access to everything accessible from operational mode. + Command completion and syntax help with `?` and `[tab]` will also work. .. code-block:: sh @@ -347,14 +304,13 @@ Command completion and syntax help with `?` and `[tab]` will also work. Configuration archive --------------------- -VyOS has built-in config archiving and versioning that renders tools like rancid, largely unnecessary. - -This feature was available in Vyatta Core since 6.3 +VyOS automatically maintains backups of previous configurations. Local archive and revisions ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Revisions are stored on disk. You can view them, compare them, and rollback to previous revisions if anything goes wrong. -Revisions are stored on disk, you can view them, compare them, and rollback to previous revisions if anything goes wrong. To view existing revisions, use `show system commit` operational mode command. .. code-block:: sh @@ -369,7 +325,36 @@ To view existing revisions, use `show system commit` operational mode command. 6 2015-03-25 00:16:47 by vyos via cli 7 2015-03-24 23:43:45 by root via boot-config-loader -You can compare revisions with `compare X Y` command, where X and Y are revision numbers. The output will describe how the configuration X is when comparted to Y, indicating with a plus sign (**+**) the additional parts X has when compared to y, and indicating with a minus sign (**-**) the lacking parts x misses when compared to y. +To compare configuration revisions in configuration mode, use the compare command: + +.. code-block:: sh + + vyos@vyos# compare [tab] + Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init + + [edit] + vyos@vyos# + +Comparing Revisions +""""""""""""""""""" + +You can compare revisions with `compare X Y` command, where X and Y are revision numbers. The output will describe how the configuration X is when compared to Y, indicating with a plus sign (**+**) the additional parts X has when compared to y, and indicating with a minus sign (**-**) the lacking parts x misses when compared to y. .. code-block:: sh @@ -386,21 +371,43 @@ You can compare revisions with `compare X Y` command, where X and Y are revision - address 192.0.2.4/24 -} +Rolling Back Changes +"""""""""""""""""""" + +You can rollback configuration using the rollback command. This +command will apply the selected revision and trigger a system reboot. + +.. code-block:: sh -You can rollback to a previous revision with `rollback X`, where X is a revision number. Your system will reboot and load the config from the archive. + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): + The system is going down for reboot NOW! + [edit] + vyos@vyos# Configuring the archive size ----------------------------- +"""""""""""""""""""""""""""" You can specify the number of revisions stored on disk with `set system config-management commit-revisions X`, where X is a number between 0 and 65535. When the number of revisions exceeds that number, the oldest revision is removed. Remote archive --------------- +^^^^^^^^^^^^^^ VyOS can copy the config to a remote location after each commit. TFTP, FTP, and SFTP servers are supported. -You can specify the location with `set system config-management commit-archive location URL` command, e.g. `set system config-management commit-archive location tftp://10.0.0.1/vyos`. +You can specify the location with: + +* `set system config-management commit-archive location URL` + +For example, `set system config-management commit-archive location tftp://10.0.0.1/vyos`. + +You can specify the location with `set system config-management commit-archive location URL` command, e.g. `set system config-management commit-archive location tftp://10.0.0.1/vyos`. Wipe config and restore default ------------------------------- @@ -412,4 +419,3 @@ In the case you want to completely delete your configuration and restore the def load /opt/vyatta/etc/config.boot.default .. note:: If you are remotely connected, you will lose your connection. You may want to copy first the config, edit it to ensure connectivity, and load the edited config. - diff --git a/docs/contributing/coding_guidelines.rst b/docs/contributing/coding_guidelines.rst index ff863d61..9c996518 100644 --- a/docs/contributing/coding_guidelines.rst +++ b/docs/contributing/coding_guidelines.rst @@ -54,7 +54,7 @@ The **get_config()** function must convert the VyOS config to an abstract intern representation. No other function is allowed to call ``vyos.config.Config`` object methods directly. The rationale for it is that when config reads are mixed with other logic, it's very hard to change the config syntax since you need to weed -out every occurence of the old syntax. If syntax-specific code is confined to a +out every occurrence of the old syntax. If syntax-specific code is confined to a single function, the rest of the code can be left untouched as long as the internal representation remains compatible. @@ -75,7 +75,7 @@ The **apply()** function applies the generated configuration to the live system. It should use non-disruptive reload whenever possible. It may execute disruptive operations such as daemon process restart if a particular component does not support non-disruptive reload, or when the expected service degradation is minimal -(for example, in case of auxillary services such as LLDPd). In case of high impact +(for example, in case of auxiliary services such as LLDPd). In case of high impact services such as VPN daemon and routing protocols, when non-disruptive reload is supported for some but not all types of configuration changes, scripts authors should make effort to determine if a configuration change can be done in a diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 4b762051..9e99ece8 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -31,7 +31,7 @@ This information is used in two ways: * Keep track of the progress (what we've already done in this branch and what we still need to do). * Prepare release notes. -To make this approach work, every change must be associated with a bug number and componant. +To make this approach work, every change must be associated with a bug number and component. If there is no bug/enhancement request for the changes you are going to make, you must create a `bugtracker`_ entry first. Once there is a `bugtracker`_ entry about it, you should reference in your commit message, as in: diff --git a/docs/contributing/vyos_cli.rst b/docs/contributing/vyos_cli.rst index f539efda..49f9a230 100644 --- a/docs/contributing/vyos_cli.rst +++ b/docs/contributing/vyos_cli.rst @@ -5,8 +5,8 @@ VyOS CLI The bash completion in VyOS is defined in *templates*. Templates are text files stored in a directory tree, where directory names define command names, and -template files define command behaviour. Befor VyOS 1.2.x this files were created -by hand. After a complex redesing process_ the new style template are in XML. +template files define command behaviour. Before VyOS 1.2.x this files were created +by hand. After a complex redesign process_ the new style template are in XML. XML interface definitions for VyOS come with a RelaxNG schema and are located in the vyos-1x_ module. This schema is a slightly modified schema from VyConf_ diff --git a/docs/high-availability.rst b/docs/high-availability.rst index c967d647..54f2f388 100644 --- a/docs/high-availability.rst +++ b/docs/high-availability.rst @@ -7,7 +7,7 @@ VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers Every VRRP router has a physical IP/IPv6 address, and a virtual address. On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. -If the master fails and stops sending keepalive packets, router with the next highest priority becomes the new master and takes over the virtual address. +If the master fails and stops sending keepalive packets, the router with the next highest priority becomes the new master and takes over the virtual address. VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). @@ -19,7 +19,7 @@ Basic setup VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. The required parameters are interface, vrid, and virtual-address. -mininmal config +minimal config .. code-block:: sh @@ -61,12 +61,12 @@ VRRP priority can be set with ``priority`` option: set high-availability vrrp group Foo priority 200 -The priority must be an interger number from 1 to 255. Higher priority value increases router's precedence in the master elections. +The priority must be an integer number from 1 to 255. Higher priority value increases router's precedence in the master elections. Preemption ---------- -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indenfinitely. +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indefinitely. By default VRRP uses preemption. You can disable it with the "no-preempt" option: @@ -117,4 +117,4 @@ This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" - set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo"
\ No newline at end of file + set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/history.rst b/docs/history.rst index 46764d89..aa9bae7e 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -20,7 +20,7 @@ Vyatta was based upon). Vyatta changed to the Quagga routing engine for release 4.0. -VyOS changed the routing enging to `FRRoution <https://frrouting.org/>`_ in +VyOS changed the routing engine to `FRRouting <https://frrouting.org/>`_ in version 1.2.0 **How it's different from other router distros?** diff --git a/docs/index.rst b/docs/index.rst index 58461850..59b74b38 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,6 +43,7 @@ as a router and firewall platform for cloud deployments. appendix/troubleshooting.rst appendix/examples/index.rst appendix/commandtree/index.rst + appendix/vyos-on-vmware.rst appendix/vyos-on-baremetal.rst appendix/migrate-from-vyatta.rst diff --git a/docs/install.rst b/docs/install.rst index 22e5061e..f64cf636 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -18,13 +18,13 @@ Registered subscribers can download stable release (LTS) images. If you log into Non-subscribers can get the LTS release by building it from source. Just follow the instructions in https://github.com/vyos/vyos-build -Everyone can dowload VyOS rolling images from https://downloads.vyos.io/ +Everyone can download VyOS rolling images from https://downloads.vyos.io/ Preparing software verification ------------------------------- -This subsection and the following one applies to dowloaded LTS images, for other cases please jump to :ref:`Install`. +This subsection and the following one applies to downloaded LTS images, for other cases please jump to :ref:`Install`. LTS images are signed by VyOS lead package-maintainer private key. If you have our public key, you will be able to verify the authenticity of the package. @@ -123,7 +123,7 @@ GPG verification As you have our public key, you just need the signature of the software you want to verify. -.. note:: **In order to get the signature, go to your web browser and append *.asc* to the URL of your dowloaded VyOS image**. You will download a small *.asc* file, that's the signature of your image. +.. note:: **In order to get the signature, go to your web browser and append .asc to the URL of your downloaded VyOS image**. You will download a small *.asc* file, that's the signature of your image. So finally you can verify the authenticity of your image. diff --git a/docs/interfaces/bridging.rst b/docs/interfaces/bridging.rst index 7fb20e0a..e42d76ad 100644 --- a/docs/interfaces/bridging.rst +++ b/docs/interfaces/bridging.rst @@ -10,8 +10,9 @@ we will be creating a bridge for VLAN 100 and assigning a VIF to the bridge. .. code-block:: sh set interfaces bridge 'br100' - set interfaces ethernet eth1 vif 100 bridge-group bridge br100 - + ~~set interfaces ethernet eth1 vif 100 bridge-group bridge br100~~ + set interfaces bridge br100 member interface eth1 + Interfaces assigned to a bridge-group do not have address configuration. An IP address can be assigned to the bridge interface itself, however, like any normal interface. diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 8ef002f8..075b3836 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -28,10 +28,12 @@ Resulting in: speed auto } -In addition, Ethernet interfaces provide the extended operational commands -`show interfaces ethernet <name> physical` and -`show interfaces ethernet <name> statistics`. Statistics available are driver -dependent. +In addition, Ethernet interfaces provide the extended operational commands: + +* `show interfaces ethernet <name> physical` +* `show interfaces ethernet <name> statistics` + +Statistics available are driver dependent. .. code-block:: sh diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index 883a3c5d..c4eb2d8f 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -8,8 +8,9 @@ There are two main ways to setup VyOS to connect over a PPPoE internet connectio **First Method:** (Common for Homes) -In this method, the DSL Modem/Router connects to the DSL ISP for you with your credentials preprogrammed into the device and it gives you a local IP address such as 192.168.1.0/24 be default. -For home networks this is usually fine and saves you trouble but if you want to run a configuration of your own controlled by VyOS, this would mean a Double Firewall, a Double NAT, and double Router as both the DSL Modem/Router and the VyOS would act as firewalls, NATs, and Routers and if you try to do more then just browse Web Sites this will usually cause you trouble. +In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an RFC1918_ address, such as 192.168.1.0/24 by default. + +For a simple home network using just the ISP's equipment, this is usually desirable. But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features. **Second Method:** (Common for Businesses) @@ -77,3 +78,5 @@ This command shows the same log as without the 'tail' option but only starts wit .. code-block:: sh show interfaces pppoe 0 log tail + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst index f466a714..7103e5a2 100644 --- a/docs/interfaces/tunnel.rst +++ b/docs/interfaces/tunnel.rst @@ -13,8 +13,8 @@ All those protocols are grouped under 'interfaces tunnel' in VyOS. Let's take a IPIP ---- -This is the simplest tunneling protocol in existence. It is defined by RFC2003_. -It simply takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason it doesn't really have any configuration options by itself. +This is one of the simplest types of tunnels, as defined by RFC2003_. +It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason, there are no other configuration options for this kind of tunnel. An example: @@ -64,7 +64,7 @@ An example: 6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in RFC4213_. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP headers have the IP protocol number set to 41. This protocol number is specifically designated for IPv6 encapsulation, the IPv4 packet header is immediately followed by the IPv6 packet being carried. -qThe encapsulation overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of 1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane Electric`_. +The encapsulation overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of 1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane Electric`_. An example: @@ -75,6 +75,8 @@ An example: set interfaces tunnel tun0 remote-ip 192.0.2.20 set interfaces tunnel tun0 address 2001:db8:bb::1/64 +A full example of a Tunnelbroker.net config can be found at :ref:`here <examples-tunnelbroker-ipv6>`. + Generic Routing Encapsulation (GRE) ----------------------------------- @@ -191,4 +193,4 @@ Results in: .. _RFC2473: https://tools.ietf.org/html/rfc2473 .. _`other proposals`: https://www.isc.org/downloads/aftr .. _RFC4213: https://tools.ietf.org/html/rfc4213 -.. _`Hurricane Electric`: https://tunnelbroker.net/
\ No newline at end of file +.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/load-balancing.rst b/docs/load-balancing.rst index 753bf6c1..0f598b6e 100644 --- a/docs/load-balancing.rst +++ b/docs/load-balancing.rst @@ -11,9 +11,9 @@ The load balancer automatically adds routes for each path to the routing table a In a minimal, configuration the following must be provided: * a interface with a nexthop - * one rule with a LAN (inbound-interface) and the WAN (interace). + * one rule with a LAN (inbound-interface) and the WAN (interface). -lets asume we have two dhcp wan interfaces a one LAN (eth2) +lets assume we have two dhcp WAN interfaces and one LAN (eth2) .. code-block:: sh @@ -50,7 +50,7 @@ Create a load balancing rule, rule can be a number between 0...4294967295: Interface weight **************** -Let's expand the example from above an add a weight to the interfaces. The bandwith from eth0 is larger than eth1. +Let's expand the example from above and add a weight to the interfaces. The bandwidth from eth0 is larger than eth1. Per default outbound traffic is distributed randomly across available interfaces. Weights can be assigned to interfaces to influence the balancing. .. code-block:: sh @@ -58,7 +58,7 @@ Per default outbound traffic is distributed randomly across available interfaces set load-balancing wan rule 0 interface eth0 weight 2 set load-balancing wan rule 0 interface eth1 weight 1 -66 % traffic is routed to eth0 and eth1 get 33% of traffic. +66% traffic is routed to eth0 and eth1 get 33% of traffic. Rate limit ********** @@ -80,7 +80,7 @@ Flow and packet-based balancing Outgoing traffic is balanced in a flow-based manner. A connection tracking table is used to track flows by their source address, destination address and port. -Each flow is assingned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. +Each flow is assigned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. This has the advantage that packets always arrive in order if links with different speeds are in use. Packet-based balancing can lead to a better balance across interfaces when out of order packets are no issue. Per-packet-based balancing can be set for a balancing rule with: @@ -92,7 +92,7 @@ Packet-based balancing can lead to a better balance across interfaces when out o Exclude traffic *************** -To exclude traffic from load blalancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: +To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: .. code-block:: sh @@ -102,7 +102,7 @@ To exclude traffic from load blalancing, traffic matching an exclude rule is not Health checks ------------- -The health of interfaces and paths assingned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. +The health of interfaces and paths assigned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. If an interface fails the health check it is removed from the load balancer's pool of interfaces. To enable health checking for an interface: .. code-block:: sh @@ -118,7 +118,7 @@ Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhc .. code-block:: sh - set load-balancing wan interface-health <interace> nexthop <ipv4-address> + set load-balancing wan interface-health <interface> nexthop <ipv4-address> Set the number of health check failures before an interface is marked as unavailable, range for number is 1 to 10, default 1. Or set the number of successful health checks before an interface is added back to the interface pool, range for number is 1 to 10, default 1. diff --git a/docs/nat.rst b/docs/nat.rst index 5c3dadc4..d20995d4 100644 --- a/docs/nat.rst +++ b/docs/nat.rst @@ -87,6 +87,9 @@ protocol behavior. For this reason, VyOS does not globally drop invalid state traffic, instead allowing the operator to make the determination on how the traffic is handled. +NAT Reflection/Hairpin NAT +^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. note:: Avoiding NAT breakage in the absence of split-DNS A typical problem with using NAT and hosting public servers is the ability for @@ -96,7 +99,7 @@ systems to the internal address when requests are made internally. Because many smaller networks lack DNS infrastructure, a work-around is commonly deployed to facilitate the traffic by NATing the request from internal hosts to the source address of the internal interface on the firewall. This technique -is commonly reffered to as **NAT Reflection**, or **Hairpin NAT**. +is commonly referred to as **NAT Reflection**, or **Hairpin NAT**. In this example, we will be using the example Quick Start configuration above as a starting point. @@ -272,8 +275,10 @@ described in RFC6296_. NPTv6 is supported in linux kernel since version 3.13. Usage ^^^^^ -NPTv6 is very useful for IPv6 multihoming. Let's assume the following network -configuration: +NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the external IPv6 prefix is dynamic, +as it prevents the need for renumbering of internal hosts when the extern prefix changes. + +Let's assume the following network configuration: * eth0 : LAN * eth1 : WAN1, with 2001:db8:e1::/48 routed towards it diff --git a/docs/qos.rst b/docs/qos.rst index d68919d7..adf59108 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -809,7 +809,7 @@ Available commands: :code:`set traffic-policy round-robin <policy name> default quantum <packets>` -* Define a maximum queue lenght for the default policy in packets: +* Define a maximum queue length for the default policy in packets: :code:`set traffic-policy round-robin <policy name> default queue-limit <limit>` @@ -926,7 +926,7 @@ different amounts of bandwidth to different traffic classes. In contrast to round robin, shaper limits bandwidth allocation by traffic class whereas round robin divides the total available bandwidth between classes. -Avialable commands: +Available commands: * Define a shaper policy: diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 226c81d0..518e5d86 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -28,15 +28,8 @@ Enable SSH for remote management: set service ssh port '22' -Configure Source NAT for our "Inside" network. - -.. code-block:: sh - - set nat source rule 100 outbound-interface 'eth0' - set nat source rule 100 source address '192.168.0.0/24' - set nat source rule 100 translation address masquerade - -Configure a DHCP Server: +Configure DHCP Server and DNS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: sh @@ -49,17 +42,27 @@ Configure a DHCP Server: And a DNS forwarder: -Please note that the `listen-on` statement is deprecated. Please use -`listen-address` instead! - .. code-block:: sh set service dns forwarding cache-size '0' - set service dns forwarding listen-on 'eth1' + set service dns forwarding listen-address '192.168.0.1' set service dns forwarding name-server '8.8.8.8' set service dns forwarding name-server '8.8.4.4' -Add a set of firewall policies for our "Outside" interface: +NAT and Firewall +^^^^^^^^^^^^^^^^ + +Configure Source NAT for our "Inside" network. + +.. code-block:: sh + + set nat source rule 100 outbound-interface 'eth0' + set nat source rule 100 source address '192.168.0.0/24' + set nat source rule 100 translation address masquerade + +Add a set of firewall policies for our "Outside" interface. + +This configuration creates a proper stateful firewall that blocks all traffic: .. code-block:: sh @@ -75,6 +78,13 @@ Add a set of firewall policies for our "Outside" interface: set firewall name OUTSIDE-LOCAL rule 20 icmp type-name 'echo-request' set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp' set firewall name OUTSIDE-LOCAL rule 20 state new 'enable' + +If you wanted to enable SSH access to your firewall from the the Internet, you could create some additional rules to allow the traffic. + +These rules allow SSH traffic and rate limit it to 4 requests per minute. This blocks brute-forcing attempts: + +.. code-block:: sh + set firewall name OUTSIDE-LOCAL rule 30 action 'drop' set firewall name OUTSIDE-LOCAL rule 30 destination port '22' set firewall name OUTSIDE-LOCAL rule 30 protocol 'tcp' @@ -105,7 +115,7 @@ Commit changes, save the configuration, and exit configuration mode: vyos@vyos$ Basic QoS ---------- +^^^^^^^^^ The traffic policy subsystem provides an interface to Linux traffic control (tc_). @@ -163,4 +173,38 @@ VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`) See further information in the :ref:`qos` chapter. +Security Hardening +^^^^^^^^^^^^^^^^^^ + +Especially if you are allowing SSH access from the Internet, there are a few additional configuration steps that should be taken. + +Create a user to replace the default `vyos` user: + +.. code-block:: sh + + set system login user myvyosuser level admin + set system login user myvyosuser authentication plaintext-password mysecurepassword + +Set up SSH key based authentication. For example, on Linux you'd want to run `ssh-keygen -t rsa`. Then the contents of `id_rsa.pub` would be used below: + +.. code-block:: sh + + set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa + set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub + +Or you can use the `loadkey` command. Commit and save. + +Finally, try and ssh into the VyOS install as your new user. + +Once you have confirmed that your new user can access your server, without a password, delete the original `vyos` user and disable password authentication into SSH: + +.. code-block:: sh + + delete system login user vyos + set service ssh disable-password-authentication + +Commit and save. + + + .. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) diff --git a/docs/routing/index.rst b/docs/routing/index.rst index 376e0919..1a1db43f 100644 --- a/docs/routing/index.rst +++ b/docs/routing/index.rst @@ -8,8 +8,7 @@ policy routing, and dynamic routing using standard protocols (RIP, OSPF, and BGP). .. toctree:: - :maxdepth: 2 - :hidden: + :maxdepth: 1 arp bgp diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst index 9409690a..7cec4b7c 100644 --- a/docs/routing/mss-clamp.rst +++ b/docs/routing/mss-clamp.rst @@ -7,7 +7,7 @@ As Internet wide PMTU discovery rarely works we sometimes need to clamp our TCP MSS value to a specific value. Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS value for IPv4 and IPv6. -Clamping can be disabled per interface using the `disable` keywork: +Clamping can be disabled per interface using the `disable` keyword: .. code-block:: sh diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst index 23033bd6..b8366cdc 100644 --- a/docs/routing/ospf.rst +++ b/docs/routing/ospf.rst @@ -15,8 +15,21 @@ OSPF is a widely used IGP in large enterprise networks. OSPFv2 (IPv4) ^^^^^^^^^^^^^ -A typical configuration using 2 nodes, redistribute loopback address and the -node 1 sending the default route: +In order to have a VyOS system exchanging routes with OSPF neighbors, you will at least need to configure the area and a network, + +.. code-block:: sh + + set protocols ospf area 0 network 192.168.0.0/24 + +as well as the router ID. + +.. code-block:: sh + + set protocols ospf parameters router-id 10.1.1.1 + +That is the minimum configuration you will need. + +Below you can see a typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route: **Node 1** diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst index a8ee9e87..62dfcaec 100644 --- a/docs/routing/pbr.rst +++ b/docs/routing/pbr.rst @@ -73,9 +73,9 @@ Add policy route matching VLAN source addresses set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' set policy route PBR rule 20 source address '192.168.188.0/24' - set policy route PBR rule 20 set table '11' - set policy route PBR rule 20 description 'Route VLAN11 traffic to table 11' - set policy route PBR rule 20 source address '192.168.189.0/24' + set policy route PBR rule 30 set table '11' + set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' + set policy route PBR rule 30 source address '192.168.189.0/24' Apply routing policy to **inbound** direction of out VLAN interfaces diff --git a/docs/routing/routing-policy.rst b/docs/routing/routing-policy.rst index 253dd980..f1b7d778 100644 --- a/docs/routing/routing-policy.rst +++ b/docs/routing/routing-policy.rst @@ -22,8 +22,8 @@ Routing Policy Example set policy route-map setmet rule 2 set as-path-prepend '2 2 2' #Apply policy to BGP - set protocols bgp 1 neighbor 1.1.1.2 route-map import 'setmet' - set protocols bgp 1 neighbor 1.1.1.2 soft-reconfiguration 'inbound' <<<< *** + set protocols bgp 1 neighbor 1.1.1.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 1.1.1.2 address-family ipv4-unicast soft-reconfiguration 'inbound' <<<< *** *** get policy update without bouncing the neighbor diff --git a/docs/routing/static.rst b/docs/routing/static.rst index e1f96c31..4faa2451 100644 --- a/docs/routing/static.rst +++ b/docs/routing/static.rst @@ -13,11 +13,10 @@ not make use of DHCP or dynamic routing protocols: set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1' Another common use of static routes is to blackhole (drop) traffic. In the -example below, RFC 1918 private IP networks are set as blackhole routes. This -does not prevent networks within these segments from being used, since the -most specific route is always used. It does, however, prevent traffic to -unknown private networks from leaving the router. Commonly refereed to as -leaking. +example below, RFC1918_ networks are set as blackhole routes. + +This prevents these networks leaking out public interfaces, but it does not prevent +them from being used as the most specific route has the highest priority. .. code-block:: sh @@ -27,3 +26,5 @@ leaking. .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index a8501c8f..4aaf6919 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -28,26 +28,37 @@ Setting a forwarding DNS server for a specific domain: .. code-block:: sh set service dns forwarding domain example.com server 192.0.2.1 + +Set which networks or clients are allowed to query the DNS Server. Allow from all: + +.. code-block:: sh + + set service dns forwarding allow-from 0.0.0.0/0 Example 1 ^^^^^^^^^ -Router with two interfaces eth0 (WAN link) and eth1 (LAN). A DNS server for the -local domain (example.com) is at 192.0.2.1, other DNS requests are forwarded -to Google's DNS servers. +Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. + +* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 +* Other DNS requests are forwarded to Google's DNS servers. +* The IP address for the LAN interface is 192.168.0.1. .. code-block:: sh set service dns forwarding domain example.com server 192.0.2.1 set service dns forwarding name-server 8.8.8.8 set service dns forwarding name-server 8.8.4.4 - set service dns forwarding listen-on 'eth1' + set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 Example 2 ^^^^^^^^^ Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers: +servers. + +The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 .. code-block:: sh @@ -56,4 +67,6 @@ servers: set service dns forwarding name-server 8.8.4.4 set service dns forwarding name-server 2001:4860:4860::8888 set service dns forwarding name-server 2001:4860:4860::8844 - set service dns forwarding listen-on 'eth1' + set service dns forwarding listen-address 2001:db8::1 + set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 diff --git a/docs/services/index.rst b/docs/services/index.rst index 03fdc9c4..3e81b7a9 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -5,10 +5,10 @@ Services ======== -This chapter descriptes the available system/network services provided by VyOS. +This chapter describes the available system/network services provided by VyOS. .. toctree:: - :hidden: + :maxdepth: 1 conntrack dhcp diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index 6a3bee7b..37214506 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -92,6 +92,6 @@ Exemple: Troubleshooting ^^^^^^^^^^^^^^^ -Use operationnal command ``show log lldp`` to display logs. +Use operational command ``show log lldp`` to display logs. .. include:: references.rst diff --git a/docs/services/pppoe-server.rst b/docs/services/pppoe-server.rst index 2acc93f1..03e14971 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/services/pppoe-server.rst @@ -41,12 +41,12 @@ Connections can be locally checked via the command Client IP address pools ======================= -To automatically assign the client an IP address as tunnel endpoint, a client IP pool is needed. The source can be either RADIUS or a local subnet or IP range defintion. +To automatically assign the client an IP address as tunnel endpoint, a client IP pool is needed. The source can be either RADIUS or a local subnet or IP range definition. Once the local tunnel endpoint ``set service pppoe-server local-ip '10.1.1.2'`` has been defined, the client IP pool can be either defined as a range or as subnet using CIDR notation. If the CIDR notation is used, multiple subnets can be setup which are used sequentially. -**Client IP address via IP range defintion** +**Client IP address via IP range definition** .. code-block:: sh @@ -116,7 +116,7 @@ If attribute Filter-Id redefined, replace it in radius coa request Automatic VLAN creation ======================= -VLAN's can be created by accel-ppp on the fly if via the use of the kernel module vlan_mon, which is monitoring incoming vlans and creates the neccessary VLAN if required and allowed. +VLAN's can be created by accel-ppp on the fly if via the use of the kernel module vlan_mon, which is monitoring incoming vlans and creates the necessary VLAN if required and allowed. VyOS supports the use of either VLAN ID's or entire ranges, both values can be defined at the same time for an interface. .. code-block:: sh @@ -127,7 +127,7 @@ VyOS supports the use of either VLAN ID's or entire ranges, both values can be d set service pppoe-server interface eth3 vlan-range 2000-3000 -The pppoe-server will now create these VLANs if required and once the user session has been cancelled, and the VLAN is not neccessary anymore, it will remove it again. +The pppoe-server will now create these VLANs if required and once the user session has been cancelled, and the VLAN is not necessary anymore, it will remove it again. diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index 4d96f8de..caa255ce 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -44,13 +44,13 @@ Options * Allow ``root`` login, this can be set to allow ``root`` logins on SSH connections, however it is not advisable to use this setting as this bears - serious security risks. The default system user posesses all required + serious security risks. The default system user possesses all required privileges. :code:`set service ssh allow-root` * Allowed ciphers - A number of allowed ciphers can be specified, use multiple - occurances to allow multiple ciphers. + occurrences to allow multiple ciphers. :code:`set service ssh ciphers <cipher>` @@ -70,7 +70,7 @@ Options * `cast128-cbc` * Disable password authentication - If SSH key authentication is set up, - password-based user authetication can be disabled. This hardens security! + password-based user authentication can be disabled. This hardens security! :code:`set service ssh disable-password-authentication` diff --git a/docs/services/sstp-server.rst b/docs/services/sstp-server.rst index 8ee8ef45..6ddbce38 100644 --- a/docs/services/sstp-server.rst +++ b/docs/services/sstp-server.rst @@ -14,7 +14,7 @@ Configuration The `Secure Socket Tunneling Protocol`_ (SSTP), provides ppp via a SSL/TLS channel. Using publically signed certificates as well a by private PKI, is fully supported. -All certficates should be stored on VyOS under ``/config/user-data/sstp``. +All certificates should be stored on VyOS under ``/config/user-data/sstp``. Self Signed CA and server certificates diff --git a/docs/system/host-information.rst b/docs/system/host-information.rst index f50585aa..788f7bcc 100644 --- a/docs/system/host-information.rst +++ b/docs/system/host-information.rst @@ -51,8 +51,8 @@ Example: Set system hostname to 'RT01': Domain Name ^^^^^^^^^^^ -A domainname is the label (name) assigned to a computer network and is thus -unique! +A domain name is the label (name) assigned to a computer network and is thus +unique. Set the system's domain: @@ -158,7 +158,7 @@ It is replaced by inserting a static route into the routing table using: set protocols static route 0.0.0.0/0 next-hop <gateway ip> -Delete default route fomr the system +Delete the default route from the system .. code-block:: sh diff --git a/docs/system/index.rst b/docs/system/index.rst index cea729e3..f52ea3d8 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -14,6 +14,7 @@ should be ready for further configuration which is described in this chapter. eventhandler flowaccounting host-information + ntp serialconsole system-users syslog diff --git a/docs/system/ntp.rst b/docs/system/ntp.rst new file mode 100644 index 00000000..ed2a0ecb --- /dev/null +++ b/docs/system/ntp.rst @@ -0,0 +1,19 @@ +.. _ntp: + +NTP +=== + +there are 3 default NTP server set. You are able to change them. + +.. code-block:: sh + + set system ntp server 0.pool.ntp.org + set system ntp server 1.pool.ntp.org + set system ntp server 2.pool.ntp.org + +To set up VyOS as an NTP responder, you must specify the listen address and optionally the permitted clients. + +.. code-block:: sh + + set system ntp listen-address 192.168.199.1 + set system ntp allow-clients address 192.168.199.0/24 diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst index 9bab2b0c..055a2d5c 100644 --- a/docs/vpn/index.rst +++ b/docs/vpn/index.rst @@ -5,7 +5,7 @@ VPN === -This chapter descriptes the available VPN services provided by VyOS. +This chapter describes the available VPN services provided by VyOS. .. toctree:: :hidden: diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 29104199..7e468c7b 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -160,7 +160,7 @@ OpenVPN Server Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. This guide assumes you have already setup a PKI and have a CA certificate, a server certificate and -key, a certificate revokation list, a Diffie-Hellman key exchange parameters +key, a certificate revocation list, a Diffie-Hellman key exchange parameters file. You do not need client certificates and keys for the server setup. In this example we will use the most complicated case: a setup where each @@ -227,15 +227,19 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10 -LDAP Authentication -******************* + +Client Authentication +********************* + +OpenLDAP +======== Enterprise installations usually ship a kind of directory service which is used -to have a single password store for all employes. VyOS and OpenVPN support using +to have a single password store for all employees. VyOS and OpenVPN support using LDAP/AD as single user backend. Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is -shiped with every VyOS installation. A dedicated configuration file is required. +shipped with every VyOS installation. A dedicated configuration file is required. It is best practise to store it in ``/config`` to survive image updates .. code-block:: sh @@ -267,7 +271,7 @@ The required config file may look like: </Authorization> Active Directory -**************** +================ Despite the fact that AD is a superset of LDAP @@ -302,22 +306,22 @@ Despite the fact that AD is a superset of LDAP </Group> </Authorization> -If you only wan't to check if the user account is enabled and can authenticate +If you only want to check if the user account is enabled and can authenticate (against the primary group) the following snipped is sufficient: .. code-block:: sh <LDAP> - URL ldap://ds0001.gefoekom.de - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,OU=GS,OU=GeFoekoM,DC=gefoekom,DC=de - Password g7LjfjmlPhhHnvmal75hbfdknms-44 + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret Timeout 15 TLSEnable no FollowReferrals no </LDAP> <Authorization> - BaseDN "OU=GeFoekoM,DC=gefoekom,DC=de" + BaseDN "DC=example,DC=com" SearchFilter "sAMAccountName=%u" RequireGroup false </Authorization> @@ -351,3 +355,75 @@ A complete LDAP auth OpenVPN configuration could look like the following example key-file /config/auth/server.key } } + +OpenVPN Client +^^^^^^^^^^^^^^ + +VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients. +You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client +connecting to a VyOS OpenVPN server or any other OpenVPN server. + +Given the following example we have one VyOS router acting as OpenVPN server +and another VyOS router acting as OpenVPN client. The Server also pushes a +static client IP address to the OpenVPN client. Remember, clients are identified +using their CN attribute in the SSL certificate. + + +Server +****** + +.. code-block:: sh + + set interfaces openvpn vtun10 encryption 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 local-host '172.18.201.10' + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' + set interfaces openvpn vtun10 server domain-name 'vyos.net' + set interfaces openvpn vtun10 server max-connections '250' + set interfaces openvpn vtun10 server name-server '172.16.254.30' + set interfaces openvpn vtun10 server subnet '10.10.0.0/24' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt' + set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem' + set interfaces openvpn vtun10 tls key-file '/config/auth/server.key' + set interfaces openvpn vtun10 use-lzo-compression + +Client +****** + +.. code-block:: sh + + set interfaces openvpn vtun10 encryption 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 mode 'client' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 remote-host '172.18.201.10' + set interfaces openvpn vtun10 remote-port '1194' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt' + set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key' + set interfaces openvpn vtun10 use-lzo-compression + +Options +^^^^^^^ + +We do not have CLI nodes for every single OpenVPN options. If an option is +missing, a feature request should be opened at https://phabricator.vyos.net so +all users can benefit from it. + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +.. code-block:: sh + + set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +Will add `persistent-key` at the end of the generated OpenVPN configuration. +Please use this only as last resort - things might break and OpenVPN won't start +if you pass invalid options/syntax. diff --git a/docs/vpn/site2site_ipsec.rst b/docs/vpn/site2site_ipsec.rst index ff398dab..ac410d52 100644 --- a/docs/vpn/site2site_ipsec.rst +++ b/docs/vpn/site2site_ipsec.rst @@ -1,7 +1,108 @@ .. _size2site_ipsec: Site-to-Site ------------- +============ + +Site-to-site mode provides a way to add remote peers, which could be configured to exchange encrypted information between them and VyOS itself or connected/routed networks. + +To configure site-to-site connection you need to add peers with the ``set vpn ipsec site-to-site`` command. + +You can identify a remote peer with: + +* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used when a peer has a public static IP address; +* Hostname. This mode is similar to IP address, only you define DNS name instead of an IP. Could be used when a peer has a public IP address and DNS name, but an IP address could be changed from time to time; +* Remote ID of the peer. In this mode, there is no predefined remote address nor DNS name of the peer. This mode is useful when a peer doesn't have a publicly available IP address (NAT between it and VyOS), or IP address could be changed. + +Each site-to-site peer has the next options: + +* ``authentication`` - configure authentication between VyOS and a remote peer. Suboptions: + + * ``id`` - ID for the local VyOS router. If defined, during the authentication it will be send to remote peer; + + * ``mode`` - mode for authentication between VyOS and remote peer: + + * ``pre-shared-secret`` - use predefined shared secret phrase, must be the same for local and remote side; + + * ``rsa`` - use simple shared RSA key. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``x509`` - use certificates infrastructure for authentication. + + * ``pre-shared-secret`` - predefined shared secret. Used if configured ``mode pre-shared-secret``; + + * ``remote-id`` - define an ID for remote peer, instead of using peer name or address. Useful in case if the remote peer is behind NAT or if ``mode x509`` is used; + + * ``rsa-key-name`` - shared RSA key for authentication. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when ``id`` is defined; + + * ``x509`` - options for x509 authentication mode: + + * ``ca-cert-file`` - CA certificate file. Using for authenticating remote peer; + + * ``cert-file`` - certificate file, which will be used for authenticating local router on remote peer; + + * ``crl-file`` - file with the Certificate Revocation List. Using to check if a certificate for the remote peer is valid or revoked; + + * ``key`` - a private key, which will be used for authenticating local router on remote peer: + + * ``file`` - path to the key file; + + * ``password`` - passphrase private key, if needed. + +* ``connection-type`` - how to handle this connection process. Possible variants: + + * ``initiate`` - do initial connection to remote peer immediately after configuring and after boot. In this mode the connection will not be restarted in case of disconnection, therefore should be used only together with DPD or another session tracking methods; + + * ``respond`` - do not try to initiate a connection to a remote peer. In this mode, the IPSec session will be established only after initiation from a remote peer. Could be useful when there is no direct connectivity to the peer due to firewall or NAT in the middle of the local and remote side. + +* ``default-esp-group`` - ESP group to use by default for traffic encryption. Might be overwritten by individual settings for tunnel or VTI interface binding; + +* ``description`` - description for this peer; + +* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec connection with this peer, instead of ``local-address``; + +* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. Useful in case if between local and remote side is firewall or NAT, which not allows passing plain ESP packets between them; + +* ``ike-group`` - IKE group to use for key exchanges; + +* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. Can be used only with IKEv2: + + * ``yes`` - create a new IKE_SA from the scratch and try to recreate all IPsec SAs; + + * ``no`` - rekey without uninstalling the IPsec SAs; + + * ``inherit`` - use default behavior for the used IKE group. + +* ``local-address`` - local IP address for IPSec connection with this peer. If defined ``any``, then an IP address which configured on interface with default route will be used; + +* ``tunnel`` - define criteria for traffic to be matched for encrypting and send it to a peer: + + * ``disable`` - disable this tunnel; + + * ``esp-group`` - define ESP group for encrypt traffic, defined by this tunnel; + + * ``local`` - define a local source for match traffic, which should be encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at local side. + + * ``protocol`` - define the protocol for match traffic, which should be encrypted and send to this peer; + + * ``remote`` - define the remote destination for match traffic, which should be encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at remote side. + +* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will be send to VTI interface will be encrypted and send to this peer. Using VTI makes IPSec configuration much flexible and easier in complex situation, and allows to dynamically add/delete remote networks, reachable via a peer, as in this mode router don't need to create additional SA/policy for each remote network: + + * ``bind`` - select a VTI interface to bind to this peer; + + * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI interface. + +Examples: +------------------ IKEv1 ^^^^^ diff --git a/docs/vpn/wireguard.rst b/docs/vpn/wireguard.rst index 141e843c..a9d27330 100644 --- a/docs/vpn/wireguard.rst +++ b/docs/vpn/wireguard.rst @@ -10,8 +10,16 @@ information. Configuration ^^^^^^^^^^^^^ +Wireguard requires the generation of a keypair, a private key which will decrypt +incoming traffic and a public key, which the peer(s) will use to encrypt traffic. + +Generate a keypair +~~~~~~~~~~~~~~~~~~ + Generate the keypair, which creates a public and private part and stores it within VyOS. +It will be used per default on any configured wireguard interface, even if +multiple interfaces are being configured. .. code-block:: sh @@ -26,6 +34,27 @@ traffic to your system using this public key. wg01# run show wireguard pubkey u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + +Generate named keypairs +~~~~~~~~~~~~~~~~~~~~~~~ + +Named keypairs can be used on a interface basis, if configured. +If multiple wireguard interfaces are being configured, each can have +their own keypairs. + +The commands below will generate 2 keypairs, which are not related +to each other. + +.. code-block:: sh + + wg01:~$ configure + wg01# run generate wireguard named-keypairs KP01 + wg01# run generate wireguard named-keypairs KP02 + + +Wireguard Interface configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The next step is to configure your local side as well as the policy based trusted destination addresses. If you only initiate a connection, the listen port and endpoint is optional, if you however act as a server and endpoints @@ -50,11 +79,25 @@ below is always the public key from your peer, not your local one. set interfaces wireguard wg01 port '12345' set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 +.. note:: The `endpoint` must be an IP and not a fully qualified domain name (FQDN). Using a FQDN will result in unexpected behavior. + The last step is to define an interface route for 10.2.0.0/24 to get through the wireguard interface `wg01`. Multiple IPs or networks can be defined and routed, the last check is allowed-ips which either prevents or allows the traffic. + +To use a named key on an interface, the option private-key needs to be set. + +.. code-block:: sh + + set interfaces wireguard wg01 private-key KP01 + set interfaces wireguard wg02 private-key KP02 + +The command ``run show wireguard named-keypairs pubkey KP01`` will then show the public key, +which needs to be shared with the peer. + + **remote side** .. code-block:: sh @@ -90,20 +133,23 @@ asymmetric crypto, which is optional. wg01# run generate wireguard preshared-key rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= -Copy the key, it is not stored on the local file system. Make sure you -distribute that key in a safe manner, it's a symmatric key, so only you and -your peer should have knowledge if its content. +Copy the key, as it is not stored on the local file system. Make sure you +distribute that key in a safe manner, it's a symmetric key, so only you and +your peer should have knowledge of its content. .. code-block:: sh wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -**operational commands** +Operational commands +^^^^^^^^^^^^^^^^^^^^ + +**Show interface status** .. code-block:: sh - vyos@wg01# show interfaces wireguard wg01 + vyos@wg01# run show interfaces wireguard wg01 interface: wg01 public key: xHvgSJC8RTClfvjc0oX6OALxU6GGLapjthjw7x82CSw= @@ -115,3 +161,25 @@ your peer should have knowledge if its content. allowed ips: 10.2.0.0/24 latest handshake: 4 minutes, 22 seconds ago transfer: 860 B received, 948 B sent + +**Show public key of the default key** + +.. code-block:: sh + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + +**Show public key of a named key** + +.. code-block:: sh + + vyos@wg01# run show wireguard keypair pubkey KP01 + HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + + +**Delete wireguard keypairs** + +.. code-block:: sh + + vyos@wg01# wireguard keypair default + |
