mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
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
This commit is contained in:
Peter Sprygada
Nathaniel Case
parent
e59922d527
commit
1183029591
2 changed files with 268 additions and 95 deletions
|
|
@ -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:
|
||||
- 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,
|
||||
- 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:
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue