From b79d15e67fc30c5fbeb00048b6728ea247783b91 Mon Sep 17 00:00:00 2001 From: John R Barker Date: Thu, 5 Oct 2017 18:47:32 +0100 Subject: [PATCH] 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 --- .../rst/network_debug_troubleshooting.rst | 61 ++++++++++--------- docs/docsite/rst/porting_guide_2.3.rst | 26 +------- 2 files changed, 33 insertions(+), 54 deletions(-) diff --git a/docs/docsite/rst/network_debug_troubleshooting.rst b/docs/docsite/rst/network_debug_troubleshooting.rst index 6cbd5c10a3c..48da69a6513 100644 --- a/docs/docsite/rst/network_debug_troubleshooting.rst +++ b/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 ` for more information. * Not using ``connection: local`` @@ -410,10 +410,10 @@ For example: Suggestions to resolve: -Increase value of presistent connection idle timeout. -Note: This value should be greater than SSH timeout ie. timeout value under defaults -section in configuration file and less than the value of the persistent -connection idle timeout (connect_timeout) +Increase the value of the persistent connection idle timeout. +Note: This value should be greater than the SSH timeout value (the timeout value under the defaults +section in the configuration file) and less than the value of the persistent +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 - ---------------------- - - FIXME Do we get an error message - - FIXME Link to howto - - +Proxy Issues +============ + .. _network_delegate_to_vs_ProxyCommand: - fixmes - ====== +delegate_to vs ProxyCommand +--------------------------- - Error: "number of connection attempts exceeded, unable to connect to control socket" - ------------------------------------------------------------------------------------ +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``. - **Platforms:** Any +To use ``ProxyCommand``, configure the proxy settings in the Ansible inventory +file to specify the proxy host. - This occurs when Ansible wasn't able to connect to the remote device and obtain a shell with the timeout. +.. code-block:: ini + [nxos] + nxos01 + nxos02 - This information is available when :ref:`DEFAULT_LOG_PATH` is set see (FIXMELINKTOSECTION): + [nxos:vars] + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' - .. 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! => { +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. - Suggestions to resolve: - Do stuff For example: +.. note:: Using ``ProxyCommand`` with passwords via variables - .. code-block:: yaml + 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. - Example stuff + We recommend using SSH Keys, and if needed an ssh-agent, rather than passwords, where ever possible. diff --git a/docs/docsite/rst/porting_guide_2.3.rst b/docs/docsite/rst/porting_guide_2.3.rst index 7b8273b51f7..cf2bebfad1d 100644 --- a/docs/docsite/rst/porting_guide_2.3.rst +++ b/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. - -.. 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. +file to specify the proxy host via ``ansible_ssh_common_args``. +For details on how to do this see the :ref:`network proxy guide `.