Merge pull request #792 from kernelkit/jovatn/doc-fixes

Minor doc fixes
kernelkit · Nov 1, 2024 · fbddedb · fbddedb
2 parents 142eda8 + 43e2201
commit fbddedb
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 15 deletions.
diff --git a/doc/boot.md b/doc/boot.md
@@ -143,7 +143,7 @@ which offers lots of benefits out-of-the-box:
   media like USB sticks or SD-cards) and from remote servers using FTP
   or HTTP(S).
 
-To initiate a system upgrade, run:
+To initiate a system upgrade from the shell[^1], run:
 
     rauc install <file|url>
 
@@ -349,3 +349,5 @@ can funtion reasonably well without a persistent `/var`, loosing
 If `var` is not available, Infix will still persist `/var/lib` using
 `cfg` as the backing storage.
 
+[^1]: See [CLI Upgrade](cli/upgrade.md) for information on upgrading
+    via CLI.
diff --git a/doc/introduction.md b/doc/introduction.md
@@ -15,7 +15,8 @@ managing entire fleets of installed equipment.
 Nevertheless, when it comes to initial deployment and debugging, it
 is very useful to know how to navigate and use the CLI.
 
-> Proceed to the [CLI User Guide](cli/tutorial.md).
+> Proceed to the [CLI Introduction](cli/introduction.md) or [CLI
+> Configuration Tutorial](cli/configure.md).
 
 
 ## Key Concepts

diff --git a/doc/networking.md b/doc/networking.md
@@ -43,15 +43,17 @@ diverted to the VLAN interface before entering the bridge, while all
 other traffic would be bridged as usual.
 
 | **Type** | **Yang Model**             | **Description**                                               |
-| -------- | -----------------          | ------------------------------------------------------------- |
+|----------|----------------------------|---------------------------------------------------------------|
 | bridge   | infix-if-bridge            | SW implementation of an IEEE 802.1Q bridge                    |
 | ip       | ietf-ip, infix-ip          | IP address to the subordinate interface                       |
 | vlan     | infix-if-vlan              | Capture all traffic belonging to a specific 802.1Q VID        |
 | lag[^1]  | infix-if-lag               | Bonds multiple interfaces into one, creating a link aggregate |
 | lo       | ietf-interfaces            | Software loopback interface                                   |
-| eth      | ietf-interfaces,           | Physical Ethernet device/port                                 |
-|          | ieee802-ethernet-interface |                                                               |
+| eth      | ieee802-ethernet-interface | Physical Ethernet device/port.                                |
+|          | infix-ethernet-interface   |                                                               |
 | veth     | infix-if-veth              | Virtual Ethernet pair, typically one end is in a container    |
+| *common* | ietf-interfaces,           | Properties common to all interface types                      |
+|          | infix-interfaces           |                                                               |
 
 
 ## Data Plane
@@ -202,14 +204,15 @@ This sets `eth0` as an untagged member of VLAN 10 and `eth1` as an
 untagged member of VLAN 20.  Switching between these ports is thus
 prohibited.
 
+![A VLAN bridge with two VLANs](img/vlan-bridge.svg)
+
 To terminate a VLAN in the switch itself, either for switch management
 or for routing, the bridge must become a (tagged) member of the VLAN.
 
 ```
 admin@example:/config/interface/br0/> set bridge vlans vlan 10 tagged br0
 admin@example:/config/interface/br0/> set bridge vlans vlan 20 tagged br0
 ```
-![A VLAN bridge with two VLANs](img/vlan-bridge.svg)
 
 > To route or to manage via a VLAN, a VLAN interface needs to be created
 > on top of the bridge, see section [VLAN Interfaces](#vlan-interfaces)
@@ -430,7 +433,7 @@ top of a bridge interface *br0* is named *vlan10*.
 #### Ethernet Settings and Status
 
 Physical Ethernet interfaces provide low-level settings for speed/duplex as
-well as packet status and statistics (*ieee802-ethernet-interface.yang*).
+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.
@@ -512,7 +515,7 @@ require auto-negotiation to be enabled.
 
 #### Ethernet statistics
 
-Ethernet packet statistics can be listed as shown below.
+Ethernet packet statistics[^6] can be listed as shown below.
 
 ```
 admin@example:/> show interfaces name eth1
@@ -856,7 +859,7 @@ have changed type to *random*.
 ### IPv4 forwarding
 
 To be able to route (static or dynamic) on the interface it is
-required to enable forwarding. This setting controlls if packets
+required to enable forwarding. This setting controls if packets
 received on this interface can be forwarded.
    ```
    admin@example:/config/> edit interface eth0
@@ -872,12 +875,12 @@ This flag behaves totally different than for IPv4. For IPv6 the
 ability to route between interfaces is always enabled, instead this
 flag controls if the interface will be in host/router mode.
 
-| **Feature**                               | **Forward enabled** | **Forward disabled** |
-|:------------------------------------------|:--------------------|:---------------------|
-| IsRouter set in Neighbour Advertisements. | Yes                 | No                   |
-| Transmit Router Solicitations.            | No                  | Yes                  |
-| Router Advertisements are ignored         | No                  | Yes                  |
-| Accept Redirects                          | No                  | Yes                  |
+| **Feature**                              | **Forward enabled** | **Forward disabled** |
+|:-----------------------------------------|:--------------------|:---------------------|
+| IsRouter set in Neighbour Advertisements | Yes                 | No                   |
+| Transmit Router Solicitations            | No                  | Yes                  |
+| Router Advertisements are ignored        | No                  | Yes                  |
+| Accept Redirects                         | No                  | Yes                  |
 
    ```
    admin@example:/config/> edit interface eth0
@@ -1150,3 +1153,8 @@ currently supported, namely `ipv4` and `ipv6`.
 [^5]: Infix MAC bridges on Marvell Linkstreet devices are currently
     limited to use a single MAC database, causing issues if the same
     MAC address appears on different MAC bridges.
+[^6]: Ethernet counters are described in
+    *ieee802-ethernet-interface.yang* and
+    *infix-ethernet-interface.yang*. [Ethernet
+    Counters](eth-counters.md) page provides additional details on
+    statistics support.