Improve network documentation

The MTU docs were not in the usage section, which is problematic
since many users will not be doing the host cloud setup.  This
change also improves the documentation around deploying a network
isolation cloud in an OVB environment.

doc/source/host-cloud/configuration.rst

@@ -31,25 +31,8 @@ host cloud.
 
    If this cannot be done (perhaps because you don't have access to make
    such a change on the host cloud), it will likely be necessary to
-   configure a smaller MTU on the deployed virtual instances.  For a
-   TripleO undercloud, this can be done by setting the ``local_mtu``
-   option in ``undercloud.conf`` to a smaller value (1450 will
-   usually work).
-
-   .. note::
-      In older versions of TripleO it may be necessary to do the MTU
-      configuration manually.  That can be done with the following
-      commands (as root)::
-
-          # Replace 'eth1' with the actual device to be used for the
-          # provisioning network
-          ip link set eth1 mtu 1350
-          echo -e "\ndhcp-option-force=26,1350" >> /etc/dnsmasq-ironic.conf
-          systemctl restart 'neutron-*'
-
-   If network isolation is used in the virtual deployment, the templates must
-   also configure mtu as discussed above, except the mtu should be set to 1350
-   instead of 1550.
+   configure a smaller MTU on the deployed virtual instances.  Details
+   on doing so can be found on the :doc:`../usage/usage` page.
 
 #. Restart ``nova-compute`` and ``neutron-openvswitch-agent`` to apply the
    changes above.

doc/source/usage/usage.rst

@@ -20,7 +20,52 @@ After an OVB environment has been deployed, there are a few things to know.
    .. note:: **Do not** rebuild the bmc.  It is unnecessary and not guaranteed
              to work.
 
-#. If using the full network isolation provided by OS::OVB::BaremetalNetworks
-   then a TripleO overcloud can be deployed in the OVB environment by using
-   the network templates in the ``network-templates`` (for ipv4) or
-   ``ipv6-network-templates`` (for ipv6) directories.
+#. If the host cloud's tenant network MTU is 1500 or less, it will be necessary
+   to configure the deployed interfaces with a smaller MTU.  The tenant network
+   MTU minus 50 is usually a safe value.  For the undercloud this can be done
+   by setting ``local_mtu`` in ``undercloud.conf``.
+
+   .. note::
+      In Mitaka and older versions of TripleO it will be necessary to do the
+      MTU configuration manually.  That can be done with the following
+      commands (as root)::
+
+          # Replace 'eth1' with the actual device to be used for the
+          # provisioning network
+          ip link set eth1 mtu 1350
+          echo -e "\ndhcp-option-force=26,1350" >> /etc/dnsmasq-ironic.conf
+          systemctl restart 'neutron-*'
+
+#. If using the full network isolation provided by one of the
+   ``all-networks*.yaml`` environments then a TripleO overcloud can be deployed
+   in the OVB environment by using the network templates in the
+   ``overcloud-templates`` directory.  The names are fairly descriptive, but
+   this is a brief explanation of each:
+
+   - **network-templates:** IPv4 multi-nic.  Usable with the network layout
+     deployed by the ``all-networks.yaml`` and
+     ``all-networks-port-security.yaml`` environments.
+   - **ipv6-network-templates:** IPv6 multi-nic. Usable with the network layout
+     deployed by the ``all-networks.yaml`` and
+     ``all-networks-port-security.yaml`` environments.
+   - **bond-network-templates:** IPv4 multi-nic, with duplicate `public`
+     interfaces for testing bonded nics.  Usable with the network layout
+     deployed by the ``all-networks-public-bond.yaml`` and
+     ``all-networks-public-bond-port-security.yaml`` environments.
+
+   The undercloud's ``public`` interface should be configured with the address
+   of the default route from the templates in use.  Firewall rules for
+   forwarding the traffic from that interface should also be added.  The
+   following commands will make the necessary configuration::
+
+      cat >> /tmp/eth2.cfg <<EOF_CAT
+      network_config:
+        - type: interface
+          name: eth2
+          use_dhcp: false
+          addresses:
+            - ip_netmask: 10.0.0.1/24
+            - ip_netmask: 2001:db8:fd00:1000::1/64
+      EOF_CAT
+      sudo os-net-config -c /tmp/eth2.cfg -v
+      sudo iptables -A POSTROUTING -s 10.0.0.0/24 ! -d 10.0.0.0/24 -j MASQUERADE -t nat