diff options
Diffstat (limited to 'docs/configuration/interfaces')
| -rw-r--r-- | docs/configuration/interfaces/bonding.rst | 560 | ||||
| -rw-r--r-- | docs/configuration/interfaces/bridge.rst | 270 | ||||
| -rw-r--r-- | docs/configuration/interfaces/dummy.rst | 79 | ||||
| -rw-r--r-- | docs/configuration/interfaces/ethernet.rst | 226 | ||||
| -rw-r--r-- | docs/configuration/interfaces/geneve.rst | 61 | ||||
| -rw-r--r-- | docs/configuration/interfaces/index.rst | 28 | ||||
| -rw-r--r-- | docs/configuration/interfaces/l2tpv3.rst | 192 | ||||
| -rw-r--r-- | docs/configuration/interfaces/loopback.rst | 71 | ||||
| -rw-r--r-- | docs/configuration/interfaces/macsec.rst | 191 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst | 584 | ||||
| -rw-r--r-- | docs/configuration/interfaces/pppoe.rst | 302 | ||||
| -rw-r--r-- | docs/configuration/interfaces/pseudo-ethernet.rst | 65 | ||||
| -rw-r--r-- | docs/configuration/interfaces/tunnel.rst | 216 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vti.rst | 22 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vxlan.rst | 295 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst | 265 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireless.rst | 575 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wirelessmodem.rst | 128 |
18 files changed, 4130 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..8ec8f34d --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,560 @@ +.. _bond-interface: + +####################### +Bond / Link Aggregation +####################### + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bonding <interface> member interface <member> + + Enslave `<member>` interface to bond `<interface>`. + +Bond options +============ + +.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the :cfgcmd:`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet mis-ordering requirements of section 43.2.4 + of the 802.3ad standard. + + * ``active-backup`` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The :cfgcmd:`primary` option, + documented below, affects the behavior of this mode. + + * ``broadcast`` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * ``round-robin`` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * ``adaptive-load-balance`` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding <interface> min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause carrier to be asserted (for 802.3ad + mode) whenever there is an active aggregator, regardless of the number of + available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. + +.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet this criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + :cfgcmd:`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + be given for ARP monitoring to function. + + The maximum number of targets that can be specified is 16. The default value + is no IP addresses. + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bond + :var1: bond0 + +******* +Example +******* + +The following configuration on VyOS applies to all following 3rd party vendors. +It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with +a per VIF IPv4 address. + +.. code-block:: none + + # Create bonding interface bond0 with 802.3ad LACP + set interfaces bonding bond0 hash-policy 'layer2' + set interfaces bonding bond0 mode '802.3ad' + + # Add the required vlans and IPv4 addresses on them + set interfaces bonding bond0 vif 10 address 192.168.0.1/24 + set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + + # Add the member interfaces to the bonding interface + set interfaces bonding bond0 member interface eth1 + set interfaces bonding bond0 member interface eth2 + +Cisco Catalyst +============== + +Assign member interfaces to PortChannel + +.. code-block:: none + + interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active + ! + interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active + ! + +A new interface becomes present ``Port-channel1``, all configuration like +allowed VLAN interfaces, STP will happen here. + +.. code-block:: none + + interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk + ! + + +Juniper EX Switch +================= + +For a headstart you can use the below example on how to build a bond with two +interfaces from VyOS to a Juniper EX Switch system. + +.. code-block:: none + + # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s + set interfaces ae0 aggregated-ether-options link-speed 10g + set interfaces ae0 aggregated-ether-options lacp active + + # Create layer 2 on the aggregated ethernet device with trunking for our vlans + set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + + # Add the required vlans to the device + set interfaces ae0 unit 0 family ethernet-switching vlan members 10 + set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + + # Add the two interfaces to the aggregated ethernet device, in this setup both + # ports are on the same switch (switch 0, module 1, port 0 and 1) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-0/1/1 ether-options 802.3ad ae0 + + # But this can also be done with multiple switches in a stack, a virtual + # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-1/1/0 ether-options 802.3ad ae0 + +Aruba/HP +======== + +For a headstart you can use the below example on how to build a bond,port-channel +with two interfaces from VyOS to a Aruba/HP 2510G switch. + +.. code-block:: none + + # Create trunk with 2 member interfaces (interface 1 and 2) and LACP + trunk 1-2 Trk1 LACP + + # Add the required vlans to the trunk + vlan 10 tagged Trk1 + vlan 100 tagged Trk1 + +Arista EOS +========== + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +.. figure:: /_static/images/vyos_arista_bond_lacp.png + :alt: VyOS Arista EOS setup + +**R1** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } + +**R2** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } + +**SW1** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +**SW2** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +.. note:: When using EVE-NG to lab this environment ensure you are using e1000 + as the desired driver for your VyOS network interfaces. When using the regular + virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel + will never become active! + +********* +Operation +********* + +.. opcmd:: show interfaces bonding + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show 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 + + +.. opcmd:: show interfaces bonding <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 + bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 + +.. opcmd:: show interfaces bonding <interface> detail + + Show detailed information about the underlaying physical links on given + bond `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 detail + Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + + Bonding Mode: IEEE 802.3ad Dynamic link aggregation + Transmit Hash Policy: layer2 (0) + MII Status: down + MII Polling Interval (ms): 100 + Up Delay (ms): 0 + Down Delay (ms): 0 + + 802.3ad info + LACP rate: slow + Min links: 0 + Aggregator selection policy (ad_select): stable + + Slave Interface: eth1 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:ef:aa + Slave queue ID: 0 + Aggregator ID: 1 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + + Slave Interface: eth2 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:19:26 + Slave queue ID: 0 + Aggregator ID: 2 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst new file mode 100644 index 00000000..766d2aa5 --- /dev/null +++ b/docs/configuration/interfaces/bridge.rst @@ -0,0 +1,270 @@ +.. _bridge-interface: + +###### +Bridge +###### + +A Bridge is a way to connect two Ethernet segments together in a +protocol independent way. Packets are forwarded based on Ethernet +address, rather than IP address (like a router). Since forwarding is +done at Layer 2, all protocols can go transparently through a bridge. +The Linux bridge code implements a subset of the ANSI/IEEE 802.1d +standard. + +.. note:: Spanning Tree Protocol is not enabled by default in VyOS. + :ref:`stp` can be easily enabled if needed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bridge + :var1: br0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + + Assign `<member>` interface to bridge `<interface>`. A completion + helper will help you with all allowed interfaces which can be + bridged. This includes :ref:`ethernet-interface`, + :ref:`bond-interface`, :ref:`l2tpv3-interface`, :ref:`openvpn`, + :ref:`vxlan-interface`, :ref:`wireless-interface`, + :ref:`tunnel-interface` and :ref:`geneve-interface`. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + priority <priority> + + Configure individual bridge port `<priority>`. + + Each bridge has a relative priority and cost. Each interface is + associated with a port (number) in the STP code. Each has a priority + and a cost, that is used to decide which is the shortest path to + forward a packet. The lowest cost path is always used unless the + other path is down. If you have multiple bridges and interfaces then + you may need to adjust the priorities to achieve optimium + performance. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + cost <cost> + + Path `<cost>` value for Spanning Tree Protocol. Each interface in a + bridge could have a different speed and this value is used when + deciding which link to use. Faster interfaces should have lower + costs. + +Bridge Options +============== + +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a another bridge in the spanning tree does not send out a hello + packet for a long period of time, it is assumed to be dead. + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier + +.. _stp: + +STP Parameter +------------- + +:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of +STP is to prevent bridge loops and the broadcast radiation that results +from them. Spanning tree also allows a network design to include backup +links providing fault tolerance if an active link fails. + +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + + +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + + Forwarding delay time is the time spent in each of the Listening and + Learning states before the Forwarding state is entered. This delay is + so that when a new bridge comes onto a busy network it looks at some + traffic before participating. + + +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + Periodically, a hello packet is sent out by the Root Bridge and the + Designated Bridges. Hello packets are used to communicate information + about the topology throughout the entire Bridged Local Area Network. + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bridge + :var1: br0 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + native-vlan <vlan-id> + + Set the native VLAN ID flag of the interface. When a data packet without a + VLAN tag enters the port, the data packet will be forced to add a tag of a + specific vlan id. When the vlan id flag flows out, the tag of the vlan id + will be stripped + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + allowed-vlan <vlan-id> + + Allows specific VLAN IDs to pass through the bridge member interface. This + can either be an individual VLAN id or a range of VLAN ids delimited by a + hyphen. + +******* +Example +******* + +Creating a bridge interface is very simple. In this example we will +have: + +* A bridge named `br100` +* Member interfaces `eth1` and VLAN 10 on interface `eth2` +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 address 192.0.2.1/24 + set interfaces bridge br100 address 2001:db8::ffff/64 + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2.10 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp + +******* +Example +******* + +An example of creating a VLAN-aware bridge is as follows: + +* A bridge named `br100` +* The member interface `eth1` is a trunk that allows VLAN 10 to pass +* VLAN 10 on member interface `eth2` (ACCESS mode) +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 member interface eth1 allowed-vlan 10 + set interfaces bridge br100 member interface eth2 native-vlan 10 + set interfaces bridge br100 vif 10 address 192.0.2.1/24 + set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } + +******* +Example +******* + +.. opcmd:: show bridge + + 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 8000.0050569d11df yes eth1 + eth2.10 + +.. opcmd:: show bridge <name> spanning-tree + + Show bridge `<name>` STP configuration. + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 8000.0050569d11df + designated root 8000.0050569d11df + 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 14.00 bridge forward delay 14.00 + ageing time 300.00 + hello timer 0.06 tcn timer 0.00 + topology change timer 0.00 gc timer 242.02 + flags + + eth1 (1) + port id 8001 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + + eth2.10 (2) + port id 8002 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8002 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + +.. opcmd: show bridge <name> macs + + Show bridge Media Access Control (MAC) address table + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:53: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..c9845230 --- /dev/null +++ b/docs/configuration/interfaces/dummy.rst @@ -0,0 +1,79 @@ +.. _dummy-interface: + +##### +Dummy +##### + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the :ref:`loopback-interface` interface, except +you can have as many as you want. + +.. note:: Dummy interfaces can be used as interfaces that always stay up (in + the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +.. hint:: A Dummy interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependent + on physical link states and multiple routes can be chosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: dummy + :var1: dum0 + +********* +Operation +********* + +.. opcmd:: show interfaces dummy + + Show brief interface information.information + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum0 172.18.254.201/32 u/u + +.. opcmd:: show interfaces dummy <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + + diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..9311c947 --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,226 @@ +.. _ethernet-interface: + +######## +Ethernet +######## + +This will be the most widely used interface on a router carrying traffic to the +real world. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 + +Ethernet options +================ + +.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | + 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + + +.. cfgcmd:: set interfaces ethernet <interface> mirror <interface> + + Use this command to mirror the inbound traffic from one Ethernet interface to + another interface. This feature is typically used to provide a copy of traffic + inbound on one interface to a system running a monitoring or IPS application + on another interface. The benefit of mirroring the traffic is that the + application is isolated from the source traffic and so application processing + does not affect the traffic or the system performance. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 mirror eth1 + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: ethernet + :var1: eth0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: ethernet + :var1: eth0 + +********* +Operation +********* + +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D + +.. opcmd:: show interfaces ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 + +.. opcmd:: show interfaces ethernet <interface> physical + + Show information about physical `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +.. opcmd:: show interfaces ethernet <interface> physical offload + + Show available offloading functions on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical offload + rx-checksumming on + tx-checksumming on + tx-checksum-ip-generic on + scatter-gather off + tx-scatter-gather off + tcp-segmentation-offload off + tx-tcp-segmentation off + tx-tcp-mangleid-segmentation off + tx-tcp6-segmentation off + udp-fragmentation-offload off + generic-segmentation-offload off + generic-receive-offload off + large-receive-offload off + rx-vlan-offload on + tx-vlan-offload on + ntuple-filters off + receive-hashing on + tx-gre-segmentation on + tx-gre-csum-segmentation on + tx-udp_tnl-segmentation on + tx-udp_tnl-csum-segmentation on + tx-gso-partial on + tx-nocache-copy off + rx-all off + +.. opcmd:: show interfaces ethernet <interface> transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx + diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst new file mode 100644 index 00000000..9e00d621 --- /dev/null +++ b/docs/configuration/interfaces/geneve.rst @@ -0,0 +1,61 @@ +.. _geneve-interface: + +###### +GENEVE +###### + +:abbr:`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of :abbr:`VXLAN (Virtual Extensible LAN)`, :abbr:`NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and :abbr:`STT +(Stateless Transport Tunneling)` and was designed to overcome their perceived +limitations. Many believe GENEVE could eventually replace these earlier formats +entirely. + +GENEVE is designed to support network virtualization use cases, where tunnels +are typically established to act as a backplane between the virtual switches +residing in hypervisors, physical switches, or middleboxes or other appliances. +An arbitrary IP network can be used as an underlay although Clos networks - A +technique for composing network fabrics larger than a single switch while +maintaining non-blocking bandwidth across connection points. ECMP is used to +divide traffic across the multiple links and switches that constitute the +fabric. Sometimes termed "leaf and spine" or "fat tree" topologies. + +Geneve Header: + +.. code-block:: none + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |Ver| Opt Len |O|C| Rsvd. | Protocol Type | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Virtual Network Identifier (VNI) | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Variable Length Options | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: geneve + :var1: gnv0 + +GENEVE options +============== + +.. cfgcmd:: set interfaces geneve gnv0 remote <address> + + Configure GENEVE tunnel far end/remote tunnel endpoint. + +.. cfgcmd:: set interfaces geneve gnv0 vni <vni> + + :abbr:`VNI (Virtual Network Identifier)` is an identifier for a unique + element of a virtual network. In many situations this may represent an L2 + segment, however, the control plane defines the forwarding semantics of + decapsulated packets. The VNI MAY be used as part of ECMP forwarding + decisions or MAY be used as a mechanism to distinguish between overlapping + address spaces contained in the encapsulated packet when load balancing + across CPUs. diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst new file mode 100644 index 00000000..85d2c177 --- /dev/null +++ b/docs/configuration/interfaces/index.rst @@ -0,0 +1,28 @@ +########## +Interfaces +########## + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + geneve + l2tpv3 + loopback + macsec + openvpn + pppoe + pseudo-ethernet + tunnel + vti + vxlan + wireguard + wireless + wirelessmodem + + diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst new file mode 100644 index 00000000..a4b7be36 --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -0,0 +1,192 @@ +.. include:: /_include/need_improvement.txt + +.. _l2tpv3-interface: + +###### +L2TPv3 +###### + +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to :ref:`mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service, but scaled to fit carrier requirements. + +L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version +of the same concept, with much of the same benefit achieved at a fraction of the +effort, at the cost of losing some technical features considered less important +in the market. + +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in :rfc:`3921`. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: l2tpv3 + :var1: l2tpeth0 + +L2TPv3 options +============== + +.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> + + Set the encapsulation type of the tunnel. Valid values for encapsulation are: + udp, ip. + + This defaults to UDP + +.. cfgcmd:: set interfaces l2tpv3 <interface> local-ip <address> + + set the IP address of the local interface to be used for the tunnel. + + This address must be the address of a local interface. May be specified as an + IPv4 address or an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> remote-ip <address> + + Set the IP address of the remote peer. May be specified as an IPv4 address or + an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> + + Set the session id, which is a 32-bit integer value. Uniquely identifies the + session being created. The value used must match the peer_session_id value + being used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> + + Set the peer session id, which is a 32-bit integer value assigned to the + session by the peer. The value used must match the session_id value being + used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +******* +Example +******* + +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. + +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. + + +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 bridge br0 member interface eth0 + set interfaces ethernet eth0 description 'L2 VPN Physical port' + +L2TPv3: + +.. code-block:: none + + set interfaces bridge br0 member interface 'l2tpeth0' + 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' diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst new file mode 100644 index 00000000..f7386c62 --- /dev/null +++ b/docs/configuration/interfaces/loopback.rst @@ -0,0 +1,71 @@ +.. _loopback-interface: + +######## +Loopback +######## + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +.. note:: There can only be one loopback ``lo`` interface on the system. If + you need multiple interfaces, please use the :ref:`dummy-interface` + interface type. + +.. hint:: A lookback interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependent + on physical link states and multiple routes can be chosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: loopback + :var1: lo + +.. cmdinclude:: /_include/interface-description.txt + :var0: loopback + :var1: lo + +********* +Operation +********* + +.. opcmd:: show interfaces loopback + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + lo 127.0.0.1/8 u/u + ::1/128 + +.. opcmd:: show interfaces loopback lo + + Show detailed information on given loopback interface `lo`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst new file mode 100644 index 00000000..2bf643aa --- /dev/null +++ b/docs/configuration/interfaces/macsec.rst @@ -0,0 +1,191 @@ +.. _macsec-interface: + +###### +MACsec +###### + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006. +It defines a way to establish a protocol independent connection between two +hosts with data confidentiality, authenticity and/or integrity, using +GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2 +protocol, which means it's designed to secure traffic within a layer 2 network, +including DHCP or ARP requests. It does not compete with other security +solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are +used for their own specific use cases. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: macsec + :var1: macsec0 + +MACsec options +============== + +.. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] + + Select cipher suite used for cryptographic operations. This setting is + mandatory. + + .. note:: gcm-aes-256 support planned once iproute2 package is updated to + version >=5.2. + +.. cfgcmd:: set interfaces macsec <interface> security encrypt + + MACsec only provides authentication by default, encryption is optional. This + command will enable encryption for all outgoing packets. + +.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source> + + A physical interface is required to connect this MACsec instance to. Traffic + leaving this interfac will now be authenticated/encrypted. + +Key Management +-------------- + +:abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +individual peers. + +.. cfgcmd:: set interfaces macsec <interface> security mka cak <key> + + IEEE 802.1X/MACsec pre-shared key mode. This allows to configure MACsec with + a pre-shared key using a (CAK,CKN) pair. + +.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> + + CAK Name + +.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> + + The peer with lower priority will become the key server and start + distributing SAKs. + +Replay protection +----------------- + +.. cfgcmd:: set interfaces macsec <interface> security replay-window <window> + + IEEE 802.1X/MACsec replay protection window. This determines a window in which + replay is tolerated, to allow receipt of frames that have been misordered by + the network. + + - ``0``: No replay window, strict check + - ``1-4294967295``: Number of packets that could be misordered + +********* +Operation +********* + +.. opcmd:: run generate macsec mka-cak + + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka-cak + 20693b6e08bfa482703a563898c9e3ad + + +.. opcmd:: run generate macsec mka-ckn + + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka-ckn + 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 + +.. opcmd:: show interfaces macsec + + List all MACsec interfaces + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + 20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + +.. opcmd:: show interfaces macsec <interface> + + Show specific MACsec interface information + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec macsec1 + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + +******** +Examples +******** + +* Two routers connected both via eth1 through an untrusted switch +* R1 has 192.0.2.1/24 & 2001:db8::1/64 +* R2 has 192.0.2.2/24 & 2001:db8::2/64 + +**R1** + +.. code-block:: none + + set interfaces macsec macsec1 address '192.0.2.1/24' + set interfaces macsec macsec1 address '2001:db8::1/64' + set interfaces macsec macsec1 security cipher 'gcm-aes-128' + set interfaces macsec macsec1 security encrypt + set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' + set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' + set interfaces macsec macsec1 source-interface 'eth1' + +**R2** + +.. code-block:: none + + set interfaces macsec macsec1 address '192.0.2.2/24' + set interfaces macsec macsec1 address '2001:db8::2/64' + set interfaces macsec macsec1 security cipher 'gcm-aes-128' + set interfaces macsec macsec1 security encrypt + set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' + set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' + set interfaces macsec macsec1 source-interface 'eth1' + +Pinging (IPv6) the other host and intercepting the traffic in ``eth1`` will +show you the content is encrypted. + +.. code-block:: none + + 17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. + +Disabling the encryption on the link by removing ``security encrypt`` will show +the unencrypted but authenticated content. + +.. code-block:: none + + 17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( + diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst new file mode 100644 index 00000000..f503ae84 --- /dev/null +++ b/docs/configuration/interfaces/openvpn.rst @@ -0,0 +1,584 @@ +.. _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`. + +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 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 256-bit AES in GCM mode +for encryption (if both sides supports NCP) and SHA-1 for HMAC authentication. +SHA-1 is considered weak, but other hashing algorithms are available, as are +encryption algorithms: + +For Encryption: + +This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or +OpenVPN version < 2.4.0. + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 encryption cipher + 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 CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM + +This sets the accepted ciphers to use when version => 2.4.0 and NCP is +enabled (which is default). Default NCP cipher for versions >= 2.4.0 is +aes256gcm. The first cipher in this list is what server pushes to clients. + +.. code-block:: none + + vyos@vyos# set int open vtun0 encryption ncp-ciphers + Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM + +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. + +Server +====== + +Multi-client server is the most popular OpenVPN mode on routers. It always uses +x.509 authentication and therefore requires a PKI setup. Refer this section +**Generate X.509 Certificate and Keys** to generate 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 + +Generate X.509 Certificate and Keys +----------------------------------- + +OpenVPN ships with a set of scripts called Easy-RSA that can generate the +appropriate files needed for an OpenVPN setup using X.509 certificates. +Easy-RSA comes installed by default on VyOS routers. + +Copy the Easy-RSA scripts to a new directory to modify the values. + +.. code-block:: none + + cp -r /usr/share/easy-rsa/ /config/my-easy-rsa-config + cd /config/my-easy-rsa-config + +To ensure the consistent use of values when generating the PKI, set default +values to be used by the PKI generating scripts. Rename the vars.example filename +to vars + +.. code-block:: none + + mv vars.example vars + +Following is the instance of the file after editing. You may also change other values in +the file at your discretion/need, though for most cases the defaults should be just fine. +(do not leave any of these parameters blank) + +.. code-block:: none + + set_var EASYRSA_DN "org" + set_var EASYRSA_REQ_COUNTRY "US" + set_var EASYRSA_REQ_PROVINCE "California" + set_var EASYRSA_REQ_CITY "San Francisco" + set_var EASYRSA_REQ_ORG "Copyleft Certificate Co" + set_var EASYRSA_REQ_EMAIL "me@example.net" + set_var EASYRSA_REQ_OU "My Organizational Unit" + set_var EASYRSA_KEY_SIZE 2048 + + +init-pki option will create a new pki directory or will delete any previously generated +certificates stored in that folder. The term 'central' is used to refer server and +'branch' for client + +.. note:: Remember the “CA Key Passphrase” prompted in build-ca command, + as it will be asked in signing the server/client certificate. + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$./easyrsa init-pki + vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-ca + vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-req central nopass + vyos@vyos:/config/my-easy-rsa-config$./easyrsa sign-req server central + vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh + vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass + +To generate a certificate revocation list for any client, execute these commands: + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$./easyrsa revoke client1 + vyos@vyos:/config/my-easy-rsa-config$ ./easyrsa gen-crl + +Copy the files to /config/auth/ovpn/ to use in OpenVPN tunnel creation + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/ovpn + +Additionally, each client needs a copy of ca.crt and its own client key and cert files. +The files are plaintext so they may be copied either manually, +or through a remote file transfer tool like scp. Whichever method you use, +the files need to end up in the proper location on each router. +For example, Branch 1's router might have the following files: + +.. code-block:: none + + vyos@branch1-rtr:$ ls /config/auth/ovpn + ca.crt branch1.crt branch1.key + +Client Authentication +===================== + +LDAP +---- + +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 + } + } + +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 cipher '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 cipher '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 Phabricator_ so all users can +benefit from it (see :ref:`issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +.. cfgcmd:: 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. + +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'push "keepalive 1 10"' + +Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. + +.. note:: Sometimes option lines in the generated OpenVPN configurarion require + quotes. This is done through a hack on our config generator. You can pass + quotes using the ``"`` statement. + + +Troubleshooting +=============== + +VyOS provides some operational commands on OpenVPN. + +Check status +------------ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client + + Use this command to check the tunnel status for OpenVPN client interfaces. + +.. opcmd:: show openvpn server + + Use this command to check the tunnel status for OpenVPN server interfaces. + +.. opcmd:: show openvpn site-to-site + + Use this command to check the tunnel status for OpenVPN site-to-site interfaces. + + +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. + + + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst new file mode 100644 index 00000000..393c71ed --- /dev/null +++ b/docs/configuration/interfaces/pppoe.rst @@ -0,0 +1,302 @@ +.. _pppoe-interface: + +##### +PPPoE +##### + +:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, +in the context of the boom of DSL as the solution for tunneling packets +over the DSL connection to the :abbr:`ISPs (Internet Service Providers)` +IP network, and from there to the rest of the Internet. A 2005 networking +book noted that "Most DSL providers use PPPoE, which provides authentication, +encryption, and compression." Typical use of PPPoE involves leveraging the +PPP facilities for authenticating the user with a username and password, +predominately via the PAP protocol and less often via CHAP. + +*************** +Operating Modes +*************** + +VyOS supports setting up PPPoE in two different ways to a PPPoE internet +connection. This is due to most ISPs provide a modem that is also a wireless +router. + +Home Users +========== + +In this method, the DSL Modem/Router connects to the ISP for you with your +credentials preprogrammed into the device. This gives you an :rfc:`1918` +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. + +Business Users +============== + +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. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: pppoe + :var1: pppoe0 + +PPPoE options +============= + +.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> + + Use this command to restrict the PPPoE session on a given access + concentrator. Normally, a host sends a PPPoE initiation packet to start the + PPPoE discovery process, a number of access concentrators respond with offer + packets and the host selects one of the responding access concentrators to + serve this session. + + This command allows you to select a specific access concentrator when you + know the access concentrators `<name>`. + +.. cfgcmd:: set interfaces pppoe <interface> authentication user <username> + + Use this command to set the username for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. + +.. cfgcmd:: set interfaces pppoe <interface> authentication password <password> + + Use this command to set the password for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. + +.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPPoE connections + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + + Enabled on-demand PPPoE connections bring up the link only when traffic needs + to pass this link. If the link fails for any reason, the link is brought + back up automatically once traffic passes the interface again. If you + configure an on-demand PPPoE connection, you must also configure the idle + timeout period, after which an idle PPPoE link will be disconnected. A + non-zero idle timeout will never disconnect the link after it first came up. + +.. cfgcmd:: set interfaces pppoe <interface> default-route + + Use this command to specify whether to automatically add a default route + pointing to the endpoint of the PPPoE when the link comes up. The default + route is only added if no other default route already exists in the system. + + **default:** A default route to the remote endpoint is automatically added + when the link comes up (i.e. auto). + +.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> + + Use this command to set the idle timeout interval to be used with on-demand + PPPoE sessions. When an on-demand connection is established, the link is + brought up only when traffic is sent and is disabled when the link is idle + for the interval specified. + + If this parameter is not set or 0, an on-demand link will not be taken down + when it is idle and after the initial establishment of the connection. It + will stay up forever. + +.. cfgcmd:: set interfaces pppoe <interface> local-address <address> + + Use this command to set the IP address of the local endpoint of a PPPoE + session. If it is not set it will be negotiated. + +.. cfgcmd:: set interfaces pppoe <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + +.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns + + Use this command to not install advertised DNS nameservers into the local + system. + +.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> + + Use this command to set the IP address of the remote endpoint of a PPPoE + session. If it is not set it will be negotiated. + +.. cfgcmd:: set interfaces pppoe <interface> service-name <name> + + Use this command to specify a service name by which the local PPPoE interface + can select access concentrators to connect with. It will connect to any + access concentrator if not set. + +.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface> + + Use this command to link the PPPoE connection to a physical interface. Each + PPPoE connection must be established over a physical interface. Interfaces + can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. + +IPv6 +---- + +.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf + + Use this command to enable acquisition of IPv6 address using stateless + autoconfig (SLAAC). + +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: pppoe + :var1: pppoe0 + +********* +Operation +********* + +.. opcmd:: show interfaces pppoe <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 + pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 + +.. opcmd:: show interfaces pppoe <interface> queue + + Displays queue information for a PPPoE interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 queue + qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 + +Connect/Disconnect +================== + +.. opcmd:: disconnect interface <interface> + + Test disconnecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. + +.. opcmd:: connect interface <interface> + + Test connecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. + +******* +Example +******* + +Requirements: + +* Your ISPs modem is connected to port ``eth0`` of your VyOS box. +* No VLAN tagging required by your ISP. +* 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``. +* With the ``name-server`` option set to ``none``, VyOS will ignore the + nameservers your ISP sens you and thus you can fully rely on the ones you + have configured statically. + +.. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically + migrated during an upgrade. + +.. code-block:: none + + set interfaces pppoe pppoe0 default-route 'auto' + set interfaces pppoe pppoe0 mtu 1492 + set interfaces pppoe pppoe0 authentication user 'userid' + set interfaces pppoe pppoe0 authentication password 'secret' + set interfaces pppoe pppoe0 source-interface 'eth0' + + +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 interfaces pppoe pppoe0 firewall in name NET-IN + set interfaces pppoe pppoe0 firewall local name NET-LOCAL + set interfaces pppoe pppoe0 firewall out name NET-OUT + +VLAN Example +============ + +Some recent ISPs require you to build the PPPoE connection through a VLAN +interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS +can easily create a PPPoE session through an encapsulated VLAN interface. +The following configuration will run your PPPoE connection through VLAN7 +which is the default VLAN for Deutsche Telekom: + +.. code-block:: none + + set interfaces pppoe pppoe0 default-route 'auto' + set interfaces pppoe pppoe0 mtu 1492 + set interfaces pppoe pppoe0 authentication user 'userid' + set interfaces pppoe pppoe0 authentication password 'secret' + set interfaces pppoe pppoe0 source-interface 'eth0.7' + + +IPv6 DHCPv6-PD Example +---------------------- + +The following configuration will assign a /64 prefix out of a /56 delegation +to eth0. The IPv6 address assigned to eth0 will be <prefix>::ffff/64. +If you do not know the prefix size delegated to you, start with sla-len 0. + +.. code-block:: none + + set interfaces pppoe pppoe0 authentication user vyos + set interfaces pppoe pppoe0 authentication password vyos + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 address 65535 + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-id 0 + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-len 8 + set interfaces pppoe pppoe0 ipv6 address autoconf + set interfaces pppoe pppoe0 source-interface eth1 diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst new file mode 100644 index 00000000..0471d2e1 --- /dev/null +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -0,0 +1,65 @@ +.. _pseudo-ethernet-interface: + +####################### +Pseudo Ethernet/MACVLAN +####################### + +Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular +ethernet interfaces. Each and every subinterface is created a different media +access control (MAC) address, for a single physical Ethernet port. Pseudo- +Ethernet interfaces have most of their application in virtualized environments, + +By using Pseudo-Ethernet interfaces there will be less system overhead compared +to running a traditional bridging approach. Pseudo-Ethernet interfaces can also +be used to workaround the general limit of 4096 virtual LANs (VLANs) per +physical Ethernet port, since that limit is with respect to a single MAC +address. + +Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They +can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/ +DHCPv6 and are associated/mapped with a real ethernet port. This also makes +Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet +device will inherit characteristics (speed, duplex, ...) from its physical +parent (the so called link) interface. + +Once created in the system, Pseudo-Ethernet interfaces can be referenced in +the exact same way as other Ethernet interfaces. Notes about using Pseudo- +Ethernet interfaces: + +* Pseudo-Ethernet interfaces can not be reached from your internal host. This + means that you can not try to ping a Pseudo-Ethernet interface from the host + system on which it is defined. The ping will be lost. +* Loopbacks occurs at the IP level the same way as for other interfaces, + ethernet frames are not forwarded between Pseudo-Ethernet interfaces. +* Pseudo-Ethernet interfaces may not work in environments which expect a + :abbr:`NIC (Network Interface Card)` to only have a single address. This + applies to: + - VMware machines using default settings + - Network switches with security settings allowing only a single MAC address + - xDSL modems that try to lear the MAC address of the NIC + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: pseudo-ethernet + :var1: peth0 + +Pseudo Ethernet/MACVLAN options +=============================== + +.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> + + Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo + Ethernet `<interface>`. + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: pseudo-ethernet + :var1: peth0 diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst new file mode 100644 index 00000000..7b1502f8 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.rst @@ -0,0 +1,216 @@ +.. _tunnel-interface: + +Tunnel +====== + +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. + +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: tunnel + :var1: tun0 + +IPIP +---- + +This is one of the simplest types of tunnels, as defined by :rfc:`2003`. +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/24 + +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 :rfc:2473`. + +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 ip6ip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 + 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 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 + set interfaces tunnel tun0 address 192.168.70.80/24 + +6in4 (SIT) +---------- + +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in +:rfc:`4213`. 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 + + +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 + + + +.. _`other proposals`: https://www.isc.org/othersoftware/ +.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst new file mode 100644 index 00000000..62cd13f3 --- /dev/null +++ b/docs/configuration/interfaces/vti.rst @@ -0,0 +1,22 @@ +############################## +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" + }
\ No newline at end of file diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst new file mode 100644 index 00000000..95f8de35 --- /dev/null +++ b/docs/configuration/interfaces/vxlan.rst @@ -0,0 +1,295 @@ +.. _vxlan-interface: + +##### +VXLAN +##### + +:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that attempts to address the scalability problems associated with large cloud +computing deployments. It uses a VLAN-like encapsulation technique to +encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using +4789 as the default IANA-assigned destination UDP port number. VXLAN +endpoints, which terminate VXLAN tunnels and may be either virtual or physical +switch ports, are known as :abbr:`VTEPs (VXLAN tunnel endpoints)`. + +VXLAN is an evolution of efforts to standardize on an overlay encapsulation +protocol. It increases scalability up to 16 million logical networks and +allows for layer 2 adjacency across IP networks. Multicast or unicast with +head-end replication (HER) is used to flood broadcast, unknown unicast, +and multicast (BUM) traffic. + +The VXLAN specification was originally created by VMware, Arista Networks +and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom, +Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson, +Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks. + +VXLAN was officially documented by the IETF in :rfc:`7348`. + +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. + +.. note:: As VyOS is based on Linux and there was no official IANA port assigned + for VXLAN, VyOS uses a default port of 8472. You can change the port on a + per VXLAN interface basis to get it working across multiple vendors. + +Configuration +============= + +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: vxlan + :var1: vxlan0 + +VXLAN specific options +----------------------- + +.. cfgcmd:: set interfaces vxlan <interface> vni <number> + + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. + +.. cfgcmd:: set interfaces vxlan <interface> port <port> + + Configure port number of remote VXLAN endpoint. + + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. + +.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> + + Source IP address used for VXLAN underlay. This is mandatory when using VXLAN + via L2VPN/EVPN. + +Unicast +^^^^^^^ + +.. cfgcmd:: set interfaces vxlan <interface> remote <address> + + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. + +Multicast +^^^^^^^^^ + +.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> + + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. + + +.. cfgcmd:: set interfaces vxlan <interface> group <address> + + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + Both IPv4 and IPv6 multicast is possible. + +Multicast VXLAN +=============== + +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. + +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 bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 source-interface 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces bridge br242 member interface 'eth1.242' + set interfaces bridge br242 member interface 'vxlan242' + + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 source-interface '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 bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 source-interface 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces bridge br242 member interface 'eth1.242' + set interfaces bridge br242 member interface 'vxlan242' + + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 source-interface '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 bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + +Binds eth1.241 and vxlan241 to each other by making them both member interfaces of +the same bridge. + +.. 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 source-interface '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 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. + +Unicast VXLAN +============= + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +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 source-interface '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> port <port>`` diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst new file mode 100644 index 00000000..3580fac3 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.rst @@ -0,0 +1,265 @@ +.. _wireguard: + +######### +WireGuard +######### + +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 keypair +---------------- + +.. opcmd:: generate wireguard default-keypair + + It generates the keypair, that is its 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. + +.. opcmd:: show wireguard keypairs pubkey default + + It shows the public key which needs to be shared with your peer(s). Your + peer will encrypt all traffic to your system using this public key. + + .. code-block:: none + + vyos@vyos:~$ show wireguard keypairs pubkey default + hW17UxY7zeydJNPIyo3UtGnBHkzTK/NeBOrDSIU9Tx0= + + +Generate named keypair +---------------------- + +Named keypairs can be used on a interface basis, if configured. If +multiple WireGuard interfaces are being configured, each can have their +own keypairs. + +The commands below will generate 2 keypairs, which are not related to +each other. + +.. code-block:: none + + vyos@vyos:~$ generate wireguard named-keypairs KP01 + vyos@vyos:~$ generate wireguard named-keypairs KP02 + + +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 address/port 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 address '192.168.0.142' + set interfaces wireguard wg01 peer to-wg02 port '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 + +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. + +.. note:: You can not assign the same allowed-ips statement to multiple + WireGuard peers. This a a design decission. For more information please + check the `WireGuard mailing list`_. + + +To use a named key on an interface, the option private-key needs to be +set. + +.. code-block:: none + + set interfaces wireguard wg01 private-key KP01 + set interfaces wireguard wg02 private-key KP02 + +The command ``run show wireguard keypairs pubkey KP01`` will then show +the public key, which needs to be shared with the peer. + + +**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 address '192.168.0.124' + set interfaces wireguard wg01 peer to-wg02 port '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=' + +Road Warrior Example +-------------------- + +With WireGuard, a Road Warrior VPN config is similar to a site-to-site +VPN. It just lacks the ``address`` and ``port`` statements. + +In the following example, the IPs for the remote clients are defined in +the peers. This would allow the peers to interact with one another. + +.. code-block:: none + + wireguard wg0 { + address 10.172.24.1/24 + address 2001:DB8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:DB8:470:22::30/128 + persistent-keepalive 15 + pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:DB8:470:22::30/128 + persistent-keepalive 15 + pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + } + +The following is the config for the iPhone peer above. It's important to +note that the ``AllowedIPs`` setting directs all IPv4 and IPv6 traffic +through the connection. + +.. code-block:: none + + [Interface] + PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= + Address = 10.172.24.20/24, 2001:DB8:470:22::20/64 + DNS = 10.0.0.53, 10.0.0.54 + + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 0.0.0.0/0, ::/0 + Endpoint = 192.0.2.1:2224 + PersistentKeepalive = 25 + + +This MacBook peer is doing split-tunneling, where only the subnets local +to the server go over the connection. + +.. code-block:: none + + [Interface] + PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= + Address = 10.172.24.30/24, 2001:DB8:470:22::30/64 + + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 10.172.24.30/24, 2001:DB8:470:22::/64 + Endpoint = 192.0.2.1:2224 + PersistentKeepalive = 25 + + +Operational commands +==================== + +**Show interface status** + +.. code-block:: none + + vyos@wg01# run show interfaces wireguard wg01 + interface: wg1 + description: VPN-to-wg01 + address: 10.2.0.1/24 + public key: RIbtUTCfgzNjnLNPQ/asldkfjhaERDFl2H/xUfbyjc= + private key: (hidden) + listening port: 53665 + peer: to-wg02 + public key: u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + latest handshake: 0:01:20 + status: active + endpoint: 192.168.0.124:12345 + allowed ips: 10.2.0.0/24 + transfer: 42 GB received, 487 MB sent + persistent keepalive: every 15 seconds + RX: + bytes packets errors dropped overrun mcast + 45252407916 31192260 0 244493 0 0 + TX: + bytes packets errors dropped carrier collisions + 511649780 5129601 24465 0 0 0 + +**Show public key of the default key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + +**Show public key of a named key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey KP01 + HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + + +**Delete wireguard keypairs** + +.. code-block:: none + + vyos@wg01# wireguard keypair default + + +.. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst new file mode 100644 index 00000000..fca285eb --- /dev/null +++ b/docs/configuration/interfaces/wireless.rst @@ -0,0 +1,575 @@ +.. _wireless-interface: + +################### +Wireless LAN (WiFi) +################### + +:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If your +hardware supports it, VyOS supports multiple logical wireless interfaces per +physical device. + +There are three modes of operation for a wireless interface: + +* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting + stations if the physical hardware supports acting as a WAP + +* A station acts as a Wi-Fi client accessing the network through an available + WAP + +* Monitor, the system passively monitors any kind of wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 + +Wireless options +================ + +.. cfgcmd:: set interfaces wireless <interface> channel <number> + + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 + +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + + Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed + to indicate country in which device is operating. This can limit available + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. + +.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid + + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know SSID. + +.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations + + Disassociate stations based on excessive transmission failures or other + indications of connection loss. + + This depends on the driver capabilities and may not be available with all + drivers. + +.. cfgcmd:: set interfaces wireless <interface> isolate-stations + + Client isolation can be used to prevent low-level bridging of frames between + associated stations in the BSS. + + By default, this bridging is allowed. + +.. cfgcmd:: set interfaces wireless <interface> max-stations + + Maximum number of stations allowed in station table. New stations will be + rejected after the station table is full. IEEE 802.11 has a limit of 2007 + different association IDs, so this number should not be larger than that. + + This defaults to 2007. + +.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection + + Management Frame Protection (MFP) according to IEEE 802.11w + +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + + Operation mode of wireless radio. + + * ``a`` - 802.11a - 54 Mbits/sec + * ``b`` - 802.11b - 11 Mbits/sec + * ``g`` - 802.11g - 54 Mbits/sec (default) + * ``n`` - 802.11n - 600 Mbits/sec + * ``ac`` - 802.11ac - 1300 Mbits/sec + +.. cfgcmd:: set interfaces wireless <interface> physical-device <device> + + Wireless hardware device used as underlay radio. + + This defaults to phy0. + +.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> + + Add Power Constraint element to Beacon and Probe Response frames. + + This option adds Power Constraint element when applicable and Country element + is added. Power Constraint element is required by Transmit Power Control. + + Valid values are 0..255. + +.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> + + SSID to be used in IEEE 802.11 management frames + +.. cfgcmd:: set interfaces wireless <interface> type <access-point | station | monitor> + + Wireless device type for this interface + + * ``access-point`` - Access-point forwards packets between other nodes + * ``station`` - Connects to another access point + * ``monitor`` - Passively monitor all packets on the frequency/channel + +PPDU +---- + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt + +HT (High Throughput) capabilities (802.11n) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable + + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave + + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht channel-set-width <ht20 | ht40+ | ht40-> + + Supported channel width set. + + * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel + * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + + .. note:: There are limits on which channels can be used with HT40- and HT40+. + Following table shows the channels that may be available for HT40- and HT40+ + use per IEEE 802.11n Annex J: + + Depending on the location, not all of these channels may be available for use! + + .. code-block:: none + + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + + .. note:: 40 MHz channels may switch their primary and secondary channels if + needed or creation of 40 MHz channel maybe rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht delayed-block-ack + + Enable HT-delayed Block Ack ``[DELAYED-BA]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 + + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield + + This enables the greenfield option which sets the ``[GF]`` option + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc + + Enable LDPC coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection + + Enable L-SIG TXOP protection capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu <3839 | 7935> + + Maximum A-MSDU length 3839 (default) or 7935 octets + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht short-gi <20 | 40> + + Short GI capabilities for 20 and 40 MHz + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht smps <static | dynamic> + + Spatial Multiplexing Power Save (SMPS) settings + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +VHT (Very High Throughput) capabilities (802.11ac) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count + + Number of antennas on this card + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-pattern-fixed + + Set if antenna pattern does not change during the lifetime of an association + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer | + multi-user-beamformee> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as single user beamformer + * ``single-user-beamformee`` - Support for operation as single user beamformee + * ``multi-user-beamformer`` - Support for operation as single user beamformer + * ``multi-user-beamformee`` - Support for operation as single user beamformer + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht center-channel-freq <freq-1 | freq-2> <number> + + VHT operating channel center frequency - center freq 1 (for use with 80, 80+80 and 160 modes) + + VHT operating channel center frequency - center freq 2 (for use with the 80+80 mode) + + <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht channel-set-width <0 | 1 | 2 | 3> + + * ``0`` - 20 or 40 MHz channel width (default) + * ``1`` - 80 MHz channel width + * ``2`` - 160 MHz channel width + * ``3`` - 80+80 MHz channel width + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc + + Enable LDPC (Low Density Parity Check) coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation + + VHT link adaptation capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht max-mpdu <value> + + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht max-mpdu-exp <value> + + Set the maximum length of A-MPDU pre-EOF padding that the station can receive + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht short-gi <80 | 160> + + Short GI capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave + + Enable VHT TXOP Power Save Mode + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf + + Station supports receiving VHT variant HT Control field + +Wireless options (Station/Client) +================================= + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (``phy0``) is used. + +.. code-block:: none + + set interfaces wireless wlan0 type station + set interfaces wireless wlan0 address dhcp + set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 security wpa + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address dhcp + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } + +Security +======== + +:abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with +802.1x based authentication can be used to authenticate users or computers +in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an :abbr:`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``Enterprise-TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` +* RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: wireless + :var1: wlan0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: wireless + :var1: wlan0 + +********* +Operation +********* + +.. opcmd:: show interfaces wireless info + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless info + Interface Type SSID Channel + wlan0 access-point VyOS-TEST-0 1 + +.. opcmd:: show interfaces wireless detail + +Use this command to view operational status and detailes wireless-specific +information about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless detail + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 + +.. opcmd:: show interfaces wireless <wlanX> + +This command shows both status and statistics on the specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + +.. opcmd:: show interfaces wireless <wlanX> brief + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 brief + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + wlan0 192.168.2.254/24 u/u + + +.. opcmd:: show interfaces wireless <wlanX> queue + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 queue + qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 + + +.. opcmd:: show interfaces wireless <wlanX> scan + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +.. note:: Scanning is not supported on all wireless drivers and wireless + hardware. Refer to your driver and wireless hardware documentation for + further details. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 scan + Address SSID Channel Signal (dbm) + 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 + 00:53:3b:88:6e:da Telekom_FON 1 -64.00 + 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 + 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 + 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 + 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 + 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 + 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 + 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 + 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 + 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 + 00:53:86:40:30:da Telekom_FON 1 -86.00 + 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 + 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 + + +******** +Examples +******** + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '12345678' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + +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. You can - of course - also +bridge the Wireless interface with any configured bridge +(:ref:`bridge-interface`) on the system. diff --git a/docs/configuration/interfaces/wirelessmodem.rst b/docs/configuration/interfaces/wirelessmodem.rst new file mode 100644 index 00000000..a65a47f4 --- /dev/null +++ b/docs/configuration/interfaces/wirelessmodem.rst @@ -0,0 +1,128 @@ +.. _wwan-interface: + +#################### +WirelessModem (WWAN) +#################### + +The wirelessmodem interface provides access (through a wireless modem/wwan) +to wireless networks provided by various cellular providers. VyOS uses the +interfaces wirelessmodem subsystem for configuration. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: wirelessmodem + :var1: wlm0 + +WirelessModem (WWAN) options +============================ + +.. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> + + Every WWAN connection requires an :abbr:`APN (Access Point Name)` which is + used by the client to dial into the ISPs network. This is a mandatory + parameter. Contact your Service Provider for correct APN. + +.. cfgcmd:: set interfaces wirelessmodem <interface> backup distance <metric> + + Configure metric of the default route added via the Wireless Modem interface. + The default metric if not specified is 10. + +.. cfgcmd:: set interfaces wirelessmodem <interface> device <tty> + + Device identifier of the underlaying physical interface. This is usually a + ttyUSB device, if not configured this defaults to ttyUSB2. + +.. cfgcmd:: set interfaces wirelessmodem <interface> no-peer-dns + + Do not install DNS nameservers received from ISP into system wide nameserver + list. + +.. cfgcmd:: set interfaces wirelessmodem <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPP connection + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + +********* +Operation +********* + +.. opcmd:: show interfaces wirelessmodem <interface> + + Retrive interface information from given WWAN interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wirelessmodem wlm0 + wlm0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master black state UNKNOWN group default qlen 3 + link/ppp + inet 10.26.238.93 peer 10.64.64.64/32 scope global wlm0 + valid_lft forever preferred_lft forever + Description: baaar + + RX: bytes packets errors dropped overrun mcast + 38 5 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 217 8 0 0 0 0 + +.. opcmd:: show interfaces wirelessmodem <interface> statistics + + Retrive interface statistics from given WWAN interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wirelessmodem wlm0 statistics + IN PACK VJCOMP VJUNC VJERR | OUT PACK VJCOMP VJUNC NON-VJ + 38 5 0 0 0 | 217 8 0 0 8 + +.. opcmd:: show interfaces wirelessmodem <interface> log + + Displays log information for a WWAN interface. + + +******* +Example +******* + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a :ref:`pc-engines-apu4`. + +.. code-block:: none + + set interfaces wirelessmodem wlm0 apn 'internet.telekom' + set interfaces wirelessmodem wlm0 backup distance '100' + set interfaces wirelessmodem wlm0 device 'ttyUSB2' + set interfaces wirelessmodem wlm0 disable + set interfaces wirelessmodem wlm0 no-peer-dns + +***************** +Supported Modules +***************** + +The following hardware modules have been tested successfully in an +:ref:`pc-engines-apu4` board: + +* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +* Huawei ME909u-521 miniPCIe card (LTE) +* Huawei ME909s-120 miniPCIe card (LTE) |