GoVPP CLI Proposal

[ondrej-fabry]

Note
This document contains info about proposal for the GoVPP CLI application.

Warning
The document is a work in progress and some of the information might be changed or removed.

Intro

The GoVPP CLI is an application to be used for any interaction with VPP API. It can consume VPP API files statically to parse then, build schema from it and then do additional processing of the data. And also, it can call the VPP API services in a running VPP instance for various purposes, such as sending VPP API requests from bash scripts, testing API handlers, measuring performance, running a proxy.. etc.

Features

Here's brief summary of features the GoVPP CLI would provide:

• list VPP API file(s) and its contents (simple, table.. or formatted: json, yaml..)
• query (filter) VPP API contents (e.g. list all events, list all messages containing field with name...)
• run linter for the VPP API schema(s) using a set of linting rules (possibly loading them from config file)
• compare VPP API schemas to produce list of changes
• check for breaking changes between VPP API schemas
• generate code bindings (potentially replacing the binapi-generator)
• run a proxy for allowing remote access to VPP API (or possibly some kind of broker for managing several VPP instances)
• start a HTTP server with auto-generated handlers for entire VPP API of any VPP version (without any generated code bindings)
• ..and definitely much much more will be possible!

Demonstration

Below are few usage examples demonstrating the some of the GoVPP CLI commands.

List VPP API

List all VPP API files in a schema as a table including brief summary about their contents:

govpp vppapi

#    API                    VERSION         PATH     IMPORTS  MESSAGES  TYPES  RPCs  
1    crypto                 1.0.1-22355ec6  core     -          4        2      2    
2    ethernet_types         1.0.0-f24103d6  core     -          -        1      -    
3    interface_types        1.0.0-9297636c  core     -          -        7      -    
4    ip_types               3.0.0-fee023ed  core     -          -       19      -    
5    memclnt                2.1.0-8d3dd881  core     -         22        2     13    
6    pci_types              1.0.0-5d418665  core     -          -        1      -    
7    policer_types          1.0.0-ae54624b  core     -          -        5      -    
8    sr_types               1.0.0-7955bd50  core     -          -        3      -    
9    tunnel_types           1.0.0-c56b5084  core     -          -        2      -    
10   virtio_types           1.0.0-7a70a44e  core     -          -        2      -    
11   vpe_types              1.0.0-5f754a1c  core     -          -        4      -    
12   builtinurl             1.0.0-25045d63  plugins  -          2        -      1    
13   cdp                    1.0.0-8cfa825e  plugins  -          2        -      1    
14   crypto_sw_scheduler    0.1.0-f4b02951  plugins  -          2        -      1    
15   dns                    1.0.0-269575cd  plugins  -          8        -      4    
16   graph                  1.0.0-a0b3fd1c  plugins  -          3        1      1    
17   http_static            2.1.0-d29e72e9  plugins  -          2        -      1    
18   ioam_cache             1.0.0-d0a0cf20  plugins  -          2        -      1    
19   nat_types              0.0.1-2ca9110f  plugins  -          -        3      -    
20   pot                    1.0.0-a9d8e55c  plugins  -          8        -      4    
21   tls_openssl            2.0.0-7386fbcd  plugins  -          2        -      1    
22   trace                  1.0.0-397cbf90  plugins  -          6        -      3    
23   tracedump              0.1.0-691543d5  plugins  -          9        1      4    
24   classify               3.0.0-b9f6a207  core     1         28        3     14    
25   cop                    1.0.1-78b974ae  core     1          4        -      2    
26   feature                1.0.2-d8824c00  core     1          2        -      1    
27   fib_types              2.0.0-21fd785b  core     1          -        6      -    
28   gso                    1.0.0-cd91bd3b  core     1          2        -      1    
29   ipfix_export           2.0.2-6ae99522  core     1         14        -      7    
30   pg                     2.0.0-7478d133  core     1          8        -      4    
31   pipe                   1.0.1-3da80245  core     1          6        -      3    
32   policer                2.0.0-d9188811  core     1          4        -      2    
33   punt                   2.2.1-ee63b6c7  core     1         10        7      5    
34   rd_cp                  1.0.1-b3358997  core     1          2        -      1    
35   span                   2.0.0-e4ccb39b  core     1          4        1      2    
36   syslog                 1.0.0-5ad12a74  core     1          8        1      4    
37   tcp                    2.0.0-93d07485  core     1          2        -      1    
38   udp                    1.1.0-65e4a4b3  core     1          6        1      3    
39   vpe                    1.6.1-40364e00  core     1         26        1     13    
40   adl                    0.0.1-586e0c93  plugins  1          4        -      2    
41   avf                    1.0.0-1f02cab0  plugins  1          4        -      2    
42   ct6                    1.0.0-b79efbb8  plugins  1          2        -      1    
43   dhcp6_ia_na_client_cp  1.0.1-8b7d00ba  plugins  1          2        -      1    
44   flowprobe              1.0.0-93135db1  plugins  1          4        2      2    
45   ioam_export            1.0.0-26bebf64  plugins  1          2        -      1    
46   ioam_vxlan_gpe         1.0.0-b49eb0b9  plugins  1         12        -      6    
47   l2e                    1.0.0-8b7d00ba  plugins  1          2        -      1    
48   lb_types               1.0.0-ba19340c  plugins  1          -        6      -    
49   mdata                  0.1.0-69e847e7  plugins  1          2        -      1    
50   nsh                    1.0.0-d2e2a1fe  plugins  1          8        -      4    
51   nsim                   2.2.1-9ef0c583  plugins  1          8        -      4    
52   oddbuf                 0.1.0-762ca14d  plugins  1          2        -      1    
53   rdma                   2.0.0-aece7cc3  plugins  1          6        1      3    
54   udp_ping               3.0.0-16d961db  plugins  1          4        -      2    
55   vxlan_gpe_ioam_export  1.0.0-26bebf64  plugins  1          2        -      1    
56   af_packet              2.0.0-88e8dc71  core     2          8        -      4    
57   bfd                    2.0.0-c430faac  core     2         28        1     14    
58   bier                   1.2.1-8d1cd497  core     2         22        2     11    
59   bond                   2.1.0-2b0675da  core     2         24        2     12    
60   flow_types             0.0.2-d3adaa63  core     2          -       20      -    
61   ip6_nd                 1.0.0-2fe73bce  core     2         13        1      6    
62   ipsec_types            3.0.0-be68e142  core     2          -        7      -    
63   mfib_types             1.0.0-d2b57aaf  core     2          -        3      -    
64   p2p_ethernet           1.0.0-99de69d2  core     2          4        -      2    
65   qos                    1.1.1-e46c0ba5  core     2         19        6      9    
66   session                3.2.0-b4e9f977  core     2         22        2     11    
67   teib                   1.0.0-bd54326   core     2          4        1      2    
68   vxlan                  2.0.0-392d0a82  core     2          8        -      4    
69   vxlan_gbp              1.1.1-4cab5d8c  core     2          6        2      3    
70   vxlan_gpe              2.0.0-15752e11  core     2          6        -      3    
71   acl_types              1.0.0-878da4fa  plugins  2          -        3      -    
72   dhcp6_pd_client_cp     2.0.0-8907187e  plugins  2          4        -      2    
73   dslite                 1.0.0-8b0d552b  plugins  2         12        -      6    
74   gtpu                   2.0.1-d80da142  plugins  2         10        -      5    
75   igmp                   1.0.0-ab6b645a  plugins  2         19        4      9    
76   ikev2_types            1.0.0-7a2a5114  plugins  2          -       11      -    
77   lacp                   2.0.0-3d0e784c  plugins  2          2        -      1    
78   lldp                   2.0.0-a664b081  plugins  2          4        -      2    
79   mactime                2.0.0-dc53be90  plugins  2          7        2      3    
80   map                    4.2.1-4bf438d8  plugins  2         32        -     16    
81   memif                  3.0.0-d09fa76   plugins  2         10        2      5    
82   stn                    2.0.0-47566cc9  plugins  2          4        -      2    
83   svs                    1.0.0-bf503ea0  plugins  2         10        -      5    
84   vmxnet3                1.2.0-7b6cdd72  plugins  2          8        2      4    
85   wireguard              0.1.0-cd532184  plugins  2         12        3      6    
86   arp                    1.0.0-7eecbba1  core     3          8        1      4    
87   gre                    2.1.1-8ac2b605  core     3          4        2      2    
88   interface              3.2.2-6d3c2922  core     3         57        -     28    
89   ip_neighbor            1.0.0-da761d45  core     3         18        3      8    
90   ipip                   2.0.2-a7344412  core     3         10        1      5    
91   l2                     3.0.0-d8cb45a8  core     3         54        6     26    
92   mpls                   1.1.1-14409f77  core     3         16        3      8    
93   sr                     2.0.0-39711e91  core     3         22        2     11    
94   sr_mpls                3.0.0-dac70c1e  core     3         10        -      5    
95   tapv2                  4.0.0-3ee2101e  core     3          6        1      3    
96   vhost_user             4.0.1-525f292b  core     3          8        -      4    
97   virtio                 3.0.0-b3c1f9aa  core     3          8        1      4    
98   abf                    1.0.0-9d2916b5  plugins  3         10        2      5    
99   cnat                   0.1.0-14fd78f   plugins  3         16        5      8    
100  det44                  1.0.0-8c5fa42d  plugins  3         38        -     19    
101  dhcp                   3.0.1-4e10b3eb  plugins  3         29        9     13    
102  gbp                    2.0.0-d2897a3c  plugins  3         48       22     23    
103  geneve                 2.1.0-9b1c8ca7  plugins  3          8        -      4    
104  ikev2                  1.0.1-f973216e  plugins  3         48        -     24    
105  l2tp                   2.0.0-57be5ae5  plugins  3         10        1      5    
106  l3xc                   1.0.1-2e8640f2  plugins  3          8        1      4    
107  lb                     1.0.0-dc20b9d0  plugins  3         16        -      8    
108  lisp_types             1.0.0-b53909    plugins  3          -        8      -    
109  nat44                  5.2.0-b426a8db  plugins  3         91        2     45    
110  nat64                  1.0.0-7d2e959   plugins  3         26        -     13    
111  nat66                  1.0.0-c4ea7e0   plugins  3          8        -      4    
112  pppoe                  2.0.0-939f0908  plugins  3          6        -      3    
113  urpf                   1.0.0-8ce7b70a  plugins  3          2        1      1    
114  vrrp                   1.0.1-42f64b4c  plugins  3         17        7      8    
115  flow                   0.0.1-48ba1f6b  core     4          8        -      4    
116  ipsec                  4.0.0-15265a51  core     4         42        4     21    
117  acl                    2.0.0-a832e616  plugins  4         38        -     19    
118  lisp                   2.0.0-7b0481e4  plugins  4         60        2     30    
119  lisp_gpe               2.0.0-f57c7618  plugins  4         20        3     10    
120  one                    2.0.0-2e88f8ed  plugins  4        108        5     54    
121  ip                     3.0.1-d7d82c5f  core     5         60        5     30  

Print VPP API file(s) in JSON

Print the definition VPP API file(s) using JSON format:

govpp vppapi -json

[
  {
    "Name": "af_packet",
    "Path": "/usr/share/vpp/api/core/af_packet.api.json",
    "CRC": "0x88e8dc71",
    "Options": {
      "version": "2.0.0"
    },
    "Imports": [
      "vnet/interface_types.api",
      "vnet/ethernet/ethernet_types.api"
    ],
    "AliasTypes": [
      {
        "Name": "interface_index",
        "Type": "u32"
      },
      {
        "Name": "mac_address",
        "Type": "u8",
        "Length": 6
      }
    ],
    "EnumTypes": [
      {
        "Name": "if_status_flags",
        "Type": "u32",
        "Entries": [
          {
            "Name": "IF_STATUS_API_FLAG_ADMIN_UP",
            "Value": 1
          },
          {
            "Name": "IF_STATUS_API_FLAG_LINK_UP",
            "Value": 2
          }
        ]
      },
      {
        "Name": "mtu_proto",
# (output truncanted)

Send CLI command via VPP API

Send CLI command to VPP via VPP API (using vlib.CliInband):

govpp cli "show version"

# show version
vpp v22.10-rc1~1-g569763f94~b3 built by root on ac322d2c016f at 2022-09-27T14:23:54