From eed5c2f20606fbdb97bcf787a5b109e26e9938a5 Mon Sep 17 00:00:00 2001
From: Joachim Wiberg <troglobit@gmail.com>
Date: Sun, 25 Jun 2023 11:56:42 +0200
Subject: [PATCH] doc/cli.md: update with a toc and help on veth pairs and
 bridging

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
---
 doc/cli.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 2 deletions(-)

diff --git a/doc/cli.md b/doc/cli.md
index c0d0b6aa..4b5b0510 100644
--- a/doc/cli.md
+++ b/doc/cli.md
@@ -1,9 +1,21 @@
 CLI User Guide
 ==============
 
+* [Introduction](#introduction)
+* [Admin Exec](#admin-exec)
+* [Configure Context](#configure-context)
+  * [Set IP Address on an Interface](#set-ip-address-on-an-interface)
+  * [Creating a VETH pair](#creating-a-veth-pair)
+  * [Creating a Bridge](#creating-a-bridge)
+  * [Saving Changes](#saving-changes)
+
+
+Introduction
+------------
+
 The Infix CLI is built on the [klish project][1], which is a framework
-for implementing a CISCO, or Juniper Networs JunOS-like CLI on a UNIX
-systems.
+for implementing a CISCO, or Juniper Networks JunOS-like CLI on a UNIX
+system.
 
 Currently, when the `admin` user logs in the default shell is Bash.  To
 access the CLI, type:
@@ -106,6 +118,58 @@ interfaces {
 }
 ```
 
+### Creating a VETH Pair
+
+The following example creates a `veth0a <--> veth0b` virtual Ethernet
+pair which is useful for connecting, e.g., a container to the physical
+world.  Here we also add an IPv4 address to one end of the pair.
+
+```
+root@infix-12-34-56:configure>
+[edit]
+root@infix-12-34-56:configure> edit interfaces interface veth0a
+[edit interfaces interface veth0a]
+root@infix-12-34-56:configure> set veth peer veth0b
+[edit interfaces interface veth0a]
+root@infix-12-34-56:configure> set ipv4 address 192.168.0.1 prefix-length 24
+[edit interfaces interface veth0a]
+root@infix-12-34-56:configure> leave
+```
+
+See the bridging example below for more.
+
+> **Note:** in the CLI you do not have to create the `veth0b` interface.
+> The system _infers_ this for you.  When setting up a VETH pair using
+> NETCONF, however, you must include the `veth0b` interface.
+
+
+### Creating a Bridge
+
+Here we create a non-VLAN filtering bridge that forwards any, normally
+link-local, LLDP traffic.
+
+```
+root@infix-12-34-56:exec> configure
+[edit]
+root@infix-12-34-56:configure> edit interfaces interface br0
+[edit interfaces interface br0]
+root@infix-12-34-56:configure> set bridge ieee-group-forward lldp
+[edit interfaces interface br0]
+root@infix-12-34-56:configure> up
+[edit interfaces]
+root@infix-12-34-56:configure> set interface eth0 bridge-port bridge br0
+[edit interfaces]
+root@infix-12-34-56:configure> set interface veth0b bridge-port bridge br0
+[edit interfaces]
+root@infix-12-34-56:configure> leave
+```
+
+Both a physical port `eth0` and a virtual port `veth0b` (bridge side of
+the VETH pair from the previous example) are now bridged.  Any traffic
+ingressing one port will egress the other.  Only reserved IEEE multicast
+is filtered, except LLDP frames as shown above.
+
+
 ### Saving Changes
 
 Apply the changes (from candidate to running):