Move CLI examples from wiki to code - VPP-165

Change-Id: I50ad0d79a6ffaf0a51848abf2c5ed57e83c8640f
Signed-off-by: Keith Burns (alagalah) <alagalah@gmail.com>

6 files changed, 243 insertions, 4 deletions

diff --git a/vnet/vnet/ethernet/arp.c b/vnet/vnet/ethernet/arp.c
index d0ed1dcb3c1..262ccd0b793 100644
--- a/vnet/vnet/ethernet/arp.c
+++ b/vnet/vnet/ethernet/arp.c
@@ -1785,7 +1785,29 @@ ip_arp_add_del_command_fn (vlib_main_t * vm,
   return 0;
 }
 
+
 /* *INDENT-OFF* */
+/*?
+ * Add or delete ip4 ARP cache entries
+ *
+ * @cliexpar
+ * @cliexstart{set ip arp}
+ * Add or delete ip4 ARP cache entries as follows:
+ *  vpp# set ip arp GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ *  vpp# set ip arp delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ * Add or delete ip4 ARP cache entries to a specific fib table:
+ *  vpp# set ip arp fib-id 1 GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ *  vpp# set ip arp fib-id 1 delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ * Add or delete ip4 static ARP cache entries as follows:
+ *  vpp# set ip arp static GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ *  vpp# set ip arp static delete GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ * For testing / debugging purposes, the 'set ip arps command can add or delete multiple entries. Supply the 'count N' parameter:
+ *  vpp# set ip arp count 10 GigabitEthernet2/0/0 6.0.0.3 dead.beef.babe
+ * @NOTE: 'set ip arp' options
+ * (e.g. delete, static, 'fib-id <id>', 'count <number>', 'interface ip4_addr mac_addr')
+ * can be added in any order and combination.
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (ip_arp_add_del_command, static) = {
   .path = "set ip arp",
   .short_help =
@@ -1832,7 +1854,23 @@ set_int_proxy_arp_command_fn (vlib_main_t * vm,
   return 0;
 }
 
+
 /* *INDENT-OFF* */
+/*?
+ * Enable proxy-arp on an interface.
+ *
+ * @cliexpar
+ * @cliexstart{set interface proxy-arp}
+ * To enable proxy arp on a range of addresses, use:
+ *  vpp# set ip arp proxy 6.0.0.1 - 6.0.0.11
+ * You must specifically enable proxy arp on individual interfaces:
+ *  vpp# set interface proxy-arp <intfc> [enable|disable]
+ * The vpp stack will answer ARP requests for the indicated address range.
+ * Use with caution. Proxy ARP as a technology is infamous for blackholing traffic.
+ * Multiple proxy-arp ranges may be provisioned.
+ * The underlying implementation has not been performance-tuned; avoid creating an unnecessarily large set of ranges.
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (set_int_proxy_enable_command, static) = {
   .path = "set interface proxy-arp",
   .short_help =
diff --git a/vnet/vnet/interface_cli.c b/vnet/vnet/interface_cli.c
index 654edcaa299..7d828f54951 100644
--- a/vnet/vnet/interface_cli.c
+++ b/vnet/vnet/interface_cli.c
@@ -162,6 +162,34 @@ done:
 }
 
 /* *INDENT-OFF* */
+/*?
+ * Displays various information about the state of the current terminal
+ * session.
+ *
+ * @cliexpar
+ * @cliexstart{show hardware}
+ * Name                Link  Hardware
+ * GigabitEthernet2/0/0               up   GigabitEthernet2/0/0
+ * Ethernet address 00:50:56:b7:7c:83
+ * Intel 82545em_copper
+ *   link up, media 1000T full-duplex, master,
+ *   0 unprocessed, 384 total buffers on rx queue 0 ring
+ *   237 buffers in driver rx cache
+ *   rx total packets                                    1816
+ *   rx total bytes                                    181084
+ *   rx good packets                                     1816
+ *   rx good bytes                                     181084
+ *   rx 65 127 byte packets                              1586
+ *   rx 256 511 byte packets                              230
+ *   tx total packets                                     346
+ *   tx total bytes                                     90224
+ *   tx good packets                                      346
+ *   tx good bytes                                      88840
+ *   tx 64 byte packets                                     1
+ *   tx 65 127 byte packets                               115
+ *   tx 256 511 byte packets                              230
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (show_hw_interfaces_command, static) = {
   .path = "show hardware-interfaces",
   .short_help = "show hardware-interfaces [brief|verbose|detail] [bond] [<if-name1> <if-name2> ...]",
@@ -674,8 +702,52 @@ done:
 }
 
 /* *INDENT-OFF* */
+/*?
+ * Create vlan subinterfaces
+ *
+ * @cliexpar
+ * @cliexstart{create sub-interfaces}
+ *
+ * To create a vlan subinterface 11 to process packets on 802.1q VLAN id 11, use:
+ *
+ *  vpp# create sub GigabitEthernet2/0/0 11
+ *
+ * This shorthand is equivalent to:
+ *  vpp# create sub GigabitEthernet2/0/0 11 dot1q 11 exact-match
+ *
+ * You can specify a subinterface number that is different from the vlan id:
+ *  vpp# create sub GigabitEthernet2/0/0 11 dot1q 100
+ *
+ * You can create qinq and q-in-any interfaces:
+ *  vpp# create sub GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200
+ *  vpp# create sub GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any
+ *
+ * You can also create dot1ad interfaces:
+ *  vpp# create sub GigabitEthernet2/0/0 11 dot1ad 11
+ *  vpp# create sub GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q 200
+ *
+ * Subinterfaces can be configured as either exact-match or non-exact match.
+ * Non-exact match is the CLI default. If exact-match is specified,
+ * packets must have the same number of vlan tags as the configuration.
+ * For non-exact-match, packets must at least that number of tags.
+ * L3 (routed) interfaces must be configured as exact-match.
+ * L2 interfaces are typically configured as non-exact-match.
+ *
+ * For example, a packet with outer vlan 100 and inner 200 would match this interface:
+ *  vpp# create sub GigabitEthernet2/0/0 5 dot1q 100
+ *
+ * but would not match this interface:
+ *  vpp# create sub GigabitEthernet2/0/0 5 dot1q 100 exact-match
+ *
+ * There are two special subinterfaces that can be configured. Subinterface untagged has no vlan tags:
+ *  vpp# create sub GigabitEthernet2/0/0 5 untagged
+ *
+ * The subinterface default matches any packet that does not match any other subinterface:
+ *  vpp# create sub GigabitEthernet2/0/0 7 default
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (create_sub_interfaces_command, static) = {
-  .path = "create sub-interface",
+  .path = "create sub-interfaces",
   .short_help = "create sub-interfaces <nn>[-<nn>] [dot1q|dot1ad|default|untagged]",
   .function = create_sub_interfaces,
 };
@@ -712,7 +784,17 @@ done:
   return error;
 }
 
+
 /* *INDENT-OFF* */
+/*?
+ * Interface admin up/down
+ *
+ * @cliexpar
+ * @cliexstart{set interface state}
+ *  vpp# set interface state GigabitEthernet2/0/0 up
+ *  vpp# set interface state GigabitEthernet2/0/0 down
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (set_state_command, static) = {
   .path = "set interface state",
   .short_help = "Set interface state",
diff --git a/vnet/vnet/ip/ip46_cli.c b/vnet/vnet/ip/ip46_cli.c
index 3bb7d766d70..0b598c6d5c9 100644
--- a/vnet/vnet/ip/ip46_cli.c
+++ b/vnet/vnet/ip/ip46_cli.c
@@ -161,7 +161,22 @@ add_del_ip_address (vlib_main_t * vm,
  done:
   return error;
 }
-
+/*?
+ * To set an interface ip address, use "set interface ip address":
+ *
+ * @cliexpar
+ * @cliexstart{set interface ip address}
+
+ *  vpp# set interface ip address GigabitEthernet2/0/0 db01::1/64
+ * Note that the debug CLI does not enforce classful mask-width / addressing constraints.
+ * Interfaces may have multiple ip4 and ip6 addresses.
+ * There is no concept of primary vs. secondary interface addresses; they're just addresses.
+ * To delete a specific interface ip address, use "set interface ip address del":
+ *  vpp# set interface ip address del GigabitEthernet2/0/0 6.0.0.2/24
+ * To delete all interfaces addresses (ip4+ip6), use "set interface ip address del <intfc> all"
+ *  vpp# set interface ip address del GigabitEthernet2/0/0 all
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (set_interface_ip_address_command, static) = {
   .path = "set interface ip address",
   .function = add_del_ip_address,
diff --git a/vnet/vnet/ip/ip4_forward.c b/vnet/vnet/ip/ip4_forward.c
index 8a49854966c..751260a72ea 100644
--- a/vnet/vnet/ip/ip4_forward.c
+++ b/vnet/vnet/ip/ip4_forward.c
@@ -3245,6 +3245,20 @@ add_del_interface_table (vlib_main_t * vm,
   return error;
 }
 
+/*?
+ * Place the indicated interface into the supplied VRF
+ *
+ * @cliexpar
+ * @cliexstart{set interface ip table}
+ *
+ *  vpp# set interface ip table GigabitEthernet2/0/0 2
+ *
+ * Interface addresses added after setting the interface IP table end up in the indicated VRF table.
+ * Predictable but potentially counter-intuitive results occur if you provision interface addresses in multiple FIBs.
+ * Upon RX, packets will be processed in the last IP table ID provisioned.
+ * It might be marginally useful to evade source RPF drops to put an interface address into multiple FIBs.
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (set_interface_ip_table_command, static) = {
   .path = "set interface ip table",
   .function = add_del_interface_table,
diff --git a/vnet/vnet/ip/lookup.c b/vnet/vnet/ip/lookup.c
index 8531f645629..47138071639 100644
--- a/vnet/vnet/ip/lookup.c
+++ b/vnet/vnet/ip/lookup.c
@@ -1674,6 +1674,33 @@ VLIB_CLI_COMMAND (vlib_cli_show_ip6_command, static) = {
   .short_help = "Internet protocol version 6 (IP6) show commands",
 };
 
+/*?
+ * To add or delete routes, use ip route add / del
+ * @cliexpar
+ * @cliexstart{ip route}
+ * To add or delete straightforward static routes, use ip route add / del:
+ *  vpp# ip route add 6.0.1.2/32 via 6.0.0.1 GigabitEthernet2/0/0
+ *  vpp# ip route del 6.0.1.2/32 via 6.0.0.1 GigabitEthernet2/0/0
+ *
+ * Multiple routes
+ *
+ * Mainly for route add/del performance testing, one can add or delete
+ * multiple routes by adding 'count N' to the previous item:
+ *  vpp# ip route add count 10 7.0.0.0/24 via 6.0.0.1 GigabitEthernet2/0/0
+ *
+ * Multipath
+ *
+ * Add multiple routes for the same destination to create equal-cost multipath:
+ *  vpp# ip route add 7.0.0.1/32 via 6.0.0.1 GigabitEthernet2/0/0
+ *  vpp# ip route add 7.0.0.1/32 via 6.0.0.2 GigabitEthernet2/0/0
+ *
+ * For unequal-cost multipath, specify the desired weights:
+ *  vpp# ip route add 7.0.0.1/32 via 6.0.0.1 GigabitEthernet2/0/0 weight 1
+ *  vpp# ip route add 7.0.0.1/32 via 6.0.0.2 GigabitEthernet2/0/0 weight 3
+ *
+ * This combination of weights results in 3/4 of the traffic following the second path, 1/4 following the first path.
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (ip_route_command, static) = {
   .path = "ip route",
   .short_help = "Add/delete IP routes",
@@ -2114,6 +2141,30 @@ ip4_show_fib (vlib_main_t * vm, unformat_input_t * input, vlib_cli_command_t * c
   return 0;
 }
 
+/*?
+ * Show FIB/route entries
+ *
+ * @cliexpar
+ * @cliexstart{show ip fib}
+ * Display the IPv4 FIB.
+ * This command will run for a long time when the FIBs comprise millions of entries.
+ *   vpp# sh ip fib
+ *   Table 0
+ *   Destination         Packets          Bytes         Adjacency
+ *   6.0.0.0/8                          0               0 weight 1, index 3
+ *                                                       arp fake-eth0 6.0.0.1/8
+ *   6.0.0.1/32                         0               0 weight 1, index 4
+ *                                                        local 6.0.0.1/8
+ *
+ *  And so forth. Use 'show ip fib summary' for a summary:
+ *
+ *   vpp# sh ip fib summary
+ *   Table 0
+ *   Prefix length         Count
+ *         8               1
+ *        32               4
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (ip4_show_fib_command, static) = {
   .path = "show ip fib",
   .short_help = "show ip fib [mtrie] [summary] [table <n>] [<ip4-addr>] [clear] [include-empty]",
@@ -2340,6 +2391,16 @@ ip6_show_fib (vlib_main_t * vm, unformat_input_t * input, vlib_cli_command_t * c
   return 0;
 }
 
+/*?
+ * Show FIB6/route entries
+ *
+ * @cliexpar
+ * @cliexstart{show ip fib}
+ * Display the IPv6 FIB.
+ * This command will run for a long time when the FIBs comprise millions of entries.
+ * See 'show ip fib'
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (ip6_show_fib_command, static) = {
   .path = "show ip6 fib",
   .short_help = "show ip6 fib [summary] [clear]",
diff --git a/vnet/vnet/l2/l2_input.c b/vnet/vnet/l2/l2_input.c
index 24cb31fbd7c..9b827bad347 100644
--- a/vnet/vnet/l2/l2_input.c
+++ b/vnet/vnet/l2/l2_input.c
@@ -839,6 +839,17 @@ done:
 }
 
 /* *INDENT-OFF* */
+/*?
+ *
+ * @cliexpar
+ * @cliexstart{set interface l2 bridge}
+ * Interfaces in a bridge-domain forward packets to other interfaces in the same bridge-domain based on destination mac address.
+ * To add an interface to bridge-domain 5 use:
+ *  vpp# set interface l2 bridge GigabitEthernet2/0/0 5
+ * A split-horizon group can also be specified. This defaults to 0 if not specified.
+ *  vpp# set interface l2 bridge GigabitEthernet2/0/0 5 1
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (int_l2_bridge_cli, static) = {
   .path = "set interface l2 bridge",
   .short_help = "set interface to L2 bridging mode in <bridge-domain ID> [bvi] [shg]",
@@ -889,9 +900,18 @@ done:
 }
 
 /* *INDENT-OFF* */
+/*?
+ * L2 Cross-connect two interfaces
+ * @cliexpar
+ * @cliexstart{set interface l2 xconnect}
+ * To cross-connect two interfaces, put both into L2 cross-connect mode. All packets received on one interface will be transmitted to the other.
+ *  vpp# set interface l2 xconnect GigabitEthernet2/0/0 GigabitEthernet2/0/1
+ *  vpp# set interface l2 xconnect GigabitEthernet2/0/1 GigabitEthernet2/0/0
+ * @cliexend
+ ?*/
 VLIB_CLI_COMMAND (int_l2_xc_cli, static) = {
   .path = "set interface l2 xconnect",
-  .short_help = "set interface to L2 cross-connect mode with <peer interface>",
+  .short_help = "set interface l2 xconnect <interface> <peer interface>",
   .function = int_l2_xc,
 };
 /* *INDENT-ON* */
@@ -928,7 +948,16 @@ done:
 }
 
 /* *INDENT-OFF* */
-VLIB_CLI_COMMAND (int_l3_cli, static) = {
+/*?
+ *
+ * @cliexpar
+ * @cliexstart{cmd}
+ * Interfaces can be set in either L3 (routed) mode or L2 (xconnect or bridged) mode.
+ * Interfaces are in L3 mode by default. To return an interface to L3 mode, use:
+ *  vpp# set interface l3 GigabitEthernet2/0/0
+ * @cliexend
+ ?*/
+     VLIB_CLI_COMMAND (int_l3_cli, static) = {
   .path = "set interface l3",
   .short_help = "set interface to L3 mode",
   .function = int_l3,