Interface

clear hardware-interfaces

clear hardware-interfaces [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]]

Clear the extended statistics for all or a list of given interfaces (statistics associated with the show hardware-interfaces command).

Example of how to clear the extended statistics for all interfaces:

clear hardware-interfaces

Example of how to clear the extended statistics for an interface by name and software index (where 2 is the software index):

clear hardware-interfaces GigabitEthernet7/0/0 2

Declaration: clear_hw_interface_counters_command src/vnet/interface_cli.c line 272

Implementation: clear_hw_interfaces

clear interface tag

clear interface tag <interface>

Declaration: clear_tag_command src/vnet/interface_cli.c line 1463

Implementation: clear_tag

clear interfaces

clear interfaces

Clear the statistics for all interfaces (statistics associated with the show interface command).

Example of how to clear the statistics for all interfaces:

clear interfaces

Declaration: clear_interface_counters_command src/vnet/interface_cli.c line 581

Implementation: clear_interface_counters

create sub-interfaces

create sub-interfaces <interface> {<subId> [default|untagged]} | {<subId>-<subId>} | {<subId> dot1q|dot1ad <vlanId>|any [inner-dot1q <vlanId>|any] [exact-match]}

This command is used to add VLAN IDs to interfaces, also known as subinterfaces. The primary input to this command is the interface and subId (subinterface Id) parameters. If no additional VLAN ID is provide, the VLAN ID is assumed to be the subId. The VLAN ID and subId can be different, but this is not recommended.

This command has several variations:

  • create sub-interfaces <interface> <subId> - Create a subinterface to process packets with a given 802.1q VLAN ID (same value as the subId).

  • create sub-interfaces <interface> <subId> default - Adding the default parameter indicates that packets with VLAN IDs that do not match any other subinterfaces should be sent to this subinterface.

  • create sub-interfaces <interface> <subId> untagged - Adding the untagged parameter indicates that packets no VLAN IDs should be sent to this subinterface.

  • create sub-interfaces <interface> <subId>-<subId> - Create a range of subinterfaces to handle a range of VLAN IDs.

  • create sub-interfaces <interface> <subId> dot1q|dot1ad <vlanId>|any [exact-match] - Use this command to specify the outer VLAN ID, to either be explicit or to make the VLAN ID different from the subId.

  • create sub-interfaces <interface> <subId> dot1q|dot1ad <vlanId>|any inner-dot1q <vlanId>|any [exact-match] - Use this command to specify the outer VLAN ID and the inner VLAN ID.

When dot1q or dot1ad is explicitly entered, 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. If dot1q or dot1ad is NOT entered, then the default behavior is exact-match.

Use the show interface command to display all subinterfaces.

Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11:

create sub-interfaces GigabitEthernet2/0/0 11

The previous example is shorthand and is equivalent to:

create sub-interfaces GigabitEthernet2/0/0 11 dot1q 11 exact-match

Example of how to create a subinterface number that is different from the VLAN ID:

create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100

Examples of how to create q-in-q and q-in-any subinterfaces:

create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200

create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any

Examples of how to create dot1ad interfaces:

create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11

create sub-interfaces GigabitEthernet2/0/0 12 dot1ad 100 inner-dot1q 200

Examples of exact-match versus non-exact match. A packet with outer VLAN 100 and inner VLAN 200 would match this interface, because the default is non-exact match:

create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100

However, the same packet would NOT match this interface because exact-match is specified and only one VLAN is configured, but packet contains two VLANs:

create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match

Example of how to created a subinterface to process untagged packets:

create sub-interfaces GigabitEthernet2/0/0 5 untagged

Example of how to created a subinterface to process any packet with a VLAN ID that does not match any other subinterface:

create sub-interfaces GigabitEthernet2/0/0 7 default

When subinterfaces are created, they are in the down state. Example of how to enable a newly created subinterface:

set interface GigabitEthernet2/0/0.7 up

Declaration: create_sub_interfaces_command src/vnet/interface_cli.c line 912

Implementation: create_sub_interfaces

interface

Interface commands

Declaration: vnet_cli_interface_command src/vnet/interface_cli.c line 528

interface collect detailed-stats

interface collect detailed-stats <enable|disable>

Declaration: collect_detailed_interface_stats_command src/vnet/interface.c line 1944

Implementation: collect_detailed_interface_stats_cli

pcap trace

pcap trace [rx] [tx] [drop] [off] [max <nn>] [intfc <interface>|any]
           [file <name>] [status] [max-bytes-per-pkt <nnnn>][filter]
           [preallocate-data][free-data]

This command is used to start or stop a packet capture, or show the status of packet capture.

This command has the following optional parameters:

  • rx - Capture received packets

  • tx - Capture transmitted packets

  • drop - Capture dropped packets

  • off - Stop capturing packets, write results to the specified file

  • max <nn> - Depth of local buffer. Once nn number

    of packets have been received, buffer is flushed to file. Once another nn number of packets have been received, buffer is flushed to file, overwriting previous write. If not entered, value defaults to 100. Can only be updated if packet capture is off.

  • max-bytes-per-pkt <nnnn> - Maximum number of bytes to capture

    for each packet. Must be >= 32, <= 9000.

  • preallocate-data - Preallocate the data buffer, to avoid

    vector expansion delays during pcap capture

  • free-data - Free the data buffer. Ordinarily it’s a feature

    to retain the data buffer so this option is seldom used.

  • intfc <interface-name>|any - Used to specify a given interface,

    or use any to run packet capture on all interfaces. any is the default if not provided. Settings from a previous packet capture are preserved, so any can be used to reset the interface setting.

  • filter - Use the pcap rx / tx / drop trace filter, which

    must be configured. Use classify filter pcap… to configure the filter. The filter will only be executed if the per-interface or any-interface tests fail.

  • error <node>.<error> - filter packets based on a specific error.

    For example: error {ip4-udp-lookup}.{No listener for dst port}

  • file <name> - Used to specify the output filename. The file will

    be placed in the /tmp directory, so only the filename is supported. Directory should not be entered. If file already exists, file will be overwritten. If no filename is provided, the file will be named “/tmp/rx.pcap”, “/tmp/tx.pcap”, “/tmp/rxandtx.pcap”, etc. Can only be updated if packet capture is off.

  • status - Displays the current status and configured attributes

    associated with a packet capture. If packet capture is in progress, status also will return the number of packets currently in the local buffer. All additional attributes entered on command line with status will be ignored and not applied.

Example of how to display the status of a tx packet capture when off:

pcap trace status

max is 100, for any interface to file /tmp/vpe.pcap
pcap tx capture is off...

Example of how to start a tx packet capture:

pcap trace tx max 35 intfc GigabitEthernet0/8/0 file vppTest.pcap

Example of how to display the status of a tx packet capture in progress:

pcap trace status

max is 35, for interface GigabitEthernet0/8/0 to file /tmp/vppTest.pcap
pcap tx capture is on: 20 of 35 pkts...

Example of how to stop a tx packet capture:

pcap trace off

captured 21 pkts...
saved to /tmp/vppTest.pcap...

Declaration: pcap_tx_trace_command src/vnet/interface_cli.c line 2431

Implementation: pcap_trace_command_fn

renumber interface

renumber interface <interface> <new-dev-instance>

Declaration: renumber_interface_command src/vnet/interface_cli.c line 1119

Implementation: renumber_interface_command_fn

set interface

Interface commands

Declaration: vnet_cli_set_interface_command src/vnet/interface_cli.c line 535

set interface handoff

set interface handoff <interface-name> workers <workers-list> [symmetrical|asymmetrical]

Declaration: set_interface_handoff_command src/vnet/handoff.c line 314

Implementation: set_interface_handoff_command_fn

set interface hw-class

Set interface hardware class

Declaration: set_hw_class_command src/vnet/interface_cli.c line 1069

Implementation: set_hw_class

set interface ip directed-broadcast

set interface enable <interface> <enable|disable>

This command is used to enable/disable IP directed broadcast If directed broadcast is enabled a packet sent to the interface’s subnet broadcast address will be sent L2 broadcast on the interface, otherwise it is dropped.

Declaration: set_ip_directed_broadcast_command src/vnet/interface_cli.c line 1503

Implementation: set_ip_directed_broadcast

set interface mac address

set interface mac address <interface> <mac-address>

The set interface mac address command allows to set MAC address of given interface. In case of NIC interfaces the one has to support MAC address change. A side effect of MAC address change are changes of MAC addresses in FIB tables (ipv4 and ipv6).

Example of how to change MAC Address of interface:

set interface mac address GigabitEthernet0/8/0 aa:bb:cc:dd:ee:01

set interface mac address host-vpp0 aa:bb:cc:dd:ee:02

set interface mac address tap-0 aa:bb:cc:dd:ee:03

set interface mac address pg0 aa:bb:cc:dd:ee:04

Declaration: set_interface_mac_address_cmd src/vnet/interface_cli.c line 1414

Implementation: set_interface_mac_address

set interface mtu

set interface mtu [packet|ip4|ip6|mpls] <value> <interface>

Declaration: set_interface_mtu_cmd src/vnet/interface_cli.c line 1212

Implementation: mtu_cmd

set interface name

set interface name <interface-name> <new-interface-name>

Declaration: cmd_set_if_name src/vnet/interface_cli.c line 2484

Implementation: set_interface_name

set interface promiscuous

set interface promiscuous [on|off] <interface>

Declaration: set_interface_promiscuous_cmd src/vnet/interface_cli.c line 1155

Implementation: promiscuous_cmd

set interface rss queues

set interface rss queues <interface> <list <queue-list>>

This command is used to set the rss queues of a given interface Not all the interfaces support this operation. To display the current rss queues, use the command show hardware-interfaces.

Example of how to set the rss queues to 0,2-5,7 of an interface:

set interface rss queues VirtualFunctionEthernet18/1/0 list 0,2-5,7

Declaration: cmd_set_interface_rss_queues src/vnet/interface_cli.c line 2034

Implementation: set_interface_rss_queues_fn

set interface rx-mode

set interface rx-mode <interface> [queue <n>] [polling | interrupt | adaptive]

This command is used to assign the RX packet processing mode (polling, interrupt, adaptive) of the a given interface, and optionally a given queue. If the queue is not provided, the mode is applied to all queues of the interface. Not all interfaces support all modes. To display the current rx-mode use the command show interface rx-placement.

Example of how to assign rx-mode to all queues on an interface:

set interface rx-mode VirtualEthernet0/0/12 polling

Example of how to assign rx-mode to one queue of an interface:

set interface rx-mode VirtualEthernet0/0/12 queue 0 interrupt

Example of how to display the rx-mode of all interfaces:

show interface rx-placement

Thread 1 (vpp_wk_0):
  node dpdk-input:
    GigabitEthernet7/0/0 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 0 (interrupt)
    VirtualEthernet0/0/12 queue 2 (polling)
    VirtualEthernet0/0/13 queue 0 (polling)
    VirtualEthernet0/0/13 queue 2 (polling)
Thread 2 (vpp_wk_1):
  node dpdk-input:
    GigabitEthernet7/0/1 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 1 (polling)
    VirtualEthernet0/0/12 queue 3 (polling)
    VirtualEthernet0/0/13 queue 1 (polling)
    VirtualEthernet0/0/13 queue 3 (polling)

Declaration: cmd_set_if_rx_mode src/vnet/interface_cli.c line 1638

Implementation: set_interface_rx_mode

set interface rx-placement

set interface rx-placement <interface> [queue <n>] [worker <n> | main]

This command is used to assign a given interface, and optionally a given queue, to a different thread. If the queue is not provided, it defaults to 0. The worker parameter is zero based and the index in the thread name, for example, 0 in the thread name vpp_wk_0.

Example of how to display the interface placement:

show interface rx-placement

Thread 1 (vpp_wk_0):
  node dpdk-input:
    GigabitEthernet7/0/0 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 0 (polling)
    VirtualEthernet0/0/12 queue 2 (polling)
    VirtualEthernet0/0/13 queue 0 (polling)
    VirtualEthernet0/0/13 queue 2 (polling)
Thread 2 (vpp_wk_1):
  node dpdk-input:
    GigabitEthernet7/0/1 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 1 (polling)
    VirtualEthernet0/0/12 queue 3 (polling)
    VirtualEthernet0/0/13 queue 1 (polling)
    VirtualEthernet0/0/13 queue 3 (polling)

Example of how to assign a interface and queue to a worker thread:

set interface rx-placement VirtualEthernet0/0/12 queue 1 worker 0

Example of how to display the interface placement:

show interface rx-placement

Thread 1 (vpp_wk_0):
  node dpdk-input:
    GigabitEthernet7/0/0 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 0 (polling)
    VirtualEthernet0/0/12 queue 1 (polling)
    VirtualEthernet0/0/12 queue 2 (polling)
    VirtualEthernet0/0/13 queue 0 (polling)
    VirtualEthernet0/0/13 queue 2 (polling)
Thread 2 (vpp_wk_1):
  node dpdk-input:
    GigabitEthernet7/0/1 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 3 (polling)
    VirtualEthernet0/0/13 queue 1 (polling)
    VirtualEthernet0/0/13 queue 3 (polling)

Declaration: cmd_set_if_rx_placement src/vnet/interface_cli.c line 1841

Implementation: set_interface_rx_placement

set interface secondary-mac-address

set interface secondary-mac-address <interface> <mac-address> [(add|del)]

The set interface secondary-mac-address command allows adding or deleting extra MAC addresses on a given interface without changing the default MAC address. This could allow packets sent to these MAC addresses to be received without setting the interface to promiscuous mode. Not all interfaces support this operation. The ones that do are mostly hardware NICs, though virtio does also.

Example of how to add a secondary MAC Address on an interface:

set interface secondary-mac-address GigabitEthernet0/8/0 aa:bb:cc:dd:ee:01 add

Example of how to delete a secondary MAC address from an interface:

set interface secondary-mac-address GigabitEthernet0/8/0 aa:bb:cc:dd:ee:01 del

Declaration: interface_add_del_mac_address_cmd src/vnet/interface_cli.c line 1364

Implementation: interface_add_del_mac_address

set interface state

set interface state <interface> [up|down|punt|enable]

This command is used to change the admin state (up/down) of an interface.

If an interface is down, the optional punt flag can also be set. The punt flag implies the interface is disabled for forwarding but punt all traffic to slow-path. Use the enable flag to clear punt flag (interface is still down).

Example of how to configure the admin state of an interface to

up:

set interface state GigabitEthernet2/0/0 up
Example of how to configure the admin state of an interface to

down:

set interface state GigabitEthernet2/0/0 down

Declaration: set_state_command src/vnet/interface_cli.c line 970

Implementation: set_state

set interface tag

set interface tag <interface> <tag>

Declaration: set_tag_command src/vnet/interface_cli.c line 1439

Implementation: set_tag

set interface tx-hash

set interface tx-hash <interface> hash-name <hash-name>

Declaration: cmd_set_if_tx_hash src/vnet/interface_cli.c line 2554

Implementation: set_interface_tx_hash_cmd

set interface tx-queue

set interface tx-queue <interface> queue <n> [threads <list>]

Declaration: cmd_set_if_tx_queue src/vnet/interface_cli.c line 1950

Implementation: set_interface_tx_queue

set interface unnumbered

set interface unnumbered [<interface> use <interface> | del <interface>]

Declaration: set_unnumbered_command src/vnet/interface_cli.c line 1026

Implementation: set_unnumbered

show hardware-interfaces

show hardware-interfaces [brief|verbose|detail] [bond] [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]]

Display more detailed information about all or a list of given interfaces. The verboseness of the output can be controlled by the following optional parameters:

  • brief: Only show name, index and state (default for bonded interfaces).

  • verbose: Also display additional attributes (default for all other interfaces).

  • detail: Also display all remaining attributes and extended statistics.

To limit the output of the command to bonded interfaces and their slave interfaces, use the bond optional parameter.

Example of how to display default data for all interfaces:

show hardware-interfaces

              Name                Idx   Link  Hardware
GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
  Ethernet address ec:f4:bb:c0:bc:fc
  Intel e1000
    carrier up full duplex speed 1000 mtu 9216
    rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
    cpu socket 0
GigabitEthernet7/0/1               2     up   GigabitEthernet7/0/1
  Ethernet address ec:f4:bb:c0:bc:fd
  Intel e1000
    carrier up full duplex speed 1000 mtu 9216
    rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
    cpu socket 0
VirtualEthernet0/0/0               3     up   VirtualEthernet0/0/0
  Ethernet address 02:fe:a5:a9:8b:8e
VirtualEthernet0/0/1               4     up   VirtualEthernet0/0/1
  Ethernet address 02:fe:c0:4e:3b:b0
VirtualEthernet0/0/2               5     up   VirtualEthernet0/0/2
  Ethernet address 02:fe:1f:73:92:81
VirtualEthernet0/0/3               6     up   VirtualEthernet0/0/3
  Ethernet address 02:fe:f2:25:c4:68
local0                             0    down  local0
  local

Example of how to display verbose data for an interface by name and software index (where 2 is the software index):

show hardware-interfaces GigabitEthernet7/0/0 2 verbose

              Name                Idx   Link  Hardware
GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
  Ethernet address ec:f4:bb:c0:bc:fc
  Intel e1000
    carrier up full duplex speed 1000 mtu 9216
    rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
    cpu socket 0
GigabitEthernet7/0/1               2    down  GigabitEthernet7/0/1
  Ethernet address ec:f4:bb:c0:bc:fd
  Intel e1000
    carrier up full duplex speed 1000 mtu 9216
    rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
    cpu socket 0

Declaration: show_hw_interfaces_command src/vnet/interface_cli.c line 251

Implementation: show_hw_interfaces

show interface

show interface [address|addr|features|feat|vtr] [<interface> [<interface> [..]]] [verbose]

Declaration: show_sw_interfaces_command src/vnet/interface_cli.c line 518

Implementation: show_sw_interfaces

show interface rx-placement

show interface rx-placement

This command is used to display the interface and queue worker thread placement.

Example of how to display the interface placement:

show interface rx-placement

Thread 1 (vpp_wk_0):
  node dpdk-input:
    GigabitEthernet7/0/0 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 0 (polling)
    VirtualEthernet0/0/12 queue 2 (polling)
    VirtualEthernet0/0/13 queue 0 (polling)
    VirtualEthernet0/0/13 queue 2 (polling)
Thread 2 (vpp_wk_1):
  node dpdk-input:
    GigabitEthernet7/0/1 queue 0 (polling)
  node vhost-user-input:
    VirtualEthernet0/0/12 queue 1 (polling)
    VirtualEthernet0/0/12 queue 3 (polling)
    VirtualEthernet0/0/13 queue 1 (polling)
    VirtualEthernet0/0/13 queue 3 (polling)

Declaration: show_interface_rx_placement src/vnet/interface_cli.c line 1710

Implementation: show_interface_rx_placement_fn

show interface secondary-mac-address

show interface secondary-mac-address [<interface>]

This command is used to display interface secondary mac addresses.

Example of how to display interface secondary mac addresses:

show interface secondary-mac-address

Declaration: show_interface_sec_mac_addr src/vnet/interface_cli.c line 1290

Implementation: show_interface_sec_mac_addr_fn

show interface tx-hash

show interface tx-hash [interface]

Declaration: cmd_show_tx_hash src/vnet/interface_cli.c line 2616

Implementation: show_tx_hash