summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_static/images/apu4c4_rack_5.jpgbin0 -> 2957985 bytes
-rw-r--r--docs/appendix/examples/azure-vpn-bgp.rst128
-rw-r--r--docs/appendix/examples/azure-vpn-dual-bgp.rst155
-rw-r--r--docs/appendix/examples/index.rst2
-rw-r--r--docs/appendix/examples/tunnelbroker-ipv6.rst151
-rw-r--r--docs/appendix/releasenotes.rst51
-rw-r--r--docs/appendix/vyos-on-baremetal.rst5
-rw-r--r--docs/build-vyos.rst35
-rw-r--r--docs/configuration-overview.rst3
-rw-r--r--docs/history.rst2
-rw-r--r--docs/install.rst2
-rw-r--r--docs/load-balancing.rst16
-rw-r--r--docs/routing/ospf.rst17
-rw-r--r--docs/routing/routing-policy.rst4
-rw-r--r--docs/vpn/openvpn.rst90
-rw-r--r--docs/vpn/site2site_ipsec.rst103
-rw-r--r--docs/vpn/wireguard.rst70
17 files changed, 791 insertions, 43 deletions
diff --git a/docs/_static/images/apu4c4_rack_5.jpg b/docs/_static/images/apu4c4_rack_5.jpg
new file mode 100644
index 00000000..534bbad6
--- /dev/null
+++ b/docs/_static/images/apu4c4_rack_5.jpg
Binary files differ
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..f9689851 100644
--- a/docs/appendix/examples/index.rst
+++ b/docs/appendix/examples/index.rst
@@ -13,3 +13,5 @@ This chapter contains various configuration Examples
zone-policy
bgp-ipv6-unnumbered
ospf-unnumbered
+ azure-vpn-bgp
+ azure-vpn-dual-bgp
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 1ed0938f..bd1ab8d8 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/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/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/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/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/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..955c2d40 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
@@ -99,11 +140,14 @@ your peer should have knowledge if its content.
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
+
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-24 19:35:03 +0000