diff options
| -rw-r--r-- | docs/examples.rst | 2 | ||||
| -rw-r--r-- | docs/index.rst | 3 | ||||
| -rw-r--r-- | docs/interfaces/addresses.rst | 122 | ||||
| -rw-r--r-- | docs/interfaces/bonding.rst | 75 | ||||
| -rw-r--r-- | docs/interfaces/bridging.rst | 104 | ||||
| -rw-r--r-- | docs/interfaces/ethernet.rst | 70 | ||||
| -rw-r--r-- | docs/interfaces/index.rst | 60 | ||||
| -rw-r--r-- | docs/interfaces/vlan.rst | 47 | ||||
| -rw-r--r-- | docs/interfaces/vti.rst | 22 | ||||
| -rw-r--r-- | docs/interfaces/vxlan.rst | 283 | ||||
| -rw-r--r-- | docs/interfaces/wireguard.rst | 4 | ||||
| -rw-r--r-- | docs/interfaces/wireless.rst | 55 | ||||
| -rw-r--r-- | docs/network-interfaces.rst | 807 | ||||
| -rw-r--r-- | docs/qos.rst | 62 | ||||
| -rw-r--r-- | docs/quick-start.rst | 2 | ||||
| -rw-r--r-- | docs/services/index.rst | 1 | ||||
| -rw-r--r-- | docs/system.rst | 10 | ||||
| -rw-r--r-- | docs/vpn.rst | 2 |
18 files changed, 913 insertions, 818 deletions
diff --git a/docs/examples.rst b/docs/examples.rst index 7194188a..f216060e 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -6,7 +6,7 @@ Appendix B - Configuration Examples VyOS DMVPN Hub -------------- -General infomration can be found in the DMVPN_ chapter. +General infomration can be found in the :ref:`vpn-dmvpn` chapter. Configuration ^^^^^^^^^^^^^ diff --git a/docs/index.rst b/docs/index.rst index f340f8b8..230b1362 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,12 +13,13 @@ as a router and firewall platform for cloud deployments. .. toctree:: :maxdepth: 2 :caption: Contents: + :includehidden: install.rst cli.rst quick-start.rst configuration-overview.rst - network-interfaces.rst + interfaces/index.rst routing.rst firewall.rst nat.rst diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst new file mode 100644 index 00000000..4c3ca7f6 --- /dev/null +++ b/docs/interfaces/addresses.rst @@ -0,0 +1,122 @@ +.. _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:: sh + + 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:: sh + + 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:: sh + + 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-vti`. + +The command is `set interfaces $type $name address $address`. Examples: + +.. code-block:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 + set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 + + + +.. _RFC4862: https://tools.ietf.org/html/rfc4862 +.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 diff --git a/docs/interfaces/bonding.rst b/docs/interfaces/bonding.rst new file mode 100644 index 00000000..d865eb78 --- /dev/null +++ b/docs/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:: sh + + set interfaces bonding bond0 description 'my-sw1 int 23 and 24' + +You are able to choose a hash policy: + +.. code-block:: sh + + 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:: sh + + 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:: sh + + set interfaces bonding bond0 mode '802.3ad' + +or some other modes: + +.. code-block:: sh + + 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:: sh + + 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:: sh + + 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/interfaces/bridging.rst b/docs/interfaces/bridging.rst new file mode 100644 index 00000000..7fb20e0a --- /dev/null +++ b/docs/interfaces/bridging.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:: sh + + 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:: sh + + set interfaces bridge br100 address '192.168.100.1/24' + set interfaces bridge br100 address '2001:db8:100::1/64' + +Example Result: + +.. code-block:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst new file mode 100644 index 00000000..8ef002f8 --- /dev/null +++ b/docs/interfaces/ethernet.rst @@ -0,0 +1,70 @@ + +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:: sh + + 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:: sh + + 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` and +`show interfaces ethernet <name> statistics`. Statistics available are driver +dependent. + +.. code-block:: sh + + 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 + [...] diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst new file mode 100644 index 00000000..577ffe09 --- /dev/null +++ b/docs/interfaces/index.rst @@ -0,0 +1,60 @@ +.. _network-interfaces: + +Network Interfaces +================== + +Configured interfaces on a VyOS system can be displayed using the +`show interfaces` command. + +.. code-block:: sh + + 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 + lo 127.0.0.1/8 u/u + ::1/128 + vyos@vyos:~$ + +A specific interface can be shown using the `show interfaces <type> <name>` +command. + +.. code-block:: sh + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 + link/ether 00:0c:29:44:3b:0f brd ff:ff:ff:ff:ff:ff + inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0 + inet6 fe80::20c:29ff:fe44:3b0f/64 scope link + valid_lft forever preferred_lft forever + Description: OUTSIDE + + RX: bytes packets errors dropped overrun mcast + 274397 3064 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 257276 1890 0 0 0 0 + vyos@vyos:~$ + +Different network interfaces provide type-specific configuration. Ethernet +interfaces, for example, allow the configuration of speed and duplex. + +Many services, such as network routing, firewall, and traffic policy also +maintain interface-specific configuration. These will be covered in their +respective sections. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + addresses + ethernet + wireless + bridging + bonding + vti + vlan + vxlan + wireguard diff --git a/docs/interfaces/vlan.rst b/docs/interfaces/vlan.rst new file mode 100644 index 00000000..76fadd3c --- /dev/null +++ b/docs/interfaces/vlan.rst @@ -0,0 +1,47 @@ +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:: sh + + 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:: sh + + 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:: sh + + 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 + diff --git a/docs/interfaces/vti.rst b/docs/interfaces/vti.rst new file mode 100644 index 00000000..bb97e323 --- /dev/null +++ b/docs/interfaces/vti.rst @@ -0,0 +1,22 @@ +.. _interfaces-vti: + +Tunnel Interfaces (vti) +----------------------- + +Set Virtual Tunnel interface + +.. code-block:: sh + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: sh + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + } diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst new file mode 100644 index 00000000..4755b7c4 --- /dev/null +++ b/docs/interfaces/vxlan.rst @@ -0,0 +1,283 @@ +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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + 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:: sh + + set interfaces vxlan vxlan241 link 'eth0' + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +.. code-block:: sh + + set interfaces vxlan vxlan241 vni '241' + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +.. code-block:: sh + + 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:: sh + + 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:: sh + + 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 + } + } + + +.. target-notes:: + +.. _RFC7348: https://datatracker.ietf.org/doc/rfc7348/ diff --git a/docs/interfaces/wireguard.rst b/docs/interfaces/wireguard.rst index f5350965..b085865a 100644 --- a/docs/interfaces/wireguard.rst +++ b/docs/interfaces/wireguard.rst @@ -114,7 +114,5 @@ your peer should have knowledge if its content. latest handshake: 4 minutes, 22 seconds ago transfer: 860 B received, 948 B sent -.. _RFC4862: https://tools.ietf.org/html/rfc4862 -.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 -.. _RFC7348: https://datatracker.ietf.org/doc/rfc7348/ + .. _WireGuard: https://www.wireguard.com diff --git a/docs/interfaces/wireless.rst b/docs/interfaces/wireless.rst new file mode 100644 index 00000000..46c038af --- /dev/null +++ b/docs/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:: sh + + set system wifi-regulatory-domain SE + +An example on how to set it up as an access point: + +.. code-block:: sh + + 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:: sh + + 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. diff --git a/docs/network-interfaces.rst b/docs/network-interfaces.rst deleted file mode 100644 index 0214ee1e..00000000 --- a/docs/network-interfaces.rst +++ /dev/null @@ -1,807 +0,0 @@ -.. _network-interfaces: - -Network Interfaces -================== - -Configured interfaces on a VyOS system can be displayed using the `show -interfaces` command. - -.. code-block:: sh - - 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 - lo 127.0.0.1/8 u/u - ::1/128 - vyos@vyos:~$ - -A specific interface can be shown using the `show interfaces <type> <name>` -command. - -.. code-block:: sh - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 - link/ether 00:0c:29:44:3b:0f brd ff:ff:ff:ff:ff:ff - inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0 - inet6 fe80::20c:29ff:fe44:3b0f/64 scope link - valid_lft forever preferred_lft forever - Description: OUTSIDE - - RX: bytes packets errors dropped overrun mcast - 274397 3064 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 257276 1890 0 0 0 0 - vyos@vyos:~$ - -Different network interfaces provide type-specific configuration. Ethernet -interfaces, for example, allow the configuration of speed and duplex. - -Many services, such as network routing, firewall, and traffic policy also -maintain interface-specific configuration. These will be covered in their -respective sections. - -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:: sh - - 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:: sh - - 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:: sh - - 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 VTI. - -The command is `set interfaces $type $name address $address`. Examples: - -.. code-block:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 - -Ethernet Interfaces -------------------- - -Ethernet interfaces allow for the configuration of speed, duplex, and hw-id -(MAC address). Below is an example configuration: - -.. code-block:: sh - - 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:: sh - - 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` and `show interfaces ethernet <name> -statistics`. Statistics available are driver dependent. - -.. code-block:: sh - - 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 - [...] - -Wireless Interfaces -------------------- -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:: sh - - set system wifi-regulatory-domain SE - -An example on how to set it up as an access point: - -.. code-block:: sh - - 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:: sh - - 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. - - -VLAN Sub-Interfaces (802.1Q) ----------------------------- - -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:: sh - - 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:: sh - - 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:: sh - - 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 - -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:: sh - - 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:: sh - - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' - -Example Result: - -.. code-block:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - vyos@vyos:~$ show bridge br100 macs - port no mac addr is local? ageing timer - 1 00:0c:29:44:3b:19 yes 0.00 - -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:: sh - - set interfaces bonding bond0 description 'my-sw1 int 23 and 24' - -You are able to choose a hash policy: - -.. code-block:: sh - - 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:: sh - - 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:: sh - - set interfaces bonding bond0 mode '802.3ad' - -or some other modes: - -.. code-block:: sh - - 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:: sh - - 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:: sh - - 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 - -Tunnel Interfaces ------------------ - -Set Virtual Tunnel interface - -.. code-block:: sh - - set interfaces vti vti0 address 192.168.2.249/30 - set interfaces vti vti0 address 2001:db8:2::249/64 - -Results in: - -.. code-block:: sh - - vyos@vyos# show interfaces vti - vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" - } - -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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - 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:: sh - - set interfaces vxlan vxlan241 link 'eth0' - -Sets the interface to listen for multicast packets on. Could be a loopback, not -yet tested. - -.. code-block:: sh - - set interfaces vxlan vxlan241 vni '241' - -Sets the unique id for this vxlan-interface. Not sure how it correlates with -multicast-address. - -.. code-block:: sh - - 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:: sh - - 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:: sh - - 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 - } - } - -.. include:: interfaces/wireguard.rst diff --git a/docs/qos.rst b/docs/qos.rst index d3ec2271..672adaa5 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -53,6 +53,68 @@ Once a traffic-policy is created, you can apply it to an interface : set interfaces ethernet eth0 traffic-policy in WAN-IN set interfaces etherhet eth0 traffic-policy out WAN-OUT + +A Real-World Example +^^^^^^^^^^^^^^^^^^^^ + +This policy sets download and upload bandwidth maximums (roughly 90% of the speeds possible), then divvies +up the traffic into buckets of importance, giving guaranteed bandwidth chunks to types of +traffic that are necessary for general interactive internet use, like web browsing, streaming, or gaming. + +After identifying and prioritizing that traffic, it drops the remaining traffic into a general-priority +bucket, which it gives a lower priority than what is required for real-time use. If there is no real-time +traffic that needs the bandwidth, the lower-priority traffic can use most of the connection. This ensures +that the connection can be used fully by whatever wants it, without suffocating real-time traffic or +throttling background traffic too much. + +.. code-block:: sh + + set traffic-policy shaper download bandwidth '175mbit' + set traffic-policy shaper download class 10 bandwidth '10%' + set traffic-policy shaper download class 10 burst '15k' + set traffic-policy shaper download class 10 ceiling '100%' + set traffic-policy shaper download class 10 match dns ip source port '53' + set traffic-policy shaper download class 10 match icmp ip protocol 'icmp' + set traffic-policy shaper download class 10 match ssh ip source port '22' + set traffic-policy shaper download class 10 priority '5' + set traffic-policy shaper download class 10 queue-type 'fair-queue' + set traffic-policy shaper download class 20 bandwidth '10%' + set traffic-policy shaper download class 20 burst '15k' + set traffic-policy shaper download class 20 ceiling '100%' + set traffic-policy shaper download class 20 match http ip source port '80' + set traffic-policy shaper download class 20 match https ip source port '443' + set traffic-policy shaper download class 20 priority '4' + set traffic-policy shaper download class 20 queue-type 'fair-queue' + set traffic-policy shaper download default bandwidth '70%' + set traffic-policy shaper download default burst '15k' + set traffic-policy shaper download default ceiling '100%' + set traffic-policy shaper download default priority '3' + set traffic-policy shaper download default queue-type 'fair-queue' + set traffic-policy shaper upload bandwidth '18mbit' + set traffic-policy shaper upload class 2 bandwidth '10%' + set traffic-policy shaper upload class 2 burst '15k' + set traffic-policy shaper upload class 2 ceiling '100%' + set traffic-policy shaper upload class 2 match ack ip tcp ack + set traffic-policy shaper upload class 2 match dns ip destination port '53' + set traffic-policy shaper upload class 2 match icmp ip protocol 'icmp' + set traffic-policy shaper upload class 2 match ssh ip destination port '22' + set traffic-policy shaper upload class 2 match syn ip tcp syn + set traffic-policy shaper upload class 2 priority '5' + set traffic-policy shaper upload class 2 queue-limit '16' + set traffic-policy shaper upload class 2 queue-type 'fair-queue' + set traffic-policy shaper upload class 5 bandwidth '10%' + set traffic-policy shaper upload class 5 burst '15k' + set traffic-policy shaper upload class 5 ceiling '100%' + set traffic-policy shaper upload class 5 match http ip destination port '80' + set traffic-policy shaper upload class 5 match https ip destination port '443' + set traffic-policy shaper upload class 5 priority '4' + set traffic-policy shaper upload class 5 queue-type 'fair-queue' + set traffic-policy shaper upload default bandwidth '60%' + set traffic-policy shaper upload default burst '15k' + set traffic-policy shaper upload default ceiling '100%' + set traffic-policy shaper upload default priority '3' + set traffic-policy shaper upload default queue-type 'fair-queue' + Traffic policies in VyOS ------------------------ diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 34dd5115..3b235513 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -162,6 +162,6 @@ interface-level traffic-policy directive: VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`) -See further information in the `QoS and Traffic Policy`_ chapter. +See further information in the :ref:`qos` chapter. .. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) diff --git a/docs/services/index.rst b/docs/services/index.rst index 80405ef7..f42fbf81 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -8,6 +8,7 @@ Services This chapter descriptes the available system/network services provided by VyOS. .. toctree:: + :hidden: conntrack dhcp diff --git a/docs/system.rst b/docs/system.rst index 445d9248..37b17823 100644 --- a/docs/system.rst +++ b/docs/system.rst @@ -3,8 +3,8 @@ System ====== -After a basic system setup by setting up `Interface Addresses`_, VyOS should -be ready for further configuration which is described in this chapter. +After a basic system setup by setting up :ref:`interfaces-addresses`, VyOS +should be ready for further configuration which is described in this chapter. Host Information ---------------- @@ -92,9 +92,9 @@ Example: Set system domain to example.com: Static host mappings ^^^^^^^^^^^^^^^^^^^^ -How to assign IPs to interfaces is described in chapter `Interface Addresses`_. -This section shows how to statically map a system IP to its host name for -local (meaning on this VyOS instance) DNS resolution: +How to assign IPs to interfaces is described in chapter +:ref:`interfaces-addresses`. This section shows how to statically map a system +IP to its host name for local (meaning on this VyOS instance) DNS resolution: .. code-block:: sh diff --git a/docs/vpn.rst b/docs/vpn.rst index 786e0a8e..ddf967b6 100644 --- a/docs/vpn.rst +++ b/docs/vpn.rst @@ -455,6 +455,8 @@ rules. (if you used the default configuration at the top of this page) set firewall name OUTSIDE-LOCAL rule 32 action 'accept' set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24' +.. _vpn-dmvpn: + DMVPN ----- |