diff options
Diffstat (limited to 'docs/configuration/interfaces')
20 files changed, 6688 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md new file mode 100644 index 00000000..837b61c5 --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,731 @@ +lastproofread +2021-06-30 + +# 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 + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Member Interfaces + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> member interface \<member\> + +Enslave <span class="title-ref">\<member\></span> interface to bond <span class="title-ref">\<interface\></span>. + +</div> + +### Bond options + +<div class="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 `hash-policy` option, documented below. + + <div class="note"> + + <div class="title"> + + Note + + </div> + + Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet misordering requirements of section 43.2.4 + of the 802.3ad standard. + + </div> + +- `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 `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 `hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +</div> + +<div class="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 the carrier to be asserted +(for 802.3ad mode) whenever there is an active aggregator, +regardless of the number of available links in that aggregator. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> lacp-rate \<slow|fast\> + +Option specifying the rate in which we'll ask our link partner to transmit +LACPDU packets in 802.3ad mode. + +This option only affects 802.3ad mode. + +- slow: Request partner to transmit LACPDUs every 30 seconds +- fast: Request partner to transmit LACPDUs every 1 second + +The default value is slow. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> system-mac \<mac address\> + +This option allow to specifies the 802.3ad system MAC address.You can set a +random mac-address that can be used for these LACPDU exchanges. + +</div> + +<div class="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 + + ``` 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: + + ``` 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 + + ``` 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 these 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> primary \<interface\> + +An <span class="title-ref">\<interface\></span> 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> arp-monitor interval \<time\> + +Specifies the ARP link monitoring <span class="title-ref">\<time\></span> 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 +`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. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> arp-monitor target \<address\> + +Specifies the IP addresses to use as ARP monitoring peers when +`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 address. + +</div> + +### VLAN + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="bondinging" var1="bond1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +#### EVPN Multihoming + +All-Active Multihoming is used for redundancy and load sharing. Servers are +attached to two or more PEs and the links are bonded (link-aggregation). +This group of server links is referred to as an `ES (Ethernet Segment)`. + +An Ethernet Segment can be configured by specifying a system-MAC and a local +discriminator or a complete ESINAME against the bond interface on the PE. + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-id \<\<1-16777215|10-byte ID\> + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-sys-mac \<xx:xx:xx:xx:xx:xx\> + +The sys-mac and local discriminator are used for generating a 10-byte, Type-3 +Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID - +"00:AA:BB:CC:DD:EE:FF:GG:HH:II". + +Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally +attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP +routes are also advertised with a destination ESI allowing for MAC-IP syncing +between Ethernet Segment peers. Reference: RFC 7432, RFC 8365 + +EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming +each PE has an unique VTEP address which requires the introduction of a new +dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of +remote PEs/VTEPs. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-df-pref \<1-65535\> + +Type-4 (ESR) routes are used for Designated Forwarder (DF) election. +DFs forward BUM traffic received via the overlay network. This +implementation uses a preference based DF election specified by +draft-ietf-bess-evpn-pref-df. + +The DF preference is configurable per-ES. + +BUM traffic is rxed via the overlay by all PEs attached to a server but +only the DF can forward the de-capsulated traffic to the access port. +To accommodate that non-DF filters are installed in the dataplane to drop +the traffic. + +Similarly traffic received from ES peers via the overlay cannot be forwarded +to the server. This is split-horizon-filtering with local bias. + +</div> + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-evpn-uplink.txt + +</div> + +## 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. + +``` 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you happen to run this in a virtual environment like by EVE-NG +you need to ensure your VyOS NIC is set to use the e1000 driver. Using the +default `virtio-net-pci` or the `vmxnet3` driver will not work. ICMP +messages will not be properly processed. They are visible on the virtual wire +but will not make it fully up the networking stack. + +You can check your NIC driver by issuing `show interfaces ethernet +eth0 physical | grep -i driver` + +</div> + +### Cisco Catalyst + +Assign member interfaces to PortChannel + +``` 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. + +``` 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. + +``` 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. + +``` 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> +<img src="/_static/images/vyos_arista_bond_lacp.webp" alt="VyOS Arista EOS setup" /> +</figure> + +**R1** + +> ``` 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** + +> ``` 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** + +> ``` 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** + +> ``` 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 +> ! +> ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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! + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces bonding + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces bonding \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces bonding \<interface\> detail + +Show detailed information about the underlaying physical links on given +bond <span class="title-ref">\<interface\></span>. + +``` 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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md new file mode 100644 index 00000000..732ea8e9 --- /dev/null +++ b/docs/configuration/interfaces/md-bridge.md @@ -0,0 +1,405 @@ +lastproofread +2021-06-30 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Spanning Tree Protocol is not enabled by default in VyOS. +`stp` can be easily enabled if needed. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="bridge" var1="br0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Member Interfaces + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> + +Assign <span class="title-ref">\<member\></span> interface to bridge <span class="title-ref">\<interface\></span>. A completion +helper will help you with all allowed interfaces which can be +bridged. This includes `ethernet-interface`, +`bond-interface`, `l2tpv3-interface`, `openvpn`, +`vxlan-interface`, `wireless-interface`, +`tunnel-interface` and `geneve-interface`. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +priority \<priority\> + +Configure individual bridge port <span class="title-ref">\<priority\></span>. + +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 optimum +performance. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +cost \<cost\> + +Path <span class="title-ref">\<cost\></span> 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. + +</div> + +### Bridge Options + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> aging \<time\> + +MAC address aging <span class="title-ref">\<time</span>\> in seconds (default: 300). + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> max-age \<time\> + +Bridge maximum aging <span class="title-ref">\<time\></span> in seconds (default: 20). + +If an 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> igmp querier + +Enable IGMP and MLD querier. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> igmp snooping + +Enable IGMP and MLD snooping. + +</div> + +#### STP Parameter + +`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. + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> stp + +Enable spanning tree protocol. STP is disabled by default. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> forwarding-delay \<delay\> + +Spanning Tree Protocol forwarding <span class="title-ref">\<delay\></span> in seconds (default: 15). + +The 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> hello-time \<interval\> + +Spanning Tree Protocol hello advertisement <span class="title-ref">\<interval\></span> 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. + +</div> + +### VLAN + +#### Enable VLAN-Aware Bridge + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> enable-vlan + +To activate the VLAN aware bridge, you must activate this setting to use VLAN +settings for the bridge + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> protocol \<802.1ad|802.1q\> + +Define used ethertype of bridge interface. + +Ethertype `0x8100` is used for `802.1q` and ethertype `0x88a8` is used +for `802.1ad`. + +The default is `802.1q`. + +</div> + +#### VLAN Options + +<div class="note"> + +<div class="title"> + +Note + +</div> + +It is not valid to use the <span class="title-ref">vif 1</span> option for VLAN aware bridges +because VLAN aware bridges assume that all unlabeled packets belong to +the default VLAN 1 member and that the VLAN ID of the bridge's parent +interface is always 1 + +</div> + +<div class="cmdinclude" var0="bridge" var1="br0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +<div class="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 + +Example: Set <span class="title-ref">eth0</span> member port to be native VLAN 2 + +``` none +set interfaces bridge br1 member interface eth0 native-vlan 2 +``` + +</div> + +<div class="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: Set <span class="title-ref">eth0</span> member port to be allowed VLAN 4 + +``` none +set interfaces bridge br1 member interface eth0 allowed-vlan 4 +``` + +Example: Set <span class="title-ref">eth0</span> member port to be allowed VLAN 6-8 + +``` none +set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 +``` + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="bridge" var1="br1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +## Examples + +### Create a basic bridge + +Creating a bridge interface is very simple. In this example, we will +have: + +- A bridge named <span class="title-ref">br100</span> +- Member interfaces <span class="title-ref">eth1</span> and VLAN 10 on interface <span class="title-ref">eth2</span> +- Enable STP +- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +``` 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: + +``` 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 +``` + +### Using VLAN aware Bridge + +An example of creating a VLAN-aware bridge is as follows: + +- A bridge named <span class="title-ref">br100</span> +- The member interface <span class="title-ref">eth1</span> is a trunk that allows VLAN 10 to pass +- VLAN 10 on member interface <span class="title-ref">eth2</span> (ACCESS mode) +- Enable STP +- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +``` none +set interfaces bridge br100 enable-vlan +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: + +``` none +vyos@vyos# show interfaces bridge br100 + enable-vlan + 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 + } +``` + +### Using the operation mode command to view Bridge Information + +<div class="opcmd"> + +show bridge + +The <span class="title-ref">show bridge</span> operational command can be used to display +configured bridges: + +``` none +vyos@vyos:~$ show bridge +3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding +priority 32 cost 100 +4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding +priority 32 cost 100 +``` + +</div> + +<div class="opcmd"> + +show bridge \<name\> fdb + +Show bridge <span class="title-ref">\<name\></span> fdb displays the current forwarding table: + +``` none +vyos@vyos:~$ show bridge br0 fdb +50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent +50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent +50:00:00:08:00:01 dev eth1 master br0 permanent +33:33:00:00:00:01 dev eth1 self permanent +33:33:00:00:00:02 dev eth1 self permanent +01:00:5e:00:00:01 dev eth1 self permanent +50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent +50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent +50:00:00:08:00:02 dev eth2 master br0 permanent +33:33:00:00:00:01 dev eth2 self permanent +33:33:00:00:00:02 dev eth2 self permanent +01:00:5e:00:00:01 dev eth2 self permanent +33:33:00:00:00:01 dev br0 self permanent +33:33:00:00:00:02 dev br0 self permanent +33:33:ff:08:00:01 dev br0 self permanent +01:00:5e:00:00:6a dev br0 self permanent +33:33:00:00:00:6a dev br0 self permanent +01:00:5e:00:00:01 dev br0 self permanent +33:33:ff:00:00:00 dev br0 self permanent +``` + +</div> + +<div class="opcmd"> + +show bridge \<name\> mdb + +Show bridge <span class="title-ref">\<name\></span> mdb displays the current multicast group membership +table.The table is populated by IGMP and MLD snooping in the bridge driver +automatically. + +``` none +vyos@vyos:~$ show bridge br0 mdb +dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 +dev br0 port br0 grp ff02::2 temp vid 1 +dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 +dev br0 port br0 grp ff02::6a temp vid 1 +``` + +</div> + +> Show bridge Media Access Control (MAC) address table +> +> ``` 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/md-dummy.md b/docs/configuration/interfaces/md-dummy.md new file mode 100644 index 00000000..ec79579e --- /dev/null +++ b/docs/configuration/interfaces/md-dummy.md @@ -0,0 +1,110 @@ +lastproofread +2023-01-20 + +# Dummy + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the `loopback-interface` interface, except +you can have as many as you want. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Dummy interfaces can be used as interfaces that always stay up (in +the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +On systems with multiple redundant uplinks and routes, +it's a good idea to use a dedicated address for management and dynamic routing protocols. +However, assigning that address to a physical link is risky: +if that link goes down, that address will become inaccessible. +A common solution is to assign the management address to a loopback or a dummy interface +and advertise that address via all physical links, so that it's reachable +through any of them. Since in Linux-based systems, there can be only one loopback interface, +it's better to use a dummy interface for that purpose, since they can be added, removed, +and taken up and down independently. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-vrf.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces dummy + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces dummy \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces dummy dum0 +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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md new file mode 100644 index 00000000..4b0ee7f5 --- /dev/null +++ b/docs/configuration/interfaces/md-ethernet.md @@ -0,0 +1,357 @@ +lastproofread +2023-01-20 + +# Ethernet + +This will be the most widely used interface on a router carrying traffic to the +real world. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Ethernet options + +<div class="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 <span class="title-ref">auto</span>. + +</div> + +<div class="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 <span class="title-ref">auto</span>. + +</div> + +<div class="cfgcmd"> + +set interface ethernet \<interface\> ring-buffer rx \<value\> + +</div> + +<div class="cfgcmd"> + +set interface ethernet \<interface\> ring-buffer tx \<value\> + +Configures the ring buffer size of the interface. + +The supported values for a specific interface can be obtained +with: <span class="title-ref">ethtool -g \<interface\></span> + +</div> + +#### Offloading + +<div class="cfgcmd"> + +set interfaces ethernet \<interface\> offload \<gro | gso | lro | rps | +sg | tso\> + +Enable different types of hardware offloading on the given NIC. + +`LRO (Large Receive Offload)` is a technique designed to boost the +efficiency of how your computer's network interface card (NIC) processes +incoming network traffic. Typically, network data arrives in smaller chunks +called packets. Processing each packet individually consumes CPU (central +processing unit) resources. Lots of small packets can lead to a performance +bottleneck. Instead of handing the CPU each packet as it comes in, LRO +instructs the NIC to combine multiple incoming packets into a single, larger +packet. This larger packet is then passed to the CPU for processing. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Under some circumstances, LRO is known to modify the packet headers +of forwarded traffic, which breaks the end-to-end principle of computer +networking. LRO is also only able to offload TCP segments encapsulated in +IPv4 packets. Due to these limitations, it is recommended to use GRO +(Generic Receive Offload) where possible. More information on the +limitations of LRO can be found here: <https://lwn.net/Articles/358910/> + +</div> + +`GSO (Generic Segmentation Offload)` is a pure software offload that is +meant to deal with cases where device drivers cannot perform the offloads +described above. What occurs in GSO is that a given skbuff will have its data +broken out over multiple skbuffs that have been resized to match the MSS +provided via skb_shinfo()-\>gso_size. + +Before enabling any hardware segmentation offload a corresponding software +offload is required in GSO. Otherwise it becomes possible for a frame to be +re-routed between devices and end up being unable to be transmitted. + +`GRO (Generic receive offload)` is the complement to GSO. Ideally any +frame assembled by GRO should be segmented to create an identical sequence of +frames using GSO, and any sequence of frames segmented by GSO should be able +to be reassembled back to the original by GRO. The only exception to this is +IPv4 ID in the case that the DF bit is set for a given IP header. If the +value of the IPv4 ID is not sequentially incrementing it will be altered so +that it is when a frame assembled via GRO is segmented via GSO. + +`RPS (Receive Packet Steering)` is logically a software implementation +of `RSS (Receive Side Scaling)`. Being in software, it is necessarily +called later in the datapath. Whereas RSS selects the queue and hence CPU that +will run the hardware interrupt handler, RPS selects the CPU to perform +protocol processing above the interrupt handler. This is accomplished by +placing the packet on the desired CPU's backlog queue and waking up the CPU +for processing. RPS has some advantages over RSS: + +- it can be used with any NIC +- software filters can easily be added to hash over new protocols +- it does not increase hardware device interrupt rate, although it does + introduce inter-processor interrupts (IPIs) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In order to use TSO/LRO with VMXNET3 adapters, the SG offloading +option must also be enabled. + +</div> + +</div> + +#### Authentication (EAPoL) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-eapol.txt + +</div> + +#### EVPN Multihoming + +Uplink/Core tracking. + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-evpn-uplink.txt + +</div> + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="ethernet" var1="eth1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces ethernet + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> physical + +Show information about physical <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> physical offload + +Show available offloading functions on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> transceiver + +Show transceiver information from plugin modules, e.g SFP+, QSFP + +``` 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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md new file mode 100644 index 00000000..8bb145df --- /dev/null +++ b/docs/configuration/interfaces/md-geneve.md @@ -0,0 +1,102 @@ +lastproofread +2023-01-20 + +# GENEVE + +`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of `VXLAN (Virtual Extensible LAN)`, `NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and `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: + +``` none ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +|Ver| Opt Len |O|C| Rsvd. | Protocol Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Virtual Network Identifier (VNI) | Reserved | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Variable Length Options | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-mac.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-ip.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-ipv6.txt + +</div> + +### GENEVE options + +<div class="cfgcmd"> + +set interfaces geneve gnv0 remote \<address\> + +Configure GENEVE tunnel far end/remote tunnel endpoint. + +</div> + +<div class="cfgcmd"> + +set interfaces geneve gnv0 vni \<vni\> + +`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. + +</div> diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md new file mode 100644 index 00000000..5d66b2d0 --- /dev/null +++ b/docs/configuration/interfaces/md-index.md @@ -0,0 +1,25 @@ +# Interfaces + +<div class="toctree" maxdepth="1" includehidden=""> + +bonding +bridge +dummy +ethernet +geneve +l2tpv3 +loopback +macsec +openvpn +wireguard +pppoe +pseudo-ethernet +sstp-client +tunnel +virtual-ethernet +vti +vxlan +wireless +wwan + +</div> diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md new file mode 100644 index 00000000..84e190f5 --- /dev/null +++ b/docs/configuration/interfaces/md-l2tpv3.md @@ -0,0 +1,206 @@ +lastproofread +2023-01-20 + +# L2TPv3 + +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to `mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service but is 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 `3931`. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="l2tpv3" var1="l2tpeth0"> + +/\_include/interface-common-without-dhcp.txt + +</div> + +### L2TPv3 options + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> source-address \<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. It may be specified as +an IPv4 address or an IPv6 address. + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> remote \<address\> + +Set the IP address of the remote peer. It may be specified as +an IPv4 address or an IPv6 address. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## Example + +### Over IP + +``` none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + tunnel-id 200 +} +``` + +The inverse configuration has to be applied to the remote side. + +### Over UDP + +UDP mode works better with NAT: + +- Set source-address to your local IP (LAN). +- Add a forwarding rule matching UDP port on your internet router. + +``` none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 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: + +``` none +set vpn ipsec authentication psk <pre-shared-name> id '%any' +set vpn ipsec authentication psk <pre-shared-name> secret <pre-shared-key> +set vpn ipsec interface <VPN-interface> +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 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 <connection-name> authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer <connection-name> connection-type 'initiate' +set vpn ipsec site-to-site peer <connection-name> ike-group 'test-IKE-1' +set vpn ipsec site-to-site peer <connection-name> ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer <connection-name> local-address <local-ip> +set vpn ipsec site-to-site peer <connection-name> tunnel 1 esp-group 'test-ESP-1' +set vpn ipsec site-to-site peer <connection-name> tunnel 1 protocol 'l2tp' +``` + +Bridge: + +``` 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: + +``` 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 source-address <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 <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/md-loopback.md b/docs/configuration/interfaces/md-loopback.md new file mode 100644 index 00000000..1d8d6766 --- /dev/null +++ b/docs/configuration/interfaces/md-loopback.md @@ -0,0 +1,97 @@ +lastproofread +2023-01-20 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There can only be one loopback `lo` interface on the system. If +you need multiple interfaces, please use the `dummy-interface` +interface type. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +A loopback interface is always up, thus it could be used for +management traffic or as source/destination for and `IGP (Interior +Gateway Protocol)` like `routing-bgp` so your internal BGP link is not +dependent on physical link states and multiple routes can be chosen to the +destination. A `dummy-interface` Interface should always be preferred +over a `loopback-interface` interface. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="loopback" var1="lo"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="loopback" var1="lo"> + +/\_include/interface-description.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces loopback + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces loopback lo + +Show detailed information on the given loopback interface <span class="title-ref">lo</span>. + +``` none +vyos@vyos:~$ show interfaces loopback lo +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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md new file mode 100644 index 00000000..17dfff1c --- /dev/null +++ b/docs/configuration/interfaces/md-macsec.md @@ -0,0 +1,332 @@ +lastproofread +2023-01-20 + +# 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 + +<div class="cmdinclude" var0="macsec" var1="macsec0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### MACsec options + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security cipher \<gcm-aes-128|gcm-aes-256\> + +Select cipher suite used for cryptographic operations. This setting is +mandatory. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> source-interface \<physical-source\> + +A physical interface is required to connect this MACsec instance to. Traffic +leaving this interface will now be authenticated/encrypted. + +</div> + +#### Static Keys + +Static `SAK (Secure Authentication Key)` mode can be configured manually on each +device wishing to use MACsec. Keys must be set statically on all devices for traffic +to flow properly. Key rotation is dependent on the administrator updating all keys +manually across connected devices. Static SAK mode can not be used with MKA. + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static key \<key\> + +Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes +(GCM-AES-128) or 32-bytes (GCM-AES-256). + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> mac \<mac address\> + +Set the peer's MAC address + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> key \<key\> + +Set the peer's key used to receive (RX) traffic + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> disable + +Disable the peer configuration + +</div> + +#### Key Management + +`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +individual peers. + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka cak \<key\> + +IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with +a pre-shared key using a `CAK (MACsec connectivity association key)` and +`CKN (MACsec connectivity association name)` pair. + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka ckn \<key\> + +`CKN (MACsec connectivity association name)` key + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka priority \<priority\> + +The peer with lower priority will become the key server and start +distributing SAKs. + +</div> + +#### Replay protection + +<div class="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 + +</div> + +## Operation + +<div class="opcmd"> + +run generate macsec mka cak \<gcm-aes-128|gcm-aes-256\> + +Generate `MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits. + +``` none +vyos@vyos:~$ generate macsec mka cak gcm-aes-128 +20693b6e08bfa482703a563898c9e3ad +``` + +</div> + +<div class="opcmd"> + +run generate macsec mka ckn + +Generate `MKA (MACsec Key Agreement protocol)` CAK key. + +``` none +vyos@vyos:~$ generate macsec mka ckn +88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 +``` + +</div> + +<div class="opcmd"> + +show interfaces macsec + +List all MACsec interfaces. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces macsec \<interface\> + +Show specific MACsec interface information + +``` 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 +``` + +</div> + +## 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** + +``` 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** + +``` 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. + +``` 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. + +``` 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.( +``` + +**R1 Static Key** + +``` 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 static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 +set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2 Static Key** + +``` 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 static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:01 +set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +## MACsec over wan + +MACsec is an interesting alternative to existing tunneling solutions that +protects layer 2 by performing integrity, origin authentication, and optionally +encryption. The typical use case is to use MACsec between hosts and access +switches, between two hosts, or between two switches. in this example below, +we use VXLAN and MACsec to secure the tunnel. + +**R1 MACsec01** + +``` 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 static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' +set interfaces vxlan vxlan1 remote '10.1.3.3' +set interfaces vxlan vxlan1 source-address '172.16.100.1' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 +``` + +**R2 MACsec02** + +``` 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 static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' +set interfaces vxlan vxlan1 remote '10.1.2.2' +set interfaces vxlan vxlan1 source-address '172.16.100.2' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 +``` diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md new file mode 100644 index 00000000..b9df5971 --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn.md @@ -0,0 +1,924 @@ +lastproofread +2021-07-05 + +# 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 <span class="title-ref">set vpn</span> stanza, OpenVPN is configured as a network +interface using <span class="title-ref">set interfaces openvpn</span>. + +## Site-to-Site + +<figure> +<img src="/_static/images/openvpn_site2site_diagram.webp" /> +</figure> + +OpenVPN is popular for client-server setups, but its site-to-site mode +remains a relatively obscure feature, and many router appliances +still don't support it. However, it's very useful for quickly setting up +tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. + +The pre-shared key mode is deprecated and will be removed from future OpenVPN versions, +so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys +is significantly less secure than using TLS. + +We'll configure OpenVPN using self-signed certificates, and then discuss the legacy +pre-shared key mode. + +In both cases, we will use the following settings: + +- The public IP address of the local side of the VPN will be 198.51.100.10. +- The public IP address of the remote side of the VPN 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. +- The local site will have a subnet of 10.0.0.0/16. +- The remote site will have a subnet of 10.1.0.0/16. +- 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. + +### Setting up certificates + +Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose +of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity, +compared to server setups that need to support multiple clients. + +However, since VyOS 1.4, it is possible to verify self-signed certificates using +certificate fingerprints. + +On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type. +You can generate them by executing command `run generate pki certificate self-signed install <name>` in the configuration mode. +Once the command is complete, it will add the certificate to the configuration session, to the `pki` subtree. +You can then review the proposed changes and commit them. + +``` none +vyos@vyos# run generate pki certificate self-signed install openvpn-local +Enter private key type: [rsa, dsa, ec] (Default: rsa) ec +Enter private key bits: (Default: 256) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + +vyos@vyos# compare +[pki] ++ certificate openvpn-local { ++ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/ uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" ++ private { ++ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" ++ } ++ } + +[edit] + +vyos@vyos# commit +``` + +You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint. +OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command: + +``` none +vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 +5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +``` + +Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary. + +Repeat the procedure on the other router. + +### Setting up OpenVPN + +Local Configuration: + +``` none +Configure the tunnel: + +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 '203.0.113.11' # Public IP of the other side +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 + on the remote rout +``` + +Remote Configuration: + +``` 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' # Pub IP of other site +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 + on the local router +``` + +### Pre-shared keys + +Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys. +That option is still available but it is deprecated and will be removed in the future. +However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, +you need to still need to know how to use it. + +First, you need to generate a key by running `run generate pki openvpn shared-secret install <name>` from configuration mode. +You can use any name, we will use `s2s`. + +``` none +vyos@local# run generate pki openvpn shared-secret install s2s +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@local# compare +[pki openvpn shared-secret] ++ s2s { ++ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" ++ version "1" ++ } + +[edit] + +vyos@local# commit +[edit] +``` + +Then you need to install the key on the remote router: + +``` none +vyos@remote# set pki openvpn shared-secret s2s key <generated key string> +``` + +Then you need to set the key in your OpenVPN interface settings: + +``` none +set interfaces openvpn vtun1 shared-secret-key s2s +``` + +### Firewall Exceptions + +For the OpenVPN traffic to pass through the WAN interface, you must create a +firewall exception. + +``` none +set firewall name OUTSIDE_LOCAL rule 10 action accept +set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall name OUTSIDE_LOCAL rule 10 state established enable +set firewall name OUTSIDE_LOCAL rule 10 state related enable +set firewall name OUTSIDE_LOCAL rule 20 action accept +set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN +set firewall name OUTSIDE_LOCAL rule 20 destination port 1195 +set firewall name OUTSIDE_LOCAL rule 20 log enable +set firewall name OUTSIDE_LOCAL rule 20 protocol udp +set firewall name OUTSIDE_LOCAL rule 20 source +``` + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and a direction (local). + +``` none +set firewall interface eth0 local name 'OUTSIDE-LOCAL' +``` + +Static Routing: + +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: + +``` none +set protocols static route 10.1.0.0/16 interface vtun1 +``` + +Remote Configuration: + +``` none +set protocols static route 10.0.0.0/16 interface vtun1 +``` + +The configurations above will default to using 256-bit AES in GCM mode +for encryption (if both sides support 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. + +``` 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 the default). Default NCP cipher for versions \>= 2.4.0 is +aes256gcm. The first cipher in this list is what server pushes to clients. + +``` 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: + +``` 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. + +Firewall policy can also be applied to the tunnel interface for <span class="title-ref">local</span>, <span class="title-ref">in</span>, +and <span class="title-ref">out</span> directions and functions 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 <span class="title-ref">show openvpn</span> 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 topic +`configuration/pki/index:pki` 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +``` 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 generate, add and specify the names of the cryptographic materials. +Each of the install command should be applied to the configuration and commited +before using under the openvpn interface configuration. + +``` none +run generate pki ca install ca-1 # Follow the instructions to generate CA cert. +Configure mode commands to install: +set pki ca ca-1 certificate 'generated_cert_string' +set pki ca ca-1 private key 'generated_private_key' + +run generate pki certificate sign ca-1 install srv-1 # Follow the instructions to generate server cert. +Configure mode commands to install: +set pki certificate srv-1 certificate 'generated_server_cert' +set pki certificate srv-1 private key 'generated_private_key' + +run generate pki dh install dh-1 # Follow the instructions to generate set of + Diffie-Hellman parameters. +Generating parameters... +Configure mode commands to install DH parameters: +set pki dh dh-1 parameters 'generated_dh_params_set' + +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +``` + +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 our router, we will use a push-route option for +installing that route on clients. + +``` 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Clients are identified by the CN field of their x.509 certificates, +in this example the CN is `client0`: + +</div> + +``` 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: + +``` none +set protocols static route 10.23.0.0/20 interface vtun10 +``` + +Additionally, each client needs a copy of ca cert and its own client key and +cert files. The files are plaintext so they may be copied either manually from the CLI. +Client key and cert files should be signed with the proper ca cert and generated on the +server side. + +HQ's router requires the following steps to generate crypto materials for the Branch 1: + +``` none +run generate pki certificate sign ca-1 install branch-1 # Follow the instructions to generate client + cert for Branch 1 +Configure mode commands to install: +``` + +Branch 1's router might have the following lines: + +``` none +set pki ca ca-1 certificate 'generated_cert_string' # CA cert generated on HQ router +set pki certificate branch-1 certificate 'generated_branch_cert' # Client cert generated and signed on HQ router +set pki certificate branch-1 private key 'generated_private_key' # Client cert key generated on HQ router + +set interfaces openvpn vtun10 tls ca-cert ca-1 +set interfaces openvpn vtun10 tls certificate branch-1 +``` + +### 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 + +``` 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 this: + +``` 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 + +``` 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: + +``` 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: + +``` 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 "--verify-client-cert none" + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-certificate ca.crt + certificate server.crt + dh-params dh1024.pem + } + } +``` + +## 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. + +### Configuration + +#### Server Side + +``` 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 ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls crypt-key srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +set interfaces openvpn vtun10 use-lzo-compression +``` + +#### Client Side + +``` 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 ca-1 +set interfaces openvpn vtun10 tls certificate client-1 +set interfaces openvpn vtun10 tls crypt-key client-1 +set interfaces openvpn vtun10 use-lzo-compression +``` + +### Options + +We do not have CLI nodes for every single OpenVPN option. If an option is +missing, a feature request should be opened at [Phabricator]() so all users can +benefit from it (see `issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +<div class="cfgcmd"> + +set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +</div> + +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. + +<div class="cfgcmd"> + +set interfaces openvpn vtun10 openvpn-option +'push \"keepalive 1 10\"' + +</div> + +Will add `push "keepalive 1 10"` to the generated OpenVPN config file. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Sometimes option lines in the generated OpenVPN configuration require +quotes. This is done through a hack on our config generator. You can pass +quotes using the `"` statement. + +</div> + +### Server bridge + +In Ethernet bridging configurations, OpenVPN's server mode can be set as a +'bridge' where the VPN tunnel encapsulates entire Ethernet frames +(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup +allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below, +we outline a basic configuration to achieve this: + +Server Side: + +``` none +set interfaces bridge br10 member interface eth1.10 +set interfaces bridge br10 member interface vtun10 +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256'' +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 server bridge gateway '10.10.0.1' +set interfaces openvpn vtun10 server bridge start '10.10.0.100' +set interfaces openvpn vtun10 server bridge stop '10.10.0.200' +set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'srv-1' +``` + +Client Side : + +``` none +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256'' +set interfaces openvpn vtun10 mode 'client' +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-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'client-1' +``` + +## Multi-factor Authentication + +VyOS supports multi-factor authentication (MFA) or two-factor authentication +using Time-based One-Time Password (TOTP). Compatible with Google Authenticator +software token, other software tokens. + +### MFA TOTP options + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp challenge \<enable | disable\> + +If set to enable, openvpn-otp will expect password as result of challenge/ +response protocol. + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp digits \<1-65535\> + +Configure number of digits to use for totp hash (default: 6) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp drift \<1-65535\> + +Configure time drift in seconds (default: 0) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp slop \<1-65535\> + +Configure maximum allowed clock slop in seconds (default: 180) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp step \<1-65535\> + +Configure step value for totp in seconds (default: 30) + +</div> + +### Example + +``` none +set interfaces openvpn vtun20 encryption cipher 'aes256' +set interfaces openvpn vtun20 hash 'sha512' +set interfaces openvpn vtun20 mode 'server' +set interfaces openvpn vtun20 persistent-tunnel +set interfaces openvpn vtun20 server client user1 +set interfaces openvpn vtun20 server mfa totp challenge 'disable' +set interfaces openvpn vtun20 server subnet '10.10.2.0/24' +set interfaces openvpn vtun20 server topology 'subnet' +set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls dh-params 'dh-pem' +``` + +For every client in the openvpn server configuration a totp secret is created. +To display the authentication information, use the command: + +<div class="cfgcmd"> + +show interfaces openvpn \<interface\> user \<username\> mfa \<qrcode[|secret|](##SUBST##|secret|)uri\> + +</div> + +An example: + +``` none +vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode +█████████████████████████████████████ +█████████████████████████████████████ +████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ +████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ +████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ +████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ +████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ +████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ +████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ +████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ +████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ +████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ +████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ +████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ +████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ +█████████████████████████████████████ +█████████████████████████████████████ +``` + +Use the QR code to add the user account in Google authenticator application and +on client side, use the OTP number as password. + +## OpenVPN Data Channel Offload (DCO) + +OpenVPN Data Channel Offload (DCO) enables significant performance enhancement +in encrypted OpenVPN data processing. By minimizing context switching for each +packet, DCO effectively reduces overhead. This optimization is achieved by +keeping most data handling tasks within the kernel, avoiding frequent switches +between kernel and user space for encryption and packet handling. + +As a result, the processing of each packet becomes more efficient, potentially +leveraging hardware encryption offloading support available in the kernel. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +OpenVPN DCO is not full OpenVPN features supported , is currently +considered experimental. Furthermore, there are certain OpenVPN features and +use cases that remain incompatible with DCO. To get a comprehensive +understanding of the limitations associated with DCO, refer to the list of +known limitations in the documentation. + +<https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features> + +</div> + +### Enabling OpenVPN DCO + +DCO support is a per-tunnel option and it is not automatically enabled by +default for new or upgraded tunnels. Existing tunnels will continue to function +as they have in the past. + +DCO can be enabled for both new and existing tunnels,VyOS adds an option in each +tunnel configuration where we can enable this function .The current best +practice is to create a new tunnel with DCO to minimize the chance of problems +with existing clients. + +<div class="cfgcmd"> + +set interfaces openvpn \<name\> offload dco + +Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel +module. + +Disabled by default - no kernel module loaded. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Enable this feature causes an interface reset. + +</div> + +</div> + +### Troubleshooting + +VyOS provides some operational commands on OpenVPN. + +#### Check status + +The following commands let you check tunnel status. + +<div class="opcmd"> + +show openvpn client + +Use this command to check the tunnel status for OpenVPN client interfaces. + +</div> + +<div class="opcmd"> + +show openvpn server + +Use this command to check the tunnel status for OpenVPN server interfaces. + +</div> + +<div class="opcmd"> + +show openvpn site-to-site + +Use this command to check the tunnel status for OpenVPN site-to-site +interfaces. + +</div> + +#### Reset OpenVPN + +The following commands let you reset OpenVPN. + +<div class="opcmd"> + +reset openvpn client \<text\> + +Use this command to reset the specified OpenVPN client. + +</div> + +<div class="opcmd"> + +reset openvpn interface \<interface\> + +Use this command to reset the OpenVPN process on a specific interface. + +</div> diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md new file mode 100644 index 00000000..f228aab2 --- /dev/null +++ b/docs/configuration/interfaces/md-pppoe.md @@ -0,0 +1,562 @@ +lastproofread +2022-07-27 + +# PPPoE + +`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 `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 because 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 `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 Transceiver has a switch, as some of them only work this way. + +Once you have an Ethernet device connected, i.e. <span class="title-ref">eth0</span>, 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 + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-vrf.txt + +</div> + +### PPPoE options + +<div class="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 <span class="title-ref">\<name\></span>. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> authentication username \<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. + +</div> + +<div class="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. + +</div> + +<div class="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 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. + +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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> no-default-route + +Only request an address from the PPPoE server but do not install any default +route. + +Example: + +``` none +set interfaces pppoe pppoe0 no-default-route +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command got added in VyOS 1.4 and inverts the logic from the old +`default-route` CLI option. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> default-route-distance \<distance\> + +Set the distance for the default gateway sent by the PPPoE server. + +Example: + +``` none +set interfaces pppoe pppoe0 default-route-distance 220 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> mru \<mru\> + +Set the `MRU (Maximum Receive Unit)` to <span class="title-ref">mru</span>. PPPd will ask the peer to +send packets of no more than <span class="title-ref">mru</span> bytes. The value of <span class="title-ref">mru</span> must be between 128 +and 16384. + +A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256 +bytes of data). + +The default is 1492. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using the IPv6 protocol, MRU must be at least 1280 bytes. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> holdoff \<time\> + +Use this command to set re-dial delay time to be used with persist PPPoE +sessions. When the PPPoE session is terminated by peer, and on-demand +option is not set, the router will attempt to re-establish the PPPoE link. + +If this parameter is not set, the default holdoff time is 30 seconds. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> no-peer-dns + +Use this command to not install advertised DNS nameservers into the local +system. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp our +TCP MSS value to a specific value. This is a field in the TCP options part of +a SYN packet. By setting the MSS value, you are telling the remote side +unequivocally 'do not try to send me packets bigger than this value'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in +1452 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip disable-forwarding + +Configure interface-specific Host/Router behaviour. If set, the interface will +switch to host mode and IPv6 forwarding will be disabled on this interface. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip source-validation \<strict | loose | disable\> + +Enable policy for source validation by reversed path, as specified in +`3704`. Current recommended practice in `3704` is to enable strict +mode to prevent IP spoofing from DDos attacks. If using asymmetric routing +or other complicated routing, then loose mode is recommended. + +- strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. +- loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. +- disable: No source validation + +</div> + +#### IPv6 + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 address autoconf + +Use this command to enable acquisition of IPv6 address using stateless +autoconfig (SLAAC). + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 adjust-mss \<mss | clamp-mss-to-pmtu\> + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp our +TCP MSS value to a specific value. This is a field in the TCP options part of +a SYN packet. By setting the MSS value, you are telling the remote side +unequivocally 'do not try to send me packets bigger than this value'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in +1432 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 disable-forwarding + +Configure interface-specific Host/Router behaviour. If set, the interface will +switch to host mode and IPv6 forwarding will be disabled on this interface. + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-dhcpv6-prefix-delegation.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces pppoe \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces pppoe \<interface\> queue + +Displays queue information for a PPPoE interface. + +``` 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 +``` + +</div> + +### Connect/Disconnect + +<div class="opcmd"> + +disconnect interface \<interface\> + +Test disconnecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`pppoe0` as the example. + +</div> + +<div class="opcmd"> + +connect interface \<interface\> + +Test connecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`pppoe0` as the example. + +</div> + +## 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 `name-server` option set to `none`, VyOS will ignore the + nameservers your ISP sends you and thus you can fully rely on the ones you + have configured statically. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Syntax has changed from VyOS 1.2 (crux) and it will be automatically +migrated during an upgrade. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A default route is automatically installed once the interface is up. +To change this behavior use the `no-default-route` CLI option. + +</div> + +``` none +set interfaces pppoe pppoe0 authentication username '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: + +``` none +set firewall interface pppoe0 in name NET-IN +set firewall interface pppoe0 local name NET-LOCAL +set firewall interface pppoe0 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: + +``` none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0.7' +``` + +#### IPv6 DHCPv6-PD Example + +The following configuration will setup a PPPoE session source from eth1 and +assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0. +The IPv6 address assigned to eth0 will be \<prefix\>::1/64. If you do not know +the prefix size delegated to you, start with sla-len 0. + +In addition we setup IPv6 `RA (Router Advertisements)` to make the +prefix known on the eth0 link. + +``` none +set interfaces pppoe pppoe0 authentication username vyos +set interfaces pppoe pppoe0 authentication password vyos +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 source-interface eth1 + +set service router-advert interface eth0 prefix ::/64 +``` diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md new file mode 100644 index 00000000..a58ccfc6 --- /dev/null +++ b/docs/configuration/interfaces/md-pseudo-ethernet.md @@ -0,0 +1,67 @@ +lastproofread +2023-01-26 + +# MACVLAN - Pseudo Ethernet + +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 + `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 learn the MAC address of the NIC + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="pseudo-ethernet" var1="peth0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Pseudo Ethernet/MACVLAN options + +<div class="cfgcmd"> + +set interfaces pseudo-ethernet \<interface\> source-interface \<ethX\> + +Specifies the physical <span class="title-ref">\<ethX\></span> Ethernet interface associated with a Pseudo +Ethernet <span class="title-ref">\<interface\></span>. + +</div> + +### VLAN + +<div class="cmdinclude" var0="pseudo-ethernet" var1="peth0"> + +/\_include/interface-vlan-8021q.txt + +</div> diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md new file mode 100644 index 00000000..d5c19d8f --- /dev/null +++ b/docs/configuration/interfaces/md-sstp-client.md @@ -0,0 +1,225 @@ +lastproofread +2022-12-11 + +# SSTP Client + +`SSTP (Secure Socket Tunneling Protocol)` is a form of `VTP (Virtual +Private Network)` tunnel that provides a mechanism to transport PPP traffic +through an SSL/TLS channel. SSL/TLS provides transport-level security with key +negotiation, encryption and traffic integrity checking. The use of SSL/TLS over +TCP port 443 (by default, port can be changed) allows SSTP to pass through +virtually all firewalls and proxy servers except for authenticated web proxies. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS also comes with a build in SSTP server, see `sstp`. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-vrf.txt + +</div> + +### SSTP Client Options + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> no-default-route + +Only request an address from the SSTP server but do not install any default +route. + +Example: + +``` none +set interfaces sstpc sstpc0 no-default-route +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command got added in VyOS 1.4 and inverts the logic from the old +`default-route` CLI option. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> default-route-distance \<distance\> + +Set the distance for the default gateway sent by the SSTP server. + +Example: + +``` none +set interfaces sstpc sstpc0 default-route-distance 220 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> no-peer-dns + +Use this command to not install advertised DNS nameservers into the local +system. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> server \<address\> + +SSTP remote server to connect to. Can be either an IP address or FQDN. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp our +TCP MSS value to a specific value. This is a field in the TCP options part of +a SYN packet. By setting the MSS value, you are telling the remote side +unequivocally 'do not try to send me packets bigger than this value'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in +1452 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip disable-forwarding + +Configure interface-specific Host/Router behaviour. If set, the interface will +switch to host mode and IPv6 forwarding will be disabled on this interface. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip source-validation \<strict | loose | disable\> + +Enable policy for source validation by reversed path, as specified in +`3704`. Current recommended practice in `3704` is to enable strict +mode to prevent IP spoofing from DDos attacks. If using asymmetric routing +or other complicated routing, then loose mode is recommended. + +- strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. +- loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. +- disable: No source validation + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces sstpc \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces sstpc sstpc10 +sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 + valid_lft forever preferred_lft forever + inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 215 9 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 539 14 0 0 0 0 +``` + +</div> + +### Connect/Disconnect + +<div class="opcmd"> + +disconnect interface \<interface\> + +Test disconnecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`sstpc0` as the example. + +</div> + +<div class="opcmd"> + +connect interface \<interface\> + +Test connecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`sstpc0` as the example. + +</div> diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md new file mode 100644 index 00000000..53ba1a3e --- /dev/null +++ b/docs/configuration/interfaces/md-tunnel.md @@ -0,0 +1,283 @@ +lastproofread +2023-01-26 + +# 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 + +<div class="cmdinclude" var0="tunnel" var1="tun0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="tunnel" var1="tun0"> + +/\_include/interface-common-without-mac.txt + +</div> + +## IPIP + +This is one of the simplest types of tunnels, as defined by `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: + +``` none +set interfaces tunnel tun0 encapsulation ipip +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 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: + +``` none +set interfaces tunnel tun0 encapsulation ip6ip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 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](https://www.isc.org/othersoftware/)). + +As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. + +An example: + +``` none +set interfaces tunnel tun0 encapsulation ipip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 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 +`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](https://tunnelbroker.net/). + +An example: + +``` none +set interfaces tunnel tun0 encapsulation sit +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 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 +`here <examples-tunnelbroker-ipv6>`. + +## Generic Routing Encapsulation (GRE) + +A GRE tunnel operates at layer 3 of the OSI model and is represented by IP +protocol 47. The main benefit of a GRE tunnel is that you are able to carry +multiple protocols inside the same tunnel. GRE also supports multicast traffic +and supports routing protocols that leverage multicast to form neighbor +adjacencies. + +A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created +over either IPv4 (gre) or IPv6 (ip6gre). + +### Configuration + +A basic configuration requires a tunnel source (source-address), a tunnel +destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6). +Below is a basic IPv4 only 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:** + +``` none +set interfaces tunnel tun100 address '10.0.0.1/30' +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 source-address '198.51.100.2' +set interfaces tunnel tun100 remote '203.0.113.10' +``` + +**Cisco IOS Router:** + +``` 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 +``` + +Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router +and a Linux host using systemd-networkd. + +**VyOS Router:** + +``` none +set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' +set interfaces tunnel tun101 address '192.168.5.1/30' +set interfaces tunnel tun101 encapsulation 'ip6gre' +set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' +set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' +``` + +**Linux systemd-networkd:** + +This requires two files, one to create the device (XXX.netdev) and one +to configure the network on the device (XXX.network) + +``` none +# cat /etc/systemd/network/gre-example.netdev +[NetDev] +Name=gre-example +Kind=ip6gre +MTUBytes=14180 + +[Tunnel] +Remote=2001:db8:babe:face::3afe:3 + + +# cat /etc/systemd/network/gre-example.network +[Match] +Name=gre-example + +[Network] +Address=2001:db8:feed:beef::2/126 + +[Address] +Address=192.168.5.2/30 +``` + +### 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: + +``` none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 10.40.50.60/24 +set interfaces tunnel tun0 parameters ip key 10 +``` + +``` none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 172.16.17.18/24 +set interfaces tunnel tun0 parameters ip key 20 +``` + +### GRETAP + +While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate +Ethernet frames, thus it can be bridged with other interfaces to create +datalink layer segments that span multiple remote sites. + +``` none +set interfaces bridge br0 member interface eth0 +set interfaces bridge br0 member interface tun0 +set interfaces tunnel tun0 encapsulation gretap +set interfaces tunnel tun0 source-address 198.51.100.2 +set interfaces tunnel tun0 remote 203.0.113.10 +``` + +### 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/destination traffic. + +**1. Confirm IP connectivity between tunnel source-address and remote:** + +``` 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:** + +``` 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:** + +``` 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There is also a GRE over IPv6 encapsulation available, it is +called: `ip6gre`. + +</div> diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md new file mode 100644 index 00000000..2d3f4c63 --- /dev/null +++ b/docs/configuration/interfaces/md-virtual-ethernet.md @@ -0,0 +1,127 @@ +lastproofread +2022-11-25 + +# Virtual Ethernet + +The veth devices are virtual Ethernet devices. They can act as tunnels between +network namespaces to create a bridge to a physical network device in another +namespace or VRF, but can also be used as standalone network devices. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +veth interfaces need to be created in pairs - it's called the peer name + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-address-with-dhcp.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-description.txt + +</div> + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vrf.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces virtual-ethernet + +Show brief interface information. + +``` none +vyos@vyos:~$ show interfaces virtual-ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +veth10 100.64.0.0/31 u/u +veth11 100.64.0.1/31 u/u +``` + +</div> + +<div class="opcmd"> + +show interfaces virtual-ethernet \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces virtual-ethernet veth11 +10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 + link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff + inet 100.64.0.1/31 scope global veth11 + valid_lft forever preferred_lft forever + inet6 fe80::b07b:dfff:fe47:e911/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 +``` + +</div> + +## Example + +Interconnect the global VRF with vrf "red" using the veth10 \<-\> veth 11 pair + +``` none +set interfaces virtual-ethernet veth10 address '100.64.0.0/31' +set interfaces virtual-ethernet veth10 peer-name 'veth11' +set interfaces virtual-ethernet veth11 address '100.64.0.1/31' +set interfaces virtual-ethernet veth11 peer-name 'veth10' +set interfaces virtual-ethernet veth11 vrf 'red' +set vrf name red table '1000' + +vyos@vyos:~$ ping 100.64.0.1 +PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. +64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms +64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms +``` diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md new file mode 100644 index 00000000..0d924f65 --- /dev/null +++ b/docs/configuration/interfaces/md-vti.md @@ -0,0 +1,46 @@ +# VTI - Virtual Tunnel Interface + +Set Virtual Tunnel Interface + +``` none +set interfaces vti vti0 address 192.168.2.249/30 +set interfaces vti vti0 address 2001:db8:2::249/64 +``` + +Results in: + +``` none +vyos@vyos# show interfaces vti +vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" +} +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall + +</div> + +``` none +set vpn ipsec options disable-route-autoinstall +``` + +More details about the IPsec and VTI issue and option disable-route-autoinstall +<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july> + +The root cause of the problem is that for VTI tunnels to work, their traffic +selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even +though actual routing decision is made according to netfilter marks. Unless +route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a +default route through the VTI peer address, which makes all traffic routed +to nowhere. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md new file mode 100644 index 00000000..9a991c08 --- /dev/null +++ b/docs/configuration/interfaces/md-vxlan.md @@ -0,0 +1,396 @@ +lastproofread +2023-01-26 + +# VXLAN + +`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 `VTEPs (VXLAN tunnel endpoints)`. + +VXLAN is an evolution of efforts to standardize an overlay encapsulation +protocol. It increases the 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 `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. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="vxlan" var1="vxlan0"> + +/\_include/interface-common-without-dhcp.txt + +</div> + +### VXLAN specific options + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> vni \<number\> + +Each VXLAN segment is identified through a 24-bit segment ID, termed the +`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows +up to 16M VXLAN segments to coexist within the same administrative domain. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> port \<port\> + +Configure port number of remote VXLAN endpoint. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> source-address \<IP address\> + +Source IP address used for VXLAN underlay. This is mandatory when using VXLAN +via L2VPN/EVPN. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> gpe + +Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only +supported together with the external keyword. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters external + +Specifies whether an external control plane (e.g. BGP L2VPN/EVPN) or the +internal FDB should be used. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters neighbor-suppress + +In order to minimize the flooding of ARP and ND messages in the VXLAN network, +EVPN includes provisions `7432#section-10` that allow participating VTEPs +to suppress such messages in case they know the MAC-IP binding and can reply +on behalf of the remote host. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters nolearning + +Specifies if unknown source link layer addresses and IP addresses are entered +into the VXLAN device forwarding database. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters vni-filter + +Specifies whether the VXLAN device is capable of vni filtering. + +Only works with a VXLAN device with external flag set. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The device can only receive packets with VNIs configured in +the VNI filtering table. + +</div> + +</div> + +#### Unicast + +<div class="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. + +</div> + +#### Multicast + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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 leaves 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 leaves 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 leaves are +added. + +For optimal scalability, Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leaves. Unfortunately, VyOS does not yet +support this. + +## Single VXLAN device (SVD) + +FRR supports a new way of configuring VLAN-to-VNI mappings for EVPN-VXLAN, when +working with the Linux kernel. In this new way, the mapping of a VLAN to a +`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured +against a container VXLAN interface which is referred to as a +`SVD (Single VXLAN device)`. + +Multiple VLAN to VNI mappings can be configured against the same SVD. This +allows for a significant scaling of the number of VNIs since a separate VXLAN +interface is no longer required for each VNI. + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> vlan-to-vni \<vlan\> vni \<vni\> + +Maps the VNI to the specified VLAN id. The VLAN can then be consumed by +a bridge. + +Sample configuration of SVD with VLAN to VNI mappings is shown below. + +``` none +set interfaces bridge br0 member interface vxlan0 +set interfaces vxlan vxlan0 parameters external +set interfaces vxlan vxlan0 source-interface 'dum0' +set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' +set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' +set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' +set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' +``` + +</div> + +### 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: + +``` 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:** + +``` 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 leaves to forward traffic between each +other in a more scalable way. This also requires PIM to be enabled towards the +leaves so that the Spine can learn what multicast groups each Leaf expects +traffic from. + +**Leaf2 configuration:** + +``` 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:** + +``` 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: + +``` 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. + +``` 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. + +``` none +set interfaces vxlan vxlan241 group '239.0.0.241' +``` + +The multicast-group used by all leaves for this vlan extension. Has to be the +same on all leaves that has this interface. + +``` none +set interfaces vxlan vxlan241 source-interface 'eth0' +``` + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +``` none +set interfaces vxlan vxlan241 vni '241' +``` + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +``` none +set interfaces vxlan vxlan241 port 12345 +``` + +The destination port used for creating a VXLAN interface defaults to +4789. Aconfiguration 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: + +``` 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 4789. +It can be changed with `set interface vxlan <vxlanN> port <port>` diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md new file mode 100644 index 00000000..4e2689f5 --- /dev/null +++ b/docs/configuration/interfaces/md-wireguard.md @@ -0,0 +1,480 @@ +lastproofread +2023-01-26 + +# 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. + +## Site to Site VPN + +This diagram corresponds with the example site to site configuration below. + +<figure> +<img src="/_static/images/wireguard_site2site_diagram.webp" /> +</figure> + +## Keypairs + +WireGuard requires the generation of a keypair, which includes a private key to +decrypt incoming traffic, and a public key for peer(s) to encrypt traffic. + +### Generate Keypair + +<div class="opcmd"> + +generate pki wireguard key-pair + +It generates the keypair, which includes the public and private parts. +The key is not stored on the system - only a keypair is generated. + +``` none +vyos@vyos:~$ generate pki wireguard key-pair +Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= +Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +</div> + +<div class="opcmd"> + +generate pki wireguard key-pair install interface \<interface\> + +Generates a keypair, which includes the public and private parts, and build +a configuration command to install this key to `interface`. + +``` none +vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from operational level. +Generated private-key is not stored to CLI, use configure mode commands to install key: + +set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' + +Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If this command is invoked from configure mode with the `run` +prefix the key is automatically installed to the appropriate interface: + +``` none +vyos@vyos# run generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from config session. +Generated private-key was imported to CLI! + +Use the following command to verify: show interfaces wireguard wg10 +Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' + +vyos@vyos# compare +[edit interfaces] ++wireguard wg10 { ++ private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= ++} +``` + +</div> + +</div> + +<div class="opcmd"> + +show interfaces wireguard \<interface\> public-key + +Retrieve public key portion from configured WIreGuard interface. + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 public-key +EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +</div> + +#### Optional + +<div class="opcmd"> + +generate pki wireguard preshared-key + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto. + +This is optional. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= +``` + +</div> + +<div class="opcmd"> + +generate pki wireguard preshared-key install interface \<interface\> peer \<peer\> + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto. This command automatically creates for you the required +CLI command to install this PSK for a given peer. + +This is optional. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo +"generate" CLI command executed from operational level. +Generated preshared-key is not stored to CLI, use configure mode commands to install key: + +set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' + +Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If this command is invoked from configure mode with the `run` +prefix the key is automatically installed to the appropriate interface: + +</div> + +</div> + +## 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; however, if you act like a server and +endpoints initiate the connections to your system, you need to define a port +your clients can connect to, otherwise the port is randomly chosen and may +make connection difficult with firewall rules, since the port may be different +each time the system is rebooted. + +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 - commands** + +- WireGuard interface itself uses address 10.1.0.1/30 +- We only allow the 192.168.2.0/24 subnet to travel over the tunnel +- Our remote end of the tunnel for peer <span class="title-ref">to-wg02</span> is reachable at 192.0.2.1 + port 51820 +- The remote peer <span class="title-ref">to-wg02</span> uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI= + as its public key portion +- We listen on port 51820 +- We route all traffic for the 192.168.2.0/24 network to interface <span class="title-ref">wg01</span> + +``` none +set interfaces wireguard wg01 address '10.1.0.1/30' +set interfaces wireguard wg01 description 'VPN-to-wg02' +set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' +set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' +set interfaces wireguard wg01 peer to-wg02 port '51820' +set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' +set interfaces wireguard wg01 port '51820' + +set protocols static route 192.168.2.0/24 interface wg01 +``` + +The last step is to define an interface route for 192.168.2.0/24 to get through +the WireGuard interface <span class="title-ref">wg01</span>. Multiple IPs or networks can be defined and +routed. The last check is allowed-ips which either prevents or allows the +traffic. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +You can not assign the same allowed-ips statement to multiple +WireGuard peers. This a design decision. For more information please +check the [WireGuard mailing list](https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html). + +</div> + +<div class="cfgcmd"> + +set interfaces wireguard \<interface\> private-key \<private-key\> + +Associates the previously generated private key to a specific WireGuard +interface. The private key can be generate via the command + +`generate pki wireguard key-pair`. + +``` none +set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' +``` + +The command `show interfaces wireguard wg01 public-key` will then show the +public key, which needs to be shared with the peer. + +</div> + +<div class="cmdinclude" var0="wireguard" var1="wg01"> + +/\_include/interface-per-client-thread.txt + +</div> + +**remote side - commands** + +``` none +set interfaces wireguard wg01 address '10.1.0.2/30' +set interfaces wireguard wg01 description 'VPN-to-wg01' +set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' +set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' +set interfaces wireguard wg01 peer to-wg01 port '51820' +set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' +set interfaces wireguard wg01 port '51820' +set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' + +set protocols static route 192.168.1.0/24 interface wg01 +``` + +## Firewall Exceptions + +For the WireGuard traffic to pass through the WAN interface, you must create a +firewall exception. + +``` none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp +``` + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and in an input (local) direction. + +``` none +set firewall ipv4 input filter rule 10 action jump +set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' +``` + +Assure that your firewall rules allow the traffic, in which case you have a +working VPN using WireGuard. + +``` none +wg01# ping 192.168.1.1 +PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. +64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms +64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms + +wg02# ping 192.168.2.1 +PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. +64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms +64 bytes from 192.168.2.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. This is optional. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= +``` + +Copy the key, as it is not stored on the local filesystem. Because it +is a symmetric key, only you and your peer should have knowledge of +its content. Make sure you distribute the key in a safe manner, + +``` 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=' +``` + +## Remote Access "RoadWarrior" 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 allows the peers to interact with one another. In +comparison to the site-to-site example the `persistent-keepalive` +flag is set to 15 seconds to assure the connection is kept alive. +This is mainly relevant if one of the peers is behind NAT and can't +be connected to if the connection is lost. To be effective this +value needs to be lower than the UDP timeout. + +``` none +wireguard wg01 { + 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 + public-key F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:db8:470:22::20/128 + persistent-keepalive 15 + public-key BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= +} +``` + +The following is the config for the iPhone peer above. It's important to +note that the `AllowedIPs` wildcard setting directs all IPv4 and IPv6 traffic +through the connection. + +``` 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 +``` + +However, split-tunneling can be achieved by specifying the remote subnets. +This ensures that only traffic destined for the remote site is sent over the +tunnel. All other traffic is unaffected. + +``` 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 + +### Status + +<div class="opcmd"> + +show interfaces wireguard wg01 summary + +Show info about the Wireguard service. +It also shows the latest handshake. + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 summary +interface: wg01 + public key: + private key: (hidden) + listening port: 51820 + +peer: <peer public-key> + endpoint: <peer public IP> + allowed ips: 10.69.69.2/32 + latest handshake: 23 hours, 45 minutes, 26 seconds ago + transfer: 1.26 MiB received, 6.47 MiB sent +``` + +</div> + +<div class="opcmd"> + +show interfaces wireguard + +Get a list of all wireguard interfaces + +``` none +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wg01 10.0.0.1/24 u/u +``` + +</div> + +<div class="opcmd"> + +show interfaces wireguard \<interface\> + +Show general information about specific WireGuard interface + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 +interface: wg01 + address: 10.0.0.1/24 + public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= + private key: (hidden) + listening port: 41751 + + 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 +``` + +</div> + +## Remote Access "RoadWarrior" clients + +Some users tend to connect their mobile devices using WireGuard to their VyOS +router. To ease deployment one can generate a "per mobile" configuration from +the VyOS CLI. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +From a security perspective, it is not recommended to let a third +party create and share the private key for a secured connection. +You should create the private portion on your own and only hand out the +public key. Please keep this in mind when using this convenience feature. + +</div> + +<div class="opcmd"> + +generate wireguard client-config \<name\> interface \<interface\> server +\<ip|fqdn\> address \<client-ip\> + +Using this command, you will create a new client configuration which can +connect to `interface` on this router. The public key from the specified +interface is automatically extracted and embedded into the configuration. + +The command also generates a configuration snipped which can be copy/pasted +into the VyOS CLI if needed. The supplied `<name>` on the CLI will become +the peer name in the snippet. + +In addition you will specifiy the IP address or FQDN for the client where it +will connect to. The address parameter can be used up to two times and is used +to assign the clients specific IPv4 (/32) or IPv6 (/128) address. + +<figure> +<img src="/_static/images/wireguard_qrcode.webp" alt="WireGuard Client QR code" /> +</figure> + +</div> diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md new file mode 100644 index 00000000..4a09b78b --- /dev/null +++ b/docs/configuration/interfaces/md-wireless.md @@ -0,0 +1,823 @@ +lastproofread +2023-01-26 + +# WLAN/WIFI - Wireless LAN + +`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: + +- `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 + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Wireless options + +<div class="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 + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This option is mandatory in Access-Point mode. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> mgmt-frame-protection + +Management Frame Protection (MFP) according to IEEE 802.11w + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> physical-device \<device\> + +Wireless hardware device used as underlay radio. + +This defaults to phy0. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> ssid \<ssid\> + +SSID to be used in IEEE 802.11 management frames + +</div> + +<div class="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 + +</div> + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-per-client-thread.txt + +</div> + +#### PPDU + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities require-ht + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities require-hvt + +</div> + +##### HT (High Throughput) capabilities (802.11n) + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht 40mhz-incapable + +Device is incapable of 40 MHz, do not advertise. This sets `[40-INTOLERANT]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht auto-powersave + +WMM-PS Unscheduled Automatic Power Save Delivery \[U-APSD\] + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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! + +``` 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 +``` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +delayed-block-ack + +Enable HT-delayed Block Ack `[DELAYED-BA]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht dsss-cck-40 + +DSSS/CCK Mode in 40 MHz, this sets `[DSSS_CCK-40]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht greenfield + +This enables the greenfield option which sets the `[GF]` option + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht ldpc + +Enable LDPC coding capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht lsig-protection + +Enable L-SIG TXOP protection capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht max-amsdu +\<3839 | 7935\> + +Maximum A-MSDU length 3839 (default) or 7935 octets + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +short-gi \<20 | 40\> + +Short GI capabilities for 20 and 40 MHz + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +smps \<static | dynamic\> + +Spatial Multiplexing Power Save (SMPS) settings + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) + +</div> + +##### VHT (Very High Throughput) capabilities (802.11ac) + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht antenna-count + +Number of antennas on this card + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +antenna-pattern-fixed + +Set if antenna pattern does not change during the lifetime of an association + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht ldpc + +Enable LDPC (Low Density Parity Check) coding capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht link-adaptation + +VHT link adaptation capabilities + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +max-mpdu \<value\> + +Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +short-gi \<80 | 160\> + +Short GI capabilities + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht tx-powersave + +Enable VHT TXOP Power Save Mode + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht vht-cf + +Station supports receiving VHT variant HT Control field + +</div> + +### 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. + +``` none +set interfaces wireless wlan0 type station +set interfaces wireless wlan0 address dhcp +set interfaces wireless wlan0 country-code de +set interfaces wireless wlan0 ssid Test +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting in + +``` none +interfaces { + [...] + wireless wlan0 { + address dhcp + country-code de + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } +``` + +### Security + +`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 `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` + +``` none +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 country-code de +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 + +``` none +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + country-code de + 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 + } +} +``` + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces wireless info + +</div> + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +``` none +vyos@vyos:~$ show interfaces wireless info +Interface Type SSID Channel +wlan0 access-point VyOS-TEST-0 1 +``` + +<div class="opcmd"> + +show interfaces wireless detail + +</div> + +Use this command to view operational status and details wireless-specific +information about all wireless interfaces. + +``` 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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> + +</div> + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +``` 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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> brief + +</div> + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +``` 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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> queue + +</div> + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +``` 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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> scan + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Scanning is not supported on all wireless drivers and wireless +hardware. Refer to your driver and wireless hardware documentation for +further details. + +</div> + +``` 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 `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` + +``` 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' +set interfaces wireless wlan0 country-code de +``` + +Resulting in + +``` none +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + country-code de + 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 an 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 +(`bridge-interface`) on the system. + +### Intel AX200 + +The Intel AX200 card does not work out of the box in AP mode, see +<https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode>. You can +still put this card into AP mode using the following configuration: + +``` none +set interfaces wireless wlan0 channel '1' +set interfaces wireless wlan0 country-code 'us' +set interfaces wireless wlan0 mode 'n' +set interfaces wireless wlan0 physical-device 'phy0' +set interfaces wireless wlan0 ssid 'VyOS' +set interfaces wireless wlan0 type 'access-point' +``` diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md new file mode 100644 index 00000000..2475e809 --- /dev/null +++ b/docs/configuration/interfaces/md-wwan.md @@ -0,0 +1,390 @@ +lastproofread +2023-01-27 + +# WWAN - Wireless Wide-Area-Network + +The Wireless Wide-Area-Network interface provides access (through a wireless +modem/wwan) to wireless networks provided by various cellular providers. + +VyOS uses the <span class="title-ref">interfaces wwan</span> subsystem for configuration. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-address-with-dhcp.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-disable-link-detect.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-ip.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-ipv6.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-vrf.txt + +</div> + +**DHCP(v6)** + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcp-options.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcpv6-options.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcpv6-prefix-delegation.txt + +</div> + +### WirelessModem (WWAN) options + +<div class="cfgcmd"> + +set interfaces wwan \<interface\> apn \<apn\> + +Every WWAN connection requires an `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. + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces wwan \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 +wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 + link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff + inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 + valid_lft 7012sec preferred_lft 7012sec + inet6 fe80::c2:f3ff:fe00:0102/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 640 2 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 3229 16 0 0 0 0 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> summary + +Show detailed information summary on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 summary + -------------------------------- + General | dbus path: /org/freedesktop/ModemManager1/Modem/0 + | device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d + -------------------------------- + Hardware | manufacturer: Sierra Wireless, Incorporated + | model: MC7710 + | revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 + | h/w revision: 1.0 + | supported: gsm-umts, lte + | current: gsm-umts, lte + | equipment id: 358xxxxxxxxxxxx + -------------------------------- + System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 + | drivers: qcserial, qmi_wwan + | plugin: Generic + | primary port: cdc-wdm0 + | ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) + -------------------------------- + Numbers | own: 4917xxxxxxxx + -------------------------------- + Status | lock: sim-pin2 + | unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) + | state: connected + | power state: on + | access tech: lte + | signal quality: 63% (recent) + -------------------------------- + Modes | supported: allowed: 2g; preferred: none + | allowed: 3g; preferred: none + | allowed: 4g; preferred: none + | allowed: 2g, 3g; preferred: 3g + | allowed: 2g, 3g; preferred: 2g + | allowed: 2g, 4g; preferred: 4g + | allowed: 2g, 4g; preferred: 2g + | allowed: 3g, 4g; preferred: 3g + | allowed: 3g, 4g; preferred: 4g + | allowed: 2g, 3g, 4g; preferred: 4g + | allowed: 2g, 3g, 4g; preferred: 3g + | allowed: 2g, 3g, 4g; preferred: 2g + | current: allowed: 2g, 3g, 4g; preferred: 2g + -------------------------------- + Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, + | eutran-7, eutran-8, eutran-20 + | current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, + | eutran-7, eutran-8, eutran-20 + -------------------------------- + IP | supported: ipv4, ipv6, ipv4v6 + -------------------------------- + 3GPP | imei: 358xxxxxxxxxxxx + | operator id: 26201 + | operator name: Telekom.de + | registration: home + -------------------------------- + 3GPP EPS | ue mode of operation: ps-1 + -------------------------------- + SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 + -------------------------------- + Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> capabilities + +Show WWAN module hardware capabilities. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 capabilities +Max TX channel rate: '50000000' +Max RX channel rate: '100000000' +Data Service: 'simultaneous-cs-ps' +SIM: 'supported' +Networks: 'gsm, umts, lte' +Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' +LTE bands: '1, 3, 7, 8, 20' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> firmware + +Show WWAN module firmware. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 firmware +Model: MC7710 +Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 +AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 +SKU ID: unknown +Package ID: unknown +Carrier ID: 0 +Config version: unknown +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> imei + +Show WWAN module IMEI. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 imei +ESN: '0' +IMEI: '358xxxxxxxxxxxx' +MEID: 'unknown' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> imsi + +Show WWAN module IMSI. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 imsi +IMSI: '262xxxxxxxxxxxx' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> model + +Show WWAN module model. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 model +Model: 'MC7710' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> msisdn + +Show WWAN module MSISDN. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 msisdn +MSISDN: '4917xxxxxxxx' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> revision + +Show WWAN module hardware revision. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 revision +Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> signal + +Show WWAN module signal strength. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 signal +LTE: +RSSI: '-74 dBm' +RSRQ: '-7 dB' +RSRP: '-100 dBm' +SNR: '13.0 dB' +Radio Interface: 'lte' +Active Band Class: 'eutran-3' +Active Channel: '1300' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> sim + +Show WWAN module SIM card information. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 sim +Provisioning applications: +Primary GW: slot '1', application '1' +Primary 1X: session doesn't exist +Secondary GW: session doesn't exist +Secondary 1X: session doesn't exist +Slot [1]: +Card state: 'present' +UPIN state: 'not-initialized' +UPIN retries: '0' +UPUK retries: '0' +Application [1]: +Application type: 'usim (2)' +Application state: 'ready' +Application ID: +A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 +Personalization state: 'ready' +UPIN replaces PIN1: 'no' +PIN1 state: 'disabled' +PIN1 retries: '3' +PUK1 retries: '10' +PIN2 state: 'enabled-not-verified' +PIN2 retries: '3' +PUK2 retries: '10' +``` + +</div> + +## 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 `pc-engines-apu4`. + +``` none +set interfaces wwan wwan0 apn 'internet.telekom' +set interfaces wwan wwan0 address 'dhcp' +``` + +## Supported Modules + +The following hardware modules have been tested successfully in an +`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) +- HP LT4120 Snapdragon X5 LTE + +## Firmware Update + +All available WWAN cards have a build in, reprogrammable firmware. Most of the +vendors provide a regular update to the firmware used in the baseband chip. + +As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also +the firmware can be reprogrammed. + +To update the firmware, VyOS also ships the <span class="title-ref">qmi-firmware-update</span> binary. To +upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware +provided in the file `9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe` +use the following command: + +``` bash +$ sudo qmi-firmware-update --update -d 1199:68a2 \ + 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe +``` |