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

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

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

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

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

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

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

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

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

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

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

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