update DOCUMENTATION for network_cli and netconf (#33396)

* update DOCUMENTATION for network_cli and netconf

This updates the DOCUMENTATION string for both the netconf and
network_cli connection plugin.

* add additional options to the connection documentation

* update documentation based on review and feedback

* adds persistent connection options to documentation string

lib/ansible/plugins/connection/netconf.py

@@ -5,68 +5,128 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+
 DOCUMENTATION = """
+---
 author: Ansible Networking Team
 connection: netconf
-    short_description: Use netconf to run command on network appliances
+short_description: Provides a persistent connection using the netconf protocol
 description:
-        - Use netconf to run command on network appliances
+  - This connection plugin provides a connection to remote devices over the
+    SSH NETCONF subsystem.  This connection plugin is typically used by
+    network devices for sending and receiving RPC calls over NETCONF.
+  - Note this connection plugin requires ncclient to be installed on the
+    local Ansible controller.
 version_added: "2.3"
+requirements:
+  - ncclient
 options:
-      network_os:
+  host:
     description:
-            - Appliance specific OS
+      - Specifies the remote device FQDN or IP address to establish the SSH
-        default: 'default'
+        connection to.
+    default: inventory_hostname
     vars:
-            - name: ansible_netconf_network_os
+      - name: ansible_host
-      password:
-        description:
-            - Secret used to authenticate
-        vars:
-            - name: ansible_pass
-            - name: ansible_netconf_pass
-      private_key_file:
-        description:
-            - Key or certificate file used for authentication
-        vars:
-            - name: ansible_private_key_file
-            - name: ansible_netconf_private_key_file
-      ssh_config:
-        type: boolean
-        default: False
-        description:
-            - Flag to decide if we use SSH configuration options with netconf
-        vars:
-            - name: ansible_netconf_ssh_config
-        env:
-            - name: ANSIBLE_NETCONF_SSH_CONFIG
-      user:
-        description:
-          - User to authenticate as
-        vars:
-          - name: ansible_user
-          - name: ansible_netconf_user
   port:
     type: int
     description:
-          - port to connect to on the remote
+      - Specifies the port on the remote device to listening for connections
+        when establishing the SSH connection.
     default: 830
+    ini:
+      - section: defaults
+        key: remote_port
+    env:
+      - name: ANSIBLE_REMOTE_PORT
     vars:
       - name: ansible_port
-          - name: ansible_netconf_port
+  network_os:
+    description:
+      - Configures the device platform network operating system.  This value is
+        used to load a device specific netconf plugin.  If this option is not
+        configured, then the default netconf plugin will be used.
+    default: null
+    vars:
+      - name: ansible_network_os
+  remote_user:
+    description:
+      - The username used to authenticate to the remote device when the SSH
+        connection is first established.  If the remote_user is not specified,
+        the connection will use the username of the logged in user.
+      - Can be configured form the CLI via the C(--user) or C(-u) options
+    ini:
+      - section: defaults
+        key: remote_user
+    env:
+      - name: ANSIBLE_REMOTE_USER
+    vars:
+      - name: ansible_user
+  password:
+    description:
+      - Configures the user password used to authenticate to the remote device
+        when first establishing the SSH connection.
+    vars:
+      - name: ansible_pass
+  private_key_file:
+    description:
+      - The private SSH key or certificate file used to to authenticate to the
+        remote device when first establishing the SSH connection.
+    ini:
+     section: defaults
+     key: private_key_file
+    env:
+      - name: ANSIBLE_PRIVATE_KEY_FILE
+    vars:
+      - name: ansible_private_key_file
   timeout:
     type: int
     description:
-          - Connection timeout in seconds
+      - Sets the connection time for the communicating with the remote device.
+        This timeout is used as the default timeout value when awaiting a
+        response after issuing a call to a RPC.  If the RPC does not return in
+        timeout seconds, an error is generated.
     default: 120
-      host_key_checking:
+  host_key_auto_add:
     type: boolean
     description:
-          - Flag to control wether we check for validity of the host key of the remote
+      - By default, Ansible will prompt the user before adding SSH keys to the
-        default: True
+        known hosts file.  Enabling this option, unknown host keys will
-# TODO:
+        automatically be added to the known hosts file.
-#look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS,
+      - Be sure to fully understand the security implications of enabling this
-#allow_agent=self.allow_agent,
+        option on production systems as it could create a security vulnerability.
+    default: False
+    ini:
+      section: paramiko_connection
+      key: host_key_auto_add
+    env:
+      - name: ANSIBLE_HOST_KEY_AUTO_ADD
+  persistent_connect_timeout:
+    type: int
+    description:
+      - Configures, in seconds, the amount of time to wait when trying to
+        initially establish a persistent connection.  If this value expires
+        before the connection to the remote device is completed, the connection
+        will fail
+    default: 30
+    ini:
+      section: persistent_connection
+      key: persistent_connect_timeout
+    env:
+      - name: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
+  persistent_command_timeout:
+    type: int
+    description:
+      - Configures, in seconds, the amount of time to wait for a command to
+        return from the remote device.  If this timer is exceeded before the
+        command returns, the connection plugin will raise an exception and
+        close
+    default: 10
+    ini:
+      section: persistent_connection
+      key: persistent_command_timeout
+    env:
+      - name: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
 """
 
 import os

lib/ansible/plugins/connection/network_cli.py

@@ -6,32 +6,69 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
+---
 author: Ansible Networking Team
 connection: network_cli
 short_description: Use network_cli to run command on network appliances
 description:
-        - This plugin actually forces use of 'local' execution but using paramiko to establish a remote ssh shell on the appliance.
+  - This connection plugin provides a connection to remote devices over the
-        - Also this plugin ignores the become_method but still uses the becoe_user and become_pass to
+    SSH and implements a CLI shell.  This connection plugin is typically used by
-          do privilege escalation, method depending on network_os used.
+    network devices for sending and receiving CLi commands to network devices.
 version_added: "2.3"
 options:
-      network_os:
+  host:
     description:
-            - Appliance specific OS
+      - Specifies the remote device FQDN or IP address to establish the SSH
-        default: 'default'
+        connection to.
+    default: inventory_hostname
     vars:
-            - name: ansible_netconf_network_os
+      - name: ansible_host
-      password:
+  port:
+    type: int
     description:
-            - Secret used to authenticate
+      - Specifies the port on the remote device to listening for connections
-        vars:
+        when establishing the SSH connection.
-            - name: ansible_pass
+    default: 22
-            - name: ansible_netconf_pass
-      private_key_file:
-        description:
-            - Key or certificate file used for authentication
     ini:
       - section: defaults
+        key: remote_port
+    env:
+      - name: ANSIBLE_REMOTE_PORT
+    vars:
+      - name: ansible_port
+  network_os:
+    description:
+      - Configures the device platform network operating system.  This value is
+        used to load the correct terminal and cliconf plugins to communicate
+        with the remote device
+    default: null
+    vars:
+      - name: ansible_network_os
+  remote_user:
+    description:
+      - The username used to authenticate to the remote device when the SSH
+        connection is first established.  If the remote_user is not specified,
+        the connection will use the username of the logged in user.
+      - Can be configured form the CLI via the C(--user) or C(-u) options
+    ini:
+      - section: defaults
+        key: remote_user
+    env:
+      - name: ANSIBLE_REMOTE_USER
+    vars:
+      - name: ansible_user
+  password:
+    description:
+      - Configures the user password used to authenticate to the remote device
+        when first establishing the SSH connection.
+    vars:
+      - name: ansible_pass
+  private_key_file:
+    description:
+      - The private SSH key or certificate file used to to authenticate to the
+        remote device when first establishing the SSH connection.
+    ini:
+     section: defaults
      key: private_key_file
     env:
       - name: ANSIBLE_PRIVATE_KEY_FILE
@@ -40,8 +77,84 @@ DOCUMENTATION = """
   timeout:
     type: int
     description:
-          - Connection timeout in seconds
+      - Sets the connection time, in seconds, for the communicating with the
+        remote device.  This timeout is used as the default timeout value for
+        commands when issuing a command to the network CLI.  If the command
+        does not return in timeout seconds, the an error is generated.
     default: 120
+  become:
+    type: boolean
+    description:
+      - The become option will instruct the CLI session to attempt privilege
+        escalation on platforms that support it.  Normally this means
+        transitioning from user mode to C(enable) mode in the CLI session.
+        If become is set to True and the remote device does not support
+        privilege escalation or the privilege has already been elevated, then
+        this option is silently ignored
+      - Can be configured form the CLI via the C(--become) or C(-b) options
+    default: False
+    ini:
+      section: privilege_escalation
+      key: become
+    env:
+      - name: ANSIBLE_BECOME
+    vars:
+      - name: ansible_become
+  become_method:
+    description:
+      - This option allows the become method to be specified in for handling
+        privilege escalation.  Typically the become_method value is set to
+        C(enable) but could be defined as other values.
+    default: sudo
+    ini:
+      section: privilege_escalation
+      key: become_method
+    env:
+      - name: ANSIBLE_BECOME_METHOD
+    vars:
+      - name: ansible_become_method
+  host_key_auto_add:
+    type: boolean
+    description:
+      - By default, Ansible will prompt the user before adding SSH keys to the
+        known hosts file.  Since persistent connections such as network_cli run
+        in background processes, the user will never be prompted.  By enabling
+        this option, unknown host keys will automatically be added to the
+        known hosts file.
+      - Be sure to fully understand the security implications of enabling this
+        option on production systems as it could create a security vulnerability.
+    default: False
+    ini:
+      section: paramiko_connection
+      key: host_key_auto_add
+    env:
+      - name: ANSIBLE_HOST_KEY_AUTO_ADD
+  persistent_connect_timeout:
+    type: int
+    description:
+      - Configures, in seconds, the amount of time to wait when trying to
+        initially establish a persistent connection.  If this value expires
+        before the connection to the remote device is completed, the connection
+        will fail
+    default: 30
+    ini:
+      section: persistent_connection
+      key: persistent_connect_timeout
+    env:
+      - name: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
+  persistent_command_timeout:
+    type: int
+    description:
+      - Configures, in seconds, the amount of time to wait for a command to
+        return from the remote device.  If this timer is exceeded before the
+        command returns, the connection plugin will raise an exception and
+        close
+    default: 10
+    ini:
+      section: persistent_connection
+      key: persistent_command_timeout
+    env:
+      - name: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
 """
 
 import json