[ovs.git] / Documentation / faq / configuration.rst

..
      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.

      Convention for heading levels in Open vSwitch documentation:

      =======  Heading 0 (reserved for the title in a document)
      -------  Heading 1
      ~~~~~~~  Heading 2
      +++++++  Heading 3
      '''''''  Heading 4

      Avoid deeper levels because they do not render well.

===================
Basic Configuration
===================

Q: How do I configure a port as an access port?

    A. Add ``tag=VLAN`` to your ``ovs-vsctl add-port`` command. For example,
    the following commands configure br0 with eth0 as a trunk port (the
    default) and tap0 as an access port for VLAN 9:

    ::

        $ ovs-vsctl add-br br0
        $ ovs-vsctl add-port br0 eth0
        $ ovs-vsctl add-port br0 tap0 tag=9

    If you want to configure an already added port as an access port, use
    ``ovs-vsctl set``, e.g.:

    ::

        $ ovs-vsctl set port tap0 tag=9

Q: How do I configure a port as a SPAN port, that is, enable mirroring of all
traffic to that port?

    A. The following commands configure br0 with eth0 and tap0 as trunk ports.
    All traffic coming in or going out on eth0 or tap0 is also mirrored to
    tap1; any traffic arriving on tap1 is dropped:

    ::

        $ ovs-vsctl add-br br0
        $ ovs-vsctl add-port br0 eth0
        $ ovs-vsctl add-port br0 tap0
        $ ovs-vsctl add-port br0 tap1 \
            -- --id=@p get port tap1 \
            -- --id=@m create mirror name=m0 select-all=true output-port=@p \
            -- set bridge br0 mirrors=@m

    To later disable mirroring, run:

    ::

        $ ovs-vsctl clear bridge br0 mirrors

Q: Does Open vSwitch support configuring a port in promiscuous mode?

    A: Yes.  How you configure it depends on what you mean by "promiscuous
    mode":

    - Conventionally, "promiscuous mode" is a feature of a network interface
      card.  Ordinarily, a NIC passes to the CPU only the packets actually
      destined to its host machine.  It discards the rest to avoid wasting
      memory and CPU cycles.  When promiscuous mode is enabled, however, it
      passes every packet to the CPU.  On an old-style shared-media or
      hub-based network, this allows the host to spy on all packets on the
      network.  But in the switched networks that are almost everywhere these
      days, promiscuous mode doesn't have much effect, because few packets not
      destined to a host are delivered to the host's NIC.

      This form of promiscuous mode is configured in the guest OS of the VMs on
      your bridge, e.g. with "ip link set <device> promisc".

    - The VMware vSwitch uses a different definition of "promiscuous mode".
      When you configure promiscuous mode on a VMware vNIC, the vSwitch sends a
      copy of every packet received by the vSwitch to that vNIC.  That has a
      much bigger effect than just enabling promiscuous mode in a guest OS.
      Rather than getting a few stray packets for which the switch does not yet
      know the correct destination, the vNIC gets every packet.  The effect is
      similar to replacing the vSwitch by a virtual hub.

      This "promiscuous mode" is what switches normally call "port mirroring"
      or "SPAN".  For information on how to configure SPAN, see "How do I
      configure a port as a SPAN port, that is, enable mirroring of all traffic
      to that port?"

Q: How do I configure a DPDK port as an access port?

    A: Firstly, you must have a DPDK-enabled version of Open vSwitch.

    If your version is DPDK-enabled it may support the dpdk_version and
    dpdk_initialized keys in the configuration database.  Earlier versions
    of Open vSwitch only supported the other-config:dpdk-init key in the
    configuration in the database.  All versions will display lines with
    "EAL:..." during startup when other_config:dpdk-init is set to 'true'.

    Secondly, when adding a DPDK port, unlike a system port, the type for the
    interface and valid dpdk-devargs must be specified. For example::

        $ ovs-vsctl add-br br0
        $ ovs-vsctl add-port br0 myportname -- set Interface myportname \
            type=dpdk options:dpdk-devargs=0000:06:00.0

    Refer to :doc:`/intro/install/dpdk` for more information on enabling and
    using DPDK with Open vSwitch.

Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all
traffic to that VLAN?

    A: The following commands configure br0 with eth0 as a trunk port and tap0
    as an access port for VLAN 10.  All traffic coming in or going out on tap0,
    as well as traffic coming in or going out on eth0 in VLAN 10, is also
    mirrored to VLAN 15 on eth0.  The original tag for VLAN 10, in cases where
    one is present, is dropped as part of mirroring:

    ::

        $ ovs-vsctl add-br br0
        $ ovs-vsctl add-port br0 eth0
        $ ovs-vsctl add-port br0 tap0 tag=10
        $ ovs-vsctl \
            -- --id=@m create mirror name=m0 select-all=true select-vlan=10 \
               output-vlan=15 \
            -- set bridge br0 mirrors=@m

    To later disable mirroring, run:

    ::

        $ ovs-vsctl clear bridge br0 mirrors

    Mirroring to a VLAN can disrupt a network that contains unmanaged switches.
    See ovs-vswitchd.conf.db(5) for details. Mirroring to a GRE tunnel has
    fewer caveats than mirroring to a VLAN and should generally be preferred.

Q: Can I mirror more than one input VLAN to an RSPAN VLAN?

    A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor of
    the specified output-vlan.  This loss of information may make the mirrored
    traffic too hard to interpret.

    To mirror multiple VLANs, use the commands above, but specify a
    comma-separated list of VLANs as the value for select-vlan.  To mirror
    every VLAN, use the commands above, but omit select-vlan and its value
    entirely.

    When a packet arrives on a VLAN that is used as a mirror output VLAN, the
    mirror is disregarded.  Instead, in standalone mode, OVS floods the packet
    across all the ports for which the mirror output VLAN is configured.  (If
    an OpenFlow controller is in use, then it can override this behavior
    through the flow table.)  If OVS is used as an intermediate switch, rather
    than an edge switch, this ensures that the RSPAN traffic is distributed
    through the network.

    Mirroring to a VLAN can disrupt a network that contains unmanaged switches.
    See ovs-vswitchd.conf.db(5) for details.  Mirroring to a GRE tunnel has
    fewer caveats than mirroring to a VLAN and should generally be preferred.

Q: How do I configure mirroring of all traffic to a GRE tunnel?

    A: The following commands configure br0 with eth0 and tap0 as trunk ports.
    All traffic coming in or going out on eth0 or tap0 is also mirrored to
    gre0, a GRE tunnel to the remote host 192.168.1.10; any traffic arriving on
    gre0 is dropped::

        $ ovs-vsctl add-br br0
        $ ovs-vsctl add-port br0 eth0
        $ ovs-vsctl add-port br0 tap0
        $ ovs-vsctl add-port br0 gre0 \
             -- set interface gre0 type=gre options:remote_ip=192.168.1.10 \
             -- --id=@p get port gre0 \
             -- --id=@m create mirror name=m0 select-all=true output-port=@p \
             -- set bridge br0 mirrors=@m

    To later disable mirroring and destroy the GRE tunnel::

        $ ovs-vsctl clear bridge br0 mirrors
        $ ovs-vsctl del-port br0 gre0

Q: Does Open vSwitch support ERSPAN?

    A: Yes. ERSPAN version I and version II over IPv4 GRE and
    IPv6 GRE tunnel are supported.  See ovs-fields(7) for matching
    and setting ERSPAN fields.

    ::

        $ ovs-vsctl add-br br0
        $ #For ERSPAN type 2 (version I)
        $ ovs-vsctl add-port br0 at_erspan0 -- \
                set int at_erspan0 type=erspan options:key=1 \
                options:remote_ip=172.31.1.1 \
                options:erspan_ver=1 options:erspan_idx=1
        $ #For ERSPAN type 3 (version II)
        $ ovs-vsctl add-port br0 at_erspan0 -- \
                set int at_erspan0 type=erspan options:key=1 \
                options:remote_ip=172.31.1.1 \
                options:erspan_ver=2 options:erspan_dir=1 \
                options:erspan_hwid=4

Q: How do I connect two bridges?

    A: First, why do you want to do this?  Two connected bridges are not much
    different from a single bridge, so you might as well just have a single
    bridge with all your ports on it.

    If you still want to connect two bridges, you can use a pair of patch
    ports.  The following example creates bridges br0 and br1, adds eth0 and
    tap0 to br0, adds tap1 to br1, and then connects br0 and br1 with a pair of
    patch ports.

    ::

        $ ovs-vsctl add-br br0
        $ ovs-vsctl add-port br0 eth0
        $ ovs-vsctl add-port br0 tap0
        $ ovs-vsctl add-br br1
        $ ovs-vsctl add-port br1 tap1
        $ ovs-vsctl \
            -- add-port br0 patch0 \
            -- set interface patch0 type=patch options:peer=patch1 \
            -- add-port br1 patch1 \
            -- set interface patch1 type=patch options:peer=patch0

    Bridges connected with patch ports are much like a single bridge. For
    instance, if the example above also added eth1 to br1, and both eth0 and
    eth1 happened to be connected to the same next-hop switch, then you could
    loop your network just as you would if you added eth0 and eth1 to the same
    bridge (see the "Configuration Problems" section below for more
    information).

    If you are using Open vSwitch 1.9 or an earlier version, then you need to
    be using the kernel module bundled with Open vSwitch rather than the one
    that is integrated into Linux 3.3 and later, because Open vSwitch 1.9 and
    earlier versions need kernel support for patch ports. This also means that
    in Open vSwitch 1.9 and earlier, patch ports will not work with the
    userspace datapath, only with the kernel module.

Q: How do I configure a bridge without an OpenFlow local port?  (Local port in
the sense of OFPP_LOCAL)

    A: Open vSwitch does not support such a configuration.  Bridges always have
    their local ports.
Commit	Line	Data
11e02906 SF	1	..
	2	Licensed under the Apache License, Version 2.0 (the "License"); you may
	3	not use this file except in compliance with the License. You may obtain
	4	a copy of the License at
	5
	6	http://www.apache.org/licenses/LICENSE-2.0
	7
	8	Unless required by applicable law or agreed to in writing, software
	9	distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	10	WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	11	License for the specific language governing permissions and limitations
	12	under the License.
	13
	14	Convention for heading levels in Open vSwitch documentation:
	15
	16	======= Heading 0 (reserved for the title in a document)
	17	------- Heading 1
	18	~~~~~~~ Heading 2
	19	+++++++ Heading 3
	20	''''''' Heading 4
	21
	22	Avoid deeper levels because they do not render well.
	23
	24	===================
	25	Basic Configuration
	26	===================
	27
	28	Q: How do I configure a port as an access port?
	29
	30	A. Add ``tag=VLAN`` to your ``ovs-vsctl add-port`` command. For example,
	31	the following commands configure br0 with eth0 as a trunk port (the
	32	default) and tap0 as an access port for VLAN 9:
	33
	34	::
	35
	36	$ ovs-vsctl add-br br0
	37	$ ovs-vsctl add-port br0 eth0
	38	$ ovs-vsctl add-port br0 tap0 tag=9
	39
	40	If you want to configure an already added port as an access port, use
	41	``ovs-vsctl set``, e.g.:
	42
	43	::
	44
	45	$ ovs-vsctl set port tap0 tag=9
	46
	47	Q: How do I configure a port as a SPAN port, that is, enable mirroring of all
	48	traffic to that port?
	49
	50	A. The following commands configure br0 with eth0 and tap0 as trunk ports.
	51	All traffic coming in or going out on eth0 or tap0 is also mirrored to
	52	tap1; any traffic arriving on tap1 is dropped:
	53
	54	::
	55
	56	$ ovs-vsctl add-br br0
	57	$ ovs-vsctl add-port br0 eth0
	58	$ ovs-vsctl add-port br0 tap0
	59	$ ovs-vsctl add-port br0 tap1 \
	60	-- --id=@p get port tap1 \
	61	-- --id=@m create mirror name=m0 select-all=true output-port=@p \
	62	-- set bridge br0 mirrors=@m
	63
	64	To later disable mirroring, run:
65
66	::
67
68	$ ovs-vsctl clear bridge br0 mirrors
69
70	Q: Does Open vSwitch support configuring a port in promiscuous mode?
71
72	A: Yes. How you configure it depends on what you mean by "promiscuous
73	mode":
74
75	- Conventionally, "promiscuous mode" is a feature of a network interface
76	card. Ordinarily, a NIC passes to the CPU only the packets actually
77	destined to its host machine. It discards the rest to avoid wasting
78	memory and CPU cycles. When promiscuous mode is enabled, however, it
79	passes every packet to the CPU. On an old-style shared-media or
80	hub-based network, this allows the host to spy on all packets on the
81	network. But in the switched networks that are almost everywhere these
82	days, promiscuous mode doesn't have much effect, because few packets not
83	destined to a host are delivered to the host's NIC.
84
85	This form of promiscuous mode is configured in the guest OS of the VMs on
0b2c7e69	86	your bridge, e.g. with "ip link set <device> promisc".
11e02906 SF	87
	88	- The VMware vSwitch uses a different definition of "promiscuous mode".
	89	When you configure promiscuous mode on a VMware vNIC, the vSwitch sends a
	90	copy of every packet received by the vSwitch to that vNIC. That has a
	91	much bigger effect than just enabling promiscuous mode in a guest OS.
	92	Rather than getting a few stray packets for which the switch does not yet
	93	know the correct destination, the vNIC gets every packet. The effect is
	94	similar to replacing the vSwitch by a virtual hub.
	95
	96	This "promiscuous mode" is what switches normally call "port mirroring"
	97	or "SPAN". For information on how to configure SPAN, see "How do I
	98	configure a port as a SPAN port, that is, enable mirroring of all traffic
	99	to that port?"
	100
	101	Q: How do I configure a DPDK port as an access port?
	102
	103	A: Firstly, you must have a DPDK-enabled version of Open vSwitch.
	104
3e52fa56 AC	105	If your version is DPDK-enabled it may support the dpdk_version and
	106	dpdk_initialized keys in the configuration database. Earlier versions
	107	of Open vSwitch only supported the other-config:dpdk-init key in the
	108	configuration in the database. All versions will display lines with
	109	"EAL:..." during startup when other_config:dpdk-init is set to 'true'.
11e02906 SF	110
11e02906 SF	111	Secondly, when adding a DPDK port, unlike a system port, the type for the
9cdef506	112	interface and valid dpdk-devargs must be specified. For example::
11e02906 SF	113
11e02906 SF	114	$ ovs-vsctl add-br br0
9cdef506 BX	115	$ ovs-vsctl add-port br0 myportname -- set Interface myportname \
9cdef506 BX	116	type=dpdk options:dpdk-devargs=0000:06:00.0
11e02906 SF	117
	118	Refer to :doc:`/intro/install/dpdk` for more information on enabling and
	119	using DPDK with Open vSwitch.
	120
	121	Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all
	122	traffic to that VLAN?
	123
	124	A: The following commands configure br0 with eth0 as a trunk port and tap0
	125	as an access port for VLAN 10. All traffic coming in or going out on tap0,
	126	as well as traffic coming in or going out on eth0 in VLAN 10, is also
	127	mirrored to VLAN 15 on eth0. The original tag for VLAN 10, in cases where
	128	one is present, is dropped as part of mirroring:
	129
	130	::
	131
	132	$ ovs-vsctl add-br br0
	133	$ ovs-vsctl add-port br0 eth0
	134	$ ovs-vsctl add-port br0 tap0 tag=10
	135	$ ovs-vsctl \
	136	-- --id=@m create mirror name=m0 select-all=true select-vlan=10 \
	137	output-vlan=15 \
	138	-- set bridge br0 mirrors=@m
	139
	140	To later disable mirroring, run:
	141
	142	::
	143
	144	$ ovs-vsctl clear bridge br0 mirrors
	145
	146	Mirroring to a VLAN can disrupt a network that contains unmanaged switches.
	147	See ovs-vswitchd.conf.db(5) for details. Mirroring to a GRE tunnel has
	148	fewer caveats than mirroring to a VLAN and should generally be preferred.
	149
	150	Q: Can I mirror more than one input VLAN to an RSPAN VLAN?
	151
	152	A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor of
	153	the specified output-vlan. This loss of information may make the mirrored
	154	traffic too hard to interpret.
	155
	156	To mirror multiple VLANs, use the commands above, but specify a
	157	comma-separated list of VLANs as the value for select-vlan. To mirror
	158	every VLAN, use the commands above, but omit select-vlan and its value
	159	entirely.
	160
	161	When a packet arrives on a VLAN that is used as a mirror output VLAN, the
	162	mirror is disregarded. Instead, in standalone mode, OVS floods the packet
	163	across all the ports for which the mirror output VLAN is configured. (If
	164	an OpenFlow controller is in use, then it can override this behavior
	165	through the flow table.) If OVS is used as an intermediate switch, rather
	166	than an edge switch, this ensures that the RSPAN traffic is distributed
	167	through the network.
	168
	169	Mirroring to a VLAN can disrupt a network that contains unmanaged switches.
	170	See ovs-vswitchd.conf.db(5) for details. Mirroring to a GRE tunnel has
	171	fewer caveats than mirroring to a VLAN and should generally be preferred.
	172
	173	Q: How do I configure mirroring of all traffic to a GRE tunnel?
	174
	175	A: The following commands configure br0 with eth0 and tap0 as trunk ports.
	176	All traffic coming in or going out on eth0 or tap0 is also mirrored to
	177	gre0, a GRE tunnel to the remote host 192.168.1.10; any traffic arriving on
	178	gre0 is dropped::
	179
	180	$ ovs-vsctl add-br br0
181	$ ovs-vsctl add-port br0 eth0
182	$ ovs-vsctl add-port br0 tap0
183	$ ovs-vsctl add-port br0 gre0 \
184	-- set interface gre0 type=gre options:remote_ip=192.168.1.10 \
185	-- --id=@p get port gre0 \
186	-- --id=@m create mirror name=m0 select-all=true output-port=@p \
187	-- set bridge br0 mirrors=@m
188
189	To later disable mirroring and destroy the GRE tunnel::
190
191	$ ovs-vsctl clear bridge br0 mirrors
192	$ ovs-vsctl del-port br0 gre0
193
194	Q: Does Open vSwitch support ERSPAN?
195
4ee9f056 WT	196	A: Yes. ERSPAN version I and version II over IPv4 GRE and
	197	IPv6 GRE tunnel are supported. See ovs-fields(7) for matching
	198	and setting ERSPAN fields.
	199
	200	::
	201
	202	$ ovs-vsctl add-br br0
	203	$ #For ERSPAN type 2 (version I)
	204	$ ovs-vsctl add-port br0 at_erspan0 -- \
	205	set int at_erspan0 type=erspan options:key=1 \
	206	options:remote_ip=172.31.1.1 \
	207	options:erspan_ver=1 options:erspan_idx=1
	208	$ #For ERSPAN type 3 (version II)
	209	$ ovs-vsctl add-port br0 at_erspan0 -- \
	210	set int at_erspan0 type=erspan options:key=1 \
	211	options:remote_ip=172.31.1.1 \
	212	options:erspan_ver=2 options:erspan_dir=1 \
	213	options:erspan_hwid=4
11e02906 SF	214
	215	Q: How do I connect two bridges?
	216
	217	A: First, why do you want to do this? Two connected bridges are not much
	218	different from a single bridge, so you might as well just have a single
	219	bridge with all your ports on it.
	220
	221	If you still want to connect two bridges, you can use a pair of patch
	222	ports. The following example creates bridges br0 and br1, adds eth0 and
	223	tap0 to br0, adds tap1 to br1, and then connects br0 and br1 with a pair of
	224	patch ports.
	225
	226	::
	227
	228	$ ovs-vsctl add-br br0
	229	$ ovs-vsctl add-port br0 eth0
	230	$ ovs-vsctl add-port br0 tap0
	231	$ ovs-vsctl add-br br1
	232	$ ovs-vsctl add-port br1 tap1
	233	$ ovs-vsctl \
	234	-- add-port br0 patch0 \
	235	-- set interface patch0 type=patch options:peer=patch1 \
	236	-- add-port br1 patch1 \
	237	-- set interface patch1 type=patch options:peer=patch0
	238
	239	Bridges connected with patch ports are much like a single bridge. For
	240	instance, if the example above also added eth1 to br1, and both eth0 and
	241	eth1 happened to be connected to the same next-hop switch, then you could
	242	loop your network just as you would if you added eth0 and eth1 to the same
	243	bridge (see the "Configuration Problems" section below for more
	244	information).
	245
	246	If you are using Open vSwitch 1.9 or an earlier version, then you need to
	247	be using the kernel module bundled with Open vSwitch rather than the one
	248	that is integrated into Linux 3.3 and later, because Open vSwitch 1.9 and
	249	earlier versions need kernel support for patch ports. This also means that
	250	in Open vSwitch 1.9 and earlier, patch ports will not work with the
	251	userspace datapath, only with the kernel module.
	252
	253	Q: How do I configure a bridge without an OpenFlow local port? (Local port in
	254	the sense of OFPP_LOCAL)
	255
	256	A: Open vSwitch does not support such a configuration. Bridges always have
	257	their local ports.