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

* add timeout option examples, link to new section, implement feedback

docs/docsite/rst/network/getting_started/index.rst

@@ -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

docs/docsite/rst/network/getting_started/network_connection_options.rst

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

docs/docsite/rst/network/getting_started/network_differences.rst

@@ -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``
 ================================================================================

docs/docsite/rst/network/user_guide/platform_ce.rst

@@ -205,3 +205,7 @@ Modules work with connection C(netconf)
    ce_vxlan_vap
 
 .. include:: shared_snippets/SSH_warning.txt
+
+.. seealso::
+
+       :ref:`timeout_options`

docs/docsite/rst/network/user_guide/platform_cnos.rst

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

docs/docsite/rst/network/user_guide/platform_dellos10.rst

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

docs/docsite/rst/network/user_guide/platform_dellos6.rst

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

docs/docsite/rst/network/user_guide/platform_dellos9.rst

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

docs/docsite/rst/network/user_guide/platform_enos.rst

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

docs/docsite/rst/network/user_guide/platform_eos.rst

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

docs/docsite/rst/network/user_guide/platform_eric_eccli.rst

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

docs/docsite/rst/network/user_guide/platform_exos.rst

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

docs/docsite/rst/network/user_guide/platform_icx.rst

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

docs/docsite/rst/network/user_guide/platform_ios.rst

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

docs/docsite/rst/network/user_guide/platform_iosxr.rst

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

docs/docsite/rst/network/user_guide/platform_ironware.rst

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

docs/docsite/rst/network/user_guide/platform_junos.rst

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

docs/docsite/rst/network/user_guide/platform_meraki.rst

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

docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst

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

docs/docsite/rst/network/user_guide/platform_netvisor.rst

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

docs/docsite/rst/network/user_guide/platform_nos.rst

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

docs/docsite/rst/network/user_guide/platform_nxos.rst

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

docs/docsite/rst/network/user_guide/platform_routeros.rst

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

docs/docsite/rst/network/user_guide/platform_slxos.rst

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

docs/docsite/rst/network/user_guide/platform_voss.rst

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

docs/docsite/rst/network/user_guide/platform_vyos.rst

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