docs/reference/cmdreference/interface/create_interface.rst

   1 .. _interface:
   2
   3 .. toctree::
   4
   5 Create Interfaces Commands
   6 ===========================
   7 This section contains those interface commands that are associated to creating an interface:
   8
   9 * `Create Host-Interface`_
  10 * `Create Interface Memif`_
  11 * `Create Loopback Interface`_
  12 * `Create Sub-Interfaces`_
  13
  14 .. 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>`_ .
  15
  16 Create Host-Interface
  17 ++++++++++++++++++++++
  18 Summary/Usage
  19 -------------
  20
  21 create host-interface name <*ifname*> [*hw-addr <*mac-addr*>]
  22
  23 Description
  24 ------------
  25
  26 Create a host interface that will attach to a linux AF_PACKET interface, one side of a veth pair.
  27 The veth pair must already exist. Once created, a new host interface will exist in VPP with the name
  28 'host-<*ifname*>', where '<*ifname*>' is the name of the specified veth pair.
  29 Use the `show interface` command to display host interface details.
  30
  31 This command has the following optional parameters:
  32
  33     hw-addr <*mac-addr*> - Optional ethernet address, can be in either X:X:X:X:X:X unix or X.X.X cisco format
  34
  35 Example Usage
  36 -------------
  37
  38 Example of how to create a host interface tied to one side of an existing linux veth pair named vpp1:
  39
  40         .. code-block:: console
  41
  42                 vpp# create host-interface name vpp1
  43
  44                 host-vpp1
  45
  46 Once the host interface is created, enable the interface using:
  47
  48         .. code-block:: console
  49
  50                 vpp# set interface state host-vpp1 up
  51
  52 Declaration and Implementation
  53 -------------------------------
  54
  55 **Declaration:** af_packet_create_command (src/vnet/devices/af_packet/cli.c line 133)
  56
  57 **Implementation:** af_packet_create_command_fn
  58
  59 Create Interface Memif
  60 +++++++++++++++++++++++
  61
  62 Summary/Usage
  63 -------------
  64
  65 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*>]
  66
  67 Declaration and Implementation
  68 -------------------------------
  69
  70 **Declaration:** memif_create_command (src/plugins/memif/cli.c line 258)
  71
  72 **Implementation:** memif_create_command_fn
  73
  74
  75 Create Loopback Interface
  76 ++++++++++++++++++++++++++
  77
  78 Summary/Usage
  79 --------------
  80
  81 create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
  82
  83 Description
  84 ------------
  85
  86 Create a loopback interface. Optionally, a MAC Address can be provided. If not provided, de:ad:00:00:00:<*loopId*> will be used.
  87
  88 Example Usage
  89 --------------
  90 The following two command syntaxes are equivalent:
  91
  92         .. code-block:: console
  93
  94                 vpp# loopback create-interface [mac <*mac-addr*>] [instance <*instance*>]
  95
  96                 vpp# create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
  97
  98 Example of how to create a loopback interface:
  99
 100         .. code-block:: console
 101
 102                 vpp# create loopback interface
 103
 104 Declaration and Implementation
 105 -------------------------------
 106
 107 **Declaration:** create_loopback_interface_command (src/vnet/ethernet/interface.c line 879)
 108
 109 **Implementation:** create_simulated_ethernet_interfaces
 110
 111
 112 Create Sub-Interfaces
 113 ++++++++++++++++++++++
 114
 115 This command is used to add VLAN IDs to interfaces, also known as
 116 subinterfaces. The primary input to this command is the *interface*
 117 and *subId* (subinterface Id) parameters. If no additional VLAN ID is
 118 provide, the VLAN ID is assumed to be the *subId*. The VLAN ID and
 119 *subId* can be different, but this is not recommended.
 120
 121 This command has several variations:
 122
 123 -  **create sub-interfaces** <*interface*> <*subId*> - Create a subinterface
 124    to process packets with a given 802.1q VLAN ID (same value as the
 125    *subId*).
 126 -  **create sub-interfaces** <*interface*> <*subId*> default - Adding the
 127    *default* parameter indicates that packets with VLAN IDs that do
 128    not match any other subinterfaces should be sent to this
 129    subinterface.
 130 -  **create sub-interfaces** <*interface*> <*subId*> untagged - Adding the
 131    *untagged* parameter indicates that packets no VLAN IDs should be
 132    sent to this subinterface.
 133 -  **create sub-interfaces** <*interface*> <*subId*>-<*subId*> - Create a
 134    range of subinterfaces to handle a range of VLAN IDs.
 135 -  **create sub-interfaces** <*interface*> <*subId*> dot1q|dot1ad <*vlanId*>|any
 136    [exact-match] - Use this command to specify the outer VLAN ID, to
 137    either be explicited or to make the VLAN ID different from the
 138    *subId*.
 139 -  **create sub-interfaces** <*interface*> <*subId*> dot1q|dot1ad <*vlanId*>|any
 140    inner-dot1q <*vlanId*>|any [exact-match] - Use this command to
 141    specify the outer VLAN ID and the innner VLAN ID.
 142
 143 When *dot1q* or *dot1ad* is explictly entered, subinterfaces can be
 144 configured as either *exact-match* or *non-exact match*. *Non-exact match* is
 145 the CLI default. If *exact-match* is specified, packets must have the
 146 same number of VLAN tags as the configuration. For *non-exact-match*,
 147 packets must at least that number of tags. L3 (routed) interfaces must
 148 be configured as exact-match. L2 interfaces are typically configured as
 149 non-exact-match. If *dot1q* or *dot1ad* is NOT entered, then the
 150 default behavior is *exact-match*.
 151
 152 Use the **show interface** command to display all subinterfaces.
 153
 154 Summary/Usage
 155 -------------
 156
 157 .. code-block:: shell
 158
 159     create sub-interfaces <interface> {<subId> [default|untagged]} | {<subId>-<subId>} | {<subId> dot1q|dot1ad <vlanId>|any [inner-dot1q <vlanId>|any] [exact-match]}
 160
 161 Example Usage
 162 --------------
 163
 164 Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11:
 165
 166 .. code-block:: console
 167
 168     vpp# create sub-interfaces GigabitEthernet2/0/0 11
 169
 170 The previous example is shorthand and is equivalent to:
 171
 172 .. code-block:: console
 173
 174     vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 11 exact-match
 175
 176 Example of how to create a subinterface number that is different from the VLAN ID:
 177
 178 .. code-block:: console
 179
 180     vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100
 181
 182 Examples of how to create q-in-q and q-in-any subinterfaces:
 183
 184 .. code-block:: console
 185
 186     vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200
 187     vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any
 188
 189 Examples of how to create dot1ad interfaces:
 190
 191 .. code-block:: console
 192
 193     vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11
 194     vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1ad 100 inner-dot1q 200
 195
 196 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:
 197
 198 .. code-block:: console
 199
 200     vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100
 201
 202 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:
 203
 204 .. code-block:: console
 205
 206     vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match
 207
 208 Example of how to created a subinterface to process untagged packets:
 209
 210 .. code-block:: console
 211
 212    vpp# create sub-interfaces GigabitEthernet2/0/0 5 untagged
 213
 214 Example of how to created a subinterface to process any packet with a VLAN ID that does not match any other subinterface:
 215
 216 .. code-block:: console
 217
 218     vpp# create sub-interfaces GigabitEthernet2/0/0 7 default
 219
 220 When subinterfaces are created, they are in the down state. Example of how to enable a newly created subinterface:
 221
 222 .. code-block:: console
 223
 224     vpp# set interface GigabitEthernet2/0/0.7 up
 225