Difference between revisions of "VPP/Command-line Interface (CLI) Guide"

Revision as of 14:09, 8 January 2016

Introduction

The vpp network stack comes equipped with a set of commands that are useful for debugging.

The easiest way to access the CLI (with proper permissions) is to use the vppctl command:

sudo vppctl <cli command>

The CLI parser matches static keyword strings, eventually invoking an action function. Unambiguous partial keyword matching always occurs. The action functions consume input until satisfied or until they fail. This model makes for easy coding, but does not guarantee useful "help" output. It's up to the CLI command writer to add useful help strings.

You can find the source code of CLI commands by searching for instances of the VLIB_CLI_COMMAND macro in the code source files.

Please help maintain and improve this document to make and keep these commands clear and useful!

Interface Commands

show interface

To display interface names and rx/tx packet/byte and drop counters, use "show interface":

vpp# show interface
             Name                    State          Counter          Count     
GigabitEthernet2/0/0                   up       rx packets                  1801
                                                rx bytes                  179560
                                                tx packets                   343
                                                tx bytes                   88050
                                                drops                       1459
GigabitEthernet2/2/0                   up       rx packets                  7875
                                                rx bytes                  740694
                                                tx packets                   228
                                                tx bytes                   78888
                                                drops                       7647
GigabitEthernet2/3/0                  down      
GigabitEthernet2/4/0                  down      
local0                                down      
pg/stream-0                           down      
pg/stream-1                           down      
pg/stream-2                           down      
pg/stream-3                           down      
tuntap-0                               up

On x86_64 hardware, interface names derive directly from PCI bus, id, and function. Local0 and the packet generator streams are "special" and should not be configured directly. When running in "punt/inject mode" tuntap-0 is "special" and should not be configured directly.

show hardware

To display hardware status and hardware-dependent counters, use "show hardware"

vpp# 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

set interface ip address

To set an interface ip address, use "set interface ip address":

vpp# set interface ip address GigabitEthernet2/0/0 6.0.0.2/24
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

set interface state

Admin up/down via "set interface state":

vpp# set interface state GigabitEthernet2/0/0 up
vpp# set interface state GigabitEthernet2/0/0 down

create vlan subinterface

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

set interface ip table

Place the indicated interface into the supplied VRF via "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.

Routing table commands

ip route add/del (basic)

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

ip route add/del (multiple)

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

ip route add/del (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.

show ip fib / show ip6 fib

Use "show ip fib" / "show ip6 fib" to display the ip4 and ip6 FIBs, respectively. These commands 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

Manipulating the ARP cache

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 arp" 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.

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 vnet stack will answer ARP requests for the indicated address range. Use with caution. Proxy ARP 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.

dhcp proxy

To configure dhcp proxy, configure as follows:

vpp# set dhcp proxy server 6.0.0.1

As of this writing, we support one DHCP server.

dhcp proxy option 82 (circuit-ID)

If configured as follows, the vnet dhcp proxy implementation will add the client-facing interface FIB number as a DHCP option 82 circuit-ID. Furthermore, the code sets suboption 5 to the first ip4 address provisioned on the client-facing interface.

 vpp# set dhcp proxy server 6.0.0.1 add-option-82

If necessary, one can configure the suboption-5-provided ip4 addresses manually; on a per-interface basis:

 vpp# set dhcp option-82 address [delete] <interface> <ip4-address>

To inspect the suboption-5 interface→ip4 address table, use:

 vpp# show dhcp option-82 addresses

provisioning martian addresses

If you intend to use the dhcp relay feature, you'll need to explicitly provision the ip4 L3 martian addresses 255.255.255.255 and 0.0.0.0:

vpp# ip route add 255.255.255.255/32 via local
vpp# ip route add 0.0.0.0/32 via local

set ip6 neighbor

To statically configure an ip6 neighbor adjacency, use the "set ip6 neighbor" command:

vpp# set ip6 neighbor [del] <intfc> <ip6-address> <mac-address>

This command is especially useful e.g. when adding an ip6 default route, since neither the ip4 nor ip6 FIB has the concept of a glean adjacency.

show ip6 neighbors

To display vnet's idea of adjacent ipv6 hosts found via neighbor discovery:

vpp# show ip6 neighbors

enable/disable source RPF checking on an interface

vpp# set interface ip source-check GigabitEthernet2/0/0
vpp# set interface ip source-check GigabitEthernet2/0/0 del

Source RPF checking is on by default.

ip probe

The ip probe command ARPs for ip4 addresses or attempts ip6 neighbor discovery depending on the supplied ip address format.

 vpp# ip probe <interface> <ip-address>

Note that this command will not immediately affect the indicated FIB; it is not suitable for use in establishing a FIB entry prior to adding recursive FIB entries. As in: don't use it in a script to probe a gateway prior to adding a default route. It won't work. Instead, configure a static ARP cache entry [see set ip arp], or a static ip6 neighbor [see set ip6 neighbor].

Layer 2 commands

The Vector Packet Engine (VPE) natively includes a small set of layer2 features.

Interface mode commands

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

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

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

l2fib commands

The mac forwarding table for bridge-domains is called the l2fib. Entries are added automatically as part of mac learning, but you can also add entries manually.

The following command associates the mac address in bridge domain 0 with GigabitEthernet2/0/0. (Note that the interface should be configured to be the specified bridge-domain but this is not enforced):

vpp# l2fib add 00:11:22:33:44:55 0 GigabitEthernet2/0/0

You can also create static mac entries. These cannot be overridden by mac learning.

vpp# l2fib add 00:11:22:33:44:55 0 GigabitEthernet2/0/0 static

You can drop packets with "bad" mac addresses by creating filter entries. If a packet's source mac or destination mac matches a filtered entry, the packet is dropped:

vpp# l2fib add 00:11:22:33:44:55 0 filter

You can also create entries that point to BVI interfaces. See the BVI section for more information.

vpp# l2fib add 00:11:22:33:44:55 0 loop0 bvi

You can delete specific l2fib entries using:

vpp# l2fib del 00:11:22:33:44:55 0 

You can delete all l2fib entries using:

vpp# clear l2fib

You can display the contents of the l2fib using:

vpp# show l2fib
   Mac Address     BD ID            Interface           Index  static  filter  bvi  refresh  timestamp 
00:02:04:06:08:0a    0        GigabitEthernet2/1/0        6       0       0     0      0         0     
00:22:44:06:08:0a    0       GigabitEthernet2/2/0.1       9       0       0     0      0         0

bridge-domain commands

You can display the list of all bridge-domains that are in use:

vpp# show bridge-domain
 ID     Learning      Forwarding      Flooding             BVI Interface        
 0       enabled        enabled        enabled                  N/A             
 2       enabled        enabled        enabled                  N/A             

You can display information on a single bridge-domain:

vpp# show bridge-domain 0
 ID     Learning      Forwarding      Flooding             BVI Interface        
 0       enabled        enabled        enabled                  N/A             

You can also display detailed information (basically the member list) on a single bridge-domain:

vpp# show bridge-domain 0 detail
 ID     Learning      Forwarding      Flooding             BVI Interface        
 0       enabled        enabled        enabled                  N/A             

          Interface             Id   BVI 
    GigabitEthernet2/1/0        6    no  
   GigabitEthernet2/2/0.1       9    no  

enable/disable learning, forwarding, and flooding

MAC learning, unicast forwarding, and flooding can be enabled and disabled independently on each interface and on each bridge-domain. By default these are enabled.

To disable learning on an interface use:

vpp# set interface l2 learn GigabitEthernet2/0/0 disable

To re-enable it use:

vpp# set interface l2 learn GigabitEthernet2/0/0

Similarly, unicast forwarding and flooding can be disabled:

vpp# set interface l2 forward GigabitEthernet2/0/0 disable
vpp# set interface l2 flood GigabitEthernet2/0/0 disable

These three features can also be disabled at the bridge-domain level. To disable learning on all interfaces in bridge-domain 2, use:

vpp# set bridge-domain learn 2 disable

VLAN Tag Rewrite

VLAN tag rewrite provides the ability to change the VLAN tags on a packet. Existing tags can be popped, new tags can be pushed, and existing tags can be swapped with new tags. The rewrite feature is attached to a subinterface as input and output operations. The input operation is explicitly configured. The output operation the symmetric opposite and is automatically derived from the input operation.

By default a subinterface has no tag-rewrite. To return a subinterface to this state use:

vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 disable

To pop vlan tags off packets received from a subinterface, use:

vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 pop 1
vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 pop 2

The subinterface encapsulation (the vlan tags specified when it was created) must have at least the number of popped tags. e.g. the "pop 2" operation would be rejected on a single-vlan interface. The output tag-rewrite operation for pops is to push the specified number of vlan tags onto the packet. The pushed tag values are the ones in the subinterface encapsulation.

To push one or two vlan tags onto packets received from an interface, use:

vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 push dot1q 100
vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 push dot1ad 100 200

The push operation also specifies the ethertype. The output tag-rewrite operation for pushes is to pop the same number of tags off the packet. If the packet doesn't have enough tags it is dropped.

Tags can also be translated, which is basically a combination of a pop and push.

vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 translate 1-1 dot1ad 100
vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 translate 2-2 dot1ad 100 200
vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 translate 1-2 dot1q 100 200
vpp# set interface tag-rewrite GigabitEthernet2/0/0.1 translate 2-1 dot1q 100

EFP Filter Check

It is possible to transmit a packet out a subinterface with vlan tags that are not compatible with that subinterface. In other words, if that packet arrived on the output port, it would not be classified as coming from the output subinterface. This can happen in various ways: through misconfiguration, by putting subinterfaces with different vlan encaps in the same bridge-domain, etc. The EFP Filter Check detects such packets and drops them. It consists of two checks, one that verifies the packet prior to output vlan tag rewrite and one that verifies the packet after vlan tag rewrite.

You can enable the EFP filter check using:

vpp# set interface efp-filter GigabitEthernet2/0/0.1

The EFP Filter check is disabled by default. You can disable it again by using:

vpp# set interface efp-filter GigabitEthernet2/0/0.1 disable

IRB/BVI

Integrated Routing and Bridging (IRB) emulates a switch connected to a router port using an internal virtual interface called a Bridged Virtual Interface (BVI). The BVI connects an L3 vrf to an L2 bridge-domain. When an L3 packet is routed to the BVI, an L2 encapsulation is added to the packet as is done normally. But instead of being transmitted out a physical interface, the packet is forwarded in the bridge-domain associated with the BVI. The packet could be unicast or flooded to all interfaces in the bridge-domain. In the other direction, an L2 packet could be forwarded to a BVI interface. This could happen via a BVI entry in the l2fib or via flooding in a bridge-domain that includes a BVI interface. The packet is then routed in the vrf associated with the BVI.

A bridge-domain can be associated with only one BVI. However a vrf can contain routes to multiple BVIs.

To configure a BVI interface, create it using a loopback interface, assign a mac address, and set its vrf and bridge-domain. This example uses vrf 0 and bridge-domain 5. Learning should be disabled on the BVI interface. It is harmless but useless to enable it because the BVI l2fib entry is static:

vpp# loop create 0000.0B51.0001
vpp# set int l2 bridge loop0 5 bvi
vpp# set int ip table loop0 0
vpp# set int l2 learn loop0 disable
vpp# set int state loop0 up

Add L2 connectivity by creating an l2fib entry for the BVI interface:

vpp# l2fib add 0000.0B51.0001 5 loop0 bvi

Add L3 connectivity by creating a route and adjacency for the BVI interface. The static ARP is not strictly necessary -- routing to an IP with an unknown mac will cause an ARP request to be generated.

vpp# ip route table 0 8.0.1.0/24 via loop0
vpp# set ip arp loop0 8.0.1.1 00:02:04:06:08:0a

Verify the BVI configuration:

vpp# show l2fib
    Mac Address     BD ID            Interface           Index  static  filter  bvi  refresh  timestamp 
 00:00:0b:51:00:01    5                loop0               9       1       0     1      0         0     
vpp# show bridge-domain
  ID     Learning      Forwarding      Flooding             BVI Interface        
  5       enabled        enabled        enabled                 loop0            
vpp# show ip fib
Table 0, flow hash: src dst sport dport proto 
     Destination         Packets          Bytes         Adjacency   
8.0.1.0/24                         0               0 weight 1, index 3
                                                     loop0
8.0.1.1/32                         0               0 weight 1, index 4
                                                     loop0
                                                     00020406080a00000b5100010800

Tunnel encapsulations

GRE tunnels

To create a GRE tunnel:

vpp# create gre tunnel src <addr> dst <addr> [outer-fib-id <fib-id>]

This creates a GRE tunnel whose outer IP header will have the indicated source and destination IP addresses. The tunnel manifests itself as a greX interface. Interface address can be set with "set interface address" command. GRE Encapsulated packets can be sent/received in non-zero FIB by specifying optional keyword outer-fib-id.

MPLS-in-GRE tunnels

To create an MPLS-in-GRE tunnel, first create the required encap and decap label mappings:

vpp# mpls decap [add|delete] label <label> fib <id>
vpp# mpls encap [add|delete] label <label> fib <id> dest <ip4-address>

Next, create the tunnel itself.

vpp# create mpls gre tunnel src <addr> dst <addr> intfc <addr>

Tunnel creation will fail if no encap label exists for the "intfc <addr>"

The dataplane expects to find a single MPLS label after the outer-IP header. The label value is translated through the MPLS decap table; the indicated FIB tables are used to route the decapsulated inner IP header.

To display the encap and decap label tables, use:

vpp# show mpls fib

To display the set of MPLS tunnels, use:

vpp# show mpls tunnel

L2tpv3-in-ip6 tunnels

To create an l2tpv3-in-ip6←→L2 VLAN tunnel, use the "create l2tpv3 tunnel" command. All parameters are specified on a single input line (of arbitrary length):

vpp# create l2tpv3 tunnel client <ip6-addr> our <ip6-addr>
      [local-cookie <%llx>] [remote-cookie <%llx>] 
      [local-session-id <dec-num>] [remote-session-id <dec-num>]
      [l2-sublayer-present]

Local-cookie and remote-cookie default to FFFFFFFFFFFFFFFF. Local-session-id and remote-session-id default to 1.

When interoperating with the current Linux l2tpv3-in-v6 implementation, you'll need to specify the l2-sublayer-present property. Conversely, when interoperating with IOS-XR, do not specify l2-sublayer-present. Since the l2 sublayer is used to transport sequence information -- not present in static l2tpv3 softwires -- it seems that the Linux implementation is incorrect.

In the tunnel-to-l2-interface direction, decapsulation must be explicitly enabled on the input interface:

vpp# set interface ip6 l2tpv3 GigabitEthernet2/1/0 

This can be deconfigured as well:

vpp# set interface ip6 l2tpv3 GigabitEthernet2/1/0 del

The vpp stack strips the ip6 and tunnel encaps and tracks down the inner l2 header. Vlan tags can be inserted using subinterface VLAN tag-rewrite commands (see above).

The session lookup key is configurable on the vpp command line. For example:

 # <vpp-app-full-path> unix interactive l2tp [lookup-v6-src | lookup-v6-dst | lookup-session-id]

The vpp stack defaults to "lookup-v6-dst."

In the l2-interface-to-tunnel direction, the vpp stack uses the l2 subinterface as the session lookup key.

Interoperation with the latest Linux kernel / network stack l2tpv3-in-ip6 implementation has been demonstrated.

L2TP Cookie Rollover Commands

Configure L2TPv3 Rollover cookie"

vpp# set l2tpv3 tunnel cookie <interface> [local <64bit hex value>] [remote <64bit hex value>]

• if the local cookie value is specified, both the existing cookie value and the specified rollover value will be accepted.
• if the remote cookie value is specified, it will immediately replace the existing remote cookie value.

P2# sh l2tpv3 verbose
1 l2tp sessions...
L2tp session lookup on dst address
[0] 2003:123a:40:11::11 (our) 2003:132a:40:11::1 (client) l2tpv3_tunnel0 (sw_if_index 9)
   local cookies 1111111111111111 0000000000000000 remote cookie 1111111111111111
   local session-id -1 remote session-id -1
   l2 specific sublayer absent
   user-to-net: 20472964 pkts 1944931580 bytes

Infrastructure Commands

statistic and error counters

The vpp stack maintains many useful statistic and error counters. To display them:

 vpp# show error
     Count                       Node                          Error       
           8077                arp-input               IP4 destination address not local to subnet
              1                arp-input               ARP replies received
            126                arp-input               Proxy ARP replies sent
              1                 ip4-arp                ARP requests sent
           1230                ip4-input               ip4 ttl <= 1
            667                ip4-input               ip4 source lookup miss
              3                ip6-input               ip6 destination lookup miss
            253          dhcp-proxy-to-server          DHCP packets relayed to the server
            252          dhcp-proxy-to-server          DHCP packets relayed to clients
              1             ip6-icmp-input             neighbor solicitations for unknown targets

To understand the precise meaning of a statistic, start with the vlib graph node name (the "Node" column above), find the graph node definition, and finally "Use the Force and Read the Source."

To clear the statistic and error counters:

vpp# clear error

graph runtime statistics

vpp# sh run
Time 75110.5, average vectors/node 1.00, last 128 main loops 0.00 per node 0.00
  vector rates in 1.4224e-1, out 8.4009e-3, drop 1.3386e-1, punt 0.0000e0
            Name                State     Vectors        Suspends         Clocks      
GigabitEthernet2/0/0-outpu      active             379               0          1.71e4 
GigabitEthernet2/0/0-tx         active             379               0          7.65e4 
GigabitEthernet2/2/0-outpu      active             252               0          1.65e4 
GigabitEthernet2/2/0-tx         active             252               0          6.48e4 
arp-input                       active            8262               0          6.97e4 
dhcp-proxy-to-client            active             252               0          4.18e4 
dhcp-proxy-to-server            active             505               0          2.49e4 
error-drop                      active           10054               0          3.08e4 
ethernet-input                  active            8262               0          5.29e4 
icmp6-neighbor-solicitatio      active               2               0          5.69e4 
ige-input                    interrupt w         10684               0          1.41e5 
ige-process                    any wait              0            2505          0.00e0 
ip4-arp                         active               1               0          4.98e5 
ip4-input-no-checksum           active            2414               0          8.51e4 
ip4-local                       active            1177               0          5.66e4 
ip4-lookup                      active            1430               0          2.96e4 
ip4-rewrite-transit             active             252               0          3.32e4 
ip6-icmp-input                  active               2               0          1.92e4 
ip6-input                       active               8               0          3.64e4 
ip6-local                       active               2               0          1.64e4 
ip6-lookup                      active               8               0          3.54e4 
ip6-miss                        active               6               0          4.69e4 
udp-input                       active             505               0          2.43e4 
unix-cli-stdin                  active               0              15          0.00e0 
unix-epoll-input                polling              0               0          2.95e7 

[note: output from a debug image processing 0.1 PPS, the per-node runtime statistics are not worth the paper they're not printed on...]

packet tracer

The packet tracer is your friend. If the vnet stack is dropping traffic, turn on the packet tracer and see why. First, identify the input node from which the traffic originates. See also "show run". In that case, we see that traffic originates from "ige-input", the e1000 driver rx graph node. Other choices: "pg-input" [packet generator], "ixge-input" [Intel 82599 physical function driver], "ixgev-input" [Intel 82599 virtual function driver], and "tuntap-rx" [tun/tap driver].

vpp# trace add ige-input 1

To display the traced packets:

vpp# show trace
Packet 1
00:00:56:143358: ige-input
 GigabitEthernet2/0/0 rx queue 0
 before: sw-owned, length this descriptor 102, end-of-packet
         ip4 checksum ok, tcp checksum ok
 buffer 0x3180: current data 14, length 88, free-list 14, trace 0x4
 IP4: 00:50:56:b7:7c:8f -> 00:50:56:b7:7c:83
 ICMP: 6.0.0.1 -> 6.0.0.2
   tos 0x00, ttl 64, length 84, checksum 0x2ea7
   fragment id 0x0000, flags DONT_FRAGMENT
 ICMP echo_request checksum 0x66d6
00:00:56:143400: ip4-input-no-checksum
 ICMP: 6.0.0.1 -> 6.0.0.2
   tos 0x00, ttl 64, length 84, checksum 0x2ea7
   fragment id 0x0000, flags DONT_FRAGMENT
 ICMP echo_request checksum 0x66d6
00:00:56:143427: ip4-local
 adjacency: local 6.0.0.2/24
00:00:56:143434: ip4-icmp-input
 ICMP: 6.0.0.1 -> 6.0.0.2
   tos 0x00, ttl 64, length 84, checksum 0x2ea7
   fragment id 0x0000, flags DONT_FRAGMENT
 ICMP echo_request checksum 0x66d6
00:00:56:143437: ip4-icmp-echo-request
 ICMP: 6.0.0.1 -> 6.0.0.2
   tos 0x00, ttl 64, length 84, checksum 0x2ea7
   fragment id 0x0000, flags DONT_FRAGMENT
 ICMP echo_request checksum 0x66d6
00:00:56:143444: ip4-rewrite-local
 adjacency: GigabitEthernet2/0/0
            IP4: 00:50:56:b7:7c:83 -> 00:50:56:b7:7c:8f
 IP4: 00:50:56:b7:7c:83 -> 00:50:56:b7:7c:8f
 ICMP: 6.0.0.2 -> 6.0.0.1
   tos 0x00, ttl 64, length 84, checksum 0xa226
   fragment id 0x8c80, flags DONT_FRAGMENT
 ICMP echo_reply checksum 0x6ed6
00:00:56:143447: GigabitEthernet2/0/0-output
 GigabitEthernet2/0/0
 IP4: 00:50:56:b7:7c:83 -> 00:50:56:b7:7c:8f
 ICMP: 6.0.0.2 -> 6.0.0.1
   tos 0x00, ttl 64, length 84, checksum 0xa226
   fragment id 0x8c80, flags DONT_FRAGMENT
 ICMP echo_reply checksum 0x6ed6
00:00:56:143450: GigabitEthernet2/0/0-tx
 GigabitEthernet2/0/0 tx queue 0
 descriptor: buffer 0x100c03200, 102 bytes this buffer
             eop, insert-fcs, 
 buffer 0x3180: current data 0, length 102, free-list 14, trace 0x4
 IP4: 00:50:56:b7:7c:83 -> 00:50:56:b7:7c:8f
 ICMP: 6.0.0.2 -> 6.0.0.1
   tos 0x00, ttl 64, length 84, checksum 0xa226
   fragment id 0x8c80, flags DONT_FRAGMENT
 ICMP echo_reply checksum 0x6ed6

Each graph node can contribute to the per-packet trace.

To clear the packet trace buffer, use "clear trace"

vpp# clear trace

command scripts

The "exec" command feeds the contents of a file to the parser:

vpp# exec /tmp/commands

Erroneous commands will result in complaints on stderr. Processing will continue.

API trace and client commands

If you've enabled API message tracing, you can save the current trace buffer to /tmp/<filename>, as follows:

vpp# api trace save <filename>

In more detail, the API trace command has the following syntax:

api trace [on|off][dump|save|replay <file>][status][free][post-mortem-on][post-mortem-off]

If API tracing is enabled and the vpp engine crashes, it makes every effort to save the current API trace to /tmp/api_post_mortem.<pid>. Enable API tracing from the beginning of time via this command line argument.

If misbehavior of the vpp engine control-plane APIs is suspected, please include a full API trace with the report. Given a reasonably similar image, we can reproduce complex multi-step issues in a few seconds.

To display the current set of connected API clients, use:

vpp# show api clients

To display statistics for the fast API message ring allocator, use:

vpp# show api ring-stats

NB the "ring miss fallback allocation" counter. If it's going through the roof, something is wrong.

connect to a tap device

To connect to a Linux "tap" device, use the "tap connect" CLI command:

vpp# tap connect <linux-tap-intfc-name> [hwaddr [<eth-addr> | random]]

Specify <eth-addr> in "xx:xx:xx:xx:xx:xx" or "xxyy.xxyy.xxyy" format. "Random" MAC addresses use the current time to seed a known-good 32-bit LCRN. Caveat emptor.

By default, the hwaddr matches the Linux device. This can easily cause confusion when placing the tap device into a Linux virtual bridge.

Display software version stamps

Depending on the application, multiple library and application version stamps may be available. The vlib shared-library should have a version stamp.

VPE: show version vlib
vlib built by dbarach on ludd-cluster-1 at Thu Aug  1 16:02:45 2013
VPE: show version help
 vlib                           show version information for vlib
 vpe                            show version information for vpe

Experimental commands

Use these commands at your own risk, and never in a production setting. These commands are intended only for experimental purposes.

ipv6 segment routing commands

Ipv6 segment routing can be used in much the same way as MPLS traffic engineering. The scheme is to add an ipv6 type 4 routing extension header which carries a list of "segments" which each participating ipv6 router / end station consults when forwarding or otherwise processing packets.

As of this writing, the code is available only in the *sr* nightly build image.

To create an SR tunnel, use the "sr tunnel" debug CLI:

sr tunnel [del] <src> <dst>/<mask-width> [next <addr>]+ [tag <addr>] [table <FIB-id>] 
          [clean] [reroute]

"tag" stanzas comprise 128-bit chunks of arbitrary data (phrased as a set of ipv6 addresses) which are not otherwise processed by the sr implementation. Suggested uses include tagging segment routed packets with the original entry router's ipv6 address, appending security cookies, etc.

Here's an actual configuration example. In this case we set up a tunnel so that an adjacent ipv6 enabled system w/ address db02::1 pings db04::1 through an sr tunnel:

set int ip address GigabitEthernet2/2/0 db02::2/64
set int state GigabitEthernet2/2/0 up

set int ip address GigabitEthernet2/0/0 db03::2/64
set int state GigabitEthernet2/0/0 up

sr tunnel src db02::1 dst db04::1/128 next db03::1 next db04::1 tag db02::2 clean

To display all known sr tunnels, use the "show sr tunnel" debug CLI:

show sr tunnel

For more information about ipv6 segment routing, refer to Stefano Previdi's slide deck and word doc.

Here's the API message which one can use to add/delete SR tunnels

define sr_tunnel_add_del {
   u32 client_index;
   u32 context;
   u8 is_add;
   u8 src_address[16];
   u8 dst_address[16];
   u8 dst_mask_width;
   u32 vrf_id;
   u8 flags;
   u8 n_segments;
   u8 n_tags;
   u8 segs_and_tags[0];
};

Here is a bit of C-code from .../closed-repo/vpe/api/test_client.c which can add or delete a specific SR tunnel:

void sr_add_del (test_main_t *tm, u8 is_add)
{
   vl_api_sr_tunnel_add_del_t * mp;
   ip6_address_t *segs;
    
   mp = vl_msg_api_alloc (sizeof(*mp) + 3*sizeof(ip6_address_t));
   memset(mp, 0, sizeof (*mp) + 3*sizeof(ip6_address_t));
   mp->_vl_msg_id = ntohs (VL_API_SR_TUNNEL_ADD_DEL);
   mp->client_index = tm->my_client_index;
   mp->context = 0xdeadbeef;
   mp->is_add = is_add;
   /* src: db01::1 */
   mp->src_address[0] = 0xdb;
   mp->src_address[1] = 0x01;
   mp->src_address[15] = 1;
   /* dst: db02::1/64 */
   mp->dst_address[0] = 0xdb;
   mp->dst_address[1] = 0x02;
   mp->dst_address[15] = 1;
   mp->dst_mask_width = 64;
   
   mp->vrf_id = ntohl(0);
   mp->flags = 0x80;           /* IP6_SR_HEADER_FLAG_CLEANUP */
       
   mp->n_segments = 2;
   mp->n_tags = 1;
    
   segs = (ip6_address_t *)mp->segs_and_tags;
       
   segs->as_u8[0] = 0xdb;
   segs->as_u8[1] = 0x03;
   segs->as_u8[15] = 1;
   segs++;
   
   segs->as_u8[0] = 0xdb;
   segs->as_u8[1] = 0x04;
   segs->as_u8[15] = 1;
   segs++;
   
   segs->as_u8[0] = 0xdb;
   segs->as_u8[1] = 0x01;
   segs->as_u8[15] = 2;
     
   vl_msg_api_send_shmem (tm->vl_input_queue, (u8 *)&mp);
}