.. _clicmd_src_vnet: =============================================================== Interface =============================================================== clear hardware-interfaces ------------------------------------------------------------------------- .. code-block:: console clear hardware-interfaces [ [ [..]]] [ [ [..]]] 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: .. code-block:: console 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): .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console clear interface tag Declaration: ``clear_tag_command`` `src/vnet/interface_cli.c line 1463 `_ Implementation: ``clear_tag`` clear interfaces ------------------------------------------------------------------------- .. code-block:: console 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: .. code-block:: console clear interfaces Declaration: ``clear_interface_counters_command`` `src/vnet/interface_cli.c line 581 `_ Implementation: ``clear_interface_counters`` create sub-interfaces ------------------------------------------------------------------------- .. code-block:: console create sub-interfaces { [default|untagged]} | {-} | { dot1q|dot1ad |any [inner-dot1q |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 ** - Create a subinterface to process packets with a given 802.1q VLAN ID (same value as the ``subId``). - **create sub-interfaces 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 untagged** - Adding the ``untagged`` parameter indicates that packets no VLAN IDs should be sent to this subinterface. - **create sub-interfaces -** - Create a range of subinterfaces to handle a range of VLAN IDs. - **create sub-interfaces dot1q|dot1ad |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 dot1q|dot1ad |any inner-dot1q |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: .. code-block:: console create sub-interfaces GigabitEthernet2/0/0 11 The previous example is shorthand and is equivalent to: .. code-block:: console 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: .. code-block:: console create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 Examples of how to create q-in-q and q-in-any subinterfaces: .. code-block:: console create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200 .. code-block:: console create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any Examples of how to create dot1ad interfaces: .. code-block:: console create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11 .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match Example of how to created a subinterface to process untagged packets: .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console set interface GigabitEthernet2/0/0.7 up Declaration: ``create_sub_interfaces_command`` `src/vnet/interface_cli.c line 912 `_ Implementation: ``create_sub_interfaces`` interface ------------------------------------------------------------------------- .. code-block:: console Interface commands Declaration: ``vnet_cli_interface_command`` `src/vnet/interface_cli.c line 528 `_ interface collect detailed-stats ------------------------------------------------------------------------- .. code-block:: console interface collect detailed-stats Declaration: ``collect_detailed_interface_stats_command`` `src/vnet/interface.c line 1944 `_ Implementation: ``collect_detailed_interface_stats_cli`` pcap trace ------------------------------------------------------------------------- .. code-block:: console pcap trace [rx] [tx] [drop] [off] [max ] [intfc |any] [file ] [status] [max-bytes-per-pkt ][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 ** - 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 ** - 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 |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 .** - filter packets based on a specific error. For example: error {ip4-udp-lookup}.{No listener for dst port} - **file ** - 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: .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console renumber interface Declaration: ``renumber_interface_command`` `src/vnet/interface_cli.c line 1119 `_ Implementation: ``renumber_interface_command_fn`` set interface ------------------------------------------------------------------------- .. code-block:: console Interface commands Declaration: ``vnet_cli_set_interface_command`` `src/vnet/interface_cli.c line 535 `_ set interface handoff ------------------------------------------------------------------------- .. code-block:: console set interface handoff workers [symmetrical|asymmetrical] Declaration: ``set_interface_handoff_command`` `src/vnet/handoff.c line 314 `_ Implementation: ``set_interface_handoff_command_fn`` set interface hw-class ------------------------------------------------------------------------- .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console set interface enable 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 ------------------------------------------------------------------------- .. code-block:: console set 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: .. code-block:: console set interface mac address GigabitEthernet0/8/0 aa:bb:cc:dd:ee:01 .. code-block:: console set interface mac address host-vpp0 aa:bb:cc:dd:ee:02 .. code-block:: console set interface mac address tap-0 aa:bb:cc:dd:ee:03 .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console set interface mtu [packet|ip4|ip6|mpls] Declaration: ``set_interface_mtu_cmd`` `src/vnet/interface_cli.c line 1212 `_ Implementation: ``mtu_cmd`` set interface name ------------------------------------------------------------------------- .. code-block:: console set interface name Declaration: ``cmd_set_if_name`` `src/vnet/interface_cli.c line 2484 `_ Implementation: ``set_interface_name`` set interface promiscuous ------------------------------------------------------------------------- .. code-block:: console set interface promiscuous [on|off] Declaration: ``set_interface_promiscuous_cmd`` `src/vnet/interface_cli.c line 1155 `_ Implementation: ``promiscuous_cmd`` set interface rss queues ------------------------------------------------------------------------- .. code-block:: console set interface rss queues > 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: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console set interface rx-mode [queue ] [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: .. code-block:: console set interface rx-mode VirtualEthernet0/0/12 polling Example of how to assign rx-mode to one queue of an interface: .. code-block:: console set interface rx-mode VirtualEthernet0/0/12 queue 0 interrupt Example of how to display the rx-mode of all interfaces: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console set interface rx-placement [queue ] [worker | 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: .. code-block:: console 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: .. code-block:: console set interface rx-placement VirtualEthernet0/0/12 queue 1 worker 0 Example of how to display the interface placement: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console set interface secondary-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: .. code-block:: console 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: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console set interface state [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``: .. code-block:: console set interface state GigabitEthernet2/0/0 up Example of how to configure the admin state of an interface to ``down``: .. code-block:: console set interface state GigabitEthernet2/0/0 down Declaration: ``set_state_command`` `src/vnet/interface_cli.c line 970 `_ Implementation: ``set_state`` set interface tag ------------------------------------------------------------------------- .. code-block:: console set interface tag Declaration: ``set_tag_command`` `src/vnet/interface_cli.c line 1439 `_ Implementation: ``set_tag`` set interface tx-hash ------------------------------------------------------------------------- .. code-block:: console set interface tx-hash 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 ------------------------------------------------------------------------- .. code-block:: console set interface tx-queue queue [threads ] Declaration: ``cmd_set_if_tx_queue`` `src/vnet/interface_cli.c line 1950 `_ Implementation: ``set_interface_tx_queue`` set interface unnumbered ------------------------------------------------------------------------- .. code-block:: console set interface unnumbered [ use | del ] Declaration: ``set_unnumbered_command`` `src/vnet/interface_cli.c line 1026 `_ Implementation: ``set_unnumbered`` show hardware-interfaces ------------------------------------------------------------------------- .. code-block:: console show hardware-interfaces [brief|verbose|detail] [bond] [ [ [..]]] [ [ [..]]] 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: .. code-block:: console 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): .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console show interface [address|addr|features|feat|vtr] [ [ [..]]] [verbose] Declaration: ``show_sw_interfaces_command`` `src/vnet/interface_cli.c line 518 `_ Implementation: ``show_sw_interfaces`` show interface rx-placement ------------------------------------------------------------------------- .. code-block:: console 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: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console show interface secondary-mac-address [] This command is used to display interface secondary mac addresses. Example of how to display interface secondary mac addresses: .. code-block:: console 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 ------------------------------------------------------------------------- .. code-block:: console show interface tx-hash [interface] Declaration: ``cmd_show_tx_hash`` `src/vnet/interface_cli.c line 2616 `_ Implementation: ``show_tx_hash``