Install Guide: Edits on Networking chapter

Adds procedure, improves text.
Changes external link to Ubuntu Install Guide to internal link.

this is taken from https://review.openstack.org/#/c/52976/2 and
taken as separate patch

backport: havana
Closes-Bug: #1243132
Change-Id: If24cf613b57bbc1f5d214f3522b1b0a158703ded

doc/install-guide/ch_neutron.xml

@@ -6,21 +6,24 @@
     <title>Installing OpenStack Networking Service</title>
     <section xml:id="neutron-considerations">
         <title>Considerations for OpenStack Networking</title>
-  <para>There are many different drivers for OpenStack Networking,
+        <para>Drivers for OpenStack Networking range from software
-      that range from software bridges to full control of certain
+            bridges to full control of certain switching hardware.
-      switching hardware. This guide focuses on Open vSwitch. However,
+            This guide focuses on the Open vSwitch driver. However,
-      the theories presented here should be mostly applicable to other
+            the theories presented here should be mostly applicable to
-      mechanisms, and the <citetitle>OpenStack Configuration
+            other mechanisms, and the <link
-        Reference</citetitle> offers additional information.</para>
+                xlink:href="http://docs.openstack.org/havana/config-reference/content/"
-    <para>Please see <link
+                    ><citetitle>OpenStack Configuration
-        xlink:href="http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-packages.html"
+                    Reference</citetitle></link> offers additional
-        >OpenStack
+            information.</para>
-        Packages</link> for specific OpenStack installation
+        <para>For specific OpenStack installation instructions to
-      instructions to prepare for installation.</para>
+            prepare for installation, see <xref
-            <warning><para>If you have followed the previous section on
+            linkend="basics-packages" />.</para>
-                setting up networking for your compute node using
+        <warning>
-                nova-network, this configuration will override those
+            <para>If you followed the previous chapter to set up
-                settings.</para></warning>
+                networking for your compute node using <systemitem
+                    role="service">nova-network</systemitem>, this
+                configuration overrides those settings.</para>
+        </warning>
     </section>
     <xi:include href="section_neutron-concepts.xml"/>
     <xi:include href="section_neutron-install.xml"/>

doc/install-guide/section_neutron-concepts.xml

@@ -4,81 +4,105 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:svg="http://www.w3.org/2000/svg"
-  xmlns:html="http://www.w3.org/1999/xhtml"
+  xmlns:html="http://www.w3.org/1999/xhtml" version="5.0">
-  version="5.0">
+  <title>Neutron Concepts</title>
-  <title>Neutron concepts</title>
+  <para>Like Nova Networking, Neutron manages software-defined
-  <para>Like Nova Networking, Neutron manages software-defined networking for your OpenStack
+    networking for your OpenStack installation. However, unlike Nova
-    installation. However, unlike Nova Networking, Neutron can be configured for advanced virtual
+    Networking, you can configure Neutron for advanced virtual network
-    network topologies, such as per-tenant private networks, and more.</para>
+    topologies, such as per-tenant private networks and more.</para>
-  <para>Neutron has three main object abstractions: networks, subnets, and routers. Each has
+  <para>Neutron has the following object abstractions: networks,
-    functionality that mimics its physical counterpart: networks contain subnets, and routers route
+    subnets, and routers. Each has functionality that mimics its
+    physical counterpart: networks contain subnets, and routers route
     traffic between different subnet and networks.</para>
-  <para>In any given Neutron setup, there is at least one external network. This network, unlike the
+  <para>Any given Neutron set up has at least one external network.
-    other networks, is not merely an virtually defined network. Instead, it represents the view into
+    This network, unlike the other networks, is not merely a virtually
-    a slice of the external network, accessible outside the OpenStack installation. IP addresses on
+    defined network. Instead, it represents the view into a slice of
-    Neutron's external network are in fact accessible by anybody physically on the outside network.
+    the external network that is accessible outside the OpenStack
-    Because this network merely represents a slice of the outside network, DHCP is disabled on this
+    installation. IP addresses on the Neutron external network are
-    network.</para>
+    accessible by anybody physically on the outside network. Because
-  <para>In addition external networks, any Neutron setup will have one or more internal networks.
+    this network merely represents a slice of the outside network,
-    These software-defined networks connect directly to the VMs. Only the VMs on any given internal
+    DHCP is disabled on this network.</para>
-    network, or those on subnets connected via interfaces to a similar router, can access VMs
+  <para>In addition to external networks, any Neutron set up has one
-    connected to that network directly.</para>
+    or more internal networks. These software-defined networks connect
-  <para>In order for the outside network to be able to access VMs, and vice versa, routers between
+    directly to the VMs. Only the VMs on any given internal network,
-    the networks are needed. Each router has one gateway, connected to a network, and many
+    or those on subnets connected through interfaces to a similar
-    interfaces, connected to subnets. Like a physical router, subnets can access machines on other
+    router, can access VMs connected to that network directly.</para>
-    subnets connected to the same router, and machines can access the outside network through the
+  <para>For the outside network to access VMs, and vice versa, routers
-    router's gateway.</para>
+    between the networks are needed. Each router has one gateway that
-  <para>Additionally, IP addresses on an external networks can be allocated to ports on the internal
+    is connected to a network and many interfaces that are connected
-    network. Whenever something is connected to a subnet, that connection is called a port. External
+    to subnets. Like a physical router, subnets can access machines on
-    network IP addresses can be associated with ports to VMs. This way, entities on the outside
+    other subnets that are connected to the same router, and machines
-    network can access VMs.</para>
+    can access the outside network through the gateway for the
-  <para>Neutron also supports "security groups." Security groups allow administrators to define
+    router.</para>
-    firewall rules in groups. Then, a given VM can have one or more security groups to which it
+  <para>Additionally, you can allocate IP addresses on an external
-    belongs, and Neutron will apply those rules to block or unblock ports, port ranges, or traffic
+    networks to ports on the internal network. Whenever something is
-    types for that VM.</para>
+    connected to a subnet, that connection is called a port. You can
-  <para>Each of the plugins that Neutron uses has its own concepts as well. While not vital to
+    associate external network IP addresses with ports to VMs. This
-    operating Neutron, these concepts can be useful to help with setting up Neutron. All Neutron
+    way, entities on the outside network can access VMs.</para>
-    installations use a core plugin, as well as a security group plugin (or just the No-Op security
+  <para>Neutron also supports <emphasis role="italic">security
-    group plugin). Additionally, Firewall-as-a-service (FWaaS) and Load-balancing-as-a-service
+      groups</emphasis>. Security groups enable administrators to
-    (LBaaS) plugins are available.</para>
+    define firewall rules in groups. A VM can belong to one or more
+    security groups, and Neutron applies the rules in those security
+    groups to block or unblock ports, port ranges, or traffic types
+    for that VM.</para>
+  <para>Each plug-in that Neutron uses has its own concepts. While not
+    vital to operating Neutron, understanding these concepts can help
+    you set up Neutron. All Neutron installations use a core plug-in
+    and a security group plug-in (or just the No-Op security group
+    plug-in). Additionally, Firewall-as-a-service (FWaaS) and
+    Load-balancing-as-a-service (LBaaS) plug-ins are available.</para>
   <section xml:id="concepts-neutron.openvswitch">
     <title>Open vSwitch Concepts</title>
-    <para>The Open vSwitch plugin is one of the most popular core plugins. Open vSwitch
+    <para>The Open vSwitch plug-in is one of the most popular core
-      configurations consists of bridges and ports. Ports represent connections to other things,
+      plug-ins. Open vSwitch configurations consists of bridges and
-      such as physical interfaces and patch cables. Packets from any given port on a bridge is
+      ports. Ports represent connections to other things, such as
-      shared with all other ports on that bridge. Bridges can be connected through Open vSwitch
+      physical interfaces and patch cables. Packets from any given
-      virtual patch cables, or through Linux virtual Ethernet cables (<literal>veth</literal>).
+      port on a bridge is shared with all other ports on that bridge.
-      Additionally, bridges appear as network interfaces to Linux, so they can be assigned IP
+      Bridges can be connected through Open vSwitch virtual patch
-      addresses.</para>
+      cables or through Linux virtual Ethernet cables
-    <para>In Neutron, there are several main bridges. The integration bridge, called
+        (<literal>veth</literal>). Additionally, bridges appear as
-        <literal>br-int</literal>, connects directly to the VMs and associated services. The
+      network interfaces to Linux, so you can assign IP addresses to
-      external bridge, called <literal>br-ex</literal>, connects to the external network. Finally,
+      them.</para>
-      the VLAN configuration of the Open vSwitch plugin uses bridges associated with each physical
+    <para>In Neutron, the integration bridge, called
+        <literal>br-int</literal>, connects directly to the VMs and
+      associated services. The external bridge, called
+        <literal>br-ex</literal>, connects to the external network.
+      Finally, the VLAN configuration of the Open vSwitch plug-in uses
+      bridges associated with each physical network.</para>
+    <para>In addition to defining bridges, Open vSwitch has OpenFlow,
+      which enables you to define networking flow rules. Certain
+      configurations use these rules to transfer packets between
+      VLANs.</para>
+    <para>Finally, some configurations of Open vSwitch use network
+      namespaces that enable Linux to group adapters into unique
+      namespaces that are not visible to other namespaces, which
+      allows the same network node to manage multiple Neutron
+      routers.</para>
+    <para>With Open vSwitch, you can use two different technologies to
+      create the virtual networks: GRE or VLANs.</para>
+    <para>Generic Routing Encapsulation (GRE) is the technology used
+      in many VPNs. It wraps IP packets to create entirely new packets
+      with different routing information. When the new packet reaches
+      its destination, it is unwrapped, and the underlying packet is
+      routed. To use GRE with Open vSwitch, Neutron creates GRE
+      tunnels. These tunnels are ports on a bridge and enable bridges
+      on different systems to act as though they were one bridge,
+      which allows the compute and network nodes to act as one for the
+      purposes of routing.</para>
+    <para>Virtual LANs (VLANs), on the other hand, use a special
+      modification to the Ethernet header. They add a 4-byte VLAN tag
+      that ranges from 1 to 4094 (the 0 tag is special, and the 4095
+      tag, made of all ones, is equivalent to an untagged packet).
+      Special NICs, switches, and routers know how to interpret the
+      VLAN tags, as does Open vSwitch. Packets tagged for one VLAN are
+      only shared with other devices configured to be on that VLAN,
+      even through all devices are on the same physical
       network.</para>
-    <para>In addition to defining bridges, Open vSwitch has OpenFlow, which allows you to define
+    <para>The most common security group driver used with Open vSwitch
-      networking flow rules. These rules are used in certain configurations to transfer packets
+      is the Hybrid IPTables/Open vSwitch plug-in. It uses a
-      between VLANs.</para>
+      combination for IPTables and OpenFlow rules. Use the IPTables
-    <para>Finally, some configurations of Open vSwitch use network namespaces. This allows linux to
+      tool to create firewalls and set up NATs on Linux. This tool
-      group adapters into unique namespaces that are not visible to other namespaces, allowing
+      uses a complex rule system and chains of rules to accommodate
-      multiple Neutron routers to be managed by the same network node.</para>
+      the complex rules required by Neutron security groups.</para>
-    <para>With Open vSwitch, there are two different technologies that can be used to create the
-      virtual networks: GRE or VLANs.</para>
-    <para>Generic Routing Encapsulation, or GRE for short, is the technology used in many VPNs. In
-      essence, it works by wrapping IP packets and creating entirely new packets with different routing
-      information. When the new packet reaches its destination, it is unwrapped, and the underlying
-      packet is routed. To use GRE with Open vSwitch, Neutron creates GRE Tunnels. This tunnels are
-      ports on a bridge, and allow bridges on different systems to act as though they were in fact
-      one bridge, allowing the compute node and network node to act as one for the purposes of
-      routing.</para>
-    <para>Virtual LANs, or VLANs for short, on the other hand, use a special modification to the
-      Ethernet header. They add a 4-byte VLAN tag that ranges between 1 and 4094 (the 0 tag is
-      special, and the 4095 tag, made of all ones, is equivalent to an untagged packet). Special
-      NICs, switches, and routers know how to interpret the VLAN tags, as does Open vSwitch. Packets
-      tagged for one VLAN will only be shared with other devices configured to be on that VLAN,
-      despite the fact that all of the devices are on the same physical network.</para>
-    <para>The most common security group driver used with Open vSwitch is the Hybrid IPTables/Open
-      vSwitch plugin. It uses a combination for IPTables and OpenFlow rules. IPTables is a tool used
-      for creating firewalls and setting up NATs on Linux. It uses a complex rule system and
-      "chains" of rules to allow for the complex rules required by Neutron's security groups.</para>
   </section>
 </section>