Edits to the Installation Guide Networking introduction

Minor edits to wording and sentence structure in the Installation Guide Networking introduction

Change-Id: I6ba52ba9b101d64c8803665bb6efadb5a4df0140
Implements: blueprint installation-guide-improvements

doc/config-reference/compute/section_hypervisor_hyper-v.xml

@@ -351,9 +351,7 @@ connection=mysql://nova:passwd@<replaceable>IP_ADDRESS</replaceable>/nova</progr
                     controller; however, I'm not seeing smiley faces for Hyper-V compute nodes, what
                     do I do?</para>
                 <para><emphasis role="italic">Verify that you are synchronized with a network time
-                        source. Instructions for configuring NTP on your Hyper-V compute node are
+                        source. For instructions about how to configure NTP on your Hyper-V compute node, see <xref linkend="configure-ntp-hyper-v"/>.</emphasis></para>
-                        located <link xlink:href="#configure_ntp">here</link>
-                    </emphasis></para>
             </listitem>
         </itemizedlist>
     </section>

doc/install-guide/ch_networking.xml

@@ -3,24 +3,26 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:id="ch_networking">
-  <title>Add a networking service</title>
+  <title>Add a networking component</title>
-  <para>Configuring networking in OpenStack can be a bewildering
+  <para>This chapter explains how to install and configure either
-    experience. This guide provides step-by-step instructions for both
+    OpenStack Networking (neutron) or the legacy <systemitem
-    OpenStack Networking (neutron) and the legacy networking (nova-network)
+      class="service">nova-network</systemitem> networking service.
-    service. If you are unsure which to use, we recommend trying
+    The <systemitem class="service">nova-network</systemitem> service
-    OpenStack Networking because it offers a considerable number of
+    enables you to deploy one network type per instance and is
-    features and flexibility including <glossterm baseform="plug-in"
+    suitable for basic network functionality. OpenStack Networking
-      >plug-ins</glossterm> for a variety of emerging products
+    enables you to deploy multiple network types per instance and
-    supporting <glossterm>virtual networking</glossterm>. See the
+    includes <glossterm baseform="plug-in">plug-ins</glossterm> for a
-      <link
+    variety of products that support <glossterm>virtual
+      networking</glossterm>.</para>
+  <para>For more information, see the <link
       xlink:href="http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html"
       >Networking</link> chapter of the <citetitle>OpenStack Cloud
-      Administrator Guide</citetitle> for more information.</para>
+      Administrator Guide</citetitle>.</para>
   <section xml:id="section_neutron-networking">
     <title>OpenStack Networking (neutron)</title>
     <xi:include href="section_neutron-concepts.xml"/>
     <section xml:id="section_neutron-networking-ml2">
-    <title>Modular Layer 2 (ML2) plug-in</title>
+      <title>Modular Layer 2 (ML2) plug-in</title>
       <xi:include href="section_neutron-ml2-controller-node.xml"/>
       <xi:include href="section_neutron-ml2-network-node.xml"/>
       <xi:include href="section_neutron-ml2-compute-node.xml"/>
@@ -35,10 +37,9 @@
   </section>
   <section xml:id="section_networking_next_steps">
     <title>Next steps</title>
-    <para>
+    <para>Your OpenStack environment now includes the core components
-      Your OpenStack environment now includes the core components necessary
+      necessary to launch a basic instance. You can <link
-      to launch a basic instance. You can
+        linkend="launch-instance">launch an instance</link> or add
-      <link linkend="launch-instance">launch an instance</link> or add more
+      more OpenStack services to your environment.</para>
-      services to your environment in the following chapters.</para>
   </section>
 </chapter>

doc/install-guide/section_dashboard-install.xml

@@ -16,7 +16,8 @@
     <para>For more information about how to deploy the dashboard, see
             <link
             xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
-            >deployment topics in the developer documentation</link>.</para>
+            >deployment topics in the developer
+        documentation</link>.</para>
     <procedure>
         <step>
             <para>Install the dashboard on the node that can contact
@@ -71,8 +72,7 @@
 'LOCATION' : '127.0.0.1:11211'
 }
 }</programlisting>
-            <note xlink:href="#installing-openstack-dashboard"
+            <note>
-                xlink:title="Notes">
                 <title>Notes</title>
                 <itemizedlist>
                     <listitem>
@@ -118,8 +118,7 @@
                     os="ubuntu;debian"
                     >/etc/openstack-dashboard/local_settings.py</filename><filename
                     os="opensuse;sles"
-                    >/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>:
+                    >/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>:</para>
-            </para>
             <programlisting language="python" linenumbering="unnumbered"><?db-font-size 75%?>ALLOWED_HOSTS = ['localhost', 'my-desktop']
     </programlisting>
         </step>
@@ -158,10 +157,9 @@
                     linkend="dashboard-session-database"/>.</para>
         </step>
         <step os="centos;fedora;rhel">
-            <para>
+            <para>Ensure that the SELinux policy of the system is
-                Ensure that the SELinux policy of the system is configured to
+                configured to allow network connections to the HTTP
-                allow network connections to the HTTP server.
+                server.</para>
-            </para>
             <screen><prompt>#</prompt> <userinput>setsebool -P httpd_can_network_connect on</userinput></screen>
         </step>
         <step>

doc/install-guide/section_neutron-concepts.xml

@@ -4,57 +4,59 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
   <title>Networking concepts</title>
-  <para>OpenStack Networking (neutron) manages all of the networking
+  <para>OpenStack Networking (neutron) manages all networking facets
-    facets for the Virtual Networking Infrastructure (VNI) in your
+    for the Virtual Networking Infrastructure (VNI) and the access
-    OpenStack environment. OpenStack Networking also manages the access
+    layer aspects of the Physical Networking Infrastructure (PNI) in
-    layer aspects of the Physical Networking Infrastructure (PNI).
+    your OpenStack environment. OpenStack Networking enables tenants
-    Tenants can create advanced virtual network topologies using
+    to create advanced virtual network topologies including services
-    OpenStack Networking. These topologies include services such as
+    such as <glossterm baseform="firewall">firewalls</glossterm>,
-    <glossterm baseform="firewall">firewalls</glossterm>,
+      <glossterm baseform="load balancer">load balancers</glossterm>,
-    <glossterm baseform="load balancer">load balancers</glossterm>, and
+    and <glossterm baseform="virtual private network (VPN)">virtual
-    <glossterm baseform="virtual private network (VPN)">
+      private networks (VPNs)</glossterm>.</para>
-      virtual private networks (VPNs)</glossterm>.</para>
+  <para>Networking provides the networks, subnets, and routers object
-  <para>Networking provides the following object abstractions: networks,
+    abstractions. Each abstraction has functionality that mimics its
-    routers, and subnets. Each has a functionality that mimics its
     physical counterpart: networks contain subnets, and routers route
     traffic between different subnet and networks.</para>
-  <para>Each router has one gateway that connects to a network, and many
+  <para>Each router has one gateway that connects to a network, and
-    interfaces connected to subnets. Subnets can access machines on
+    many interfaces connected to subnets. Subnets can access machines
-    other subnets connected to the same router.</para>
+    on other subnets connected to the same router.</para>
   <para>Any given Networking set up has at least one external network.
-    This external network, unlike the other networks, is not solely a
+    This network, unlike the other networks, is not merely a virtually
-    virtually defined network. It instead provides a view into a slice
+    defined network. Instead, it represents the view into a slice of
-    of the network accessible outside the OpenStack installation, which
+    the external network that is accessible outside the OpenStack
-    is the outside network. IP addresses on the external network are
+    installation. IP addresses on the Networking external network are
-    accessible by anybody physically on the outside network. DHCP is
+    accessible by anybody physically on the outside network. Because
-    disabled on this network.</para>
+    this network merely represents a slice of the outside network,
-  <para>Machines can access the outside network through the gateway
+    DHCP is disabled on this network.</para>
-    for the router. For the outside network to access VMs, and for VM's
+  <para>In addition to external networks, any Networking set up has
-    to access the outside network, routers between the networks are
+    one or more internal networks. These software-defined networks
-    needed.</para>
+    connect directly to the VMs. Only the VMs on any given internal
-  <para>In addition to external networks, any Networking set up has one
+    network, or those on subnets connected through interfaces to a
-    or more internal networks. These software-defined networks connect
+    similar router, can access VMs connected to that network
-    directly to the VMs. Only the VMs on any given internal network,
+    directly.</para>
-    or those on subnets connected through interfaces to a similar
+  <para>For the outside network to access VMs, and vice versa, routers
-    router, can access VMs connected to that network directly.</para>
+    between the networks are needed. Each router has one gateway that
-   <para>Additionally, you can allocate IP addresses on external
+    is connected to a network and many interfaces that are connected
+    to subnets. Like a physical router, subnets can access machines on
+    other subnets that are connected to the same router, and machines
+    can access the outside network through the gateway for the
+    router.</para>
+  <para>Additionally, you can allocate IP addresses on external
     networks to ports on the internal network. Whenever something is
     connected to a subnet, that connection is called a port.You can
-    associate external network IP addresses with ports to VMs.
+    associate external network IP addresses with ports to VMs. This
-    This way, entities on the outside network can access VMs.</para>
+    way, entities on the outside network can access VMs.</para>
   <para>Networking also supports <emphasis role="italic">security
-    groups</emphasis>, which enable administrators to define
+      groups</emphasis>. Security groups enable administrators to
-    firewall rules in groups. A VM can belong to one or more
+    define firewall rules in groups. A VM can belong to one or more
-    security groups. Networking applies the rules in those security
+    security groups, and Networking applies the rules in those
-    groups to block or unblock ports, port ranges, or traffic types
+    security groups to block or unblock ports, port ranges, or traffic
-    for that VM.</para>
+    types for that VM.</para>
-  <simplesect><title>Networking plug-ins</title>
+  <para>Each plug-in that Networking uses has its own concepts. While
-  <para>Each plug-in that Networking uses has its own concepts. These
+    not vital to operating Networking, understanding these concepts
-    plug-in concepts are not vital to operating Networking.
+    can help you set up Networking. All Networking installations use a
-    Understanding these concepts can help you set up the Openstack
+    core plug-in and a security group plug-in (or just the No-Op
-    Networking service, however. All Networking installations use a core
+    security group plug-in). Additionally, Firewall as a Service
-    plug-in and a security group plug-in (or just the No-Op security
+    (FWaaS) and Load Balancer as a Service (LBaaS) plug-ins are
-    group plug-in). Additionally, Firewall-as-a-service (FWaaS) and
+    available.</para>
-    Load-balancing-as-a-service (LBaaS) plug-ins are available.</para>
-  </simplesect>
 </section>

doc/install-guide/section_neutron-ml2-compute-node.xml

@@ -4,13 +4,13 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
   <title>Configure compute node</title>
+  <para>Before you install and configure OpenStack Networking, you
+    must enable certain kernel networking functions.</para>
   <procedure>
-    <title>Prerequisites</title>
+    <title>To enable kernel networking functions</title>
-    <para>Before you configure OpenStack Networking, you must enable certain
-      kernel networking functions.</para>
     <step>
-      <para>Edit <filename>/etc/sysctl.conf</filename> to contain the
+      <para>Edit the <filename>/etc/sysctl.conf</filename> file and
-        following:</para>
+        add the following lines:</para>
       <programlisting>net.ipv4.conf.all.rp_filter=0
 net.ipv4.conf.default.rp_filter=0</programlisting>
     </step>
@@ -27,8 +27,9 @@ net.ipv4.conf.default.rp_filter=0</programlisting>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-neutron-ml2 openstack-neutron-openvswitch</userinput></screen>
       <screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-neutron-openvswitch-agent</userinput></screen>
       <note os="ubuntu">
-        <para>Ubuntu installations using Linux kernel version 3.11 or newer
+        <para>Ubuntu installations that use Linux kernel version 3.11
-          do not require the <emphasis>openvswitch-datapath-dkms</emphasis>
+          or later do not require the
+            <emphasis>openvswitch-datapath-dkms</emphasis>
           package.</para>
       </note>
       <note os="sles;opensuse">
@@ -41,21 +42,17 @@ net.ipv4.conf.default.rp_filter=0</programlisting>
     <para>The Networking common component configuration includes the
       authentication mechanism, message broker, and plug-in.</para>
     <step os="debian">
-      <para>Respond to prompts for
+      <para>Respond to prompts for <link
-        <link linkend="debconf-dbconfig-common">database management</link>,
+          linkend="debconf-dbconfig-common">database
-        <link linkend="debconf-keystone_authtoken">Identity service
+        management</link>, <link linkend="debconf-keystone_authtoken"
-        credentials</link>,
+          >Identity service credentials</link>, <link
-        <link linkend="debconf-api-endpoints">service endpoint
+          linkend="debconf-api-endpoints">service endpoint
-        registration</link>, and
+          registration</link>, and <link linkend="debconf-rabbitmq"
-        <link linkend="debconf-rabbitmq">message broker
+          >message broker credentials</link>.</para>
-        credentials</link>.</para>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Configure Networking to use the Identity service for
         authentication:</para>
-      <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-        password you chose for the <literal>neutron</literal> user
-        in the Identity service.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   auth_strategy keystone</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf keystone_authtoken \
@@ -72,23 +69,24 @@ net.ipv4.conf.default.rp_filter=0</programlisting>
   admin_user neutron</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf keystone_authtoken \
   admin_password <replaceable>NEUTRON_PASS</replaceable></userinput></screen>
+      <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
+        password you chose for the <literal>neutron</literal> user in
+        the Identity service.</para>
     </step>
     <step os="ubuntu">
       <para>Configure Networking to use the Identity service for
         authentication:</para>
       <substeps>
         <step>
-          <para>Edit the <filename>/etc/neutron/neutron.conf</filename>
+          <para>Edit the
-            file and add the following key to the
+              <filename>/etc/neutron/neutron.conf</filename> file and
-            <literal>[DEFAULT]</literal> section:</para>
+            add the following key to the <literal>[DEFAULT]</literal>
-            <programlisting language="ini">[DEFAULT]
+            section:</para>
+          <programlisting language="ini">[DEFAULT]
 ...
 auth_strategy = keystone</programlisting>
           <para>Add the following keys to the
-            <literal>[keystone_authtoken]</literal> section:</para>
+              <literal>[keystone_authtoken]</literal> section:</para>
-          <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-            password you chose for the <literal>neutron</literal> user
-            in the Identity service.</para>
           <programlisting language="ini">[keystone_authtoken]
 ...
 auth_uri = http://<replaceable>controller</replaceable>:5000
@@ -98,14 +96,14 @@ auth_port = 35357
 admin_tenant_name = service
 admin_user = neutron
 admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
+          <para>Replace <replaceable>NEUTRON_PASS</replaceable> with
+            the password you chose for the <literal>neutron</literal>
+            user in the Identity service.</para>
         </step>
       </substeps>
     </step>
     <step os="opensuse;sles;rhel;centos;fedora">
       <para>Configure Networking to use the message broker:</para>
-      <para>Replace <replaceable>RABBIT_PASS</replaceable> with the password
-        you chose for the <literal>guest</literal> account in
-        <application>RabbitMQ</application>.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   rpc_backend neutron.openstack.common.rpc.impl_kombu</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
@@ -114,17 +112,21 @@ admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
   rabbit_userid guest</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   rabbit_password <replaceable>RABBIT_PASS</replaceable></userinput></screen>
+      <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
+        password you chose for the <literal>guest</literal> account in
+          <application>RabbitMQ</application>.</para>
     </step>
     <step os="ubuntu">
       <para>Configure Networking to use the message broker:</para>
       <substeps>
         <step>
-          <para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
+          <para>Edit the
-            and add the following keys to the <literal>[DEFAULT]</literal>
+              <filename>/etc/neutron/neutron.conf</filename> file and
+            add the following keys to the <literal>[DEFAULT]</literal>
             section:</para>
-          <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
+          <para>Replace <replaceable>RABBIT_PASS</replaceable> with
-            password you chose for the <literal>guest</literal> account in
+            the password you chose for the <literal>guest</literal>
-            <application>RabbitMQ</application>.</para>
+            account in <application>RabbitMQ</application>.</para>
           <programlisting language="ini">[DEFAULT]
 ...
 rpc_backend = neutron.openstack.common.rpc.impl_kombu
@@ -134,26 +136,27 @@ rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
       </substeps>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
-      <para>Configure Networking to use the Modular Layer 2 (ML2) plug-in
+      <para>Configure Networking to use the Modular Layer 2 (ML2)
-        and associated services:</para>
+        plug-in and associated services:</para>
-        <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
+      <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   core_plugin ml2</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   service_plugins router</userinput></screen>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/neutron.conf</filename> to assist with
+          in the <filename>/etc/neutron/neutron.conf</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
     <step os="ubuntu;debian">
-      <para>Configure Networking to use the Modular Layer 2 (ML2) plug-in
+      <para>Configure Networking to use the Modular Layer 2 (ML2)
-        and associated services:</para>
+        plug-in and associated services:</para>
       <substeps>
         <step>
-          <para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
+          <para>Edit the
-            and add the following keys to the <literal>[DEFAULT]</literal>
+              <filename>/etc/neutron/neutron.conf</filename> file and
+            add the following keys to the <literal>[DEFAULT]</literal>
             section:</para>
           <programlisting os="ubuntu;debian" language="ini">[DEFAULT]
 ...
@@ -161,10 +164,11 @@ core_plugin = ml2
 service_plugins = router
 allow_overlapping_ips = True</programlisting>
           <note>
-            <para>We recommend adding <literal>verbose = True</literal> to
+            <para>To assist with troubleshooting, add <literal>verbose
-              the <literal>[DEFAULT]</literal> section in
+                = True</literal> to the <literal>[DEFAULT]</literal>
-              <filename>/etc/neutron/neutron.conf</filename> to assist with
+              section in the
-              troubleshooting.</para>
+                <filename>/etc/neutron/neutron.conf</filename>
+              file.</para>
           </note>
         </step>
       </substeps>
@@ -172,17 +176,11 @@ allow_overlapping_ips = True</programlisting>
   </procedure>
   <procedure>
     <title>To configure the Modular Layer 2 (ML2) plug-in</title>
-    <para>The ML2 plug-in uses the Open vSwitch (OVS) mechanism (agent) to
+    <para>The ML2 plug-in uses the Open vSwitch (OVS) mechanism
-      build the virtual networking framework for instances.</para>
+      (agent) to build the virtual networking framework for
+      instances.</para>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Run the following commands:</para>
-      <para>Replace
-        <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
-        with the IP address of the instance tunnels network interface on
-        your compute node. This guide uses
-        <literal>10.0.1.31</literal> for the IP address of the
-        instance tunnels network interface on the first compute
-        node.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 \
   type_drivers gre</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 \
@@ -201,29 +199,35 @@ allow_overlapping_ips = True</programlisting>
   firewall_driver neutron.agent.linux.iptables_firewall.OVSHybridIptablesFirewallDriver</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/plugins/ml2/ml2_conf.ini securitygroup \
   enable_security_group True</userinput></screen>
+      <para>Replace
+          <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
+        with the IP address of the instance tunnels network interface
+        on your compute node. This guide uses
+          <literal>10.0.1.31</literal> for the IP address of the
+        instance tunnels network interface on the first compute
+        node.</para>
     </step>
     <step os="ubuntu;debian">
       <para>Edit the
-        <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
+          <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
-        file:</para>
+        file and add the following keys to the
-      <para>Add the following keys to the <literal>[ml2]</literal>
+          <literal>[ml2]</literal> section:</para>
-        section:</para>
       <programlisting language="ini">[ml2]
 ...
 type_drivers = gre
 tenant_network_types = gre
 mechanism_drivers = openvswitch</programlisting>
       <para>Add the following keys to the
-        <literal>[ml2_type_gre]</literal> section:</para>
+          <literal>[ml2_type_gre]</literal> section:</para>
       <programlisting language="ini">[ml2_type_gre]
 ...
 tunnel_id_ranges = 1:1000</programlisting>
       <para>Add the <literal>[ovs]</literal> section and the following
         keys to it:</para>
       <para>Replace
-        <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
+          <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
-        with the IP address of the instance tunnels network interface on
+        with the IP address of the instance tunnels network interface
-        your compute node.</para>
+        on your compute node.</para>
       <programlisting language="ini">[ovs]
 ...
 local_ip = <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
@@ -239,28 +243,29 @@ enable_security_group = True</programlisting>
   </procedure>
   <procedure>
     <title>To configure the Open vSwitch (OVS) service</title>
-    <para>The OVS service provides the underlying virtual networking framework
+    <para>The OVS service provides the underlying virtual networking
-      for instances. The integration bridge <literal>br-int</literal> handles
+      framework for instances. The integration bridge
-      internal instance network traffic within OVS.</para>
+        <literal>br-int</literal> handles internal instance network
+      traffic within OVS.</para>
     <step os="rhel;centos;fedora">
-      <para>Start the OVS service and configure it to start when the system
+      <para>Start the OVS service and configure it to start when the
-        boots:</para>
+        system boots:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch start</userinput>
+      <screen><prompt>#</prompt> <userinput>service openvswitch start</userinput>
 <prompt>#</prompt> <userinput>chkconfig openvswitch on</userinput></screen>
     </step>
     <step os="sles;opensuse">
-      <para>Start the OVS service and configure it to start when the system
+      <para>Start the OVS service and configure it to start when the
-        boots:</para>
+        system boots:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch-switch start</userinput>
+      <screen><prompt>#</prompt> <userinput>service openvswitch-switch start</userinput>
 <prompt>#</prompt> <userinput>chkconfig openvswitch-switch on</userinput></screen>
     </step>
     <step os="ubuntu">
       <para>Restart the OVS service:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch-switch restart</userinput></screen>
+      <screen><prompt>#</prompt> <userinput>service openvswitch-switch restart</userinput></screen>
     </step>
     <step os="debian">
       <para>Restart the OVS service:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch restart</userinput></screen>
+      <screen><prompt>#</prompt> <userinput>service openvswitch restart</userinput></screen>
     </step>
     <step>
       <para>Add the integration bridge:</para>
@@ -269,14 +274,11 @@ enable_security_group = True</programlisting>
   </procedure>
   <procedure>
     <title>To configure Compute to use Networking</title>
-    <para>By default, most distributions configure Compute to use legacy
+    <para>By default, most distributions configure Compute to use
-      networking. You must reconfigure Compute to manage networks through
+      legacy networking. You must reconfigure Compute to manage
-      Networking.</para>
+      networks through Networking.</para>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Run the following commands:</para>
-      <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-        password you chose for the <literal>neutron</literal> user
-        in the Identity service.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
   network_api_class nova.network.neutronv2.api.API</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
@@ -297,20 +299,24 @@ enable_security_group = True</programlisting>
   firewall_driver nova.virt.firewall.NoopFirewallDriver</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
   security_group_api neutron</userinput></screen>
+      <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
+        password you chose for the <literal>neutron</literal> user in
+        the Identity service.</para>
       <note>
-        <para>By default, Compute uses an internal firewall service. Since
+        <para>By default, Compute uses an internal firewall service.
-          Networking includes a firewall service, you must disable the
+          Since Networking includes a firewall service, you must
-          Compute firewall service by using the
+          disable the Compute firewall service by using the
-          <literal>nova.virt.firewall.NoopFirewallDriver</literal> firewall
+            <literal>nova.virt.firewall.NoopFirewallDriver</literal>
-          driver.</para>
+          firewall driver.</para>
       </note>
     </step>
     <step os="ubuntu;debian">
-      <para>Edit the <filename>/etc/nova/nova.conf</filename> and add the
+      <para>Edit the <filename>/etc/nova/nova.conf</filename> and add
-        following keys to the <literal>[DEFAULT]</literal> section:</para>
+        the following keys to the <literal>[DEFAULT]</literal>
+        section:</para>
       <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-        password you chose for the <literal>neutron</literal> user
+        password you chose for the <literal>neutron</literal> user in
-        in the Identity service.</para>
+        the Identity service.</para>
       <programlisting language="ini">[DEFAULT]
 ...
 network_api_class = nova.network.neutronv2.api.API
@@ -324,42 +330,43 @@ linuxnet_interface_driver = nova.network.linux_net.LinuxOVSInterfaceDriver
 firewall_driver = nova.virt.firewall.NoopFirewallDriver
 security_group_api = neutron</programlisting>
       <note>
-        <para>By default, Compute uses an internal firewall service. Since
+        <para>By default, Compute uses an internal firewall service.
-          Networking includes a firewall service, you must disable the
+          Since Networking includes a firewall service, you must
-          Compute firewall service by using the
+          disable the Compute firewall service by using the
-          <literal>nova.virt.firewall.NoopFirewallDriver</literal> firewall
+            <literal>nova.virt.firewall.NoopFirewallDriver</literal>
-          driver.</para>
+          firewall driver.</para>
       </note>
     </step>
   </procedure>
   <procedure>
     <title>To finalize the installation</title>
     <step os="rhel;centos;fedora">
-      <para>The Networking service initialization scripts expect a symbolic
+      <para>The Networking service initialization scripts expect a
-        link <filename>/etc/neutron/plugin.ini</filename> pointing to the
+        symbolic link <filename>/etc/neutron/plugin.ini</filename>
-        configuration file associated with your chosen plug-in. Using
+        pointing to the configuration file associated with your chosen
-        the ML2 plug-in, for example, the symbolic link must point to
+        plug-in. Using the ML2 plug-in, for example, the symbolic link
-        <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
+        must point to
+          <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
         If this symbolic link does not exist, create it using the
         following commands:</para>
       <screen><prompt>#</prompt> <userinput>ln -s plugins/ml2/ml2_conf.ini /etc/neutron/plugin.ini</userinput></screen>
-<!-- https://bugzilla.redhat.com/show_bug.cgi?id=1087647 -->
+      <!-- https://bugzilla.redhat.com/show_bug.cgi?id=1087647 -->
-      <para>Due to a packaging bug, the Open vSwitch agent initialization
+      <para>Due to a packaging bug, the Open vSwitch agent
-        script explicitly looks for the Open vSwitch plug-in configuration
+        initialization script explicitly looks for the Open vSwitch
-        file rather than a symbolic link
+        plug-in configuration file rather than a symbolic link
-        <filename>/etc/neutron/plugin.ini</filename> pointing to the ML2
+          <filename>/etc/neutron/plugin.ini</filename> pointing to the
-        plug-in configuration file. Run the following commands to resolve this
+        ML2 plug-in configuration file. Run the following commands to
-        issue:</para>
+        resolve this issue:</para>
       <screen><prompt>#</prompt> <userinput>cp /etc/init.d/neutron-openvswitch-agent /etc/init.d/neutron-openvswitch-agent.orig</userinput>
 <prompt>#</prompt> <userinput>sed -i 's,plugins/openvswitch/ovs_neutron_plugin.ini,plugin.ini,g' /etc/init.d/neutron-openvswitch-agent</userinput></screen>
     </step>
     <step os="sles;opensuse">
-      <para>The Networking service initialization scripts expect the variable
+      <para>The Networking service initialization scripts expect the
-        <literal>NEUTRON_PLUGIN_CONF</literal> in the
+        variable <literal>NEUTRON_PLUGIN_CONF</literal> in the
-        <filename>/etc/sysconfig/neutron</filename> file to reference the
+          <filename>/etc/sysconfig/neutron</filename> file to
-        configuration file associated with your chosen plug-in. Using
+        reference the configuration file associated with your chosen
-        ML2, for example, edit the
+        plug-in. Using ML2, for example, edit the
-        <filename>/etc/sysconfig/neutron</filename> file and add the
+          <filename>/etc/sysconfig/neutron</filename> file and add the
         following:</para>
       <programlisting>NEUTRON_PLUGIN_CONF="/etc/neutron/plugins/ml2/ml2_conf.ini"</programlisting>
     </step>
@@ -369,8 +376,8 @@ security_group_api = neutron</programlisting>
       <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service nova-compute restart</userinput></screen>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
-      <para>Start the Open vSwitch (OVS) agent and configure it to start when
+      <para>Start the Open vSwitch (OVS) agent and configure it to
-        the system boots:</para>
+        start when the system boots:</para>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>service neutron-openvswitch-agent start</userinput>
 <prompt>#</prompt> <userinput>chkconfig neutron-openvswitch-agent on</userinput></screen>
       <screen os="sles;opensuse"><prompt>#</prompt> <userinput>service openstack-neutron-openvswitch-agent start</userinput>

doc/install-guide/section_neutron-ml2-network-node.xml

@@ -4,10 +4,10 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
   <title>Configure network node</title>
+  <para>Before you install and configure OpenStack Networking, you
+    must enable certain kernel networking functions.</para>
   <procedure>
-    <title>Prerequisites</title>
+    <title>To enable kernel networking functions</title>
-    <para>Before you configure OpenStack Networking, you must enable certain
-      kernel networking functions.</para>
     <step>
       <para>Edit <filename>/etc/sysctl.conf</filename> to contain the
         following:</para>
@@ -30,8 +30,9 @@ net.ipv4.conf.default.rp_filter=0</programlisting>
       <screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-neutron-openvswitch-agent openstack-neutron-l3-agent \
   openstack-neutron-dhcp-agent openstack-neutron-metadata-agent</userinput></screen>
       <note os="ubuntu">
-        <para>Ubuntu installations using Linux kernel version 3.11 or newer
+        <para>Ubuntu installations using Linux kernel version 3.11 or
-          do not require the <emphasis>openvswitch-datapath-dkms</emphasis>
+          newer do not require the
+            <emphasis>openvswitch-datapath-dkms</emphasis>
           package.</para>
       </note>
       <note os="sles;opensuse">
@@ -44,21 +45,20 @@ net.ipv4.conf.default.rp_filter=0</programlisting>
     <para>The Networking common component configuration includes the
       authentication mechanism, message broker, and plug-in.</para>
     <step os="debian">
-      <para>Respond to prompts for
+      <para>Respond to prompts for <link
-        <link linkend="debconf-dbconfig-common">database management</link>,
+          linkend="debconf-dbconfig-common">database
-        <link linkend="debconf-keystone_authtoken">Identity service
+        management</link>, <link linkend="debconf-keystone_authtoken"
-        credentials</link>,
+          >Identity service credentials</link>, <link
-        <link linkend="debconf-api-endpoints">service endpoint
+          linkend="debconf-api-endpoints">service endpoint
-        registration</link>, and
+          registration</link>, and <link linkend="debconf-rabbitmq"
-        <link linkend="debconf-rabbitmq">message broker
+          >message broker credentials</link>.</para>
-        credentials</link>.</para>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Configure Networking to use the Identity service for
         authentication:</para>
       <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-        password you chose for the <literal>neutron</literal> user
+        password you chose for the <literal>neutron</literal> user in
-        in the Identity service.</para>
+        the Identity service.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   auth_strategy keystone</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf keystone_authtoken \
@@ -81,17 +81,18 @@ net.ipv4.conf.default.rp_filter=0</programlisting>
         authentication:</para>
       <substeps>
         <step>
-          <para>Edit the <filename>/etc/neutron/neutron.conf</filename>
+          <para>Edit the
-            file and add the following key to the
+              <filename>/etc/neutron/neutron.conf</filename> file and
-            <literal>[DEFAULT]</literal> section:</para>
+            add the following key to the <literal>[DEFAULT]</literal>
-            <programlisting language="ini">[DEFAULT]
+            section:</para>
+          <programlisting language="ini">[DEFAULT]
 ...
 auth_strategy = keystone</programlisting>
           <para>Add the following keys to the
-            <literal>[keystone_authtoken]</literal> section:</para>
+              <literal>[keystone_authtoken]</literal> section:</para>
-          <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
+          <para>Replace <replaceable>NEUTRON_PASS</replaceable> with
-            password you chose for the <literal>neutron</literal> user
+            the password you chose for the <literal>neutron</literal>
-            in the Identity service.</para>
+            user in the Identity service.</para>
           <programlisting language="ini">[keystone_authtoken]
 ...
 auth_uri = http://<replaceable>controller</replaceable>:5000
@@ -106,9 +107,9 @@ admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
     </step>
     <step os="sles;opensuse;rhel;centos;fedora">
       <para>Configure Networking to use the message broker:</para>
-      <para>Replace <replaceable>RABBIT_PASS</replaceable> with the password
+      <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
-        you chose for the <literal>guest</literal> account in
+        password you chose for the <literal>guest</literal> account in
-        <application>RabbitMQ</application>.</para>
+          <application>RabbitMQ</application>.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   rpc_backend neutron.openstack.common.rpc.impl_kombu</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
@@ -122,12 +123,13 @@ admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
       <para>Configure Networking to use the message broker:</para>
       <substeps>
         <step>
-          <para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
+          <para>Edit the
-            and add the following keys to the <literal>[DEFAULT]</literal>
+              <filename>/etc/neutron/neutron.conf</filename> file and
+            add the following keys to the <literal>[DEFAULT]</literal>
             section:</para>
-          <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
+          <para>Replace <replaceable>RABBIT_PASS</replaceable> with
-            password you chose for the <literal>guest</literal> account in
+            the password you chose for the <literal>guest</literal>
-            <application>RabbitMQ</application>.</para>
+            account in <application>RabbitMQ</application>.</para>
           <programlisting language="ini">[DEFAULT]
 ...
 rpc_backend = neutron.openstack.common.rpc.impl_kombu
@@ -137,26 +139,27 @@ rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
       </substeps>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
-      <para>Configure Networking to use the Modular Layer 2 (ML2) plug-in
+      <para>Configure Networking to use the Modular Layer 2 (ML2)
-        and associated services:</para>
+        plug-in and associated services:</para>
-        <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
+      <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   core_plugin ml2</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/neutron.conf DEFAULT \
   service_plugins router</userinput></screen>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/neutron.conf</filename> to assist with
+          in the <filename>/etc/neutron/neutron.conf</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
     <step os="ubuntu;debian">
-      <para>Configure Networking to use the Modular Layer 2 (ML2) plug-in
+      <para>Configure Networking to use the Modular Layer 2 (ML2)
-        and associated services:</para>
+        plug-in and associated services:</para>
       <substeps>
         <step>
-          <para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
+          <para>Edit the
-            and add the following keys to the <literal>[DEFAULT]</literal>
+              <filename>/etc/neutron/neutron.conf</filename> file and
+            add the following keys to the <literal>[DEFAULT]</literal>
             section:</para>
           <programlisting language="ini">[DEFAULT]
 ...
@@ -164,10 +167,11 @@ core_plugin = ml2
 service_plugins = router
 allow_overlapping_ips = True</programlisting>
           <note>
-            <para>We recommend adding <literal>verbose = True</literal> to
+            <para>To assist with troubleshooting, add <literal>verbose
-              the <literal>[DEFAULT]</literal> section in
+                = True</literal> to the <literal>[DEFAULT]</literal>
-              <filename>/etc/neutron/neutron.conf</filename> to assist with
+              section in the
-              troubleshooting.</para>
+                <filename>/etc/neutron/neutron.conf</filename>
+              file.</para>
           </note>
         </step>
       </substeps>
@@ -175,8 +179,8 @@ allow_overlapping_ips = True</programlisting>
   </procedure>
   <procedure>
     <title>To configure the Layer-3 (L3) agent</title>
-    <para>The <glossterm>Layer-3 (L3) agent</glossterm> provides routing
+    <para>The <glossterm>Layer-3 (L3) agent</glossterm> provides
-      services for instance virtual networks.</para>
+      routing services for instance virtual networks.</para>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Run the following commands:</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/l3_agent.ini DEFAULT \
@@ -184,32 +188,32 @@ allow_overlapping_ips = True</programlisting>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/l3_agent.ini DEFAULT \
   use_namespaces True</userinput></screen>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/l3_agent.ini</filename> to assist with
+          in the <filename>/etc/neutron/l3_agent.ini</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
     <step os="ubuntu;debian">
-      <para>Edit the <filename>/etc/neutron/l3_agent.ini</filename> file
+      <para>Edit the <filename>/etc/neutron/l3_agent.ini</filename>
-        and add the following keys to the <literal>[DEFAULT]</literal>
+        file and add the following keys to the
-        section:</para>
+          <literal>[DEFAULT]</literal> section:</para>
       <programlisting language="ini">[DEFAULT]
 ...
 interface_driver = neutron.agent.linux.interface.OVSInterfaceDriver
 use_namespaces = True</programlisting>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/l3_agent.ini</filename> to assist with
+          in the <filename>/etc/neutron/l3_agent.ini</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
   </procedure>
   <procedure>
     <title>To configure the DHCP agent</title>
     <para>The <glossterm>DHCP agent</glossterm> provides
-      <glossterm>DHCP</glossterm> services for instance virtual
+        <glossterm>DHCP</glossterm> services for instance virtual
       networks.</para>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Run the following commands:</para>
@@ -220,39 +224,40 @@ use_namespaces = True</programlisting>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/dhcp_agent.ini DEFAULT \
   use_namespaces True</userinput></screen>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/dhcp_agent.ini</filename> to assist with
+          in the <filename>/etc/neutron/dhcp_agent.ini</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
     <step os="ubuntu;debian">
-      <para>Edit the <filename>/etc/neutron/dhcp_agent.ini</filename> file
+      <para>Edit the <filename>/etc/neutron/dhcp_agent.ini</filename>
-        and add the following keys to the <literal>[DEFAULT]</literal>
+        file and add the following keys to the
-        section:</para>
+          <literal>[DEFAULT]</literal> section:</para>
       <programlisting language="ini">[DEFAULT]
 ...
 interface_driver = neutron.agent.linux.interface.OVSInterfaceDriver
 dhcp_driver = neutron.agent.linux.dhcp.Dnsmasq
 use_namespaces = True</programlisting>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/dhcp_agent.ini</filename> to assist with
+          in the <filename>/etc/neutron/dhcp_agent.ini</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
   </procedure>
   <procedure>
     <title>To configure the metadata agent</title>
-    <para>The <glossterm>metadata agent</glossterm> provides configuration
+    <para>The <glossterm>metadata agent</glossterm> provides
-      information such as credentials for remote access to instances.</para>
+      configuration information such as credentials for remote access
+      to instances.</para>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Run the following commands:</para>
       <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-        password you chose for the <literal>neutron</literal> user
+        password you chose for the <literal>neutron</literal> user in
-        in the Identity service. Replace
+        the Identity service. Replace
-        <replaceable>METADATA_SECRET</replaceable> with a suitable
+          <replaceable>METADATA_SECRET</replaceable> with a suitable
         secret for the metadata proxy.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/metadata_agent.ini DEFAULT \
   auth_url http://<replaceable>controller</replaceable>:5000/v2.0</userinput>
@@ -269,20 +274,21 @@ use_namespaces = True</programlisting>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/metadata_agent.ini DEFAULT \
   metadata_proxy_shared_secret <replaceable>METADATA_SECRET</replaceable></userinput></screen>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/metadata_agent.ini</filename> to assist with
+          in the <filename>/etc/neutron/metadata_agent.ini</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
     <step os="ubuntu;debian">
-      <para>Edit the <filename>/etc/neutron/metadata_agent.ini</filename> file
+      <para>Edit the
+          <filename>/etc/neutron/metadata_agent.ini</filename> file
         and add the following keys to the <literal>[DEFAULT]</literal>
         section:</para>
       <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
-        password you chose for the <literal>neutron</literal> user
+        password you chose for the <literal>neutron</literal> user in
-        in the Identity service. Replace
+        the Identity service. Replace
-        <replaceable>METADATA_SECRET</replaceable> with a suitable
+          <replaceable>METADATA_SECRET</replaceable> with a suitable
         secret for the metadata proxy.</para>
       <programlisting language="ini">[DEFAULT]
 ...
@@ -294,24 +300,23 @@ admin_password = <replaceable>NEUTRON_PASS</replaceable>
 nova_metadata_ip = <replaceable>controller</replaceable>
 metadata_proxy_shared_secret = <replaceable>METADATA_SECRET</replaceable></programlisting>
       <note>
-        <para>We recommend adding <literal>verbose = True</literal> to
+        <para>To assist with troubleshooting, add <literal>verbose =
-          the <literal>[DEFAULT]</literal> section in
+            True</literal> to the <literal>[DEFAULT]</literal> section
-          <filename>/etc/neutron/metadata_agent.ini</filename> to assist with
+          in the <filename>/etc/neutron/metadata_agent.ini</filename>
-          troubleshooting.</para>
+          file.</para>
       </note>
     </step>
     <step>
       <note>
         <para>Perform the next two steps on the
-        <emphasis>controller</emphasis> node.</para>
+            <emphasis>controller</emphasis> node.</para>
       </note>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
-      <para>On the <emphasis>controller</emphasis> node, configure Compute to
+      <para>On the <emphasis>controller</emphasis> node, configure
-        use the metadata service:</para>
+        Compute to use the metadata service:</para>
-      <para>Replace
+      <para>Replace <replaceable>METADATA_SECRET</replaceable> with
-        <replaceable>METADATA_SECRET</replaceable> with the secret you chose
+        the secret you chose for the metadata proxy.</para>
-        for the metadata proxy.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
   service_neutron_metadata_proxy true</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
@@ -319,36 +324,36 @@ metadata_proxy_shared_secret = <replaceable>METADATA_SECRET</replaceable></progr
     </step>
     <step os="ubuntu;debian">
       <para>On the <emphasis>controller</emphasis> node, edit the
-        <filename>/etc/nova/nova.conf</filename> file and add the following
+          <filename>/etc/nova/nova.conf</filename> file and add the
-        keys to the <literal>[DEFAULT]</literal> section:</para>
+        following keys to the <literal>[DEFAULT]</literal>
-      <para>Replace
+        section:</para>
-        <replaceable>METADATA_SECRET</replaceable> with the secret you chose
+      <para>Replace <replaceable>METADATA_SECRET</replaceable> with
-        for the metadata proxy.</para>
+        the secret you chose for the metadata proxy.</para>
       <programlisting language="ini">[DEFAULT]
 ...
 service_neutron_metadata_proxy = true
 neutron_metadata_proxy_shared_secret = <replaceable>METADATA_SECRET</replaceable></programlisting>
     </step>
     <step>
-      <para>On the <emphasis>controller</emphasis> node, restart the Compute
+      <para>On the <emphasis>controller</emphasis> node, restart the
-        <glossterm>API</glossterm> service:</para>
+        Compute <glossterm>API</glossterm> service:</para>
       <screen os="rhel;centos;fedora;sles;opensuse"><prompt>#</prompt> <userinput>service openstack-nova-api restart</userinput></screen>
       <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service nova-api restart</userinput></screen>
     </step>
   </procedure>
   <procedure>
     <title>To configure the Modular Layer 2 (ML2) plug-in</title>
-    <para>The ML2 plug-in uses the Open vSwitch (OVS) mechanism (agent) to
+    <para>The ML2 plug-in uses the Open vSwitch (OVS) mechanism
-      build virtual networking framework for instances.</para>
+      (agent) to build virtual networking framework for
+      instances.</para>
     <step os="rhel;centos;fedora;sles;opensuse">
       <para>Run the following commands:</para>
       <para>Replace
-        <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
+          <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
         with the IP address of the instance tunnels network interface
         on your network node. This guide uses
-        <literal>10.0.1.21</literal> for the IP address of the
+          <literal>10.0.1.21</literal> for the IP address of the
-        instance tunnels network interface on the network
+        instance tunnels network interface on the network node.</para>
-        node.</para>
       <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 \
   type_drivers gre</userinput>
 <prompt>#</prompt> <userinput>openstack-config --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 \
@@ -370,7 +375,7 @@ neutron_metadata_proxy_shared_secret = <replaceable>METADATA_SECRET</replaceable
     </step>
     <step os="ubuntu;debian">
       <para>Edit the
-        <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
+          <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
         file.</para>
       <para>Add the following keys to the <literal>[ml2]</literal>
         section:</para>
@@ -380,16 +385,16 @@ type_drivers = gre
 tenant_network_types = gre
 mechanism_drivers = openvswitch</programlisting>
       <para>Add the following keys to the
-        <literal>[ml2_type_gre]</literal> section:</para>
+          <literal>[ml2_type_gre]</literal> section:</para>
       <programlisting language="ini">[ml2_type_gre]
 ...
 tunnel_id_ranges = 1:1000</programlisting>
       <para>Add the <literal>[ovs]</literal> section and the following
         keys to it:</para>
       <para>Replace
-        <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
+          <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
-        with the IP address of the instance tunnels network interface on
+        with the IP address of the instance tunnels network interface
-        your network node.</para>
+        on your network node.</para>
       <programlisting language="ini">[ovs]
 ...
 local_ip = <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
@@ -405,33 +410,34 @@ enable_security_group = True</programlisting>
   </procedure>
   <procedure>
     <title>To configure the Open vSwitch (OVS) service</title>
-    <para>The OVS service provides the underlying virtual networking framework
+    <para>The OVS service provides the underlying virtual networking
-      for instances. The integration bridge <literal>br-int</literal> handles
+      framework for instances. The integration bridge
-      internal instance network traffic within OVS. The external bridge
+        <literal>br-int</literal> handles internal instance network
-      <literal>br-ex</literal> handles external instance network traffic
+      traffic within OVS. The external bridge <literal>br-ex</literal>
-      within OVS. The external bridge requires a port on the physical external
+      handles external instance network traffic within OVS. The
-      network interface to provide instances with external network access.
+      external bridge requires a port on the physical external network
-      In essence, this port bridges the virtual and physical external
+      interface to provide instances with external network access. In
+      essence, this port bridges the virtual and physical external
       networks in your environment.</para>
     <step os="rhel;centos;fedora">
-      <para>Start the OVS service and configure it to start when the system
+      <para>Start the OVS service and configure it to start when the
-        boots:</para>
+        system boots:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch start</userinput>
+      <screen><prompt>#</prompt> <userinput>service openvswitch start</userinput>
 <prompt>#</prompt> <userinput>chkconfig openvswitch on</userinput></screen>
     </step>
     <step os="sles;opensuse">
-      <para>Start the OVS service and configure it to start when the system
+      <para>Start the OVS service and configure it to start when the
-        boots:</para>
+        system boots:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch-switch start</userinput>
+      <screen><prompt>#</prompt> <userinput>service openvswitch-switch start</userinput>
 <prompt>#</prompt> <userinput>chkconfig openvswitch-switch on</userinput></screen>
     </step>
     <step os="ubuntu">
       <para>Restart the OVS service:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch-switch restart</userinput></screen>
+      <screen><prompt>#</prompt> <userinput>service openvswitch-switch restart</userinput></screen>
     </step>
     <step os="debian">
       <para>Restart the OVS service:</para>
-        <screen><prompt>#</prompt> <userinput>service openvswitch restart</userinput></screen>
+      <screen><prompt>#</prompt> <userinput>service openvswitch restart</userinput></screen>
     </step>
     <step>
       <para>Add the integration bridge:</para>
@@ -442,19 +448,19 @@ enable_security_group = True</programlisting>
       <screen><prompt>#</prompt> <userinput>ovs-vsctl add-br br-ex</userinput></screen>
     </step>
     <step>
-      <para>Add a port to the external bridge that connects to the physical
+      <para>Add a port to the external bridge that connects to the
-        external network interface:</para>
+        physical external network interface:</para>
       <para>Replace <replaceable>INTERFACE_NAME</replaceable> with the
-        actual interface name. For example, <emphasis>eth2</emphasis> or
+        actual interface name. For example, <emphasis>eth2</emphasis>
-        <emphasis>ens256</emphasis>.</para>
+        or <emphasis>ens256</emphasis>.</para>
       <screen><prompt>#</prompt> <userinput>ovs-vsctl add-port br-ex <replaceable>INTERFACE_NAME</replaceable></userinput></screen>
       <note>
-        <para>Depending on your network interface driver, you may need to
+        <para>Depending on your network interface driver, you may need
-          disable <glossterm>Generic Receive Offload (GRO)</glossterm> to
+          to disable <glossterm>Generic Receive Offload
-          achieve suitable throughput between your instances and the external
+            (GRO)</glossterm> to achieve suitable throughput between
-          network.</para>
+          your instances and the external network.</para>
-        <para>To temporarily disable GRO on the external network interface
+        <para>To temporarily disable GRO on the external network
-          while testing your environment:</para>
+          interface while testing your environment:</para>
         <screen><prompt>#</prompt> <userinput>ethtool -K <replaceable>INTERFACE_NAME</replaceable> gro off</userinput></screen>
       </note>
     </step>
@@ -462,37 +468,38 @@ enable_security_group = True</programlisting>
   <procedure>
     <title>To finalize the installation</title>
     <step os="rhel;centos;fedora">
-      <para>The Networking service initialization scripts expect a symbolic
+      <para>The Networking service initialization scripts expect a
-        link <filename>/etc/neutron/plugin.ini</filename> pointing to the
+        symbolic link <filename>/etc/neutron/plugin.ini</filename>
-        configuration file associated with your chosen plug-in. Using
+        pointing to the configuration file associated with your chosen
-        the ML2 plug-in, for example, the symbolic link must point to
+        plug-in. Using the ML2 plug-in, for example, the symbolic link
-        <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
+        must point to
+          <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
         If this symbolic link does not exist, create it using the
         following commands:</para>
-    <screen><prompt>#</prompt> <userinput>ln -s plugins/ml2/ml2_conf.ini /etc/neutron/plugin.ini</userinput></screen>
+      <screen><prompt>#</prompt> <userinput>ln -s plugins/ml2/ml2_conf.ini /etc/neutron/plugin.ini</userinput></screen>
-<!-- https://bugzilla.redhat.com/show_bug.cgi?id=1087647 -->
+      <!-- https://bugzilla.redhat.com/show_bug.cgi?id=1087647 -->
-      <para>Due to a packaging bug, the Open vSwitch agent initialization
+      <para>Due to a packaging bug, the Open vSwitch agent
-        script explicitly looks for the Open vSwitch plug-in configuration
+        initialization script explicitly looks for the Open vSwitch
-        file rather than a symbolic link
+        plug-in configuration file rather than a symbolic link
-        <filename>/etc/neutron/plugin.ini</filename> pointing to the ML2
+          <filename>/etc/neutron/plugin.ini</filename> pointing to the
-        plug-in configuration file. Run the following commands to resolve this
+        ML2 plug-in configuration file. Run the following commands to
-        issue:</para>
+        resolve this issue:</para>
       <screen><prompt>#</prompt> <userinput>cp /etc/init.d/neutron-openvswitch-agent /etc/init.d/neutron-openvswitch-agent.orig</userinput>
 <prompt>#</prompt> <userinput>sed -i 's,plugins/openvswitch/ovs_neutron_plugin.ini,plugin.ini,g' /etc/init.d/neutron-openvswitch-agent</userinput></screen>
     </step>
     <step os="sles;opensuse">
-      <para>The Networking service initialization scripts expect the variable
+      <para>The Networking service initialization scripts expect the
-        <literal>NEUTRON_PLUGIN_CONF</literal> in the
+        variable <literal>NEUTRON_PLUGIN_CONF</literal> in the
-        <filename>/etc/sysconfig/neutron</filename> file to reference the
+          <filename>/etc/sysconfig/neutron</filename> file to
-        configuration file associated with your chosen plug-in. Using
+        reference the configuration file associated with your chosen
-        ML2, for example, edit the
+        plug-in. Using ML2, for example, edit the
-        <filename>/etc/sysconfig/neutron</filename> file and add the
+          <filename>/etc/sysconfig/neutron</filename> file and add the
         following:</para>
       <programlisting>NEUTRON_PLUGIN_CONF="/etc/neutron/plugins/ml2/ml2_conf.ini"</programlisting>
     </step>
     <step os="rhel;centos;fedora;sles;opensuse">
-      <para>Start the Networking services and configure them to start when
+      <para>Start the Networking services and configure them to start
-        the system boots:</para>
+        when the system boots:</para>
       <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>service neutron-openvswitch-agent start</userinput>
 <prompt>#</prompt> <userinput>service neutron-l3-agent start</userinput>
 <prompt>#</prompt> <userinput>service neutron-dhcp-agent start</userinput>

doc/pom.xml

@@ -17,7 +17,6 @@
     <module>image-guide</module>
     <module>install-guide</module>
     <module>security-guide</module>
-    <module>training-guides</module>
     <module>user-guide</module>
     <module>user-guide-admin</module>
   </modules>
@@ -48,7 +47,7 @@
       <plugin>
         <groupId>com.rackspace.cloud.api</groupId>
         <artifactId>clouddocs-maven-plugin</artifactId>
-        <version>2.0.4</version>
+        <version>2.1.0</version>
       </plugin>
     </plugins>
   </build>