From b22b07e300b68e68cf21fbf6f268eb69194580ba Mon Sep 17 00:00:00 2001 From: Nathaniel Case Date: Tue, 11 Sep 2018 14:23:38 -0400 Subject: [PATCH] Fixup network connection documentation (#45487) * Fixup network connection documentation similar to suggestions in #45224 * Another tpyo --- lib/ansible/plugins/connection/httpapi.py | 34 +++++++++++-------- lib/ansible/plugins/connection/netconf.py | 26 +++++++------- lib/ansible/plugins/connection/network_cli.py | 20 +++++------ 3 files changed, 42 insertions(+), 38 deletions(-) diff --git a/lib/ansible/plugins/connection/httpapi.py b/lib/ansible/plugins/connection/httpapi.py index 05a6628032..af81631f78 100644 --- a/lib/ansible/plugins/connection/httpapi.py +++ b/lib/ansible/plugins/connection/httpapi.py @@ -24,9 +24,9 @@ options: port: type: int description: - - Specifies the port on the remote device to listening for connections + - Specifies the port on the remote device that listens for connections when establishing the HTTP(S) connection. - When unspecified, will pick 80 or 443 based on the value of use_ssl + - When unspecified, will pick 80 or 443 based on the value of use_ssl. ini: - section: defaults key: remote_port @@ -46,7 +46,7 @@ options: - The username used to authenticate to the remote device when the API 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 + - Can be configured from the CLI via the C(--user) or C(-u) options. ini: - section: defaults key: remote_user @@ -56,13 +56,15 @@ options: - name: ansible_user password: description: - - Secret used to authenticate + - Configures the user password used to authenticate to the remote device + when needed for the device API. vars: - name: ansible_password - name: ansible_httpapi_pass use_ssl: + type: boolean description: - - Whether to connect using SSL (HTTPS) or not (HTTP) + - Whether to connect using SSL (HTTPS) or not (HTTP). default: False vars: - name: ansible_httpapi_use_ssl @@ -76,10 +78,10 @@ options: timeout: type: int description: - - Sets the connection time, in seconds, for the communicating with the + - Sets the connection time, in seconds, for 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. + does not return in timeout seconds, an error is generated. default: 120 become: type: boolean @@ -89,12 +91,12 @@ options: 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 + this option is silently ignored. + - Can be configured from the CLI via the C(--become) or C(-b) options. default: False ini: - section: privilege_escalation - key: become + - section: privilege_escalation + key: become env: - name: ANSIBLE_BECOME vars: @@ -106,8 +108,8 @@ options: C(enable) but could be defined as other values. default: sudo ini: - section: privilege_escalation - key: become_method + - section: privilege_escalation + key: become_method env: - name: ANSIBLE_BECOME_METHOD vars: @@ -118,7 +120,7 @@ options: - 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 + will fail. default: 30 ini: - section: persistent_connection @@ -131,13 +133,15 @@ options: - 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 + close. default: 10 ini: - section: persistent_connection key: command_timeout env: - name: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT + vars: + - name: ansible_command_timeout """ from io import BytesIO diff --git a/lib/ansible/plugins/connection/netconf.py b/lib/ansible/plugins/connection/netconf.py index 147facd254..b4cfd41620 100644 --- a/lib/ansible/plugins/connection/netconf.py +++ b/lib/ansible/plugins/connection/netconf.py @@ -30,7 +30,7 @@ options: port: type: int description: - - Specifies the port on the remote device to listening for connections + - Specifies the port on the remote device that listens for connections when establishing the SSH connection. default: 830 ini: @@ -52,7 +52,7 @@ options: - 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 + - Can be configured from the CLI via the C(--user) or C(-u) options. ini: - section: defaults key: remote_user @@ -69,7 +69,7 @@ options: - name: ansible_ssh_pass private_key_file: description: - - The private SSH key or certificate file used to to authenticate to the + - The private SSH key or certificate file used to authenticate to the remote device when first establishing the SSH connection. ini: - section: defaults @@ -81,20 +81,20 @@ options: 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. + - Sets the connection time, in seconds, for 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: bool + 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 + known hosts file. 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: 'no' + default: False ini: - section: paramiko_connection key: host_key_auto_add @@ -103,7 +103,7 @@ options: look_for_keys: default: True description: - - enables looking for ssh keys in the usual locations for ssh keys (e.g. :file:`~/.ssh/id_*`) + - Enables looking for ssh keys in the usual locations for ssh keys (e.g. :file:`~/.ssh/id_*`). env: - name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS ini: @@ -133,7 +133,7 @@ options: - 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 + will fail. default: 30 ini: - section: persistent_connection @@ -146,7 +146,7 @@ options: - 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 + close. default: 10 ini: - section: persistent_connection diff --git a/lib/ansible/plugins/connection/network_cli.py b/lib/ansible/plugins/connection/network_cli.py index f25f7706e5..1f7d58ace5 100644 --- a/lib/ansible/plugins/connection/network_cli.py +++ b/lib/ansible/plugins/connection/network_cli.py @@ -26,7 +26,7 @@ options: port: type: int description: - - Specifies the port on the remote device to listening for connections + - Specifies the port on the remote device that listens for connections when establishing the SSH connection. default: 22 ini: @@ -40,7 +40,7 @@ options: 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 + with the remote device. vars: - name: ansible_network_os remote_user: @@ -48,7 +48,7 @@ options: - 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 + - Can be configured from the CLI via the C(--user) or C(-u) options. ini: - section: defaults key: remote_user @@ -65,7 +65,7 @@ options: - name: ansible_ssh_pass private_key_file: description: - - The private SSH key or certificate file used to to authenticate to the + - The private SSH key or certificate file used to authenticate to the remote device when first establishing the SSH connection. ini: - section: defaults @@ -77,10 +77,10 @@ options: timeout: type: int description: - - Sets the connection time, in seconds, for the communicating with the + - Sets the connection time, in seconds, for 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. + does not return in timeout seconds, an error is generated. default: 120 become: type: boolean @@ -90,8 +90,8 @@ options: 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 + this option is silently ignored. + - Can be configured from the CLI via the C(--become) or C(-b) options. default: False ini: - section: privilege_escalation @@ -135,7 +135,7 @@ options: - 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 + will fail. default: 30 ini: - section: persistent_connection @@ -148,7 +148,7 @@ options: - 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 + close. default: 10 ini: - section: persistent_connection