diff options
Diffstat (limited to 'docs/configuration/interfaces')
| -rw-r--r-- | docs/configuration/interfaces/bonding.rst | 75 | ||||
| -rw-r--r-- | docs/configuration/interfaces/bridge.rst | 104 | ||||
| -rw-r--r-- | docs/configuration/interfaces/dummy.rst | 21 | ||||
| -rw-r--r-- | docs/configuration/interfaces/ethernet.rst | 263 | ||||
| -rw-r--r-- | docs/configuration/interfaces/index.rst | 199 | ||||
| -rw-r--r-- | docs/configuration/interfaces/l2tpv3.rst | 119 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst | 468 | ||||
| -rw-r--r-- | docs/configuration/interfaces/tunnel.rst | 237 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vxlan.rst | 305 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst | 148 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireless.rst | 55 |
11 files changed, 1994 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..76c8714a --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,75 @@ +Bonding +------- + +You can combine (aggregate) 2 or more physical interfaces into a single +logical one. It's called bonding, or LAG, or ether-channel, or port-channel. + +Create interface bondX, where X is just a number: + +.. code-block:: none + + set interfaces bonding bond0 description 'my-sw1 int 23 and 24' + +You are able to choose a hash policy: + +.. code-block:: none + + vyos@vyos# set interfaces bonding bond0 hash-policy + Possible completions: + layer2 use MAC addresses to generate the hash (802.3ad) + layer2+3 combine MAC address and IP address to make hash + layer3+4 combine IP address and port to make hash + +For example: + +.. code-block:: none + + set interfaces bonding bond0 hash-policy 'layer2' + +You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP +(don't forget to setup it on the other end of these links): + +.. code-block:: none + + set interfaces bonding bond0 mode '802.3ad' + +or some other modes: + +.. code-block:: none + + vyos@vyos# set interfaces bonding bond0 mode + Possible completions: + 802.3ad IEEE 802.3ad Dynamic link aggregation (Default) + active-backup + Fault tolerant: only one slave in the bond is active + broadcast Fault tolerant: transmits everything on all slave interfaces + round-robin Load balance: transmit packets in sequential order + transmit-load-balance + Load balance: adapts based on transmit load and speed + adaptive-load-balance + Load balance: adapts based on transmit and receive plus ARP + xor-hash Load balance: distribute based on MAC address + +Now bond some physical interfaces into bond0: + +.. code-block:: none + + set interfaces ethernet eth0 bond-group 'bond0' + set interfaces ethernet eth0 description 'member of bond0' + set interfaces ethernet eth1 bond-group 'bond0' + set interfaces ethernet eth1 description 'member of bond0' + +After a commit you may treat bond0 as almost a physical interface (you can't +change its` duplex, for example) and assign IPs or VIFs on it. + +You may check the result: + +.. code-block:: none + + vyos@vyos# run sh interfaces bonding + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + bond0 - u/u my-sw1 int 23 and 24 + bond0.10 192.168.0.1/24 u/u office-net + bond0.100 10.10.10.1/24 u/u management-net diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst new file mode 100644 index 00000000..30ece53d --- /dev/null +++ b/docs/configuration/interfaces/bridge.rst @@ -0,0 +1,104 @@ +Bridging +-------- + +Interfaces in VyOS can be bridged together to provide software switching of +Layer-2 traffic. + +A bridge is created when a bridge interface is defined. In the example below +we will be creating a bridge for VLAN 100 and assigning a VIF to the bridge. + +.. code-block:: none + + set interfaces bridge 'br100' + set interfaces ethernet eth1 vif 100 bridge-group bridge br100 + +Interfaces assigned to a bridge-group do not have address configuration. An IP +address can be assigned to the bridge interface itself, however, like any +normal interface. + +.. code-block:: none + + set interfaces bridge br100 address '192.168.100.1/24' + set interfaces bridge br100 address '2001:db8:100::1/64' + +Example Result: + +.. code-block:: none + + bridge br100 { + address 192.168.100.1/24 + address 2001:db8:100::1/64 + } + [...] + ethernet eth1 { + [...] + vif 100 { + bridge-group { + bridge br100 + } + } + } + +In addition to normal IP interface configuration, bridge interfaces support +Spanning-Tree Protocol. STP is disabled by default. + +.. note:: Please use caution when introducing spanning-tree protocol on a + network as it may result in topology changes. + +To enable spanning-tree use the +`set interfaces bridge <name> stp true` command: + +.. code-block:: none + + set interfaces bridge br100 stp true + +STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be +configured for the bridge-group. The MAC aging time can also be configured +using the `aging` directive. + +For member interfaces, the bridge-group `priority` and `cost` can be +configured. + +The `show bridge` operational command can be used to display configured +bridges: + +.. code-block:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 0000.000c29443b19 yes eth1.100 + +If spanning-tree is enabled, the `show bridge <name> spanning-tree` command +can be used to show STP configuration: + +.. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 0000.000c29443b19 + designated root 0000.000c29443b19 + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 15.00 bridge forward delay 15.00 + ageing time 300.00 + hello timer 0.47 tcn timer 0.00 + topology change timer 0.00 gc timer 64.63 + flags + + eth1.100 (1) + port id 8001 state forwarding + designated root 0000.000c29443b19 path cost 4 + designated bridge 0000.000c29443b19 message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + +The MAC address-table for a bridge can be displayed using the +`show bridge <name> macs` command: + +.. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:0c:29:44:3b:19 yes 0.00 diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst new file mode 100644 index 00000000..dea4c387 --- /dev/null +++ b/docs/configuration/interfaces/dummy.rst @@ -0,0 +1,21 @@ +.. _dummy-interface: + +Dummy Interfaces +---------------- + +Dummy interfaces — much like the loopback, except you can have as many as you want. +Dummy interfaces can be used as interfaces that always stay up (in the same fashion to loopbacks in IOS), or for testing purposes. + +Configuration commands: + +.. code-block:: none + + interfaces + dummy <dum[0-999]> + + address IP address + description Description + disable Disable interface + > ip IPv4 routing parameters + > ipv6 IPv6 routing parameters + redirect Incoming packet redirection destination + > traffic-policy Traffic-policy for interface
\ No newline at end of file diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..18530c8a --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,263 @@ + +Ethernet Interfaces +------------------- +.. _interfaces-ethernet: + +Ethernet interfaces allow for the configuration of speed, duplex, and hw-id +(MAC address). Below is an example configuration: + +.. code-block:: none + + set interfaces ethernet eth1 address '192.168.0.1/24' + set interfaces ethernet eth1 address '2001:db8:1::ffff/64' + set interfaces ethernet eth1 description 'INSIDE' + set interfaces ethernet eth1 duplex 'auto' + set interfaces ethernet eth1 speed 'auto' + +Resulting in: + +.. code-block:: none + + ethernet eth1 { + address 192.168.0.1/24 + address 2001:db8:1::ffff/64 + description INSIDE + duplex auto + hw-id 00:0c:29:44:3b:19 + smp_affinity auto + speed auto + } + +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:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 10baseT/Half 10baseT/Full + 100baseT/Half 100baseT/Full + 1000baseT/Full + Supports auto-negotiation: Yes + Advertised link modes: 10baseT/Half 10baseT/Full + 100baseT/Half 100baseT/Full + 1000baseT/Full + Advertised pause frame use: No + Advertised auto-negotiation: Yes + Speed: 1000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: on + MDI-X: Unknown + Supports Wake-on: d + Wake-on: d + Current message level: 0x00000007 (7) + Link detected: yes + driver: e1000 + version: 7.3.21-k8-NAPI + firmware-version: + bus-info: 0000:02:01.0 + + vyos@vyos:~$ show interfaces ethernet eth0 statistics + NIC statistics: + rx_packets: 3530 + tx_packets: 2179 + [...] + +VLAN Sub-Interfaces (802.1Q) +---------------------------- +.. _interfaces-vlan: + +802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The +term used for this is `vif`. Configuration of a tagged sub-interface is +accomplished using the configuration command +`set interfaces ethernet <name> vif <vlan-id>`. + +.. code-block:: none + + set interfaces ethernet eth1 vif 100 description 'VLAN 100' + set interfaces ethernet eth1 vif 100 address '192.168.100.1/24' + set interfaces ethernet eth1 vif 100 address '2001:db8:100::1/64' + +Resulting in: + +.. code-block:: none + + ethernet eth1 { + address 192.168.100.1/24 + address 2001:db8:100::1/64 + description INSIDE + duplex auto + hw-id 00:0c:29:44:3b:19 + smp_affinity auto + speed auto + vif 100 { + address 192.168.100.1/24 + description "VLAN 100" + } + } + +VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`: + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.16.51.129/24 u/u OUTSIDE + eth1 192.168.0.1/24 u/u INSIDE + eth1.100 192.168.100.1/24 u/u VLAN 100 + lo 127.0.0.1/8 u/u + ::1/128 + + + +.. _interfaces-qinq: + +QinQ +---- + +QinQ (802.1ad_) — allows multiple VLAN tags to be inserted into a single frame. + +QinQ can be used to tunnel vlans in a vlan. + +**vif-s** and **vif-c** stand for the ethertype tags that get set: + +The inner tag is the tag which is closest to the payload portion of the frame; it is officially called C-TAG (Customer tag, with ethertype 0x8100). +The outer tag is the one closer/closest to the Ethernet header; its name is S-TAG (Service tag, ethertype 0x88a8). + +Configuration commands: + +.. code-block:: none + + interfaces + ethernet <eth[0-999]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + vif-s <[0-4096]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + vif-c <[0-4096]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + + +Example: + +.. code-block:: none + + set interfaces ethernet eth0 vif-s 333 + set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32 + set interfaces ethernet eth0 vif-s 333 vif-c 777 + set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24 + +.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad + +.. _pppoe: + + +PPPoE +===== + +There are two main ways to setup VyOS to connect over a PPPoE internet connection. This is due to most ISPs (Internet Service Providers) providing a DSL modem that is also a wireless router. + +**First Method:** (Common for Homes) + +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) + +In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control it. +In order for this method to work, you will have to figure out how to make your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable. +Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it. +Please make sure you connect to the Ethernet Port 1 if your DSL Transeiver has a switch, as some of them only work this way. +Once you have an Ethernet device connected, i.e. eth0, then you can configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. + +**Here is an example configuration:** + +.. code-block:: none + + set interface ethernet eth0 description "DSL Modem" + set interface ethernet eth0 duplex auto + set interface ethernet eth0 smp_affinity auto + set interface ethernet eth0 speed auto + set interface ethernet eth0 pppoe 0 default-route auto + set interface ethernet eth0 pppoe 0 mtu 1492 + set interface ethernet eth0 pppoe 0 name-server auto + set interface ethernet eth0 pppoe 0 user-id <PPPoE Username> + set interface ethernet eth0 pppoe 0 password <PPPoE Password> + + +* You should add a firewall to your configuration above as well by assigning it to the pppoe0 itself as shown here: + +.. code-block:: none + + set interface ethernet eth0 pppoe 0 firewall in name NET-IN + set interface ethernet eth0 pppoe 0 firewall local name NET-LOCAL + set interface ethernet eth0 pppoe 0 firewall out name NET-OUT + +* You need your PPPoE credentials from your DSL ISP in order to configure this. The usual username is in the form of name@host.net but may vary depending on ISP. +* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit. +* With the ``default-route`` option set to ``auto``, VyOS will only add the Default Gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a Dual WAN connection, change the ``default-route`` option to ``force``. + +Handling and troubleshooting +---------------------------- + +You can test connecting and disconnecting with the below commands: + +.. code-block:: none + + disconnect interface 0 + connect interface 0 + + +You can check the PPPoE connection logs with the following: + +This command shows the current statistics, status and some of the settings (i.e. MTU) for the current connection on pppoe0. + +.. code-block:: none + + show interfaces pppoe 0 + +This command shows the entire log for the PPPoE connection starting with the oldest data. Scroll down with the <space> key to reach the end where the current data is. + +.. code-block:: none + + show interfaces pppoe 0 log + + +This command shows the same log as without the 'tail' option but only starts with the last few lines and continues to show added lines until you exit with ``Ctrl + x`` + +.. code-block:: none + + show interfaces pppoe 0 log tail + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst new file mode 100644 index 00000000..e22c8708 --- /dev/null +++ b/docs/configuration/interfaces/index.rst @@ -0,0 +1,199 @@ +########## +Interfaces +########## + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + l2tpv3 + openvpn + tunnel + vxlan + wireguard + wireless + + +.. _interfaces-addresses: + +Interface Addresses +------------------- + +Each interface can be configured with a description and address. Interface +addresses might be: + +* Static IPv4 `address 172.16.51.129/24` +* Static IPv6 `address 2001:db8:1::ffff/64` +* DHCP IPv4 `address dhcp` +* DHCP IPv6 `address dhcpv6` + +An interface description is assigned using the following command: + +.. code-block:: none + + set interfaces ethernet eth0 description 'OUTSIDE' + +IPv4 +^^^^ + +Static Address +************** + +This method is supported on all interfaces, apart from OpenVPN that uses +different syntax and wireless modems that are always autoconfigured through +PPP. + +The command is `set interfaces $type $name address $address`. Examples: + +.. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + set interfaces tunnel tun0 address 10.0.0.1/30 + set interfaces bridge br0 address 203.0.113.45/26 + set interfaces ethernet eth0 vif 30 address 192.0.30.254/24 + +DHCP +**** + +This method is supported on all physical interfaces, and those that are +directly connected to a physical interface (ethernet, VLAN, bridge, bond, +pseudo-ethernet, wireless). + +The command is `set interfaces $type $name address dhcp`. Examples: + +.. code-block:: none + + set interfaces ethernet eth0 vif 90 address dhcp + set interfaces bridge br0 address dhcp + +IPv6 +^^^^ + +Static Address +************** + +This method is supported on all interfaces, apart from OpenVPN that uses +different syntax and wireless modems that are always autoconfigured through +PPP. Static IPv6 addresses are supported on all interfaces +except :ref:`interfaces-tunnel`. + +The command is `set interfaces $type $name address $address`. Examples: + +.. code-block:: none + + set interfaces ethernet eth0 address 2001:db8:100::ffff/64 + set interfaces tunnel tun0 address 2001:db8::1/64 + set interfaces bridge br0 address 2001:db8:200::1/64 + set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64 + +DHCP +**** + +This method is supported on all physical interfaces, and those that are +directly connected to a physical interface (ethernet, VLAN, bridge, bond, +pseudo-ethernet, wireless). + +The command is `set interfaces $type $name address dhcpv6`. Examples: + +.. code-block:: none + + set interfaces bonding bond1 address dhcpv6 + set interfaces bridge br0 vif 56 address dhcpv6 + +Autoconfiguration (SLAAC) +************************* + +SLAAC is specified in RFC4862_. This method is supported on all physical +interfaces, and those that are directly connected to a physical interface +(ethernet, VLAN, bridge, bond, pseudo-ethernet, wireless). + +The command is `set interfaces $type $name ipv6 address autoconf`. Examples: + +.. code-block:: none + + set interfaces ethernet eth0 vif 90 ipv6 address autoconf + set interfaces bridge br0 ipv6 address autoconf + +.. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. + +EUI-64 +****** + +EUI-64 (64-Bit Extended Unique Identifier) as specified in RFC4291_. IPv6 +addresses in /64 networks can be automatically generated from the prefix and +MAC address, if you specify the prefix. + +The command is `set interfaces $type $name ipv6 address eui64 $prefix`. +Examples: + +.. code-block:: none + + set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 + set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 + + +Router Advertisements +********************* + +Router advertisements are described in `RFC4861 section 4.2`_. They are part of what is known as SLAAC (Stateless Address Autoconfiguration). + +To enable or disable, use: + +.. code-block:: none + + set interfaces <interface> ipv6 router-advert send-advert <true or false> + + +To set the options described in "Router Advertisement Message Format": + +.. code-block:: none + + vyos@vyos# set interfaces <interface> ipv6 router-advert + Possible completions: + cur-hop-limit Value to be placed in the "Current Hop Limit" field in RAs + default-lifetime Value to be placed in "Router Lifetime" field in RAs + default-preference Default router preference + link-mtu Value of link MTU to place in RAs + managed-flag Value for "managed address configuration" flag in RAs + max-interval Maximum interval between unsolicited multicast RAs + min-interval Minimum interval between unsolicited multicast RAs + + name-server IPv6 address of a Recursive DNS Server + other-config-flag Value to be placed in the "other configuration" flag in RAs + +> prefix IPv6 prefix to be advertised in Router Advertisements (RAs) + reachable-time Value to be placed in "Reachable Time" field in RAs + retrans-timer Value to place in "Retrans Timer" field in RAs. + send-advert Enable/disable sending RAs + + +**Prefix Information** + +Prefix information is described in `RFC4861 section 4.6.2`_ + +.. code-block:: none + + vyos@vyos# set interfaces <interface> ipv6 router-advert prefix <h:h:h:h:h:h:h:h/x> + Possible completions: + autonomous-flag Whether prefix can be used for address auto-configuration + on-link-flag Flag that prefix can be used for on-link determination + preferred-lifetime Time in seconds that the prefix will remain preferred + valid-lifetime Time in seconds that the prefix will remain valid + +**Receiving Router Advertisements** + +To receive and accept RAs on an interface, you need to enable it with the following configuration command + +.. code-block:: none + + vyos@vyos# set system sysctl custom net.ipv6.conf.<interface name>.accept_ra value 2 + + +.. _`RFC4861 section 4.6.2`: https://tools.ietf.org/html/rfc4861#section-4.6.2 +.. _`RFC4861 section 4.2`: https://tools.ietf.org/html/rfc4861#section-4.2 +.. _RFC4862: https://tools.ietf.org/html/rfc4862 +.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst new file mode 100644 index 00000000..4514412d --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -0,0 +1,119 @@ +.. _l2tpv3-interface: + +L2TPv3 Interfaces +----------------- + +L2TPv3 is a pseudowire protocol, you can read more about here `Wikipedia L2TPv3`_ or `RFC3921`_ + +L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited to PPP. + + +L2TPv3 over IP +^^^^^^^^^^^^^^ + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + tunnel-id 200 + } + +Inverse configuration has to be applied to the remote side. + +L2TPv3 over UDP +^^^^^^^^^^^^^^^ + +UDP mode works better with NAT: + +* Set local-ip to your local IP (LAN). +* Add a forwarding rule matching UDP port on your internet router. + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 + } + +To create more than one tunnel, use distinct UDP ports. + + +L2TPv3 over IPSec, L2 VPN (bridge) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is the LAN extension use case. The eth0 port of the distant VPN peers will be directly connected like if there was a switch between them. + +IPSec: + +.. code-block:: none + + set vpn ipsec ipsec-interfaces <VPN-interface> + set vpn ipsec esp-group test-ESP-1 compression 'disable' + set vpn ipsec esp-group test-ESP-1 lifetime '3600' + set vpn ipsec esp-group test-ESP-1 mode 'transport' + set vpn ipsec esp-group test-ESP-1 pfs 'enable' + set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128' + set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1' + set vpn ipsec ike-group test-IKE-1 ikev2-reauth 'no' + set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1' + set vpn ipsec ike-group test-IKE-1 lifetime '3600' + set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5' + set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128' + set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1' + set vpn ipsec site-to-site peer <peer-ip> authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer <peer-ip> authentication pre-shared-secret <pre-shared-key> + set vpn ipsec site-to-site peer <peer-ip> connection-type 'initiate' + set vpn ipsec site-to-site peer <peer-ip> ike-group 'test-IKE-1' + set vpn ipsec site-to-site peer <peer-ip> ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer <peer-ip> local-address <local-ip> + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-public-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 esp-group 'test-ESP-1' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 protocol 'l2tp' + +Bridge: + +.. code-block:: none + + set interfaces bridge br0 description 'L2 VPN Bridge' + # remote side in this example: + # set interfaces bridge br0 address '172.16.30.18/30' + set interfaces bridge br0 address '172.16.30.17/30' + set interfaces ethernet eth0 bridge-group bridge 'br0' + set interfaces ethernet eth0 description 'L2 VPN Physical port' + +L2TPv3: + +.. code-block:: none + + set interfaces l2tpv3 l2tpeth0 bridge-group bridge 'br0' + set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel' + set interfaces l2tpv3 l2tpeth0 destination-port '5000' + set interfaces l2tpv3 l2tpeth0 encapsulation 'ip' + set interfaces l2tpv3 l2tpeth0 local-ip <local-ip> + set interfaces l2tpv3 l2tpeth0 mtu '1500' + set interfaces l2tpv3 l2tpeth0 peer-session-id '110' + set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10' + set interfaces l2tpv3 l2tpeth0 remote-ip <peer-ip> + set interfaces l2tpv3 l2tpeth0 session-id '110' + set interfaces l2tpv3 l2tpeth0 source-port '5000' + set interfaces l2tpv3 l2tpeth0 tunnel-id '10' + +.. _`Wikipedia L2TPv3`: http://en.wikipedia.org/wiki/L2TPv3 +.. _`RFC3921`: https://tools.ietf.org/html/rfc3931
\ No newline at end of file diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst new file mode 100644 index 00000000..b2559c95 --- /dev/null +++ b/docs/configuration/interfaces/openvpn.rst @@ -0,0 +1,468 @@ +.. _openvpn: + +####### +OpenVPN +####### + +Traditionally hardware routers implement IPsec exclusively due to relative +ease of implementing it in hardware and insufficient CPU power for doing +encryption in software. Since VyOS is a software router, this is less of a +concern. OpenVPN has been widely used on UNIX platform for a long time and is +a popular option for remote access VPN, though it's also capable of +site-to-site connections. + +Advantages of OpenVPN are: + +* It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it will work even through a double NAT: perfect for public + hotspots and such + +* It's easy to setup and offers very flexible split tunneling + +* There's a variety of client GUI frontends for any platform + +Disadvantages are: + +* It's slower than IPsec due to higher protocol overhead and the fact it runs + in user mode while IPsec, on Linux, is in kernel mode + +* None of the operating systems have client software installed by default + +In the VyOS CLI, a key point often overlooked is that rather than being +configured using the `set vpn` stanza, OpenVPN is configured as a network +interface using `set interfaces openvpn`. + +OpenVPN Site-To-Site +#################### + +While many are aware of OpenVPN as a Client VPN solution, it is often +overlooked as a site-to-site VPN solution due to lack of support for this mode +in many router platforms. + +Site-to-site mode supports x.509 but doesn't require it and can also work with +static keys, which is simpler in many cases. In this example, we'll configure +a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key. + +First, one one of the systems generate the key using the operational command +``generate openvpn key <filename>``. This will generate a key with the name +provided in the `/config/auth/` directory. Once generated, you will need to +copy this key to the remote router. + +In our example, we used the filename `openvpn-1.key` which we will reference +in our configuration. + +* The public IP address of the local side of the VPN will be 198.51.100.10 +* The remote will be 203.0.113.11 +* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. +* OpenVPN allows for either TCP or UDP. UDP will provide the lowest latency, + while TCP will work better for lossy connections; generally UDP is preferred + when possible. +* The official port for OpenVPN is 1194, which we reserve for client VPN; we + will use 1195 for site-to-site VPN. +* The `persistent-tunnel` directive will allow us to configure tunnel-related + attributes, such as firewall policy as we would on any normal network + interface. +* If known, the IP of the remote router can be configured using the + `remote-host` directive; if unknown, it can be omitted. We will assume a + dynamic IP for our remote router. + +Local Configuration: + +.. code-block:: none + + set interfaces openvpn vtun1 mode site-to-site + set interfaces openvpn vtun1 protocol udp + set interfaces openvpn vtun1 persistent-tunnel + set interfaces openvpn vtun1 local-host '198.51.100.10' + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 local-address '10.255.1.1' + set interfaces openvpn vtun1 remote-address '10.255.1.2' + +Remote Configuration: + +.. code-block:: none + + set interfaces openvpn vtun1 mode site-to-site + set interfaces openvpn vtun1 protocol udp + set interfaces openvpn vtun1 persistent-tunnel + set interfaces openvpn vtun1 remote-host '198.51.100.10' + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 local-address '10.255.1.2' + set interfaces openvpn vtun1 remote-address '10.255.1.1' + +The configurations above will default to using 128-bit Blowfish in CBC mode +for encryption and SHA-1 for HMAC authentication. These are both considered +weak, but a number of other encryption and hashing algorithms are available: + +For Encryption: + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 encryption + Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + bf128 Blowfish algorithm with 128-bit key + bf256 Blowfish algorithm with 256-bit key + aes128 AES algorithm with 128-bit key + aes192 AES algorithm with 192-bit key + aes256 AES algorithm with 256-bit key + +For Hashing: + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 hash + Possible completions: + md5 MD5 algorithm + sha1 SHA-1 algorithm + sha256 SHA-256 algorithm + sha512 SHA-512 algorithm + +If you change the default encryption and hashing algorithms, be sure that the +local and remote ends have matching configurations, otherwise the tunnel will +not come up. + +Static routes can be configured referencing the tunnel interface; for example, +the local router will use a network of 10.0.0.0/16, while the remote has a +network of 10.1.0.0/16: + +Local Configuration: + +.. code-block:: none + + set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1 + +Remote Configuration: + +.. code-block:: none + + set protocols static interface-route 10.0.0.0/16 next-hop-interface vtun1 + +Firewall policy can also be applied to the tunnel interface for `local`, `in`, +and `out` directions and function identically to ethernet interfaces. + +If making use of multiple tunnels, OpenVPN must have a way to distinguish +between different tunnels aside from the pre-shared-key. This is either by +referencing IP address or port number. One option is to dedicate a public IP +to each tunnel. Another option is to dedicate a port number to each tunnel +(e.g. 1195,1196,1197...). + +OpenVPN status can be verified using the `show openvpn` operational commands. +See the built-in help for a complete list of options. + +OpenVPN Server +############## + +Multi-client server is the most popular OpenVPN mode on routers. It always uses +x.509 authentication and therefore requires a PKI setup. This guide assumes you +have already setup a PKI and have a CA certificate, a server certificate and +key, a certificate revocation list, a Diffie-Hellman key exchange parameters +file. You do not need client certificates and keys for the server setup. + +In this example we will use the most complicated case: a setup where each +client is a router that has its own subnet (think HQ and branch offices), since +simpler setups are subsets of it. + +Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and +all client subnets belong to 10.23.0.0/20. All clients need access to the +192.168.0.0/16 network. + +First we need to specify the basic settings. 1194/UDP is the default. The +`persistent-tunnel` option is recommended, it prevents the TUN/TAP device from +closing on connection resets or daemon reloads. + + +.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is used to renegotiate data channel after n seconds. When used at both server and client, the lower value will trigger the renegotiation. If you set it to 0 on one side of the connection (to disable it), the chosen value on the other side will determine when the renegotiation will occur. + + +.. code-block:: none + + set interfaces openvpn vtun10 mode server + set interfaces openvpn vtun10 local-port 1194 + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol udp + +Then we need to specify the location of the cryptographic materials. Suppose +you keep the files in `/config/auth/openvpn` + +.. code-block:: none + + set interfaces openvpn vtun10 tls ca-cert-file /config/auth/openvpn/ca.crt + set interfaces openvpn vtun10 tls cert-file /config/auth/openvpn/server.crt + set interfaces openvpn vtun10 tls key-file /config/auth/openvpn/server.key + set interfaces openvpn vtun10 tls crl-file /config/auth/openvpn/crl.pem + set interfaces openvpn vtun10 tls dh-file /config/auth/openvpn/dh2048.pem + +Now we need to specify the server network settings. In all cases we need to +specify the subnet for client tunnel endpoints. Since we want clients to access +a specific network behind out router, we will use a push-route option for +installing that route on clients. + +.. code-block:: none + + set interfaces openvpn vtun10 server push-route 192.168.0.0/16 + set interfaces openvpn vtun10 server subnet 10.23.1.0/24 + +Since it's a HQ and branch offices setup, we will want all clients to have +fixed addresses and we will route traffic to specific subnets through them. We +need configuration for each client to achieve this. + +.. note:: Clients are identified by the CN field of their x.509 certificates, + in this example the CN is ``client0``: + +.. code-block:: none + + set interfaces openvpn vtun10 server client client0 ip 10.23.1.10 + set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25 + +OpenVPN **will not** automatically create routes in the kernel for client +subnets when they connect and will only use client-subnet association +internally, so we need to create a route to the 10.23.0.0/20 network ourselves: + +.. code-block:: none + + set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10 + + +Client Authentication +===================== + +OpenLDAP +-------- + +Enterprise installations usually ship a kind of directory service which is used +to have a single password store for all employees. VyOS and OpenVPN support using +LDAP/AD as single user backend. + +Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is +shipped with every VyOS installation. A dedicated configuration file is required. +It is best practise to store it in ``/config`` to survive image updates + +.. code-block:: none + + set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + +The required config file may look like: + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://ldap.example.com + # Bind DN (If your LDAP server doesn't support anonymous binds) + BindDN cn=LDAPUser,dc=example,dc=com + # Bind Password password + Password S3cr3t + # Network timeout (in seconds) + Timeout 15 + </LDAP> + + <Authorization> + # Base DN + BaseDN "ou=people,dc=example,dc=com" + # User Search Filter + SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" + # Require Group Membership - allow all users + RequireGroup false + </Authorization> + +Active Directory +---------------- + +Despite the fact that AD is a superset of LDAP + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no + </LDAP> + + <Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> + </Authorization> + +If you only want to check if the user account is enabled and can authenticate +(against the primary group) the following snipped is sufficient: + +.. code-block:: none + + <LDAP> + 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 "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false + </Authorization> + +A complete LDAP auth OpenVPN configuration could look like the following example: + +.. code-block:: none + + vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option --client-cert-not-required + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 1.1.1.1 + name-server 9.9.9.9 + subnet 172.18.100.128/29 + } + tls { + ca-cert-file /config/auth/ca.crt + cert-file /config/auth/server.crt + dh-file /config/auth/dh1024.pem + 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:: none + + 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:: none + + 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:: none + + 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. + +Troubleshooting +############### + +VyOS provides some operational commands on OpenVPN. + +Check status +============ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client status + + Use this command to check the tunnel status for OpenVPN client. + +.. opcmd:: show openvpn server status + + Use this command to check the tunnel status for OpenVPN server. + +.. opcmd:: show openvpn site-to-site status + + Use this command to check the tunnel status for OpenVPN site-to-site. + + +Reset OpenVPN +============= + +The following commands let you reset OpenVPN. + +.. opcmd:: reset openvpn client <text> + + Use this command to reset specified OpenVPN client. + +.. opcmd:: reset openvpn interface <interface> + + Uset this command to reset the OpenVPN process on a specific interface. + + diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst new file mode 100644 index 00000000..43c217a0 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.rst @@ -0,0 +1,237 @@ +.. _interfaces-tunnel: + +Tunnel Interfaces +================= + +This article touches on 'classic' IP tunneling protocols. + +GRE is often seen as a one size fits all solution when it comes to classic IP tunneling protocols, and for a good reason. +However, there are more specialized options, and many of them are supported by VyOS. There are also rather obscure GRE options that can be useful. + +All those protocols are grouped under 'interfaces tunnel' in VyOS. Let's take a closer look at the protocols and options currently supported by VyOS. + +IPIP +---- + +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: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.20 + set interfaces tunnel tun0 address 192.168.100.200 + +IP6IP6 +------ + +This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this encapsulation specifically, but it's a natural specific case of IPv6 encapsulation mechanisms described in RFC2473_. + +It's not likely that anyone will need it any time soon, but it does exist. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip + set interfaces tunnel tun0 local-ip 2001:db8:aa::1/64 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2/64 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +IPIP6 +----- + +In the future this is expected to be a very useful protocol (though there are `other proposals`_). + +As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1/64 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2/64 + set interfaces tunnel tun0 address 192.168.70.80 + +6in4 (SIT) +---------- + + +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. +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: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation sit + set interfaces tunnel tun0 local-ip 192.0.2.10 + 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) +----------------------------------- + +A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP protocol 47. The +main benefit of a GRE tunnel is that you are able to route traffic across disparate networks. +GRE also supports multicast traffic and supports routing protocols that leverage multicast to +form neighbor adjacencies. + +Configuration +^^^^^^^^^^^^^ + +A basic configuration requires a tunnel source (local-ip), a tunnel destination (remote-ip), +an encapsulation type (gre), and an address (ipv4/ipv6). Below is a configuration example +taken from a VyOS router and a Cisco IOS router. The main difference between these two +configurations is that VyOS requires you explicitly configure the encapsulation type. +The Cisco router defaults to 'gre ip' otherwise it would have to be configured as well. + +**VyOS Router:** + +.. code-block:: none + + set interfaces tunnel tun100 address '10.0.0.1/30' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '198.51.100.2' + set interfaces tunnel tun100 remote-ip '203.0.113.10' + +**Cisco IOS Router:** + +.. code-block:: none + + interface Tunnel100 + ip address 10.0.0.2 255.255.255.252 + tunnel source 203.0.113.10 + tunnel destination 198.51.100.2 + + +Tunnel keys +^^^^^^^^^^^ + +GRE is also the only classic protocol that allows creating multiple tunnels with the same source and destination due to its support for tunnel keys. Despite its name, this feature has nothing to do with security: it's simply an identifier that allows routers to tell one tunnel from another. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 10.40.50.60/24 + set interfaces tunnel tun0 parameters ip key 10 + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 172.16.17.18/24 + set interfaces tunnel tun0 parameters ip key 20 + + +GRE-Bridge +^^^^^^^^^^ +While normal GRE is for layer 3, GRE-Bridge is for layer 2. GRE-Bridge can encapsulate Ethernet frames, thus it can be bridged with other interfaces to create datalink layer segments that span multiple remote sites. + +Layer 2 GRE example: + +.. code-block:: none + + set interfaces bridge br0 + set interfaces tunnel tun0 encapsulation gre-bridge + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 parameters ip bridge-group bridge br0 + set interfaces ethernet eth1 bridge-group br0 + +As you can see, the bridge-group option for tunnels is in a rather unusual place, different from all other interfaces. + + +Troubleshooting +^^^^^^^^^^^^^^^ + +GRE is a well defined standard that is common in most networks. While not inherently difficult +to configure there are a couple of things to keep in mind to make sure the configuration performs +as expected. A common cause for GRE tunnels to fail to come up correctly include ACL or Firewall +configurations that are discarding IP protocol 47 or blocking your source/desintation traffic. + +**1. Confirm IP connectivity between tunnel local-ip and remote-ip:** + +.. code-block:: none + + vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 + PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. + 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms + 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms + 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms + 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + + --- 203.0.113.10 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3007ms + rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms + +**2. Confirm the link type has been set to GRE:** + +.. code-block:: none + + vyos@vyos:~$ show interfaces tunnel tun100 + tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 + +**3. Confirm IP connectivity across the tunnel:** + +.. code-block:: none + + vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 + PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + + --- 10.0.0.2 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3008ms + rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms + +Virtual Tunnel Interface (VTI) +------------------------------ + +Set Virtual Tunnel Interface + +.. code-block:: none + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: none + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + } + + +.. _RFC2003: https://tools.ietf.org/html/rfc2003 +.. _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/ diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst new file mode 100644 index 00000000..e3eb5c43 --- /dev/null +++ b/docs/configuration/interfaces/vxlan.rst @@ -0,0 +1,305 @@ +VXLAN +----- + +VXLAN is an overlaying Ethernet over IP protocol. +It is described in RFC7348_. + +If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames +may be blocked by the hypervisor. + +Multicast VXLAN +^^^^^^^^^^^^^^^^ + +Example Topology: + +PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in +the same broadcast domain. + +Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 +as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and +sends it to its designated multicast-address via Spine1. When Spine1 receives +this packet it forwards it to all other Leafs who has joined the same +multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards +it, while at the same time learning that PC4 is reachable behind Leaf2, because +the encapsulated packet had Leaf2's IP-address set as source IP. + +PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and +this time forwards to Leaf2's unicast address directly because it learned the +location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that +it came from Leaf3 and so remembers that PC5 is reachable via Leaf3. + +Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not +be using the multicast-address between the Leafs as they both know behind which +Leaf the PCs are connected. This saves traffic as less multicast packets sent +reduces the load on the network, which improves scalability when more Leafs are +added. + +For optimal scalability Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leafs. Unfortunately, VyOS does not yet +support this. + +Configuration commands +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + interfaces + vxlan <vxlan[0-16777215]> + address # IP address of the VXLAN interface + bridge-group # Configure a L2 bridge-group + description # Description + group <ipv4> # IPv4 Multicast group address (required) + ip # IPv4 routing options + ipv6 # IPv6 routing options + link <dev> # IP interface for underlay of this vxlan overlay (optional) + mtu # MTU + policy # Policy routing options + remote # Remote address of the VXLAN tunnel, used for PTP instead of multicast + vni <1-16777215> # Virtual Network Identifier (required) + +Configuration Example +^^^^^^^^^^^^^^^^^^^^^ + +The setup is this: + +Leaf2 - Spine1 - Leaf3 + +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a +VyOS router running 1.2. + +This topology was built using GNS3. + +Topology: + +.. code-block:: none + + Spine1: + fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 + fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + + Leaf2: + Eth0 towards Spine1, IP-address: 10.1.2.2/24 + Eth1 towards a vlan-aware switch + + Leaf3: + Eth0 towards Spine1, IP-address 10.1.3.3/24 + Eth1 towards a vlan-aware switch + +Spine1 Configuration: + +.. code-block:: none + + conf t + ip multicast-routing + ! + interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode + ! + interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode + ! + router ospf 1 + network 10.0.0.0 0.255.255.255 area 0 + +Multicast-routing is required for the leafs to forward traffic between each +other in a more scalable way. This also requires PIM to be enabled towards the +Leafs so that the Spine can learn what multicast groups each Leaf expect traffic +from. + +Leaf2 configuration: + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.2.2/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces ethernet eth1 vif 241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces ethernet eth1 vif 242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 vni '242' + +Leaf3 configuration: + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.3.3/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces ethernet eth1 vif 241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces ethernet eth1 vif 242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 vni '242' + +As you can see, Leaf2 and Leaf3 configuration is almost identical. There are +lots of commands above, I'll try to into more detail below, command +descriptions are placed under the command boxes: + +.. code-block:: none + + set interfaces bridge br241 address '172.16.241.1/24' + +This commands creates a bridge that is used to bind traffic on eth1 vlan 241 +with the vxlan241-interface. The IP-address is not required. It may however be +used as a default gateway for each Leaf which allows devices on the vlan to +reach other subnets. This requires that the subnets are redistributed by OSPF +so that the Spine will learn how to reach it. To do this you need to change the +OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be +advertised. + +.. code-block:: none + + set interfaces ethernet eth1 vif 241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 bridge-group bridge 'br241' + +Binds eth1 vif 241 and vxlan241 to each other by putting them in the same +bridge-group. Internal VyOS requirement. + +.. code-block:: none + + set interfaces vxlan vxlan241 group '239.0.0.241' + +The multicast-group used by all Leafs for this vlan extension. Has to be the +same on all Leafs that has this interface. + +.. code-block:: none + + set interfaces vxlan vxlan241 link 'eth0' + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +.. code-block:: none + + set interfaces vxlan vxlan241 vni '241' + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +.. code-block:: none + + set interfaces vxlan vxlan241 remote-port 12345 + +The destination port used for creating a VXLAN interface in Linux defaults to +its pre-standard value of 8472 to preserve backwards compatibility. A +configuration directive to support a user-specified destination port to override +that behavior is available using the above command. + +Older Examples +^^^^^^^^^^^^^^ + +Example for bridging normal L2 segment and vxlan overlay network, and using a +vxlan interface as routing interface. + +.. code-block:: none + + interfaces { + bridge br0 { + } + ethernet eth0 { + address dhcp + } + loopback lo { + } + vxlan vxlan0 { + bridge-group { + bridge br0 + } + group 239.0.0.1 + vni 0 + } + vxlan vxlan1 { + address 192.168.0.1/24 + link eth0 + group 239.0.0.1 + vni 1 + } + } + +Here is a working configuration that creates a VXLAN between two routers. Each +router has a VLAN interface (26) facing the client devices and a VLAN interface +(30) that connects it to the other routers. With this configuration, traffic +can flow between both routers' VLAN 26, but can't escape since there is no L3 +gateway. You can add an IP to a bridge-group to create a gateway. + +.. code-block:: none + + interfaces { + bridge br0 { + } + ethernet eth0 { + duplex auto + smp-affinity auto + speed auto + vif 26 { + bridge-group { + bridge br0 + } + } + vif 30 { + address 10.7.50.6/24 + } + } + loopback lo { + } + vxlan vxlan0 { + bridge-group { + bridge br0 + } + group 239.0.0.241 + vni 241 + } + } + +Unicast VXLAN +^^^^^^^^^^^^^ + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly. +Let's change the Multicast example from above: + + +.. code-block:: none + + # leaf2 and leaf3 + delete interfaces vxlan vxlan241 group '239.0.0.241' + delete interfaces vxlan vxlan241 link 'eth0' + + # leaf2 + set interface vxlan vxlan241 remote 10.1.3.3 + + # leaf3 + set interface vxlan vxlan241 remote 10.1.2.2 + +The default port udp is set to 8472. +It can be changed with ``set interface vxlan <vxlanN> remote-port <port>`` + + +.. target-notes:: + +.. _RFC7348: https://datatracker.ietf.org/doc/rfc7348/ diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst new file mode 100644 index 00000000..a7241613 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.rst @@ -0,0 +1,148 @@ +.. _wireguard: + +WireGuard VPN Interface +----------------------- + +WireGuard is an extremely simple yet fast and modern VPN that utilizes +state-of-the-art cryptography. See https://www.wireguard.com for more +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:: none + + wg01:~$ configure + wg01# run generate wireguard keypair + +The public key is being shared with your peer(s), your peer will encrypt all +traffic to your system using this public key. + +.. code-block:: none + + wg01# run show wireguard pubkey + u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + +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 +initiate the connections to your system, you need to define a port your clients +can connect to, otherwise it's randomly chosen and may make it difficult with +firewall rules, since the port may be a different one when you reboot your +system. + +You will also need the public key of your peer as well as the network(s) you +want to tunnel (allowed-ips) to configure a wireguard tunnel. The public key +below is always the public key from your peer, not your local one. + +**local side** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.1/24' + set interfaces wireguard wg01 description 'VPN-to-wg02' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24' + set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.142:12345' + set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' + set interfaces wireguard wg01 port '12345' + set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 + +.. note:: The `endpoint` must be an IP and not a fully qualified domain name (FQDN). Using a FQDN will result in unexpected behavior. + +The last step is to define an interface route for 10.2.0.0/24 to get through +the wireguard interface `wg01`. Multiple IPs or networks can be defined and +routed, the last check is allowed-ips which either prevents or allows the +traffic. + +**remote side** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.2.0.1/24' + set interfaces wireguard wg01 description 'VPN-to-wg01' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24' + set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.124:12345' + set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' + set interfaces wireguard wg01 port '12345' + set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01 + +Assure that your firewall rules allow the traffic, in which case you have a +working VPN using wireguard. + +.. code-block:: none + + wg01# ping 10.2.0.1 + PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data. + 64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms + 64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms + + wg02# ping 10.1.0.1 + PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data. + 64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms + 64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto, which is optional. + +.. code-block:: none + + wg01# run generate wireguard preshared-key + rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= + +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:: none + + 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 +^^^^^^^^^^^^^^^^^^^^ + +**Show interface status** + +.. code-block:: none + + vyos@wg01# run show interfaces wireguard wg01 + + interface: wg01 + public key: xHvgSJC8RTClfvjc0oX6OALxU6GGLapjthjw7x82CSw= + private key: (hidden) + listening port: 12345 + + peer: 9Ek3R30mG6Vk+GHsENtPF0b9Ul+ftxx4dDBa1bdBxX8= + endpoint: 192.168.0.142:12345 + 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:: none + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + + +**Delete wireguard keypairs** + +.. code-block:: none + + vyos@wg01# wireguard keypair default + diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst new file mode 100644 index 00000000..a7e796e9 --- /dev/null +++ b/docs/configuration/interfaces/wireless.rst @@ -0,0 +1,55 @@ +Wireless Interfaces +------------------- +.. _interfaces-wireless: + +Wireless, for example WiFi 802.11 b/g/n, interfaces allow for connection to +WiFi networks or act as an access-point. +If your device is configurable it will appear as `wlan` in `show interfaces`. + +To be able to use the wireless interfaces you will first need to set a +regulatory domain with the country code of your locaion. + +.. code-block:: none + + set system wifi-regulatory-domain SE + +An example on how to set it up as an access point: + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.99.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 ssid '<your ssid>' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '<your passphrase>' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.99.1/24 + channel 1 + mode g + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "<your passphrase>" + } + } + ssid "<your ssid>" + type access-point + } + } + system { + [...] + wifi-regulatory-domain SE + } + +To get it to work as a access point with this configuration you will need +to set up a DHCP server to work with that network. |