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

Describe different ways to set connection timeout options (#65126)

Browse source 
* add timeout option examples, link to new section, implement feedback
This commit is contained in:
Sandra McCann 2019-12-02 11:42:45 -05:00 • committed by Alicia Cozine
parent a8ef5d5034
commit 41472ee387
26 changed files with 153 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/docsite/rst/network/getting_started/index.rst
View file

@ -30,4 +30,5 @@ This guide introduces basic Ansible concepts and guides you through your first A
first_inventory
network_roles
intermediate_concepts
network_connection_options
network_resources

48
docs/docsite/rst/network/getting_started/network_connection_options.rst Normal file
View file

@ -0,0 +1,48 @@
.. _network_connection_options:
***************************************
Working with network connection options
***************************************
Network modules can support multiple connection protocols, such as ``network_cli``, ``netconf``, and ``httpapi``. These connections include some common options you can set to control how the connection to your network device behaves.
Common options are:
* ``become`` and ``become_method`` as described in :ref:`privilege_escalation`.
* ``network_os`` - set to match your network platform you are communicating with. See the :ref:`platform-specific <platform_options>` pages.
* ``remote_user`` as described in :ref:`playbook_hosts_and_users`.
* Timeout options - ``persistent_command_timeout``, ``persistent_connect_timeout``, and ``timeout``.
.. _timeout_options:
Setting timeout options
=======================
When communicating with a remote device, you have control over how long Ansible maintains the connection to that device, as well as how long Ansible waits for a command to complete on that device. Each of these options can be set as variables in your playbook files, environment variables, or settings in your :ref:`ansible.cfg file <ansible_configuration_settings>`.
For example, the three options for controlling the connection timeout are as follows.
Using vars (per task):
.. code-block:: yaml
- name: save running-config
ios_command:
commands: copy running-config startup-config
vars:
ansible_command_timeout: 30
Using the environment variable:
.. code-block:: bash
$export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=30
Using the global configuration (in :file:`ansible.cfg`)
.. code-block:: ini
[persistent_connection ]
command_timeout = 30
See :ref:`ansible_variable_precedence` for details on the relative precedence of each of these variables. See the individual connection type to understand each option.

3
docs/docsite/rst/network/getting_started/network_differences.rst
View file

@ -30,7 +30,7 @@ Because network modules execute on the control node instead of on the managed no
.. note::
``httpapi`` deprecates ``eos_eapi`` and ``nxos_nxapi``. See :ref:`httpapi_plugins` for details and an example.
Beginning with Ansible 2.6, we recommend using one of the persistent connection types listed above instead of ``local``. With persistent connections, you can define the hosts and credentials only once, rather than in every task. For more details on using each connection type on various platforms, see the :ref:`platform-specific <platform_options>` pages.
Beginning with Ansible 2.6, we recommend using one of the persistent connection types listed above instead of ``local``. With persistent connections, you can define the hosts and credentials only once, rather than in every task. You also need to set the ``network_os`` variable for the specific network platform you are communicating with. For more details on using each connection type on various platforms, see the :ref:`platform-specific <platform_options>` pages.
Modules Organized by Network Platform
@ -45,6 +45,7 @@ A network platform is a set of network devices with a common operating system th
All modules within a network platform share certain requirements. Some network platforms have specific differences - see the :ref:`platform-specific <platform_options>` documentation for details.
.. _privilege_escalation:
Privilege Escalation: ``enable`` mode, ``become``, and ``authorize``
================================================================================

8
docs/docsite/rst/network/user_guide/platform_ce.rst
View file

@ -17,7 +17,7 @@ Connections Available
==================== ========================================== =========================
.. CLI NETCONF
==================== ========================================== =========================
Protocol SSH XML over SSH
@ -88,7 +88,7 @@ To enable NETCONF on a new switch via Ansible, use the ``ce_config`` module via
connection: network_cli
ce_config:
lines:
- snetconf server enable
- snetconf server enable
when: ansible_network_os == 'ce'
Once NETCONF is enabled, change your variables to use the NETCONF connection.
@ -205,3 +205,7 @@ Modules work with connection C(netconf)
ce_vxlan_vap
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

6
docs/docsite/rst/network/user_guide/platform_cnos.rst
View file

@ -4,7 +4,7 @@
CNOS Platform Options
***************************************
CNOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible.
CNOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible.
.. contents:: Topics
@ -71,3 +71,7 @@ Example CLI Task
when: ansible_network_os == 'cnos'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_dellos10.rst
View file

@ -72,3 +72,7 @@ Example CLI Task
when: ansible_network_os == 'dellos10'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_dellos6.rst
View file

@ -72,3 +72,7 @@ Example CLI Task
when: ansible_network_os == 'dellos6'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_dellos9.rst
View file

@ -72,3 +72,7 @@ Example CLI Task
when: ansible_network_os == 'dellos9'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

6
docs/docsite/rst/network/user_guide/platform_enos.rst
View file

@ -4,7 +4,7 @@
ENOS Platform Options
***************************************
ENOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible.
ENOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible.
.. contents:: Topics
@ -73,3 +73,7 @@ Example CLI Task
when: ansible_network_os == 'enos'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_eos.rst
View file

@ -178,3 +178,7 @@ In this example two variables defined in ``group_vars`` get passed to the module
- the ``proxy_env`` variable gets passed to the ``environment`` option of the module
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_eric_eccli.rst
View file

@ -66,3 +66,7 @@ Example CLI Task
when: ansible_network_os == 'eric_eccli'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_exos.rst
View file

@ -100,3 +100,7 @@ Example EXOS-API Task
In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module used in the task.
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_icx.rst
View file

@ -70,3 +70,7 @@ Example CLI Task
when: ansible_network_os == 'icx'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_ios.rst
View file

@ -72,3 +72,7 @@ Example CLI Task
when: ansible_network_os == 'ios'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

10
docs/docsite/rst/network/user_guide/platform_iosxr.rst
View file

@ -17,8 +17,8 @@ Connections Available
==================== ========================================== =========================
.. CLI NETCONF
only for modules ``iosxr_banner``,
``iosxr_interface``, ``iosxr_logging``,
only for modules ``iosxr_banner``,
``iosxr_interface``, ``iosxr_logging``,
``iosxr_system``, ``iosxr_user``
==================== ========================================== =========================
Protocol SSH XML over SSH
@ -121,4 +121,8 @@ Example NETCONF Task
- redhat.com
- cisco.com
.. include:: shared_snippets/SSH_warning.txt
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_ironware.rst
View file

@ -73,3 +73,7 @@ Example CLI Task
when: ansible_network_os == 'ironware'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_junos.rst
View file

@ -121,3 +121,7 @@ Example NETCONF Task
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_meraki.rst
View file

@ -37,3 +37,7 @@ Example Meraki Task
org_name: YourOrg
state: present
delegate_to: localhost
.. seealso::
:ref:`timeout_options`

6
docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst
View file

@ -100,7 +100,7 @@ To use a jump host to connect to a NETCONF enabled device you must set the ``ANS
- 1 or TRUE (to trigger the use of the default SSH config file ~/.ssh/config)
- The absolute path to a custom SSH config file.
The SSH config file should look something like:
The SSH config file should look something like:
.. code-block:: ini
@ -126,3 +126,7 @@ If ``ansible_network_os`` is not specified for a host, then Ansible will attempt
``ansible_network_os`` auto-detection can also be triggered by using ``auto`` as the ``ansible_network_os``. (Note: Previously ``default`` was used instead of ``auto``).
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_netvisor.rst
View file

@ -71,3 +71,7 @@ Example CLI Task
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_nos.rst
View file

@ -69,3 +69,7 @@ Example CLI Task
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_nxos.rst
View file

@ -162,3 +162,7 @@ The following platforms and software versions have been certified by Cisco to wo
N7k Support includes all N7xxx models
N9k Support includes all N9xxx models
======== ==============================================
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_routeros.rst
View file

@ -70,3 +70,7 @@ Example CLI Task
when: ansible_network_os == 'routeros'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_slxos.rst
View file

@ -70,3 +70,7 @@ Example CLI Task
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

4
docs/docsite/rst/network/user_guide/platform_voss.rst
View file

@ -71,3 +71,7 @@ Example CLI Task
when: ansible_network_os == 'voss'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`

8
docs/docsite/rst/network/user_guide/platform_vyos.rst
View file

@ -27,9 +27,9 @@ Connections Available
Connection Settings ``ansible_connection: network_cli``
|enable_mode| not supported
|enable_mode| not supported
Returned Data Format Refer to individual module documentation
Returned Data Format Refer to individual module documentation
==================== ==========================================
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
@ -67,3 +67,7 @@ Example CLI Task
when: ansible_network_os == 'vyos'
.. include:: shared_snippets/SSH_warning.txt
.. seealso::
:ref:`timeout_options`