diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 14:41:08 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 12:41:08 +0100 |
| commit | 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e (patch) | |
| tree | 8d97f7766d9bbd2d0e3a55e5643a60b387308675 /docs/configuration/interfaces | |
| parent | c21b38dbe24088eaca73dbc8030cfebc898d2186 (diff) | |
| download | vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.tar.gz vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.zip | |
Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)
* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism
Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta's (not current's).
Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
Sphinx builds, restore after; writes _build/_swap_state.json and
_build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
loader; _prefer_webp builder hook so html prefers webp over png
Content:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
(already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
default, revert a page by removing its stem from _swap.txt
🤖 Generated by [robots](https://vyos.io)
* feat(conf): copy .md sources into HTML output for plain-text serving
Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.
🤖 Generated by [robots](https://vyos.io)
* docs: address review feedback (backport from PR #1857)
Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.
🤖 Generated by [robots](https://vyos.io)
* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857
Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.
- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
scripts/swap_sources.py --swap before the Sphinx build and --restore
after. Without this, the swap mechanism ships but never runs on RTD
builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
when self.state._renderer is not present. Required for cfgcmd /
opcmd / cmdincludemd directives to render correctly when included
from MyST pages (the swap mechanism's whole point). Sagitta-only
delta on _ext/vyos.py (the path = str(path) line on 224) is
intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
swap scripts. The scripts on this branch are byte-identical to
current's, so the same tests apply. Travels with the branch so CI
catches per-branch regressions if the scripts ever drift.
🤖 Generated by [robots](https://vyos.io)
* fix(conf): skip md-*.md staging files in _copy_md_sources
Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
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 +``` |