diff options
Diffstat (limited to 'docs/cli-reference/interface')
| -rw-r--r-- | docs/cli-reference/interface/basic.rst | 83 | ||||
| -rw-r--r-- | docs/cli-reference/interface/create_interface.rst | 223 | ||||
| -rw-r--r-- | docs/cli-reference/interface/hardware.rst | 161 | ||||
| -rw-r--r-- | docs/cli-reference/interface/index.rst | 17 | ||||
| -rw-r--r-- | docs/cli-reference/interface/setinterface.rst | 182 |
5 files changed, 666 insertions, 0 deletions
diff --git a/docs/cli-reference/interface/basic.rst b/docs/cli-reference/interface/basic.rst new file mode 100644 index 00000000000..2d4202dfc57 --- /dev/null +++ b/docs/cli-reference/interface/basic.rst @@ -0,0 +1,83 @@ +.. _interface: + +.. toctree:: + +Basic Interface Commands +========================= + +There are several commands that are associated to Basic Interface: + +* `Show Interface`_ +* `Clear Interfaces`_ + +.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ . + +.. _showintcommand: + +Show Interface +++++++++++++++++ +Shows software interface information including counters and features. + +.. code-block:: shell + + show interface [address|addr|features|feat] [<interface> [<interface> [..]]] + +Examples +-------- + +Example of how to show the interface counters: + +.. code-block:: console + + vpp# show int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 up rx packets 6569213 + rx bytes 9928352943 + tx packets 50384 + tx bytes 3329279 + TenGigabitEthernet86/0/1 2 down + VirtualEthernet0/0/0 3 up rx packets 50384 + rx bytes 3329279 + tx packets 6569213 + tx bytes 9928352943 + drops 1498 + local0 0 down + +Example of how to display the interface placement: + +.. code-block:: console + + vpp# 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) + +Clear Interfaces ++++++++++++++++++ +Clear the statistics for all interfaces (statistics associated with the +'*show interface*' command). + +.. code-block:: shell + + clear interfaces + +Example +------- +Example of how to clear the statistics for all interfaces: + +.. code-block:: console + + vpp# clear interfaces diff --git a/docs/cli-reference/interface/create_interface.rst b/docs/cli-reference/interface/create_interface.rst new file mode 100644 index 00000000000..abd1f40de04 --- /dev/null +++ b/docs/cli-reference/interface/create_interface.rst @@ -0,0 +1,223 @@ +.. _interface: + +.. toctree:: + +Create Interfaces Commands +=========================== +This section contains those interface commands that are associated to creating an interface: + +* `Create Host-Interface`_ +* `Create Interface Memif`_ +* `Create Loopback Interface`_ +* `Create Sub-Interfaces`_ + +.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ . + +Create Host-Interface +++++++++++++++++++++++ + +.. code-block:: console + + create host-interface name <*ifname*> [*hw-addr <*mac-addr*>] + + +Description +------------ + +Create a host interface that will attach to a linux AF_PACKET interface, one side of a veth pair. +The veth pair must already exist. Once created, a new host interface will exist in VPP with the name +'host-<*ifname*>', where '<*ifname*>' is the name of the specified veth pair. +Use the `show interface` command to display host interface details. + +This command has the following optional parameters: + + hw-addr <*mac-addr*> - Optional ethernet address, can be in either X:X:X:X:X:X unix or X.X.X cisco format + +Example Usage +------------- + +Example of how to create a host interface tied to one side of an existing linux veth pair named vpp1: + + .. code-block:: console + + vpp# create host-interface name vpp1 + + host-vpp1 + +Once the host interface is created, enable the interface using: + + .. code-block:: console + + vpp# set interface state host-vpp1 up + +Declaration and Implementation +------------------------------- + +**Declaration:** af_packet_create_command (src/vnet/devices/af_packet/cli.c line 133) + +**Implementation:** af_packet_create_command_fn + +Create Interface Memif ++++++++++++++++++++++++ + +.. code-block:: console + + create interface memif [id <*id*>] [socket-id <*socket-id*>] [ring-size <*size*>] [buffer-size <*size*>] [hw-addr <*mac-address*>] <master|slave> [rx-queues <*number*>] [tx-queues <*number*>] [mode ip] [secret <*string*>] + + +Declaration and Implementation +------------------------------- + +**Declaration:** memif_create_command (src/plugins/memif/cli.c line 258) + +**Implementation:** memif_create_command_fn + + +Create Loopback Interface +++++++++++++++++++++++++++ + + +Create a loopback interface. Optionally, a MAC Address can be provided. If not provided, de:ad:00:00:00:<*loopId*> will be used. + +.. code-block:: console + + create loopback interface [mac <*mac-addr*>] [instance <*instance*>] + + +Example Usage +-------------- +The following two command syntaxes are equivalent: + + .. code-block:: console + + vpp# loopback create-interface [mac <*mac-addr*>] [instance <*instance*>] + + vpp# create loopback interface [mac <*mac-addr*>] [instance <*instance*>] + +Example of how to create a loopback interface: + + .. code-block:: console + + vpp# create loopback interface + +Declaration and Implementation +------------------------------- + +**Declaration:** create_loopback_interface_command (src/vnet/ethernet/interface.c line 879) + +**Implementation:** create_simulated_ethernet_interfaces + + +Create Sub-Interfaces +++++++++++++++++++++++ + +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 explicitly specify the outer VLAN ID, + 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. + +Summary/Usage +------------- + +.. code-block:: shell + + create sub-interfaces <interface> {<subId> [default|untagged]} | {<subId>-<subId>} | {<subId> dot1q|dot1ad <vlanId>|any [inner-dot1q <vlanId>|any] [exact-match]} + +Example Usage +-------------- + +Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11: + +.. code-block:: console + + vpp# create sub-interfaces GigabitEthernet2/0/0 11 + +The previous example is shorthand and is equivalent to: + +.. code-block:: console + + vpp# 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 + + vpp# 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 + + vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200 + vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any + +Examples of how to create dot1ad interfaces: + +.. code-block:: console + + vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11 + vpp# 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 + + vpp# 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 + + vpp# 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 + + vpp# 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 + + vpp# 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 + + vpp# set interface GigabitEthernet2/0/0.7 up + diff --git a/docs/cli-reference/interface/hardware.rst b/docs/cli-reference/interface/hardware.rst new file mode 100644 index 00000000000..0d124385fac --- /dev/null +++ b/docs/cli-reference/interface/hardware.rst @@ -0,0 +1,161 @@ +.. _interface: + +.. toctree:: + +Hardware-Interfaces Commands +============================ +This section contains those interface commands that are related to hardware-interfaces: + + +* `Show Bridge-Domain`_ +* `Show Hardware-Interfaces`_ +* `Clear Hardware-Interfaces`_ + +.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ . + +Show Bridge-Domain ++++++++++++++++++++ + +Show a summary of all the bridge-domain instances or detailed view of a single bridge-domain. +Bridge-domains are created by adding an interface to a bridge using the **set interface l2 bridge** command. + + +.. code-block:: console + + show bridge-domain [*bridge-domain-id* [detail|int|arp| *bd-tag* ]] + + +Example Usage +------------- +.. code-block:: console + + Example of displaying all bridge-domains: + + vpp# show bridge-domain + + ID Index Learning U-Forwrd UU-Flood Flooding ARP-Term BVI-Intf + 0 0 off off off off off local0 + 200 1 on on on on off N/A + + Example of displaying details of a single bridge-domains: + + vpp# show bridge-domain 200 detail + + ID Index Learning U-Forwrd UU-Flood Flooding ARP-Term BVI-Intf + 200 1 on on on on off N/A + + Interface Index SHG BVI VLAN-Tag-Rewrite + GigabitEthernet0/8/0.200 3 0 - none + GigabitEthernet0/9/0.200 4 0 - none + +Declaration and Implementation +------------------------------ + +**Declaration:** bd_show_cli (src/vnet/l2/l2_bd.c line 1151) + +**Implementation:** bd_show + +Show Hardware-Interfaces ++++++++++++++++++++++++++ +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. + +.. note:: + To limit the output of the command to bonded interfaces and their + slave interfaces, use the '*bond*' optional parameter. + + +.. code-block:: shell + + show hardware-interfaces [brief|verbose|detail] [bond] [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]]. + + +Examples +-------- +Example of how to display default data for all interfaces: + +.. code-block:: console + + vpp# 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 + + vpp# 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 + +Clear Hardware-Interfaces ++++++++++++++++++++++++++ + +Clear the extended statistics for all or a list of given interfaces +(statistics associated with the **show hardware-interfaces** command). + + +.. code-block:: shell + + clear hardware-interfaces [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]]. + + +Examples +-------- + +Example of how to clear the extended statistics for all interfaces: + + +.. code-block:: console + + vpp# 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 + + vpp# clear hardware-interfaces GigabitEthernet7/0/0 2 + + diff --git a/docs/cli-reference/interface/index.rst b/docs/cli-reference/interface/index.rst new file mode 100644 index 00000000000..7fca8f11df2 --- /dev/null +++ b/docs/cli-reference/interface/index.rst @@ -0,0 +1,17 @@ +.. _interface: + +.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ . + +.. _intcommands: + +Interface Commands +================== +This section identifies the following types of interface commands: + +.. toctree:: + :maxdepth: 2 + + basic + hardware + create_interface + setinterface diff --git a/docs/cli-reference/interface/setinterface.rst b/docs/cli-reference/interface/setinterface.rst new file mode 100644 index 00000000000..7eb14adf455 --- /dev/null +++ b/docs/cli-reference/interface/setinterface.rst @@ -0,0 +1,182 @@ +====================== +Set Interface Commands +====================== + +This section covers those commands that are related to setting an +interface: + +- `Set Interface IP Address <#set-interface-ip-address>`__ +- `Set Interface L2 Bridge <#set-interface-l2-bridge>`__ +- `Set Interface MTU <#set-interface-mtu>`__ +- `Set Interface Promiscuous <#set-interface-promiscuous>`__ +- `Set Interface State <#set-interface-state>`__ + +.. note:: + + For a complete list of CLI Debug commands refer to the Debug CLI + section of the `Source Code + Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`__ . + +Set Interface IP Address +======================== + +.. code:: console + + set interface ip address [del] <*interface*> <*ip-addr*>/<*mask*> | [all] + +Add an IP Address to an interface or remove and IP Address from an +interface. The IP Address can be an IPv4 or an IPv6 address. Interfaces +may have multiple IPv4 and IPv6 addresses. There is no concept of +primary vs. secondary interface addresses; they're just addresses. + +To display the addresses associated with a given interface, use the +command **show interface address** <*interface*>. + +.. note:: + + The debug CLI does not enforce classful mask-width / addressing + constraints. + +Example Usage +------------- + +An example of how to add an IPv4 address to an interface: + +.. code:: console + + vpp# set interface ip address GigabitEthernet2/0/0 172.16.2.12/24 + +An example of how to add an IPv6 address to an interface: + +.. code:: console + + vpp# set interface ip address GigabitEthernet2/0/0 ::a:1:1:0:7/126 + +To delete a specific interface ip address: + +.. code:: console + + vpp# set interface ip address GigabitEthernet2/0/0 172.16.2.12/24 del + +To delete all interfaces addresses (IPv4 and IPv6): + +.. code:: console + + vpp# set interface ip address GigabitEthernet2/0/0 del all + +Declaration and Implementation +------------------------------ + +**Declaration:** set_interface_ip_address_command +(src/vnet/ip/ip46_cli.c line 216) + +**Implementation:** add_del_ip_address + +Set Interface L2 Bridge +======================= + +.. code:: console + + set interface l2 bridge <*interface*> <*bridge-domain-id*> [bvi|uu-fwd] + [shg] + +Use this command put an interface into Layer 2 bridge domain. If a +bridge-domain with the provided bridge-domain-id does not exist, it will +be created. Interfaces in a bridge-domain forward packets to other +interfaces in the same bridge-domain based on destination mac address. +To remove an interface from a the Layer 2 bridge domain, put the +interface in a different mode, for example Layer 3 mode. + +Optionally, an interface can be added to a Layer 2 bridge-domain as a +Bridged Virtual Interface (bvi). Only one interface in a Layer 2 +bridge-domain can be a bvi. + +Optionally, a split-horizon group can also be specified. This defaults +to 0 if not specified. + +.. _example-usage-1: + +Example Usage +------------- + +Example of how to configure a Layer 2 bridge-domain with three +interfaces (where 200 is the bridge-domain-id): + +.. code:: console + + vpp# set interface l2 bridge GigabitEthernet0/8/0.200 200 + +This interface is added a BVI interface: + +.. code:: console + + vpp# set interface l2 bridge GigabitEthernet0/9/0.200 200 bvi + +This interface also has a split-horizon group of 1 specified: + +.. code:: console + + vpp# set interface l2 bridge GigabitEthernet0/a/0.200 200 1 + +Example of how to remove an interface from a Layer2 bridge-domain: + +.. code:: console + + vpp# set interface l3 GigabitEthernet0/a/0.200 + +.. _declaration-and-implementation-1: + +Declaration and Implementation +------------------------------ + +**Declaration:** int_l2_bridge_cli (src/vnet/l2/l2_input.c line 949) + +**Implementation:** int_l2_bridge + +Set Interface MTU +================= + +.. code:: shell + + set interface mtu [packet|ip4|ip6|mpls] <value> <interface> + +Set Interface Promiscuous +========================= + +.. code:: shell + + set interface promiscuous [on|off] <interface>. + +.. _setintstate: + +Set Interface State +=================== + +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). + +.. code:: shell + + set interface state <interface> [up|down|punt|enable]. + +.. _example-usage-2: + +Example Usage +------------- + +Example of how to configure the admin state of an interface to **up**: + +.. code:: console + + vpp# set interface state GigabitEthernet2/0/0 up + +Example of how to configure the admin state of an interface to **down**: + +.. code:: console + + vpp# set interface state GigabitEthernet2/0/0 down |