[mirror_ovs.git] / rhel / README.RHEL.rst

===================================
Red Hat network scripts integration
===================================

The RPM packages for Open vSwitch provide some integration with Red Hat's
network scripts.  Using this integration is optional.

To use the integration for a Open vSwitch bridge or interface named ``<name>``,
create or edit ``/etc/sysconfig/network-scripts/ifcfg-<name>``.  This is a
shell script that consists of a series of ``VARIABLE=VALUE`` assignments.  The
following OVS-specific variable names are supported:

DEVICETYPE
  Always set to "ovs".

TYPE
  If this is "OVSBridge", then this file represents an OVS bridge named <name>.
  Otherwise, it represents a port on an OVS bridge and TYPE must have one of
  the following values:

  * ``OVSPort``, if ``<name>`` is a physical port (e.g. eth0) or
    virtual port (e.g. vif1.0).

  * ``OVSIntPort``, if ``<name>`` is an internal port (e.g. a tagged
    VLAN).

  * ``OVSBond``, if ``<name>`` is an OVS bond.

  * ``OVSTunnel``, if ``<name>`` is an OVS tunnel.

  * ``OVSPatchPort``, if ``<name>`` is a patch port

  Additionally the following DPDK port types may be available, depends on OVS
  build- and runtime configuration:

  * ``OVSDPDKPort``, if ``<name>`` is a physical DPDK NIC port (name must start
    with ``dpdk`` and end with portid, eg ``dpdk0``)

  * ``OVSDPDKRPort``, if ``<name>`` is a DPDK ring port (name must start with
    ``dpdkr`` and end with portid, e.g. ``dpdkr0``)

  * ``OVSDPDKVhostUserPort`` if ``<name>`` is a DPDK vhost-user port

  * ``OVSDPDKBond`` if ``<name>`` is an OVS DPDK bond.

OVS_BRIDGE
  If TYPE is anything other than "OVSBridge", set to the name of the OVS bridge
  to which the port should be attached.

OVS_OPTIONS
  Optionally, extra options to set in the "Port" table when adding the port to
  the bridge, as a sequence of column[:key]=value options.  For example,
  "tag=100" to make the port an access port for VLAN 100.  See the
  documentation of "add-port" in ovs-vsctl(8) for syntax and the section on the
  Port table in ovs-vswitchd.conf.db(5) for available options.

OVS_EXTRA
  Optionally, additional ovs-vsctl commands, separated by ``--`` (double dash).

BOND_IFACES
  For "OVSBond" and "OVSDPDKBond" interfaces, a list of physical interfaces to
  bond together.

OVS_TUNNEL_TYPE
  For "OVSTunnel" interfaces, the type of the tunnel.  For example, "gre",
  "vxlan", etc.

OVS_TUNNEL_OPTIONS
  For "OVSTunnel" interfaces, this field should be used to specify the tunnel
  options like remote_ip, key, etc.

OVS_PATCH_PEER
  For "OVSPatchPort" devices, this field specifies the patch's peer on the
  other bridge.

OVS_PORT_MODE
  For "OVSDPDKVhostUserPort" devices, this field can be set to "client" which
  indicates that the port will be used in client mode.

OVS_PORT_PATH
  For "OVSDPDKVhostUserPort" devices, this field specifies the path to the
  vhost-user server socket.  It will only be used if OVS_PORT_MODE is set to
  "client".

Note
----

* ``ifdown`` on a bridge will not bring individual ports on the bridge down.
  "ifup" on a bridge will not add ports to the bridge.  This behavior should be
  compatible with standard bridges (with ``TYPE=Bridge``).

* If ``ifup`` on an interface is called multiple times, one can see ``RTNETLINK
  answers: File exists`` printed on the console. This comes from ifup-eth
  trying to add zeroconf route multiple times and is harmless.

Examples
--------

Standalone bridge:

::

    ==> ifcfg-ovsbridge0 <==
    DEVICE=ovsbridge0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSBridge
    BOOTPROTO=static
    IPADDR=A.B.C.D
    NETMASK=X.Y.Z.0
    HOTPLUG=no

Enable DHCP on the bridge:

* Needs ``OVSBOOTPROTO`` instead of ``BOOTPROTO``.
* All the interfaces that can reach the DHCP server as a space separated list
  in ``OVSDHCPINTERFACES``.

::

    DEVICE=ovsbridge0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSBridge
    OVSBOOTPROTO="dhcp"
    OVSDHCPINTERFACES="eth0"
    HOTPLUG=no


Adding Internal Port to ovsbridge0:

::

    ==> ifcfg-intbr0 <==
    DEVICE=intbr0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSIntPort
    OVS_BRIDGE=ovsbridge0
    HOTPLUG=no

Internal Port with fixed IP address:

::

    DEVICE=intbr0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSIntPort
    OVS_BRIDGE=ovsbridge0
    BOOTPROTO=static
    IPADDR=A.B.C.D
    NETMASK=X.Y.Z.0
    HOTPLUG=no

Internal Port with DHCP:

* Needs ``OVSBOOTPROTO`` or ``BOOTPROTO``.
* All the interfaces that can reach the DHCP server as a space separated list
  in ``OVSDHCPINTERFACES``.

::

    DEVICE=intbr0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSIntPort
    OVS_BRIDGE=ovsbridge0
    OVSBOOTPROTO="dhcp"
    OVSDHCPINTERFACES="eth0"
    HOTPLUG=no

Adding physical ``eth0`` to ``ovsbridge0`` described above:

::

     ==> ifcfg-eth0 <==
     DEVICE=eth0
     ONBOOT=yes
     DEVICETYPE=ovs
     TYPE=OVSPort
     OVS_BRIDGE=ovsbridge0
     BOOTPROTO=none
     HOTPLUG=no

Tagged VLAN interface on top of ``ovsbridge0``:

::

    ==> ifcfg-vlan100 <==
    DEVICE=vlan100
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSIntPort
    BOOTPROTO=static
    IPADDR=A.B.C.D
    NETMASK=X.Y.Z.0
    OVS_BRIDGE=ovsbridge0
    OVS_OPTIONS="tag=100"
    OVS_EXTRA="set Interface $DEVICE external-ids:iface-id=$(hostname -s)-$DEVICE-vif"
    HOTPLUG=no

Bonding:

::

    ==> ifcfg-bond0 <==
    DEVICE=bond0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSBond
    OVS_BRIDGE=ovsbridge0
    BOOTPROTO=none
    BOND_IFACES="gige-1b-0 gige-1b-1 gige-21-0 gige-21-1"
    OVS_OPTIONS="bond_mode=balance-tcp lacp=active"
    HOTPLUG=no

::

    ==> ifcfg-gige-* <==
    DEVICE=gige-*
    ONBOOT=yes
    HOTPLUG=no

An Open vSwitch Tunnel:

::

    ==> ifcfg-gre0 <==
    DEVICE=ovs-gre0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSTunnel
    OVS_BRIDGE=ovsbridge0
    OVS_TUNNEL_TYPE=gre
    OVS_TUNNEL_OPTIONS="options:remote_ip=A.B.C.D"

Patch Ports:

::

    ==> ifcfg-patch-ovs-0 <==
    DEVICE=patch-ovs-0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSPatchPort
    OVS_BRIDGE=ovsbridge0
    OVS_PATCH_PEER=patch-ovs-1

::

    ==> ifcfg-patch-ovs-1 <==
    DEVICE=patch-ovs-1
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSPatchPort
    OVS_BRIDGE=ovsbridge1
    OVS_PATCH_PEER=patch-ovs-0

User bridge:

::

    ==> ifcfg-obr0 <==
    DEVICE=obr0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSUserBridge
    BOOTPROTO=static
    IPADDR=A.B.C.D
    NETMASK=X.Y.Z.0
    HOTPLUG=no

DPDK NIC port:

::

    ==> ifcfg-dpdk0 <==
    DPDK vhost-user port:
    DEVICE=dpdk0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSDPDKPort
    OVS_BRIDGE=obr0

::

    ==> ifcfg-vhu0 <==
    DEVICE=vhu0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSDPDKVhostUserPort
    OVS_BRIDGE=obr0

::

    ==> ifcfg-bond0 <==
    DEVICE=bond0
    ONBOOT=yes
    DEVICETYPE=ovs
    TYPE=OVSDPDKBond
    OVS_BRIDGE=ovsbridge0
    BOOTPROTO=none
    BOND_IFACES="dpdk0 dpdk1"
    OVS_OPTIONS="bond_mode=active-backup"
    HOTPLUG=no


Red Hat systemd integration
---------------------------

The RPM packages for Open vSwitch provide support for systemd integration. It's
recommended to use the openvswitch.service to start and stop the Open vSwitch
daemons. The below table shows systemd's behavior:

=============================== ============== ============== ============== =============== ===============
              -                 Process Status                systemctl <> status
------------------------------- ----------------------------- ----------------------------------------------
Action                          ovs-vswitch     ovsdb-server  openvswitch    ovs-vswitchd    ovsdb-server
=============================== ============== ============== ============== =============== ===============
systemctl start openvswitch*    started        started        active, exited active, running active, running
crash of vswitchd               crash, started re-started     active, exited active, running active, running
crash of ovsdb                  re-started     crash, started active, exited active, running active, running
systemctl restart openvswitch   re-started     re-started     active, exited active, running active, running
systemctl restart ovs-vswitchd  re-started     re-started     active, exited active, running active, running
systemctl restart ovsdb-server  re-started     re-started     active, exited active, running active, running
systemctl stop openvswitch      stopped        stopped        inactive, dead inactive, dead  inactive, dead
systemctl stop ovs-vswitchd     stopped        stopped        inactive, dead inactive, dead  inactive, dead
systemctl stop ovsdb-server     stopped        stopped        inactive, dead inactive, dead  inactive, dead
systemctl start ovs-vswitchd*   started        started        inactive, dead active, running active, running
systemctl start ovsdb-server*   not started    started        inactive, dead inactive, dead  active, running
=============================== ============== ============== ============== =============== ===============


\* These commands where executed when no Open vSwitch related processes where
running. All other commands where executed when Open vSwitch was successfully
running.


Non-root User Support
-----------------------
Fedora and RHEL support running the Open vSwitch daemons as a non-root user.
By default, a fresh installation will create an *openvswitch* user, along
with any additional support groups needed (such as *hugetlbfs* for DPDK
support).

This is controlled by modifying the ``OVS_USER_ID`` option.  Setting this
to 'root:root', or commenting the variable out will revert this behavior.


Reporting Bugs
--------------

Please report problems to bugs@openvswitch.org.
Commit	Line	Data
1c904eed SF	1	===================================
	2	Red Hat network scripts integration
	3	===================================
	4
	5	The RPM packages for Open vSwitch provide some integration with Red Hat's
	6	network scripts. Using this integration is optional.
	7
	8	To use the integration for a Open vSwitch bridge or interface named ``<name>``,
	9	create or edit ``/etc/sysconfig/network-scripts/ifcfg-<name>``. This is a
	10	shell script that consists of a series of ``VARIABLE=VALUE`` assignments. The
	11	following OVS-specific variable names are supported:
	12
	13	DEVICETYPE
	14	Always set to "ovs".
	15
	16	TYPE
	17	If this is "OVSBridge", then this file represents an OVS bridge named <name>.
	18	Otherwise, it represents a port on an OVS bridge and TYPE must have one of
	19	the following values:
	20
	21	* ``OVSPort``, if ``<name>`` is a physical port (e.g. eth0) or
	22	virtual port (e.g. vif1.0).
	23
	24	* ``OVSIntPort``, if ``<name>`` is an internal port (e.g. a tagged
	25	VLAN).
	26
	27	* ``OVSBond``, if ``<name>`` is an OVS bond.
	28
	29	* ``OVSTunnel``, if ``<name>`` is an OVS tunnel.
	30
	31	* ``OVSPatchPort``, if ``<name>`` is a patch port
	32
	33	Additionally the following DPDK port types may be available, depends on OVS
	34	build- and runtime configuration:
	35
	36	* ``OVSDPDKPort``, if ``<name>`` is a physical DPDK NIC port (name must start
	37	with ``dpdk`` and end with portid, eg ``dpdk0``)
	38
	39	* ``OVSDPDKRPort``, if ``<name>`` is a DPDK ring port (name must start with
	40	``dpdkr`` and end with portid, e.g. ``dpdkr0``)
	41
	42	* ``OVSDPDKVhostUserPort`` if ``<name>`` is a DPDK vhost-user port
	43
	44	* ``OVSDPDKBond`` if ``<name>`` is an OVS DPDK bond.
	45
	46	OVS_BRIDGE
	47	If TYPE is anything other than "OVSBridge", set to the name of the OVS bridge
	48	to which the port should be attached.
	49
	50	OVS_OPTIONS
	51	Optionally, extra options to set in the "Port" table when adding the port to
	52	the bridge, as a sequence of column[:key]=value options. For example,
	53	"tag=100" to make the port an access port for VLAN 100. See the
	54	documentation of "add-port" in ovs-vsctl(8) for syntax and the section on the
	55	Port table in ovs-vswitchd.conf.db(5) for available options.
	56
	57	OVS_EXTRA
	58	Optionally, additional ovs-vsctl commands, separated by ``--`` (double dash).
	59
	60	BOND_IFACES
	61	For "OVSBond" and "OVSDPDKBond" interfaces, a list of physical interfaces to
	62	bond together.
	63
	64	OVS_TUNNEL_TYPE
65	For "OVSTunnel" interfaces, the type of the tunnel. For example, "gre",
66	"vxlan", etc.
67
68	OVS_TUNNEL_OPTIONS
69	For "OVSTunnel" interfaces, this field should be used to specify the tunnel
70	options like remote_ip, key, etc.
71
72	OVS_PATCH_PEER
73	For "OVSPatchPort" devices, this field specifies the patch's peer on the
74	other bridge.
75
d46b6037 AC	76	OVS_PORT_MODE
	77	For "OVSDPDKVhostUserPort" devices, this field can be set to "client" which
	78	indicates that the port will be used in client mode.
	79
	80	OVS_PORT_PATH
	81	For "OVSDPDKVhostUserPort" devices, this field specifies the path to the
	82	vhost-user server socket. It will only be used if OVS_PORT_MODE is set to
	83	"client".
	84
1c904eed SF	85	Note
	86	----
	87
	88	* ``ifdown`` on a bridge will not bring individual ports on the bridge down.
	89	"ifup" on a bridge will not add ports to the bridge. This behavior should be
	90	compatible with standard bridges (with ``TYPE=Bridge``).
	91
	92	* If ``ifup`` on an interface is called multiple times, one can see ``RTNETLINK
	93	answers: File exists`` printed on the console. This comes from ifup-eth
	94	trying to add zeroconf route multiple times and is harmless.
	95
	96	Examples
	97	--------
	98
	99	Standalone bridge:
	100
	101	::
	102
	103	==> ifcfg-ovsbridge0 <==
	104	DEVICE=ovsbridge0
	105	ONBOOT=yes
	106	DEVICETYPE=ovs
	107	TYPE=OVSBridge
	108	BOOTPROTO=static
	109	IPADDR=A.B.C.D
	110	NETMASK=X.Y.Z.0
	111	HOTPLUG=no
	112
	113	Enable DHCP on the bridge:
	114
	115	* Needs ``OVSBOOTPROTO`` instead of ``BOOTPROTO``.
	116	* All the interfaces that can reach the DHCP server as a space separated list
	117	in ``OVSDHCPINTERFACES``.
	118
	119	::
	120
	121	DEVICE=ovsbridge0
	122	ONBOOT=yes
	123	DEVICETYPE=ovs
	124	TYPE=OVSBridge
	125	OVSBOOTPROTO="dhcp"
	126	OVSDHCPINTERFACES="eth0"
	127	HOTPLUG=no
	128
	129
	130	Adding Internal Port to ovsbridge0:
	131
	132	::
	133
	134	==> ifcfg-intbr0 <==
	135	DEVICE=intbr0
	136	ONBOOT=yes
	137	DEVICETYPE=ovs
	138	TYPE=OVSIntPort
	139	OVS_BRIDGE=ovsbridge0
	140	HOTPLUG=no
	141
	142	Internal Port with fixed IP address:
	143
	144	::
	145
	146	DEVICE=intbr0
	147	ONBOOT=yes
	148	DEVICETYPE=ovs
149	TYPE=OVSIntPort
150	OVS_BRIDGE=ovsbridge0
151	BOOTPROTO=static
152	IPADDR=A.B.C.D
153	NETMASK=X.Y.Z.0
154	HOTPLUG=no
155
156	Internal Port with DHCP:
157
158	* Needs ``OVSBOOTPROTO`` or ``BOOTPROTO``.
159	* All the interfaces that can reach the DHCP server as a space separated list
160	in ``OVSDHCPINTERFACES``.
161
162	::
163
164	DEVICE=intbr0
165	ONBOOT=yes
166	DEVICETYPE=ovs
167	TYPE=OVSIntPort
168	OVS_BRIDGE=ovsbridge0
169	OVSBOOTPROTO="dhcp"
170	OVSDHCPINTERFACES="eth0"
171	HOTPLUG=no
172
173	Adding physical ``eth0`` to ``ovsbridge0`` described above:
174
175	::
176
177	==> ifcfg-eth0 <==
178	DEVICE=eth0
179	ONBOOT=yes
180	DEVICETYPE=ovs
181	TYPE=OVSPort
182	OVS_BRIDGE=ovsbridge0
183	BOOTPROTO=none
184	HOTPLUG=no
185
186	Tagged VLAN interface on top of ``ovsbridge0``:
187
188	::
189
190	==> ifcfg-vlan100 <==
191	DEVICE=vlan100
192	ONBOOT=yes
193	DEVICETYPE=ovs
194	TYPE=OVSIntPort
195	BOOTPROTO=static
196	IPADDR=A.B.C.D
197	NETMASK=X.Y.Z.0
198	OVS_BRIDGE=ovsbridge0
199	OVS_OPTIONS="tag=100"
200	OVS_EXTRA="set Interface $DEVICE external-ids:iface-id=$(hostname -s)-$DEVICE-vif"
201	HOTPLUG=no
202
203	Bonding:
204
205	::
206
207	==> ifcfg-bond0 <==
208	DEVICE=bond0
209	ONBOOT=yes
210	DEVICETYPE=ovs
211	TYPE=OVSBond
212	OVS_BRIDGE=ovsbridge0
213	BOOTPROTO=none
214	BOND_IFACES="gige-1b-0 gige-1b-1 gige-21-0 gige-21-1"
215	OVS_OPTIONS="bond_mode=balance-tcp lacp=active"
216	HOTPLUG=no
217
218	::
219
220	==> ifcfg-gige-* <==
221	DEVICE=gige-*
222	ONBOOT=yes
223	HOTPLUG=no
224
225	An Open vSwitch Tunnel:
226
227	::
228
229	==> ifcfg-gre0 <==
230	DEVICE=ovs-gre0
231	ONBOOT=yes
232	DEVICETYPE=ovs
233	TYPE=OVSTunnel
234	OVS_BRIDGE=ovsbridge0
235	OVS_TUNNEL_TYPE=gre
236	OVS_TUNNEL_OPTIONS="options:remote_ip=A.B.C.D"
237
238	Patch Ports:
239
240	::
241
242	==> ifcfg-patch-ovs-0 <==
243	DEVICE=patch-ovs-0
244	ONBOOT=yes
245	DEVICETYPE=ovs
246	TYPE=OVSPatchPort
247	OVS_BRIDGE=ovsbridge0
248	OVS_PATCH_PEER=patch-ovs-1
249
250	::
251
252	==> ifcfg-patch-ovs-1 <==
253	DEVICE=patch-ovs-1
254	ONBOOT=yes
255	DEVICETYPE=ovs
256	TYPE=OVSPatchPort
257	OVS_BRIDGE=ovsbridge1
258	OVS_PATCH_PEER=patch-ovs-0
259
260	User bridge:
261
262	::
263
264	==> ifcfg-obr0 <==
265	DEVICE=obr0
266	ONBOOT=yes
267	DEVICETYPE=ovs
268	TYPE=OVSUserBridge
269	BOOTPROTO=static
270	IPADDR=A.B.C.D
271	NETMASK=X.Y.Z.0
272	HOTPLUG=no
273
274	DPDK NIC port:
275
276	::
277
278	==> ifcfg-dpdk0 <==
279	DPDK vhost-user port:
280	DEVICE=dpdk0
281	ONBOOT=yes
282	DEVICETYPE=ovs
283	TYPE=OVSDPDKPort
284	OVS_BRIDGE=obr0
285
286	::
287
288	==> ifcfg-vhu0 <==
289	DEVICE=vhu0
290	ONBOOT=yes
291	DEVICETYPE=ovs
292	TYPE=OVSDPDKVhostUserPort
293	OVS_BRIDGE=obr0
294
295	::
296
297	==> ifcfg-bond0 <==
298	DEVICE=bond0
299	ONBOOT=yes
300	DEVICETYPE=ovs
301	TYPE=OVSDPDKBond
302	OVS_BRIDGE=ovsbridge0
303	BOOTPROTO=none
304	BOND_IFACES="dpdk0 dpdk1"
305	OVS_OPTIONS="bond_mode=active-backup"
306	HOTPLUG=no
307
090cc60c EC	308
	309	Red Hat systemd integration
	310	---------------------------
	311
	312	The RPM packages for Open vSwitch provide support for systemd integration. It's
	313	recommended to use the openvswitch.service to start and stop the Open vSwitch
	314	daemons. The below table shows systemd's behavior:
	315
	316	=============================== ============== ============== ============== =============== ===============
c94d8154	317	- Process Status systemctl <> status
090cc60c EC	318	------------------------------- ----------------------------- ----------------------------------------------
	319	Action ovs-vswitch ovsdb-server openvswitch ovs-vswitchd ovsdb-server
	320	=============================== ============== ============== ============== =============== ===============
	321	systemctl start openvswitch* started started active, exited active, running active, running
	322	crash of vswitchd crash, started re-started active, exited active, running active, running
	323	crash of ovsdb re-started crash, started active, exited active, running active, running
	324	systemctl restart openvswitch re-started re-started active, exited active, running active, running
	325	systemctl restart ovs-vswitchd re-started re-started active, exited active, running active, running
	326	systemctl restart ovsdb-server re-started re-started active, exited active, running active, running
	327	systemctl stop openvswitch stopped stopped inactive, dead inactive, dead inactive, dead
	328	systemctl stop ovs-vswitchd stopped stopped inactive, dead inactive, dead inactive, dead
	329	systemctl stop ovsdb-server stopped stopped inactive, dead inactive, dead inactive, dead
	330	systemctl start ovs-vswitchd* started started inactive, dead active, running active, running
	331	systemctl start ovsdb-server* not started started inactive, dead inactive, dead active, running
	332	=============================== ============== ============== ============== =============== ===============
	333
	334
	335	\* These commands where executed when no Open vSwitch related processes where
	336	running. All other commands where executed when Open vSwitch was successfully
	337	running.
	338
	339
e3e738a3	340	Non-root User Support
	341	-----------------------
	342	Fedora and RHEL support running the Open vSwitch daemons as a non-root user.
	343	By default, a fresh installation will create an openvswitch user, along
	344	with any additional support groups needed (such as hugetlbfs for DPDK
	345	support).
	346
	347	This is controlled by modifying the ``OVS_USER_ID`` option. Setting this
	348	to 'root:root', or commenting the variable out will revert this behavior.
	349
	350
1c904eed SF	351	Reporting Bugs
	352	--------------
	353
	354	Please report problems to bugs@openvswitch.org.