mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-04-24 03:11:24 -07: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)
|
from __future__ import (absolute_import, division, print_function)
|
||||||
__metaclass__ = type
|
__metaclass__ = type
|
||||||
|
|
||||||
|
|
||||||
DOCUMENTATION = """
|
DOCUMENTATION = """
|
||||||
author: Ansible Networking Team
|
---
|
||||||
connection: netconf
|
author: Ansible Networking Team
|
||||||
short_description: Use netconf to run command on network appliances
|
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:
|
description:
|
||||||
- Use netconf to run command on network appliances
|
- Specifies the remote device FQDN or IP address to establish the SSH
|
||||||
version_added: "2.3"
|
connection to.
|
||||||
options:
|
default: inventory_hostname
|
||||||
network_os:
|
vars:
|
||||||
description:
|
- name: ansible_host
|
||||||
- Appliance specific OS
|
port:
|
||||||
default: 'default'
|
type: int
|
||||||
vars:
|
description:
|
||||||
- name: ansible_netconf_network_os
|
- Specifies the port on the remote device to listening for connections
|
||||||
password:
|
when establishing the SSH connection.
|
||||||
description:
|
default: 830
|
||||||
- Secret used to authenticate
|
ini:
|
||||||
vars:
|
- section: defaults
|
||||||
- name: ansible_pass
|
key: remote_port
|
||||||
- name: ansible_netconf_pass
|
env:
|
||||||
private_key_file:
|
- name: ANSIBLE_REMOTE_PORT
|
||||||
description:
|
vars:
|
||||||
- Key or certificate file used for authentication
|
- name: ansible_port
|
||||||
vars:
|
network_os:
|
||||||
- name: ansible_private_key_file
|
description:
|
||||||
- name: ansible_netconf_private_key_file
|
- Configures the device platform network operating system. This value is
|
||||||
ssh_config:
|
used to load a device specific netconf plugin. If this option is not
|
||||||
type: boolean
|
configured, then the default netconf plugin will be used.
|
||||||
default: False
|
default: null
|
||||||
description:
|
vars:
|
||||||
- Flag to decide if we use SSH configuration options with netconf
|
- name: ansible_network_os
|
||||||
vars:
|
remote_user:
|
||||||
- name: ansible_netconf_ssh_config
|
description:
|
||||||
env:
|
- The username used to authenticate to the remote device when the SSH
|
||||||
- name: ANSIBLE_NETCONF_SSH_CONFIG
|
connection is first established. If the remote_user is not specified,
|
||||||
user:
|
the connection will use the username of the logged in user.
|
||||||
description:
|
- Can be configured form the CLI via the C(--user) or C(-u) options
|
||||||
- User to authenticate as
|
ini:
|
||||||
vars:
|
- section: defaults
|
||||||
- name: ansible_user
|
key: remote_user
|
||||||
- name: ansible_netconf_user
|
env:
|
||||||
port:
|
- name: ANSIBLE_REMOTE_USER
|
||||||
type: int
|
vars:
|
||||||
description:
|
- name: ansible_user
|
||||||
- port to connect to on the remote
|
password:
|
||||||
default: 830
|
description:
|
||||||
vars:
|
- Configures the user password used to authenticate to the remote device
|
||||||
- name: ansible_port
|
when first establishing the SSH connection.
|
||||||
- name: ansible_netconf_port
|
vars:
|
||||||
timeout:
|
- name: ansible_pass
|
||||||
type: int
|
private_key_file:
|
||||||
description:
|
description:
|
||||||
- Connection timeout in seconds
|
- The private SSH key or certificate file used to to authenticate to the
|
||||||
default: 120
|
remote device when first establishing the SSH connection.
|
||||||
host_key_checking:
|
ini:
|
||||||
type: boolean
|
section: defaults
|
||||||
description:
|
key: private_key_file
|
||||||
- Flag to control wether we check for validity of the host key of the remote
|
env:
|
||||||
default: True
|
- name: ANSIBLE_PRIVATE_KEY_FILE
|
||||||
# TODO:
|
vars:
|
||||||
#look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS,
|
- name: ansible_private_key_file
|
||||||
#allow_agent=self.allow_agent,
|
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
|
import os
|
||||||
|
|
|
||||||
|
|
@ -6,42 +6,155 @@ from __future__ import (absolute_import, division, print_function)
|
||||||
__metaclass__ = type
|
__metaclass__ = type
|
||||||
|
|
||||||
DOCUMENTATION = """
|
DOCUMENTATION = """
|
||||||
author: Ansible Networking Team
|
---
|
||||||
connection: network_cli
|
author: Ansible Networking Team
|
||||||
short_description: Use network_cli to run command on network appliances
|
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:
|
description:
|
||||||
- This plugin actually forces use of 'local' execution but using paramiko to establish a remote ssh shell on the appliance.
|
- Specifies the remote device FQDN or IP address to establish the SSH
|
||||||
- Also this plugin ignores the become_method but still uses the becoe_user and become_pass to
|
connection to.
|
||||||
do privilege escalation, method depending on network_os used.
|
default: inventory_hostname
|
||||||
version_added: "2.3"
|
vars:
|
||||||
options:
|
- name: ansible_host
|
||||||
network_os:
|
port:
|
||||||
description:
|
type: int
|
||||||
- Appliance specific OS
|
description:
|
||||||
default: 'default'
|
- Specifies the port on the remote device to listening for connections
|
||||||
vars:
|
when establishing the SSH connection.
|
||||||
- name: ansible_netconf_network_os
|
default: 22
|
||||||
password:
|
ini:
|
||||||
description:
|
- section: defaults
|
||||||
- Secret used to authenticate
|
key: remote_port
|
||||||
vars:
|
env:
|
||||||
- name: ansible_pass
|
- name: ANSIBLE_REMOTE_PORT
|
||||||
- name: ansible_netconf_pass
|
vars:
|
||||||
private_key_file:
|
- name: ansible_port
|
||||||
description:
|
network_os:
|
||||||
- Key or certificate file used for authentication
|
description:
|
||||||
ini:
|
- Configures the device platform network operating system. This value is
|
||||||
- section: defaults
|
used to load the correct terminal and cliconf plugins to communicate
|
||||||
key: private_key_file
|
with the remote device
|
||||||
env:
|
default: null
|
||||||
- name: ANSIBLE_PRIVATE_KEY_FILE
|
vars:
|
||||||
vars:
|
- name: ansible_network_os
|
||||||
- name: ansible_private_key_file
|
remote_user:
|
||||||
timeout:
|
description:
|
||||||
type: int
|
- The username used to authenticate to the remote device when the SSH
|
||||||
description:
|
connection is first established. If the remote_user is not specified,
|
||||||
- Connection timeout in seconds
|
the connection will use the username of the logged in user.
|
||||||
default: 120
|
- 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
|
import json
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue