diff options
28 files changed, 888 insertions, 90 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..325c629a 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -215,6 +215,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 ^^^^^^^ diff --git a/docs/build-vyos.rst b/docs/build-vyos.rst index b5f10954..2ea2c217 100644 --- a/docs/build-vyos.rst +++ b/docs/build-vyos.rst @@ -3,13 +3,16 @@ 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. -.. 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 .. 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/configuration-overview.rst b/docs/configuration-overview.rst index 67bc6316..fcaefa5e 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -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. diff --git a/docs/high-availability.rst b/docs/high-availability.rst index c967d647..9f4dd35d 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 @@ -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/install.rst b/docs/install.rst index 22e5061e..ba311a41 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -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 dowloaded 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/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/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/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/index.rst b/docs/services/index.rst index 03fdc9c4..8f7553a8 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -8,7 +8,7 @@ Services This chapter descriptes the available system/network services provided by VyOS. .. toctree:: - :hidden: + :maxdepth: 1 conntrack dhcp 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/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 29104199..e252d016 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -227,8 +227,12 @@ 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 @@ -267,7 +271,7 @@ The required config file may look like: </Authorization> Active Directory -**************** +================ Despite the fact that AD is a superset of LDAP @@ -308,16 +312,16 @@ If you only wan't to check if the user account is enabled and can authenticate .. 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..41115f8c 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 revocated; + + * ``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..a2f45913 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 releated +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 @@ -55,6 +84,18 @@ 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 +131,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 +159,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 + |
