Skip to content

Commit 32b7dfd

Browse files
troglobittroglobit
committed
doc: refresh show interface samples and rename plural form
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>
1 parent 11bad29 commit 32b7dfd

10 files changed

Lines changed: 177 additions & 149 deletions

File tree

‎doc/cli/introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ interfaces {
164164
}
165165
}
166166
admin@host-12-34-56:/config/interface/eth0/> leave
167-
admin@host-12-34-56:/> show interfaces
167+
admin@host-12-34-56:/> show interface
168168
INTERFACE PROTOCOL STATE DATA
169169
lo loopback UNKNOWN 00:00:00:00:00:00
170170
ipv4 127.0.0.1/8 (static)

‎doc/dhcp.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -109,11 +109,11 @@ When configuring, e.g., `dns-server`, or `router` options with the value
109109
`auto`, the system uses the IP address from the interface matching the
110110
subnet. For example:
111111

112-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
113-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
114-
eth0 ethernet UP 02:00:00:00:00:00
112+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
113+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
114+
eth0 ethernet UP 02:00:00:00:00:00
115115
ipv4 192.168.1.1/24 (static)
116-
eth1 ethernet UP 02:00:00:00:00:01
116+
eth1 ethernet UP 02:00:00:00:00:01
117117
ipv4 192.168.2.1/24 (static)
118118

119119
admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> <b>edit option dns-server</b>

‎doc/ethernet.md‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -56,22 +56,41 @@ top of a bridge interface *br0* is named *vlan10*.
5656
Physical Ethernet interfaces provide low-level settings for speed/duplex as
5757
well as packet status and [statistics](#ethernet-statistics).
5858

59-
By default, Ethernet interfaces defaults to auto-negotiating
60-
speed/duplex modes, advertising all speed and duplex modes available.
61-
In the example below, the switch would by default auto-negotiate speed
62-
1 Gbit/s on port eth1 and 100 Mbit/s on port eth4, as those are the
63-
highest speeds supported by H1 and H2 respectively.
59+
By default, Ethernet interfaces defaults to auto-negotiating speed/duplex
60+
modes, advertising all speed and duplex modes available. In the example
61+
below, the switch would by default auto-negotiate speed 1 Gbps on port eth1
62+
and 100 Mbps on port eth4, as those are the highest speeds supported by H1 and
63+
H2 respectively.
6464

6565
![4-port Gbit/s switch connected to Gbit and Fast Ethernet Hosts](img/ethernet-autoneg.svg)
6666

67-
The speed and duplex status for the links can be listed as shown
68-
below, assuming the link operational status is 'up'.
67+
A quick at-a-glance view of the physical link is available in the summary
68+
listing. When a port is up, a physical-layer row appears above the ethernet
69+
row, naming the IEEE PMD type (e.g. `1000baseT`, `10GbaseLR`) in the PROTOCOL
70+
column and the negotiated duplex in DATA. When the link is down the row is
71+
omitted and the interface name falls onto the ethernet row.
72+
73+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
74+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
75+
eth1 1000baseT UP duplex: full
76+
ethernet 00:53:00:06:11:01
77+
eth2 1000baseT UP duplex: full
78+
ethernet 00:53:00:06:11:02
79+
eth3 ethernet DOWN 00:53:00:06:11:03
80+
eth4 100baseTX UP duplex: full
81+
ethernet 00:53:00:06:11:04
82+
...
83+
</code></pre>
84+
85+
The detail view spells everything out, including auto-negotiation
86+
state and the speed in Mbit/s.
6987

7088
<pre class="cli"><code>admin@example:/> <b>show interface eth1</b>
7189
name : eth1
7290
index : 2
7391
mtu : 1500
7492
operational status : up
93+
link mode : 1000baseT
7594
auto-negotiation : on
7695
duplex : full
7796
speed : 1000
@@ -86,6 +105,7 @@ name : eth4
86105
index : 5
87106
mtu : 1500
88107
operational status : up
108+
link mode : 100baseTX
89109
auto-negotiation : on
90110
duplex : full
91111
speed : 100
@@ -142,6 +162,7 @@ name : eth1
142162
index : 2
143163
mtu : 1500
144164
operational status : up
165+
link mode : 1000baseT
145166
auto-negotiation : on
146167
duplex : full
147168
speed : 1000

‎doc/iface.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,19 @@ admin@example:/config/interface/eth0/> <b>leave</b>
6161
The operational status can be inspected to see both administrative and
6262
actual link state:
6363

64-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
65-
INTERFACE PROTOCOL STATE DATA
66-
eth0 ethernet <b>DISABLED</b> 02:00:00:00:00:00
67-
eth1 ethernet UP 02:00:00:00:00:01
64+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
65+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
66+
eth0 ethernet <b>DISABLED</b> 02:00:00:00:00:00
67+
eth1 1000baseT UP duplex: full
68+
ethernet 02:00:00:00:00:01
6869
...
6970
</code></pre>
7071

72+
The rows are layered bottom-up by protocol: a physical-medium row (only
73+
emitted when the link is up) on top, then the ethernet row carrying the
74+
bare MAC, then any ipv4/ipv6 sub-rows. See [Ethernet](ethernet.md) for the
75+
full set of summary fields.
76+
7177

7278
## Description
7379

‎doc/ip.md‎

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,11 @@ will be ignored. For details on how to enable the NTP client, see the
117117

118118
![Switch example (eth0 and lo)](img/ip-address-example-switch.svg)
119119

120-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
121-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
122-
eth0 ethernet UP 02:00:00:00:00:00
120+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
121+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
122+
eth0 ethernet UP 02:00:00:00:00:00
123123
ipv6 fe80::ff:fe00:0/64 (link-layer)
124-
lo ethernet UP 00:00:00:00:00:00
124+
lo ethernet UP 00:00:00:00:00:00
125125
ipv4 127.0.0.1/8 (static)
126126
ipv6 ::1/128 (static)
127127
admin@example:/>
@@ -153,13 +153,13 @@ admin@example:/config/interface/eth0/ipv4/> <b>diff</b>
153153
+ }
154154
+}
155155
admin@example:/config/interface/eth0/ipv4/> <b>leave</b>
156-
admin@example:/> <b>show interfaces</b>
157-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
158-
eth0 ethernet UP 02:00:00:00:00:00
156+
admin@example:/> <b>show interface</b>
157+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
158+
eth0 ethernet UP 02:00:00:00:00:00
159159
ipv4 169.254.1.3/16 (random)
160160
ipv4 10.0.1.1/24 (static)
161161
ipv6 fe80::ff:fe00:0/64 (link-layer)
162-
lo ethernet UP 00:00:00:00:00:00
162+
lo ethernet UP 00:00:00:00:00:00
163163
ipv4 127.0.0.1/8 (static)
164164
ipv6 ::1/128 (static)
165165
admin@example:/>
@@ -188,12 +188,12 @@ admin@example:/config/interface/eth0/ipv4/autoconf/> <b>leave</b>
188188
admin@example:/config/> <b>edit interface eth0 ipv4</b>
189189
admin@example:/config/interface/eth0/ipv4/> <b>set dhcp</b>
190190
admin@example:/config/interface/eth0/ipv4/> <b>leave</b>
191-
admin@example:/> <b>show interfaces</b>
192-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
193-
eth0 ethernet UP 02:00:00:00:00:00
191+
admin@example:/> <b>show interface</b>
192+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
193+
eth0 ethernet UP 02:00:00:00:00:00
194194
ipv4 10.1.2.100/24 (dhcp)
195195
ipv6 fe80::ff:fe00:0/64 (link-layer)
196-
lo ethernet UP 00:00:00:00:00:00
196+
lo ethernet UP 00:00:00:00:00:00
197197
ipv4 127.0.0.1/8 (static)
198198
ipv6 ::1/128 (static)
199199
admin@example:/>
@@ -235,11 +235,11 @@ admin@example:/config/> <b>edit interface eth0 ipv6</b>
235235
admin@example:/config/interface/eth0/ipv6/> <b>set dhcp</b>
236236
admin@example:/config/interface/eth0/ipv6/> <b>leave</b>
237237
admin@example:/> <b>show interface</b>
238-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
239-
eth0 ethernet UP 02:00:00:00:00:00
238+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
239+
eth0 ethernet UP 02:00:00:00:00:00
240240
ipv6 2001:db8::42/128 (dhcp)
241241
ipv6 fe80::ff:fe00:0/64 (link-layer)
242-
lo ethernet UP 00:00:00:00:00:00
242+
lo ethernet UP 00:00:00:00:00:00
243243
ipv4 127.0.0.1/8 (static)
244244
ipv6 ::1/128 (static)
245245
admin@example:/>
@@ -291,10 +291,10 @@ on the interface.
291291
admin@example:/config/> <b>edit interface eth0 ipv6</b>
292292
admin@example:/config/interface/eth0/ipv6/> <b>set enabled false</b>
293293
admin@example:/config/interface/eth0/ipv6/> <b>leave</b>
294-
admin@example:/> <b>show interfaces</b>
295-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
296-
eth0 ethernet UP 02:00:00:00:00:00
297-
lo ethernet UP 00:00:00:00:00:00
294+
admin@example:/> <b>show interface</b>
295+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
296+
eth0 ethernet UP 02:00:00:00:00:00
297+
lo ethernet UP 00:00:00:00:00:00
298298
ipv4 127.0.0.1/8 (static)
299299
ipv6 ::1/128 (static)
300300
admin@example:/>
@@ -308,12 +308,12 @@ admin@example:/>
308308
admin@example:/config/> <b>edit interface eth0 ipv6</b>
309309
admin@example:/config/interface/eth0/ipv6/> <b>set address 2001:db8::1 prefix-length 64</b>
310310
admin@example:/config/interface/eth0/ipv6/> <b>leave</b>
311-
admin@example:/> <b>show interfaces</b>
312-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
313-
eth0 ethernet UP 02:00:00:00:00:00
311+
admin@example:/> <b>show interface</b>
312+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
313+
eth0 ethernet UP 02:00:00:00:00:00
314314
ipv6 2001:db8::1/64 (static)
315315
ipv6 fe80::ff:fe00:0/64 (link-layer)
316-
lo ethernet UP 00:00:00:00:00:00
316+
lo ethernet UP 00:00:00:00:00:00
317317
ipv4 127.0.0.1/8 (static)
318318
ipv6 ::1/128 (static)
319319
admin@example:/>
@@ -330,12 +330,12 @@ advertised by the router (here 2001:db8:0:1::0/64) and the interface
330330
identifier. The resulting address is of type *link-layer*, as it is
331331
formed based on the interface identifier ([ietf-ip.yang][2]).
332332

333-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
334-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
335-
eth0 ethernet UP 02:00:00:00:00:00
333+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
334+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
335+
eth0 ethernet UP 02:00:00:00:00:00
336336
ipv6 2001:db8:0:1:0:ff:fe00:0/64 (link-layer)
337337
ipv6 fe80::ff:fe00:0/64 (link-layer)
338-
lo ethernet UP 00:00:00:00:00:00
338+
lo ethernet UP 00:00:00:00:00:00
339339
ipv4 127.0.0.1/8 (static)
340340
ipv6 ::1/128 (static)
341341
admin@example:/>
@@ -348,11 +348,11 @@ below.
348348
admin@example:/config/> <b>edit interface eth0 ipv6</b>
349349
admin@example:/config/interface/eth0/ipv6/> <b>set autoconf create-global-addresses false</b>
350350
admin@example:/config/interface/eth0/ipv6/> <b>leave</b>
351-
admin@example:/> <b>show interfaces</b>
352-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
353-
eth0 ethernet UP 02:00:00:00:00:00
351+
admin@example:/> <b>show interface</b>
352+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
353+
eth0 ethernet UP 02:00:00:00:00:00
354354
ipv6 fe80::ff:fe00:0/64 (link-layer)
355-
lo ethernet UP 00:00:00:00:00:00
355+
lo ethernet UP 00:00:00:00:00:00
356356
ipv4 127.0.0.1/8 (static)
357357
ipv6 ::1/128 (static)
358358
admin@example:/>
@@ -366,12 +366,12 @@ admin@example:/>
366366
By default, the auto-configured link-local and global IPv6 addresses
367367
are formed from a link-identifier based on the MAC address.
368368

369-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
370-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
371-
eth0 ethernet UP 02:00:00:00:00:00
369+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
370+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
371+
eth0 ethernet UP 02:00:00:00:00:00
372372
ipv6 2001:db8:0:1:0:ff:fe00:0/64 (link-layer)
373373
ipv6 fe80::ff:fe00:0/64 (link-layer)
374-
lo ethernet UP 00:00:00:00:00:00
374+
lo ethernet UP 00:00:00:00:00:00
375375
ipv4 127.0.0.1/8 (static)
376376
ipv6 ::1/128 (static)
377377
admin@example:/>
@@ -385,12 +385,12 @@ possible to specify use of a random identifier ([ietf-ip.yang][2] and
385385
admin@example:/config/> <b>edit interface eth0 ipv6</b>
386386
admin@example:/config/interface/eth0/ipv6/> <b>set autoconf create-temporary-addresses true</b>
387387
admin@example:/config/interface/eth0/ipv6/> <b>leave</b>
388-
admin@example:/> <b>show interfaces</b>
389-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
390-
eth0 ethernet UP 02:00:00:00:00:00
388+
admin@example:/> <b>show interface</b>
389+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
390+
eth0 ethernet UP 02:00:00:00:00:00
391391
ipv6 2001:db8:0:1:b705:8374:638e:74a8/64 (random)
392392
ipv6 fe80::ad3d:b274:885a:9ffb/64 (random)
393-
lo ethernet UP 00:00:00:00:00:00
393+
lo ethernet UP 00:00:00:00:00:00
394394
ipv4 127.0.0.1/8 (static)
395395
ipv6 ::1/128 (static)
396396
admin@example:/>

‎doc/lag.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -87,34 +87,34 @@ Like other interfaces, link aggregates are also available in the general
8787
interfaces overview in the CLI admin-exec context. Here is the above
8888
static mode aggregate:
8989

90-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
91-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
92-
lo ethernet UP 00:00:00:00:00:00
93-
ipv4 127.0.0.1/8 (static)
94-
ipv6 ::1/128 (static)
90+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
91+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
92+
lo ethernet UP 00:00:00:00:00:00
93+
ipv4 127.0.0.1/8 (static)
94+
ipv6 ::1/128 (static)
9595
.
9696
.
9797
.
98-
lag0 lag UP static: balance-xor, hash: layer2
99-
│ ethernet UP 00:a0:85:00:02:00
100-
├ eth7 lag ACTIVE
101-
└ eth8 lag ACTIVE
98+
lag0 lag UP static: balance-xor, hash: layer2
99+
│ ethernet UP 00:a0:85:00:02:00
100+
├ eth7 lag ACTIVE
101+
└ eth8 lag ACTIVE
102102
</code></pre>
103103

104104
Same aggregate, but in LACP mode:
105105

106-
<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
107-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
108-
lo ethernet UP 00:00:00:00:00:00
109-
ipv4 127.0.0.1/8 (static)
110-
ipv6 ::1/128 (static)
106+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
107+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
108+
lo ethernet UP 00:00:00:00:00:00
109+
ipv4 127.0.0.1/8 (static)
110+
ipv6 ::1/128 (static)
111111
.
112112
.
113113
.
114-
lag0 lag UP lacp: active, rate: fast (1s), hash: layer2
115-
│ ethernet UP 00:a0:85:00:02:00
116-
├ eth7 lag ACTIVE active, short_timeout, aggregating, in_sync, collecting, distributing
117-
└ eth8 lag ACTIVE active, short_timeout, aggregating, in_sync, collecting, distributing
114+
lag0 lag UP lacp: active, rate: fast (1s), hash: layer2
115+
│ ethernet UP 00:a0:85:00:02:00
116+
├ eth7 lag ACTIVE active, short_timeout, aggregating, in_sync, collecting, distributing
117+
└ eth8 lag ACTIVE active, short_timeout, aggregating, in_sync, collecting, distributing
118118
</code></pre>
119119

120120

‎doc/management.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -109,13 +109,13 @@ CLI can be entered from shell in the same way as for SSH.
109109

110110
See the 'help' command for an introduction to the system
111111

112-
admin@example:/> <b>show interfaces</b>
113-
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
114-
lo ethernet UP 00:00:00:00:00:00
112+
admin@example:/> <b>show interface</b>
113+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
114+
lo ethernet UP 00:00:00:00:00:00
115115
ipv4 127.0.0.1/8 (static)
116116
ipv6 ::1/128 (static)
117-
e1 ethernet LOWER-DOWN 00:53:00:06:03:01
118-
e2 ethernet LOWER-DOWN 00:53:00:06:03:02
117+
e1 ethernet LOWER-DOWN 00:53:00:06:03:01
118+
e2 ethernet LOWER-DOWN 00:53:00:06:03:02
119119
...
120120
admin@example:/>
121121
</code></pre>

0 commit comments

Comments
 (0)