mirror of
https://github.com/kernelkit/infix.git
synced 2026-07-22 01:13:00 +02:00
Joachim Wiberg
4c17a79de6
Update CLI samples across the documentation to the new layered presentation: physical-medium row when linked (1000baseT/...), bare MACs, and key: value DATA tokens. Add a short prose block in ethernet.md and iface.md explaining the layering. Drop the historical 'show interfaces' (plural) form — removed from klish years ago — from all user-facing examples and the landing page. Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
262 lines
9.2 KiB
Markdown
262 lines
9.2 KiB
Markdown
# Ethernet Interfaces
|
|
|
|
This document covers VLAN interfaces, physical Ethernet interfaces,
|
|
and virtual Ethernet (VETH) pairs.
|
|
|
|
|
|
## VLAN Interfaces
|
|
|
|
Creating a VLAN can be done in many ways. This section assumes VLAN
|
|
interfaces created atop another Linux interface. E.g., the VLAN
|
|
interfaces created on top of the Ethernet interface or bridge in the
|
|
picture below.
|
|
|
|
|
|
|
|
A VLAN interface is basically a filtering abstraction. When you run
|
|
`tcpdump` on a VLAN interface you will only see the frames matching the
|
|
VLAN ID of the interface, compared to *all* the VLAN IDs if you run
|
|
`tcpdump` on the lower-layer interface.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>configure</b>
|
|
admin@example:/config/> <b>edit interface eth0.20</b>
|
|
admin@example:/config/interface/eth0.20/> <b>show</b>
|
|
type vlan;
|
|
vlan {
|
|
tag-type c-vlan;
|
|
id 20;
|
|
lower-layer-if eth0;
|
|
}
|
|
admin@example:/config/interface/eth0.20/> <b>leave</b>
|
|
</code></pre>
|
|
|
|
The example below assumes bridge br0 is already created, see [VLAN
|
|
Filtering Bridge](bridging.md#vlan-filtering-bridge).
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>configure</b>
|
|
admin@example:/config/> <b>edit interface vlan10</b>
|
|
admin@example:/config/interface/vlan10/> <b>set vlan id 10</b>
|
|
admin@example:/config/interface/vlan10/> <b>set vlan lower-layer-if br0</b>
|
|
admin@example:/config/interface/vlan10/> <b>leave</b>
|
|
</code></pre>
|
|
|
|
As conventions, a VLAN interface for VID 20 on top of an Ethernet
|
|
interface *eth0* is named *eth0.20*, and a VLAN interface for VID 10 on
|
|
top of a bridge interface *br0* is named *vlan10*.
|
|
|
|
> [!NOTE]
|
|
> If you name your VLAN interface `foo0.N` or `vlanN`, where `N` is a
|
|
> number, the CLI infers the interface type automatically.
|
|
|
|
|
|
## Physical Ethernet Interfaces
|
|
|
|
### Ethernet Settings and Status
|
|
|
|
Physical Ethernet interfaces provide low-level settings for speed/duplex as
|
|
well as packet status and [statistics](#ethernet-statistics).
|
|
|
|
By default, Ethernet interfaces defaults to auto-negotiating speed/duplex
|
|
modes, advertising all speed and duplex modes available. In the example
|
|
below, the switch would by default auto-negotiate speed 1 Gbps on port eth1
|
|
and 100 Mbps on port eth4, as those are the highest speeds supported by H1 and
|
|
H2 respectively.
|
|
|
|
|
|
|
|
A quick at-a-glance view of the physical link is available in the summary
|
|
listing. When a port is up, a physical-layer row appears above the ethernet
|
|
row, naming the IEEE PMD type (e.g. `1000baseT`, `10GbaseLR`) in the PROTOCOL
|
|
column and the negotiated duplex in DATA. When the link is down the row is
|
|
omitted and the interface name falls onto the ethernet row.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>show interface</b>
|
|
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
|
|
eth1 1000baseT UP duplex: full
|
|
ethernet 00:53:00:06:11:01
|
|
eth2 1000baseT UP duplex: full
|
|
ethernet 00:53:00:06:11:02
|
|
eth3 ethernet DOWN 00:53:00:06:11:03
|
|
eth4 100baseTX UP duplex: full
|
|
ethernet 00:53:00:06:11:04
|
|
...
|
|
</code></pre>
|
|
|
|
The detail view spells everything out, including auto-negotiation
|
|
state and the speed in Mbit/s.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>show interface eth1</b>
|
|
name : eth1
|
|
index : 2
|
|
mtu : 1500
|
|
operational status : up
|
|
link mode : 1000baseT
|
|
auto-negotiation : on
|
|
duplex : full
|
|
speed : 1000
|
|
physical address : 00:53:00:06:11:01
|
|
ipv4 addresses :
|
|
ipv6 addresses :
|
|
in-octets : 75581
|
|
out-octets : 43130
|
|
...
|
|
admin@example:/> <b>show interface eth4</b>
|
|
name : eth4
|
|
index : 5
|
|
mtu : 1500
|
|
operational status : up
|
|
link mode : 100baseTX
|
|
auto-negotiation : on
|
|
duplex : full
|
|
speed : 100
|
|
physical address : 00:53:00:06:11:04
|
|
ipv4 addresses :
|
|
ipv6 addresses :
|
|
in-octets : 75439
|
|
out-octets : 550704
|
|
...
|
|
admin@example:/>
|
|
</code></pre>
|
|
|
|
### Restricting advertised link modes
|
|
|
|
Auto-negotiation of speed/duplex is the desired default for almost all
|
|
use-cases, but sometimes a port must come up at a specific speed —
|
|
typically when interoperating with legacy hardware that does not
|
|
auto-negotiate, or that does so poorly. IEEE Std 802.3.2-2025 retired
|
|
the older *disable auto-negotiation, then set fixed speed/duplex*
|
|
idiom; the standards-correct way to express the same intent is to
|
|
**restrict the set of PMD types auto-negotiation may advertise**.
|
|
When only one PMD is advertised, the link pins to that mode against
|
|
any cooperating peer.
|
|
|
|
Each entry in `auto-negotiation/advertised-pmd-types` is an IEEE
|
|
PMD-type identity (`ieee802-ethernet-phy-type:pmd-type-*`). Half- vs
|
|
full-duplex pinning is expressed by the orthogonal `duplex` leaf.
|
|
|
|
The example below pins port `eth3` to 100 Mbit/s half-duplex.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>configure</b>
|
|
admin@example:/config/> <b>edit interface eth3 ethernet</b>
|
|
admin@example:/config/interface/eth3/ethernet/> <b>set auto-negotiation advertised-pmd-types pmd-type-100BASE-TX</b>
|
|
admin@example:/config/interface/eth3/ethernet/> <b>set duplex half</b>
|
|
admin@example:/config/interface/eth3/ethernet/> <b>show</b>
|
|
auto-negotiation {
|
|
advertised-pmd-types [ ieee802-ethernet-phy-type:pmd-type-100BASE-TX ];
|
|
}
|
|
duplex half;
|
|
admin@example:/config/interface/eth3/ethernet/> <b>leave</b>
|
|
admin@example:/>
|
|
</code></pre>
|
|
|
|
Listing multiple PMD identities advertises that set; the peer's
|
|
auto-negotiation picks the highest mutually-supported mode.
|
|
|
|
> [!IMPORTANT]
|
|
> When pinning to a specific link mode, ensure both sides of the link
|
|
> agree on at least one common (PMD, duplex) combination. If they
|
|
> don't, the link will not come up.
|
|
|
|
> [!NOTE]
|
|
> Earlier Infix releases used `auto-negotiation/enable=false` with
|
|
> `speed` and `duplex` leaves to express the same thing. That syntax
|
|
> is retired together with the IEEE obsoletion of `eth:speed`; existing
|
|
> `startup-config.cfg` snippets are automatically migrated to the new
|
|
> shape on upgrade.
|
|
|
|
The detail view exposes a `supported` block (operational state,
|
|
backed by the `supported-pmd-types` leaf-list) listing the PMD types
|
|
the kernel currently believes the interface can operate at. For
|
|
SFP/SFP+ cages this set reflects the inserted module: plug in a 10G
|
|
LR optic and `supported` will narrow to `10GbaseLR` only. Combined
|
|
with the operational `link mode` row above it, this makes it trivial
|
|
to confirm what an unknown transceiver actually is — no `ethtool -m`
|
|
round-trip needed.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>show interface eth13</b>
|
|
name : eth13
|
|
type : ethernet
|
|
operational status : up
|
|
link mode : 10GbaseLR
|
|
auto-negotiation : off
|
|
supported : 10GbaseLR
|
|
duplex : full
|
|
speed : 10000
|
|
...
|
|
</code></pre>
|
|
|
|
### Ethernet statistics
|
|
|
|
Ethernet packet statistics[^1] can be listed as shown below.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>show interface eth1</b>
|
|
name : eth1
|
|
index : 2
|
|
mtu : 1500
|
|
operational status : up
|
|
link mode : 1000baseT
|
|
auto-negotiation : on
|
|
duplex : full
|
|
speed : 1000
|
|
physical address : 00:53:00:06:11:0a
|
|
ipv4 addresses :
|
|
ipv6 addresses :
|
|
in-octets : 75581
|
|
out-octets : 43130
|
|
|
|
eth-in-frames : 434
|
|
eth-in-multicast-frames : 296
|
|
eth-in-broadcast-frames : 138
|
|
eth-in-error-fcs-frames : 0
|
|
eth-in-error-oversize-frames : 0
|
|
eth-out-frames : 310
|
|
eth-out-multicast-frames : 310
|
|
eth-out-broadcast-frames : 0
|
|
eth-out-good-octets : 76821
|
|
eth-in-good-octets : 60598
|
|
admin@example:/>
|
|
</code></pre>
|
|
|
|
|
|
## VETH Pairs
|
|
|
|
A Virtual Ethernet (VETH) pair is basically a virtual Ethernet cable. A
|
|
cable can be "plugged in" to a bridge and the other end can be given to
|
|
a [container](container.md), or plugged into another bridge.
|
|
|
|
The latter example is useful if you have multiple bridges in the system
|
|
with different properties (VLAN filtering, IEEE group forwarding, etc.),
|
|
but still want some way of communicating between these domains.
|
|
|
|
<pre class="cli"><code>admin@example:/> <b>configure</b>
|
|
admin@example:/config/> <b>edit interface veth0a</b>
|
|
admin@example:/config/interface/veth0a/> <b>set veth peer veth0b</b>
|
|
admin@example:/config/interface/veth0a/> <b>end</b>
|
|
admin@example:/config/> <b>diff</b>
|
|
interfaces {
|
|
+ interface veth0a {
|
|
+ type veth;
|
|
+ veth {
|
|
+ peer veth0b;
|
|
+ }
|
|
+ }
|
|
+ interface veth0b {
|
|
+ type veth;
|
|
+ veth {
|
|
+ peer veth0a;
|
|
+ }
|
|
+ }
|
|
}
|
|
admin@example:/config/>
|
|
</code></pre>
|
|
|
|
> [!TIP]
|
|
> This is another example of the automatic inference of the interface
|
|
> type from the name. Any name can be used, but then you have to set
|
|
> the interface type to `veth` manually.
|
|
|
|
[^1]: Ethernet counters are described in *ieee802-ethernet-interface.yang*
|
|
and *infix-ethernet-interface.yang*. There is a dedicated document on
|
|
[Ethernet Counters](eth-counters.md) that provide additional details
|
|
on the statistics support.
|