cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Improve and link Network Proxy docs (#31316)

Browse source 
* 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
This commit is contained in:
John R Barker 2017-10-05 18:47:32 +01:00 • committed by GitHub
parent 95e1d91d5d
commit b79d15e67f
2 changed files with 38 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
docs/docsite/rst/network_debug_troubleshooting.rst
View file

@ -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.
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
----------------------
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
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
We recommend using SSH Keys, and if needed an ssh-agent, rather than passwords, where ever possible.

26
docs/docsite/rst/porting_guide_2.3.rst
View file

@ -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 <network_delegate_to_vs_ProxyCommand>`.