Improve and link Network Proxy docs (#31316)

* Improve and link Network Proxy docs

It is possible for proxy issues to cause "unable to open shell", so
detail there.

Having the "how-to" in the debug page makes more sense than on the
porting page, so move it.

Fixed a few formatting issues at the same time.

* Edits

* typo

docs/docsite/rst/network_debug_troubleshooting.rst

@@ -32,7 +32,7 @@ Errors generally fall into one of the following categories:
   * Can occur when trying to pull a large amount of data
   * May actually be masking a authentication issue
 :Playbook issues:
-  * Use of ``delegate_to``, instead of ``ProxyCommand``
+  * Use of ``delegate_to``, instead of ``ProxyCommand``. See :ref:`network proxy guide <network_delegate_to_vs_ProxyCommand>` for more information.
   * Not using ``connection: local``
 
 
@@ -410,10 +410,10 @@ For example:
 
 Suggestions to resolve:
 
-Increase value of presistent connection idle timeout.
+Increase the value of the persistent connection idle timeout.
-Note: This value should be greater than SSH timeout ie. timeout value under defaults
+Note: This value should be greater than the SSH timeout value (the timeout value under the defaults
-section in configuration file and less than the value of the persistent
+section in the configuration file) and less than the value of the persistent
-connection idle timeout (connect_timeout)
+connection idle timeout (connect_timeout).
 
 .. code-block:: yaml
 
@@ -493,7 +493,7 @@ Add ``authorize: yes`` to the task. For example:
 If the user requires a password to go into privileged mode, this can be specified with ``auth_pass``; if ``auth_pass`` isn't set, the environment variable :envvar:`ANSIBLE_NET_AUTHORIZE` will be used instead.
 
 
-Add `authorize: yes` to the task. For example:
+Add ``authorize: yes`` to the task. For example:
 
 .. code-block:: yaml
 
@@ -506,40 +506,41 @@ Add `authorize: yes` to the task. For example:
   register: result
 
 
-.. delete_to not honoured
+Proxy Issues
-   ----------------------
+============
 
-   FIXME Do we get an error message
+ .. _network_delegate_to_vs_ProxyCommand:
 
-   FIXME Link to howto
+delegate_to vs ProxyCommand
+---------------------------
+
+The new connection framework for Network Modules in Ansible 2.3 that uses ``cli`` transport
+no longer supports the use of the ``delegate_to`` directive.
+In order to use a bastion or intermediate jump host to connect to network devices over ``cli``
+transport, network modules now support the use of ``ProxyCommand``.
+
+To use ``ProxyCommand``, configure the proxy settings in the Ansible inventory
+file to specify the proxy host.
+
+.. code-block:: ini
+
+    [nxos]
+    nxos01
+    nxos02
+
+    [nxos:vars]
+    ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
 
 
+With the configuration above, simply build and run the playbook as normal with
+no additional changes necessary.  The network module will now connect to the
+network device by first connecting to the host specified in
+``ansible_ssh_common_args``, which is ``bastion01`` in the above example.
 
 
-   fixmes
+.. note:: Using ``ProxyCommand`` with passwords via variables
-   ======
 
-   Error: "number of connection attempts exceeded, unable to connect to control socket"
+   By design, SSH doesn't support providing passwords via environment variables.
-   ------------------------------------------------------------------------------------
+   This is done to prevent secrets from leaking out, for example in ``ps`` output.
 
-   **Platforms:** Any
+   We recommend using SSH Keys, and if needed an ssh-agent, rather than passwords, where ever possible.
-
-   This occurs when Ansible wasn't able to connect to the remote device and obtain a shell with the timeout.
-
-
-   This information is available when :ref:`DEFAULT_LOG_PATH` is set see (FIXMELINKTOSECTION):
-
-   .. code-block:: yaml
-
-     less $ANSIBLE_LOG_PATH
-     2017-03-10 15:32:06,173 p=19677 u=fred |  connect retry timeout expired, unable to connect to control socket
-     2017-03-10 15:32:06,174 p=19677 u=fred |  persistent_connect_retry_timeout is 15 secs
-     2017-03-10 15:32:06,222 p=19669 u=fred |  fatal: [veos01]: FAILED! => {
-
-   Suggestions to resolve:
-
-   Do stuff For example:
-
-   .. code-block:: yaml
-
-   	Example stuff

docs/docsite/rst/porting_guide_2.3.rst

@@ -219,28 +219,6 @@ In order to use a bastion or intermediate jump host to connect to network device
 transport, network modules now support the use of ``ProxyCommand``.
 
 To use ``ProxyCommand`` configure the proxy settings in the Ansible inventory
-file to specify the proxy host.
+file to specify the proxy host via ``ansible_ssh_common_args``.
-
-.. code-block:: ini
-
-    [nxos]
-    nxos01
-    nxos02
-
-    [nxos:vars]
-    ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
-
-
-With the configuration above, simply build and run the playbook as normal with
-no additional changes necessary.  The network module will now connect to the
-network device by first connecting to the host specified in
-``ansible_ssh_common_args`` which is ``bastion01`` in the above example.
-
-
-.. notes: Using ``ProxyCommand`` with passwords via variables
-
-   It is a feature that SSH doesn't support providing passwords via environment variables.
-   This is done to prevent secrets from leaking out, for example in ``ps`` output.
-
-   We recommend using SSH Keys, and if needed and ssh-agent, rather than passwords, where ever possible.
 
+For details on how to do this see the :ref:`network proxy guide <network_delegate_to_vs_ProxyCommand>`.