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