From 11830295918a82bff8063f51173430fd84c78ba5 Mon Sep 17 00:00:00 2001 From: Peter Sprygada Date: Wed, 3 Jan 2018 15:10:35 -0500 Subject: [PATCH] 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 | 180 +++++++++++------ lib/ansible/plugins/connection/network_cli.py | 183 ++++++++++++++---- 2 files changed, 268 insertions(+), 95 deletions(-) diff --git a/lib/ansible/plugins/connection/netconf.py b/lib/ansible/plugins/connection/netconf.py index 56fad9c53bc..a94125b851a 100644 --- a/lib/ansible/plugins/connection/netconf.py +++ b/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 +--- +author: Ansible Networking Team +connection: netconf +short_description: Provides a persistent connection using the netconf protocol +description: + - 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: + host: + description: + - Specifies the remote device FQDN or IP address to establish the SSH + connection to. + default: inventory_hostname + vars: + - name: ansible_host + port: + type: int + description: + - 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 + 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: + - 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_auto_add: + type: boolean + description: + - By default, Ansible will prompt the user before adding SSH keys to the + known hosts file. 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: - - Use netconf to run command on network appliances - version_added: "2.3" - options: - network_os: - description: - - Appliance specific OS - default: 'default' - vars: - - name: ansible_netconf_network_os - 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 - default: 830 - vars: - - name: ansible_port - - name: ansible_netconf_port - timeout: - type: int - description: - - Connection timeout in seconds - default: 120 - host_key_checking: - type: boolean - description: - - Flag to control wether we check for validity of the host key of the remote - default: True -# TODO: -#look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS, -#allow_agent=self.allow_agent, + - 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 diff --git a/lib/ansible/plugins/connection/network_cli.py b/lib/ansible/plugins/connection/network_cli.py index 7c47ddf14e3..30ca54af57b 100644 --- a/lib/ansible/plugins/connection/network_cli.py +++ b/lib/ansible/plugins/connection/network_cli.py @@ -6,42 +6,155 @@ 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 +--- +author: Ansible Networking Team +connection: network_cli +short_description: Use network_cli to run command on network appliances +description: + - This connection plugin provides a connection to remote devices over the + SSH and implements a CLI shell. This connection plugin is typically used by + network devices for sending and receiving CLi commands to network devices. +version_added: "2.3" +options: + host: description: - - This plugin actually forces use of 'local' execution but using paramiko to establish a remote ssh shell on the appliance. - - Also this plugin ignores the become_method but still uses the becoe_user and become_pass to - do privilege escalation, method depending on network_os used. - version_added: "2.3" - options: - network_os: - description: - - Appliance specific OS - default: 'default' - vars: - - name: ansible_netconf_network_os - 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 - 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 - default: 120 + - Specifies the remote device FQDN or IP address to establish the SSH + connection to. + default: inventory_hostname + vars: + - name: ansible_host + port: + type: int + description: + - Specifies the port on the remote device to listening for connections + when establishing the SSH connection. + default: 22 + 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 + vars: + - name: ansible_private_key_file + timeout: + type: int + description: + - 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