diff options
Diffstat (limited to 'docs/configuration/interfaces/ethernet.md')
| -rw-r--r-- | docs/configuration/interfaces/ethernet.md | 515 |
1 files changed, 515 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/ethernet.md b/docs/configuration/interfaces/ethernet.md new file mode 100644 index 00000000..eac0b443 --- /dev/null +++ b/docs/configuration/interfaces/ethernet.md @@ -0,0 +1,515 @@ +--- +lastproofread: '2026-01-19' +--- + +(ethernet-interface)= + +# Ethernet + +Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical +or virtual network ports. + +They are the most common interface type, serving as the base layer upon which +IP addresses, VLANs, and tunnels are configured to carry traffic across both +LANs and WANs. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: ethernet +:var1: eth0 +``` + +```{cfgcmd} set interfaces ethernet \<interface\> switchdev + +**Enable** ``switchdev`` **mode for the interface.** + +In ``switchdev`` mode, the interface offloads traffic switching between ports +to the hardware, bypassing the host CPU. This increases the interface’s +traffic-handling capacity and reduces its forwarding delay. +``` + +:::{note} +`switchdev` mode is available only on certain physical network +interfaces and requires a switchdev-compatible driver. +::: + +### Ethernet options + +```{cfgcmd} set interfaces ethernet \<interface\> duplex \<auto | full | half\> + +**Configure duplex mode for the interface.** + +The following duplex modes are available: + +* ``auto``: The interface negotiates the duplex mode with the connected device. +* ``full``: The interface sends and receives data simultaneously. The + connected device must also be set to full-duplex to avoid a duplex mismatch. +* ``half``: The interface either sends or receives data, but not both at the + same time. + +The default duplex mode is ``auto``. +``` + +```{cfgcmd} set interfaces ethernet \<interface\> speed \<auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000\> + +**Configure the interface's speed, in Mbit/s.** + +The following options are available: + +* ``auto``: The interface negotiates the speed with the connected device. +* ``10, 100, 1000 ...``: The interface operates at the selected speed. The + connected device must be set to the same speed to establish a connection. + +The default option is ``auto``. +``` + +```{cfgcmd} set interfaces ethernet \<interface\> ring-buffer rx \<value\> + +**Configure the receive (RX) ring buffer size for the interface.** + +The RX ring buffer size defines the number of incoming packets the interface +can queue in hardware before the CPU processes them. + +Higher values reduce the risk of drops when the NIC receives network traffic +faster than the CPU can process it, though latency may increase. Lower values +reduce latency but increase the risk of packet drops during incoming traffic +bursts. + +To view supported values for a specific interface, use: +``` + +```none +ethtool -g <interface> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> ring-buffer tx \<value\> + +**Configure the transmit (TX) ring buffer size.** + +The TX ring buffer size defines the number of outgoing packets the interface +can queue in hardware before they are transmitted onto the network. + +Higher values reduce the risk of drops when the CPU generates traffic faster +than the NIC can handle, though latency may increase. Lower values reduce +latency but increase the risk of packet drops during outgoing traffic bursts. + +To view supported values for a specific interface, use: +``` + +```none +ethtool -g <interface> +``` + + +#### Interrupt Coalescing + +Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling +multiple packets into a single interrupt event instead of interrupting +the CPU for every packet arrival or transmission. + +:::{note} +Not all network drivers or virtual interfaces support all +coalescing parameters. Use `ethtool --show-coalesce <interface>` +to verify which settings are supported by your hardware and driver. +::: + +**Basic adaptive coalescing** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing adaptive-rx + +``` +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing adaptive-tx + +Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX +interrupt pacing based on traffic patterns to reduce CPU utilization +during high throughput while preserving latency at low packet rates. +``` + +**Basic interrupt delay** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs \<0-16384\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs \<0-16384\> + +Set the delay in microseconds before generating an RX/TX interrupt after +receiving or transmitting a packet. Lower values reduce latency; higher +values reduce CPU load. +``` + +**Interrupt frame thresholds** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frames \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frames \<number\> + +Generate an RX/TX interrupt only after the specified number of packets +have been received or transmitted. +``` + +**IRQ-specific coalescing** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs-irq \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frames-irq \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs-irq \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frames-irq \<number\> + +Control interrupt coalescing parameters while the driver is already +servicing an interrupt (IRQ context). These settings allow finer tuning +of interrupt behavior under sustained load. +``` + +**Adaptive rate thresholds** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing pkt-rate-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing pkt-rate-high \<number\> + +Define packet-rate thresholds (packets per second) used by adaptive +coalescing to switch between low-rate and high-rate interrupt coalescing +profiles. +``` + +**Low-rate adaptive parameters** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frame-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frame-low \<number\> + +Interrupt coalescing parameters applied when the packet rate is below +``pkt-rate-low``. Typically optimized for lower latency. +``` + +**High-rate adaptive parameters** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs-high \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frame-high \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs-high \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frame-high \<number\> + +Interrupt coalescing parameters applied when the packet rate exceeds +``pkt-rate-high``. Typically optimized for maximum throughput and +reduced CPU utilization. +``` + +**Statistics and sampling** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing stats-block-usecs \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing sample-interval \<number\> + +Control how frequently coalescing statistics are updated and how often +the NIC samples traffic rates for adaptive coalescing decisions. +``` + +**Completion queue (CQE) mode** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing cqe-mode-rx +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing cqe-mode-tx + +Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the +driver. CQE mode can improve performance on high-speed NICs by +optimizing completion handling. +``` + +**Transmit aggregation** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-aggr-max-bytes \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-aggr-max-frames \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-aggr-time-usecs \<number\> + +Control transmit packet aggregation. Packets may be buffered and sent +together until one of the configured limits (bytes, frames, or time) +is reached, reducing interrupt and DMA overhead. +``` + +#### Offloading + +```{cfgcmd} set interfaces ethernet \<interface\> offload \<lro | tso | gso | gro | rps | sg\> + +**Configure the offloading features for the interface.** + +The interface offloading features define whether specific packet-processing tasks +are performed by hardware (the NIC) or by software (the kernel). You can enable +multiple offloading features for a single interface. + + * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple + incoming packets into one larger packet before sending it to the CPU. + + :::{note} + {abbr}`LRO (Large Receive Offload)` hardware support is often limited + to TCP/IPv4 packets. For details on LRO limitations, see + https://lwn.net/Articles/358910/ + ::: + :::{warning} + {abbr}`LRO (Large Receive Offload)` irreversibly alters packet + headers during merging. This prevents the merged packet from being correctly + split back into the original packets, causing packet drops and forwarding + failures on routers and bridges. Use {abbr}`LRO (Large Receive Offload)` only + for end-hosts that do not forward traffic. + ::: + * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP + packets into smaller ones before transmitting them to the network. + + **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled + for {abbr}`TSO (TCP Segmentation Offload)` to work. Additionally, {abbr}`GSO + (Generic Segmentation Offload)` should be enabled as a safety fallback; it + ensures that if traffic is rerouted to hardware without {abbr}`TSO (TCP + Segmentation Offload)` support, the kernel can still segment the packets, + preventing transmission failures. + + * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split + large packets into smaller ones before sending them to the NIC. + + {abbr}`GSO (Generic Segmentation Offload)` serves as a software fallback for + hardware that does not support {abbr}`TSO (TCP Segmentation Offload)` or for + protocols (like UDP) that hardware cannot offload. + + **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled + for {abbr}`GSO (Generic Segmentation Offload)` to work. + + * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple + incoming packets into one larger packet before passing it to upper protocol + layers. + + Unlike LRO, GRO preserves the necessary packet metadata so the merged packet + can be correctly split back into the original packets. This makes GRO safe for + use on routers and bridges. + + :::{note} +The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is +set and IDs are not sequential, {abbr}`GSO (Generic Segmentation Offload)` +alters them to maintain a consistent sequence for {abbr}`GSO (Generic +Segmentation Offload)` compatibility. + ::: + * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute + the processing of incoming packets across multiple CPU cores. + + The kernel calculates a hash from packet headers (IP addresses and ports) to + ensure packets from the same flow are processed by the same CPU core. + + :::{note} +{abbr}`RPS (Receive Packet Steering)` is a software version of +{abbr}`RSS (Receive Side Scaling)` and is useful for NICs without hardware +multi-queue support. + ::: + * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch + data fragments from various RAM locations and transmit them as a single packet + to the network, eliminating the need for the kernel to copy them into a + contiguous block first. +``` + +#### 802.1X (EAPOL) authentication + +```{cmdincludemd} /_include/interface-eapol.txt +:var0: ethernet +:var1: eth0 +``` + +#### EVPN Multihoming + +Uplink/core tracking. + +```{cmdincludemd} /_include/interface-evpn-uplink.txt +:var0: ethernet +:var1: eth0 +``` + +### VLAN +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: ethernet +:var1: eth0 +``` + +#### 802.1ad (QinQ) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: ethernet +:var1: eth0 +``` + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: ethernet +:var1: eth1 +:var2: eth3 +``` + +## Operation + +```{opcmd} show interfaces ethernet + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 172.18.201.10/24 u/u LAN +eth1 172.18.202.11/24 u/u WAN +eth2 - u/D +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 +eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> physical + +Show interface hardware-level and driver details. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 physical +Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes +driver: vmxnet3 +version: 1.4.16.0-k-NAPI +firmware-version: +expansion-rom-version: +bus-info: 0000:0b:00.0 +supports-statistics: yes +supports-test: no +supports-eeprom-access: no +supports-register-dump: yes +supports-priv-flags: no +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> physical offload + +Show the status of the interface offloading features. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 physical offload +rx-checksumming on +tx-checksumming on +tx-checksum-ip-generic on +scatter-gather off +tx-scatter-gather off +tcp-segmentation-offload off +tx-tcp-segmentation off +tx-tcp-mangleid-segmentation off +tx-tcp6-segmentation off +udp-fragmentation-offload off +generic-segmentation-offload off +generic-receive-offload off +large-receive-offload off +rx-vlan-offload on +tx-vlan-offload on +ntuple-filters off +receive-hashing on +tx-gre-segmentation on +tx-gre-csum-segmentation on +tx-udp_tnl-segmentation on +tx-udp_tnl-csum-segmentation on +tx-gso-partial on +tx-nocache-copy off +rx-all off +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> transceiver + +Show information about the transceiver module plugged into the interface +(e.g., SFP+, QSFP). + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx +::: +```
\ No newline at end of file |