summaryrefslogtreecommitdiffstats
path: root/docs/cli-reference/interface
diff options
context:
space:
mode:
Diffstat (limited to 'docs/cli-reference/interface')
-rw-r--r--docs/cli-reference/interface/basic.rst83
-rw-r--r--docs/cli-reference/interface/create_interface.rst223
-rw-r--r--docs/cli-reference/interface/hardware.rst161
-rw-r--r--docs/cli-reference/interface/index.rst17
-rw-r--r--docs/cli-reference/interface/setinterface.rst182
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