doc: Convert rhel/README.RHEL to rST

This is a top-level document, so plain old rST is preferred.

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

7 files changed, 309 insertions, 274 deletions

diff --git a/INSTALL.Fedora.md b/INSTALL.Fedora.md
index d2e55b2d9..a9eba08b7 100644
--- a/INSTALL.Fedora.md
+++ b/INSTALL.Fedora.md
@@ -127,4 +127,4 @@ Please report problems to bugs@openvswitch.org.
 
 [INSTALL.rst]:INSTALL.rst
 [FAQ.rst]:FAQ.rst
-[README.RHEL]:rhel/README.RHEL
+[README.RHEL]:rhel/README.RHEL.rst
diff --git a/INSTALL.RHEL.md b/INSTALL.RHEL.md
index c7343ce88..7c39029a5 100644
--- a/INSTALL.RHEL.md
+++ b/INSTALL.RHEL.md
@@ -157,8 +157,8 @@ Red Hat Network Scripts Integration
 -----------------------------------
 
 Simple integration with Red Hat network scripts has been implemented.
-Please read [rhel/README.RHEL] in the source tree or
-/usr/share/doc/openvswitch/README.RHEL in the installed openvswitch
+Please read [rhel/README.RHEL.rst] in the source tree or
+/usr/share/doc/openvswitch/README.RHEL.rst in the installed openvswitch
 package for details.
 
 Reporting Bugs
@@ -168,4 +168,4 @@ Please report problems to bugs@openvswitch.org.
 
 [INSTALL.rst]:INSTALL.rst
 [INSTALL.Fedora.md]:INSTALL.Fedora.md
-[rhel/README.RHEL]:rhel/README.RHEL
+[rhel/README.RHEL.rst]:rhel/README.RHEL.rst
diff --git a/rhel/README.RHEL b/rhel/README.RHEL
deleted file mode 100644
index fec9c7547..000000000
--- a/rhel/README.RHEL
+++ /dev/null
@@ -1,267 +0,0 @@
-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, eg "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.
-
-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
-
-Reporting Bugs
---------------
-
-Please report problems to bugs@openvswitch.org.
diff --git a/rhel/README.RHEL.rst b/rhel/README.RHEL.rst
new file mode 100644
index 000000000..afccf1703
--- /dev/null
+++ b/rhel/README.RHEL.rst
@@ -0,0 +1,302 @@
+===================================
+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.
+
+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
+
+Reporting Bugs
+--------------
+
+Please report problems to bugs@openvswitch.org.
diff --git a/rhel/automake.mk b/rhel/automake.mk
index 541f3fc65..45aa9b10a 100644
--- a/rhel/automake.mk
+++ b/rhel/automake.mk
@@ -6,7 +6,7 @@
 # without warranty of any kind.
 
 EXTRA_DIST += \
-	rhel/README.RHEL \
+	rhel/README.RHEL.rst \
 	rhel/automake.mk \
 	rhel/etc_init.d_openvswitch \
 	rhel/etc_logrotate.d_openvswitch \
diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in
index 19ae7a334..029471cee 100644
--- a/rhel/openvswitch-fedora.spec.in
+++ b/rhel/openvswitch-fedora.spec.in
@@ -475,7 +475,7 @@ fi
 %{_mandir}/man8/ovs-parse-backtrace.8*
 %{_mandir}/man8/ovs-testcontroller.8*
 %doc COPYING DESIGN.rst INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst
-%doc FAQ.rst NEWS INSTALL.DPDK.rst rhel/README.RHEL
+%doc FAQ.rst NEWS INSTALL.DPDK.rst rhel/README.RHEL.rst
 /var/lib/openvswitch
 /var/log/openvswitch
 %ghost %attr(755,root,root) %{_rundir}/openvswitch
diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in
index b40ede226..2e429e69d 100644
--- a/rhel/openvswitch.spec.in
+++ b/rhel/openvswitch.spec.in
@@ -248,7 +248,7 @@ exit 0
 /usr/share/openvswitch/vswitch.ovsschema
 /usr/share/openvswitch/vtep.ovsschema
 %doc COPYING DESIGN.rst INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS
-%doc INSTALL.DPDK.rst rhel/README.RHEL README-native-tunneling.rst
+%doc INSTALL.DPDK.rst rhel/README.RHEL.rst README-native-tunneling.rst
 /var/lib/openvswitch
 /var/log/openvswitch