1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
|
: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
==============================
.. cmdinclude:: /_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:
.. code-block:: 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:
.. code-block:: 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
-----------------------------
.. cmdinclude:: /_include/interface-eapol.txt
:var0: ethernet
:var1: eth0
EVPN Multihoming
----------------
Uplink/core tracking.
.. cmdinclude:: /_include/interface-evpn-uplink.txt
:var0: ethernet
:var1: eth0
VLAN
====
Regular VLANs (802.1q)
----------------------
.. cmdinclude:: /_include/interface-vlan-8021q.txt
:var0: ethernet
:var1: eth0
802.1ad (QinQ)
--------------
.. cmdinclude:: /_include/interface-vlan-8021ad.txt
:var0: ethernet
:var1: eth0
SPAN port mirroring
===================
.. cmdinclude:: ../../_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
.. stop_vyoslinter
.. 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
.. start_vyoslinter
.. 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
|
