diff options
Diffstat (limited to 'docs/docsite/rst/network/user_guide')
35 files changed, 5173 insertions, 0 deletions
diff --git a/docs/docsite/rst/network/user_guide/cli_parsing.rst b/docs/docsite/rst/network/user_guide/cli_parsing.rst new file mode 100644 index 0000000..5b6b40e --- /dev/null +++ b/docs/docsite/rst/network/user_guide/cli_parsing.rst @@ -0,0 +1,744 @@ +.. _cli_parsing: + +***************************************** +Parsing semi-structured text with Ansible +***************************************** + +The :ref:`cli_parse <ansible_collections.ansible.utils.cli_parse_module>` module parses semi-structured data such as network configurations into structured data to allow programmatic use of the data from that device. You can pull information from a network device and update a CMDB in one playbook. Use cases include automated troubleshooting, creating dynamic documentation, updating IPAM (IP address management) tools and so on. + + +.. contents:: + :local: + + +Understanding the CLI parser +============================= + +The `ansible.utils <https://galaxy.ansible.com/ansible/utils>`_ collection version 1.0.0 or later includes the :ref:`cli_parse <ansible_collections.ansible.utils.cli_parse_module>` module that can run CLI commands and parse the semi-structured text output. You can use the ``cli_parse`` module on a device, host, or platform that only supports a command-line interface and the commands issued return semi-structured text. The ``cli_parse`` module can either run a CLI command on a device and return a parsed result or can simply parse any text document. The ``cli_parse`` module includes cli_parser plugins to interface with a variety of parsing engines. + +Why parse the text? +-------------------- + +Parsing semi-structured data such as network configurations into structured data allows programmatic use of the data from that device. Use cases include automated troubleshooting, creating dynamic documentation, updating IPAM (IP address management) tools and so on. You may prefer to do this with Ansible natively to take advantage of native Ansible constructs such as: + +- The ``when`` clause to conditionally run other tasks or roles +- The ``assert`` module to check configuration and operational state compliance +- The ``template`` module to generate reports about configuration and operational state information +- Templates and ``command`` or ``config`` modules to generate host, device, or platform commands or configuration +- The current platform ``facts`` modules to supplement native facts information + +By parsing semi-structured text into Ansible native data structures, you can take full advantage of Ansible's network modules and plugins. + + +When not to parse the text +--------------------------- + +You should not parse semi-structured text when: + +- The device, host, or platform has a RESTAPI and returns JSON. +- Existing Ansible facts modules already return the desired data. +- Ansible network resource modules exist for configuration management of the device and resource. + +Parsing the CLI +========================= + +The ``cli_parse`` module includes the following cli_parsing plugins: + +``native`` + The native parsing engine built into Ansible and requires no addition python libraries +``xml`` + Convert XML to an Ansible native data structure +``textfsm`` + A python module which implements a template based state machine for parsing semi-formatted text +``ntc_templates`` + Predefined ``textfsm`` templates packages supporting a variety of platforms and commands +``ttp`` + A library for semi-structured text parsing using templates, with added capabilities to simplify the process +``pyats`` + Uses the parsers included with the Cisco Test Automation & Validation Solution +``jc`` + A python module that converts the output of dozens of popular Linux/UNIX/macOS/Windows commands and file types to python dictionaries or lists of dictionaries. Note: this filter plugin can be found in the ``community.general`` collection. +``json`` + Converts JSON output at the CLI to an Ansible native data structure + +Although Ansible contains a number of plugins that can convert XML to Ansible native data structures, the ``cli_parse`` module runs the command on devices that return XML and returns the converted data in a single task. + +Because ``cli_parse`` uses a plugin based architecture, it can use additional parsing engines from any Ansible collection. + +.. note:: + + The ``ansible.netcommon.native`` and ``ansible.utils.json`` parsing engines are fully supported with a Red Hat Ansible Automation Platform subscription. Red Hat Ansible Automation Platform subscription support is limited to the use of the ``ntc_templates``, pyATS, ``textfsm``, ``xmltodict``, public APIs as documented. + +Parsing with the native parsing engine +-------------------------------------- + +The native parsing engine is included with the ``cli_parse`` module. It uses data captured using regular expressions to populate the parsed data structure. The native parsing engine requires a YAML template file to parse the command output. + +Networking example +^^^^^^^^^^^^^^^^^^ + +This example uses the output of a network device command and applies a native template to produce an output in Ansible structured data format. + +The ``show interface`` command output from the network device looks as follows: + +.. code-block:: console + + Ethernet1/1 is up + admin state is up, Dedicated Interface + Hardware: 100/1000/10000 Ethernet, address: 5254.005a.f8bd (bia 5254.005a.f8bd) + MTU 1500 bytes, BW 1000000 Kbit, DLY 10 usec + reliability 255/255, txload 1/255, rxload 1/255 + Encapsulation ARPA, medium is broadcast + Port mode is access + full-duplex, auto-speed + Beacon is turned off + Auto-Negotiation is turned on FEC mode is Auto + Input flow-control is off, output flow-control is off + Auto-mdix is turned off + Switchport monitor is off + EtherType is 0x8100 + EEE (efficient-ethernet) : n/a + Last link flapped 4week(s) 6day(s) + Last clearing of "show interface" counters never + <...> + + +Create the native template to match this output and store it as ``templates/nxos_show_interface.yaml``: + +.. code-block:: yaml + + --- + - example: Ethernet1/1 is up + getval: '(?P<name>\S+) is (?P<oper_state>\S+)' + result: + "{{ name }}": + name: "{{ name }}" + state: + operating: "{{ oper_state }}" + shared: true + + - example: admin state is up, Dedicated Interface + getval: 'admin state is (?P<admin_state>\S+),' + result: + "{{ name }}": + name: "{{ name }}" + state: + admin: "{{ admin_state }}" + + - example: " Hardware: Ethernet, address: 5254.005a.f8b5 (bia 5254.005a.f8b5)" + getval: '\s+Hardware: (?P<hardware>.*), address: (?P<mac>\S+)' + result: + "{{ name }}": + hardware: "{{ hardware }}" + mac_address: "{{ mac }}" + + +This native parser template is structured as a list of parsers, each containing the following key-value pairs: + +- ``example`` - An example line of the text line to be parsed +- ``getval`` - A regular expression using named capture groups to store the extracted data +- ``result`` - A data tree, populated as a template, from the parsed data +- ``shared`` - (optional) The shared key makes the parsed values available to the rest of the parser entries until matched again. + +The following example task uses ``cli_parse`` with the native parser and the example template above to parse the ``show interface`` command from a Cisco NXOS device: + +.. code-block:: yaml + + - name: "Run command and parse with native" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.netcommon.native + set_fact: interfaces + +Taking a deeper dive into this task: + +- The ``command`` option provides the command you want to run on the device or host. Alternately, you can provide text from a previous command with the ``text`` option instead. +- The ``parser`` option provides information specific to the parser engine. +- The ``name`` suboption provides the fully qualified collection name (FQCN) of the parsing engine (``ansible.netcommon.native``). +- The ``cli_parse`` module, by default, looks for the template in the templates directory as ``{{ short_os }}_{{ command }}.yaml``. + + - The ``short_os`` in the template filename is derived from either the host ``ansible_network_os`` or ``ansible_distribution``. + - Spaces in the network or host command are replace with ``_`` in the ``command`` portion of the template filename. In this example, the ``show interfaces`` network CLI command becomes ``show_interfaces`` in the filename. + +.. note:: + + ``ansible.netcommon.native`` parsing engine is fully supported with a Red Hat Ansible Automation Platform subscription. + +Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` fact for the device based on the now-structured data returned from ``cli_parse``: + +.. code-block:: yaml + + Ethernet1/1: + hardware: 100/1000/10000 Ethernet + mac_address: 5254.005a.f8bd + name: Ethernet1/1 + state: + admin: up + operating: up + Ethernet1/10: + hardware: 100/1000/10000 Ethernet + mac_address: 5254.005a.f8c6 + <...> + + +Linux example +^^^^^^^^^^^^^ + +You can also use the native parser to run commands and parse output from Linux hosts. + +The output of a sample Linux command (``ip addr show``) looks as follows: + +.. code-block:: bash + + 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + 2: enp0s31f6: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN group default qlen 1000 + link/ether x2:6a:64:9d:84:19 brd ff:ff:ff:ff:ff:ff + 3: wlp2s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000 + link/ether x6:c2:44:f7:41:e0 brd ff:ff:ff:ff:ff:ff permaddr d8:f2:ca:99:5c:82 + +Create the native template to match this output and store it as ``templates/fedora_ip_addr_show.yaml``: + +.. code-block:: yaml + + --- + - example: '1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000' + getval: | + (?x) # free-spacing + \d+:\s # the interface index + (?P<name>\S+):\s # the name + <(?P<properties>\S+)> # the properties + \smtu\s(?P<mtu>\d+) # the mtu + .* # gunk + state\s(?P<state>\S+) # the state of the interface + result: + "{{ name }}": + name: "{{ name }}" + loopback: "{{ 'LOOPBACK' in stats.split(',') }}" + up: "{{ 'UP' in properties.split(',') }}" + carrier: "{{ not 'NO-CARRIER' in properties.split(',') }}" + broadcast: "{{ 'BROADCAST' in properties.split(',') }}" + multicast: "{{ 'MULTICAST' in properties.split(',') }}" + state: "{{ state|lower() }}" + mtu: "{{ mtu }}" + shared: True + + - example: 'inet 192.168.122.1/24 brd 192.168.122.255 scope global virbr0' + getval: | + (?x) # free-spacing + \s+inet\s(?P<inet>([0-9]{1,3}\.){3}[0-9]{1,3}) # the ip address + /(?P<bits>\d{1,2}) # the mask bits + result: + "{{ name }}": + ip_address: "{{ inet }}" + mask_bits: "{{ bits }}" + +.. note:: + + The ``shared`` key in the parser template allows the interface name to be used in subsequent parser entries. The use of examples and free-spacing mode with the regular expressions makes the template easier to read. + +The following example task uses ``cli_parse`` with the native parser and the example template above to parse the Linux output: + +.. code-block:: yaml + + - name: Run command and parse + ansible.utils.cli_parse: + command: ip addr show + parser: + name: ansible.netcommon.native + set_fact: interfaces + +This task assumes you previously gathered facts to determine the ``ansible_distribution`` needed to locate the template. Alternately, you could provide the path in the ``parser/template_path`` option. + + +Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` fact for the host, based on the now-structured data returned from ``cli_parse``: + +.. code-block:: yaml + + lo: + broadcast: false + carrier: true + ip_address: 127.0.0.1 + mask_bits: 8 + mtu: 65536 + multicast: false + name: lo + state: unknown + up: true + enp64s0u1: + broadcast: true + carrier: true + ip_address: 192.168.86.83 + mask_bits: 24 + mtu: 1500 + multicast: true + name: enp64s0u1 + state: up + up: true + <...> + + +Parsing JSON +------------- + +Although Ansible will natively convert serialized JSON to Ansible native data when recognized, you can also use the ``cli_parse`` module for this conversion. + +Example task: + +.. code-block:: yaml + + - name: "Run command and parse as json" + ansible.utils.cli_parse: + command: show interface | json + parser: + name: ansible.utils.json + register: interfaces + +Taking a deeper dive into this task: + +- The ``show interface | json`` command is issued on the device. +- The output is set as the ``interfaces`` fact for the device. +- JSON support is provided primarily for playbook consistency. + +.. note:: + + The use of ``ansible.netcommon.json`` is fully supported with a Red Hat Ansible Automation Platform subscription + +Parsing with ntc_templates +---------------------------- + +The ``ntc_templates`` python library includes pre-defined ``textfsm`` templates for parsing a variety of network device commands output. + +Example task: + +.. code-block:: yaml + + - name: "Run command and parse with ntc_templates" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.netcommon.ntc_templates + set_fact: interfaces + +Taking a deeper dive into this task: + +- The ``ansible_network_os`` of the device is converted to the ntc_template format ``cisco_nxos``. Alternately, you can provide the ``os`` with the ``parser/os`` option instead. +- The ``cisco_nxos_show_interface.textfsm`` template, included with the ``ntc_templates`` package, parses the output. +- See `the ntc_templates README <https://github.com/networktocode/ntc-templates/blob/master/README.md>`_ for additional information about the ``ntc_templates`` python library. + +.. note:: + + Red Hat Ansible Automation Platform subscription support is limited to the use of the ``ntc_templates`` public APIs as documented. + + +This task and and the predefined template sets the following fact as the ``interfaces`` fact for the host: + +.. code-block:: yaml + + interfaces: + - address: 5254.005a.f8b5 + admin_state: up + bandwidth: 1000000 Kbit + bia: 5254.005a.f8b5 + delay: 10 usec + description: '' + duplex: full-duplex + encapsulation: ARPA + hardware_type: Ethernet + input_errors: '' + input_packets: '' + interface: mgmt0 + ip_address: 192.168.101.14/24 + last_link_flapped: '' + link_status: up + mode: '' + mtu: '1500' + output_errors: '' + output_packets: '' + speed: 1000 Mb/s + - address: 5254.005a.f8bd + admin_state: up + bandwidth: 1000000 Kbit + bia: 5254.005a.f8bd + delay: 10 usec + + +Parsing with pyATS +---------------------- + +``pyATS`` is part of the Cisco Test Automation & Validation Solution. It includes many predefined parsers for a number of network platforms and commands. You can use the predefined parsers that are part of the ``pyATS`` package with the ``cli_parse`` module. + +Example task: + +.. code-block:: yaml + + - name: "Run command and parse with pyats" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.netcommon.pyats + set_fact: interfaces + + +Taking a deeper dive into this task: + +- The ``cli_parse`` modules converts the ``ansible_network_os`` automatically (in this example, ``ansible_network_os`` set to ``cisco.nxos.nxos``, converts to ``nxos`` for pyATS. Alternately, you can set the OS with the ``parser/os`` option instead. +- Using a combination of the command and OS, the pyATS selects the following parser: https://pubhub.devnetcloud.com/media/genie-feature-browser/docs/#/parsers/show%2520interface. +- The ``cli_parse`` module sets ``cisco.ios.ios`` to ``iosxe`` for pyATS. You can override this with the ``parser/os`` option. +- ``cli_parse`` only uses the predefined parsers in pyATS. See the `pyATS documentation <https://developer.cisco.com/docs/pyats/>`_ and the full list of `pyATS included parsers <https://pubhub.devnetcloud.com/media/genie-feature-browser/docs/#/parsers>`_. + +.. note:: + + Red Hat Ansible Automation Platform subscription support is limited to the use of the pyATS public APIs as documented. + + +This task sets the following fact as the ``interfaces`` fact for the host: + +.. code-block:: yaml + + mgmt0: + admin_state: up + auto_mdix: 'off' + auto_negotiate: true + bandwidth: 1000000 + counters: + in_broadcast_pkts: 3 + in_multicast_pkts: 1652395 + in_octets: 556155103 + in_pkts: 2236713 + in_unicast_pkts: 584259 + rate: + in_rate: 320 + in_rate_pkts: 0 + load_interval: 1 + out_rate: 48 + out_rate_pkts: 0 + rx: true + tx: true + delay: 10 + duplex_mode: full + enabled: true + encapsulations: + encapsulation: arpa + ethertype: '0x0000' + ipv4: + 192.168.101.14/24: + ip: 192.168.101.14 + prefix_length: '24' + link_state: up + <...> + + +Parsing with textfsm +--------------------- + +``textfsm`` is a Python module which implements a template-based state machine for parsing semi-formatted text. + +The following sample ``textfsm`` template is stored as ``templates/nxos_show_interface.textfsm`` + +.. code-block:: text + + + Value Required INTERFACE (\S+) + Value LINK_STATUS (.+?) + Value ADMIN_STATE (.+?) + Value HARDWARE_TYPE (.\*) + Value ADDRESS ([a-zA-Z0-9]+.[a-zA-Z0-9]+.[a-zA-Z0-9]+) + Value BIA ([a-zA-Z0-9]+.[a-zA-Z0-9]+.[a-zA-Z0-9]+) + Value DESCRIPTION (.\*) + Value IP_ADDRESS (\d+\.\d+\.\d+\.\d+\/\d+) + Value MTU (\d+) + Value MODE (\S+) + Value DUPLEX (.+duplex?) + Value SPEED (.+?) + Value INPUT_PACKETS (\d+) + Value OUTPUT_PACKETS (\d+) + Value INPUT_ERRORS (\d+) + Value OUTPUT_ERRORS (\d+) + Value BANDWIDTH (\d+\s+\w+) + Value DELAY (\d+\s+\w+) + Value ENCAPSULATION (\w+) + Value LAST_LINK_FLAPPED (.+?) + + Start + ^\S+\s+is.+ -> Continue.Record + ^${INTERFACE}\s+is\s+${LINK_STATUS},\sline\sprotocol\sis\s${ADMIN_STATE}$$ + ^${INTERFACE}\s+is\s+${LINK_STATUS}$$ + ^admin\s+state\s+is\s+${ADMIN_STATE}, + ^\s+Hardware(:|\s+is)\s+${HARDWARE_TYPE},\s+address(:|\s+is)\s+${ADDRESS}(.*bia\s+${BIA})* + ^\s+Description:\s+${DESCRIPTION} + ^\s+Internet\s+Address\s+is\s+${IP_ADDRESS} + ^\s+Port\s+mode\s+is\s+${MODE} + ^\s+${DUPLEX}, ${SPEED}(,|$$) + ^\s+MTU\s+${MTU}.\*BW\s+${BANDWIDTH}.\*DLY\s+${DELAY} + ^\s+Encapsulation\s+${ENCAPSULATION} + ^\s+${INPUT_PACKETS}\s+input\s+packets\s+\d+\s+bytes\s\*$$ + ^\s+${INPUT_ERRORS}\s+input\s+error\s+\d+\s+short\s+frame\s+\d+\s+overrun\s+\d+\s+underrun\s+\d+\s+ignored\s\*$$ + ^\s+${OUTPUT_PACKETS}\s+output\s+packets\s+\d+\s+bytes\s\*$$ + ^\s+${OUTPUT_ERRORS}\s+output\s+error\s+\d+\s+collision\s+\d+\s+deferred\s+\d+\s+late\s+collision\s\*$$ + ^\s+Last\s+link\s+flapped\s+${LAST_LINK_FLAPPED}\s\*$$ + +The following task uses the example template for ``textfsm`` with the ``cli_parse`` module. + +.. code-block:: yaml + + - name: "Run command and parse with textfsm" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.utils.textfsm + set_fact: interfaces + +Taking a deeper dive into this task: + +- The ``ansible_network_os`` for the device (``cisco.nxos.nxos``) is converted to ``nxos``. Alternately you can provide the OS in the ``parser/os`` option instead. +- The textfsm template name defaulted to ``templates/nxos_show_interface.textfsm`` using a combination of the OS and command run. Alternately you can override the generated template path with the ``parser/template_path`` option. +- See the `textfsm README <https://github.com/google/textfsm>`_ for details. +- ``textfsm`` was previously made available as a filter plugin. Ansible users should transition to the ``cli_parse`` module. + +.. note:: + + Red Hat Ansible Automation Platform subscription support is limited to the use of the ``textfsm`` public APIs as documented. + +This task sets the following fact as the ``interfaces`` fact for the host: + +.. code-block:: yaml + + - ADDRESS: X254.005a.f8b5 + ADMIN_STATE: up + BANDWIDTH: 1000000 Kbit + BIA: X254.005a.f8b5 + DELAY: 10 usec + DESCRIPTION: '' + DUPLEX: full-duplex + ENCAPSULATION: ARPA + HARDWARE_TYPE: Ethernet + INPUT_ERRORS: '' + INPUT_PACKETS: '' + INTERFACE: mgmt0 + IP_ADDRESS: 192.168.101.14/24 + LAST_LINK_FLAPPED: '' + LINK_STATUS: up + MODE: '' + MTU: '1500' + OUTPUT_ERRORS: '' + OUTPUT_PACKETS: '' + SPEED: 1000 Mb/s + - ADDRESS: X254.005a.f8bd + ADMIN_STATE: up + BANDWIDTH: 1000000 Kbit + BIA: X254.005a.f8bd + + +Parsing with TTP +----------------- + +TTP is a Python library for semi-structured text parsing using templates. TTP uses a jinja-like syntax to limit the need for regular expressions. Users familiar with jinja templating may find the TTP template syntax familiar. + +The following is an example TTP template stored as ``templates/nxos_show_interface.ttp``: + +.. code-block:: jinja + + {{ interface }} is {{ state }} + admin state is {{ admin_state }}{{ ignore(".\*") }} + +The following task uses this template to parse the ``show interface`` command output: + +.. code-block:: yaml + + - name: "Run command and parse with ttp" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.utils.ttp + set_fact: interfaces + +Taking a deeper dive in this task: + +- The default template path ``templates/nxos_show_interface.ttp`` was generated using the ``ansible_network_os`` for the host and ``command`` provided. +- TTP supports several additional variables that will be passed to the parser. These include: + + - ``parser/vars/ttp_init`` - Additional parameter passed when the parser is initialized. + - ``parser/vars/ttp_results`` - Additional parameters used to influence the parser output. + - ``parser/vars/ttp_vars`` - Additional variables made available in the template. + +- See the `TTP documentation <https://ttp.readthedocs.io>`_ for details. + + +The task sets the follow fact as the ``interfaces`` fact for the host: + +.. code-block:: yaml + + - admin_state: up, + interface: mgmt0 + state: up + - admin_state: up, + interface: Ethernet1/1 + state: up + - admin_state: up, + interface: Ethernet1/2 + state: up + + +Parsing with JC +----------------- + +JC is a python library that converts the output of dozens of common Linux/UNIX/macOS/Windows command-line tools and file types to python dictionaries or lists of dictionaries for easier parsing. JC is available as a filter plugin in the ``community.general`` collection. + +The following is an example using JC to parse the output of the ``dig`` command: + +.. code-block:: yaml + + - name: "Run dig command and parse with jc" + hosts: ubuntu + tasks: + - shell: dig example.com + register: result + - set_fact: + myvar: "{{ result.stdout | community.general.jc('dig') }}" + - debug: + msg: "The IP is: {{ myvar[0].answer[0].data }}" + +- The JC project and documentation can be found `here <https://github.com/kellyjonbrazil/jc/>`_. +- See this `blog entry <https://blog.kellybrazil.com/2020/08/30/parsing-command-output-in-ansible-with-jc/>`_ for more information. + + +Converting XML +----------------- + +Although Ansible contains a number of plugins that can convert XML to Ansible native data structures, the ``cli_parse`` module runs the command on devices that return XML and returns the converted data in a single task. + +This example task runs the ``show interface`` command and parses the output as XML: + +.. code-block:: yaml + + - name: "Run command and parse as xml" + ansible.utils.cli_parse: + command: show interface | xml + parser: + name: ansible.utils.xml + set_fact: interfaces + +.. note:: + + Red Hat Ansible Automation Platform subscription support is limited to the use of the ``xmltodict`` public APIs as documented. + +This task sets the ``interfaces`` fact for the host based on this returned output: + +.. code-block:: yaml + + nf:rpc-reply: + '@xmlns': http://www.cisco.com/nxos:1.0:if_manager + '@xmlns:nf': urn:ietf:params:xml:ns:netconf:base:1.0 + nf:data: + show: + interface: + __XML__OPT_Cmd_show_interface_quick: + __XML__OPT_Cmd_show_interface___readonly__: + __readonly__: + TABLE_interface: + ROW_interface: + - admin_state: up + encapsulation: ARPA + eth_autoneg: 'on' + eth_bia_addr: x254.005a.f8b5 + eth_bw: '1000000' + + +Advanced use cases +=================== + +The ``cli_parse`` module supports several features to support more complex uses cases. + +Provide a full template path +----------------------------- + +Use the ``template_path`` option to override the default template path in the task: + +.. code-block:: yaml + + - name: "Run command and parse with native" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.netcommon.native + template_path: /home/user/templates/filename.yaml + + +Provide command to parser different than the command run +----------------------------------------------------------- + +Use the ``command`` suboption for the ``parser`` to configure the command the parser expects if it is different from the command ``cli_parse`` runs: + +.. code-block:: yaml + + - name: "Run command and parse with native" + ansible.utils.cli_parse: + command: sho int + parser: + name: ansible.netcommon.native + command: show interface + +Provide a custom OS value +-------------------------------- + +Use the ``os`` suboption to the parser to directly set the OS instead of using ``ansible_network_os`` or ``ansible_distribution`` to generate the template path or with the specified parser engine: + +.. code-block:: yaml + + - name: Use ios instead of iosxe for pyats + ansible.utils.cli_parse: + command: show something + parser: + name: ansible.netcommon.pyats + os: ios + + - name: Use linux instead of fedora from ansible_distribution + ansible.utils.cli_parse: + command: ps -ef + parser: + name: ansible.netcommon.native + os: linux + + +Parse existing text +-------------------- + +Use the ``text`` option instead of ``command`` to parse text collected earlier in the playbook. + +.. code-block:: yaml + + # using /home/user/templates/filename.yaml + - name: "Parse text from previous task" + ansible.utils.cli_parse: + text: "{{ output['stdout'] }}" + parser: + name: ansible.netcommon.native + template_path: /home/user/templates/filename.yaml + + # using /home/user/templates/filename.yaml + - name: "Parse text from file" + ansible.utils.cli_parse: + text: "{{ lookup('file', 'path/to/file.txt') }}" + parser: + name: ansible.netcommon.native + template_path: /home/user/templates/filename.yaml + + # using templates/nxos_show_version.yaml + - name: "Parse text from previous task" + ansible.utils.cli_parse: + text: "{{ sho_version['stdout'] }}" + parser: + name: ansible.netcommon.native + os: nxos + command: show version + + +.. seealso:: + + * :ref:`develop_cli_parse_plugins` diff --git a/docs/docsite/rst/network/user_guide/faq.rst b/docs/docsite/rst/network/user_guide/faq.rst new file mode 100644 index 0000000..cb43ac2 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/faq.rst @@ -0,0 +1,76 @@ +.. _network_faq: + +******************* +Ansible Network FAQ +******************* + +.. contents:: Topics + +.. _network_faq_performance: + +How can I improve performance for network playbooks? +==================================================== + +.. _network_faq_strategy_free: + +Consider ``strategy: free`` if you are running on multiple hosts +--------------------------------------------------------------------------------- + +The ``strategy`` plugin tells Ansible how to order multiple tasks on multiple hosts. :ref:`Strategy<strategy_plugins>` is set at the playbook level. + +The default strategy is ``linear``. With strategy set to ``linear``, Ansible waits until the current task has run on all hosts before starting the next task on any host. Ansible may have forks free, but will not use them until all hosts have completed the current task. If each task in your playbook must succeed on all hosts before you run the next task, use the ``linear`` strategy. + +Using the ``free`` strategy, Ansible uses available forks to execute tasks on each host as quickly as possible. Even if an earlier task is still running on one host, Ansible executes later tasks on other hosts. The ``free`` strategy uses available forks more efficiently. If your playbook stalls on each task, waiting for one slow host, consider using ``strategy: free`` to boost overall performance. + +.. _network_faq_limit_show_running: + +Execute ``show running`` only if you absolutely must +--------------------------------------------------------------------------------- + +The ``show running`` command is the most resource-intensive command to execute on a network device, because of the way queries are handled by the network OS. Using the command in your Ansible playbook will slow performance significantly, especially on large devices; repeating it will multiply the performance hit. If you have a playbook that checks the running config, then executes changes, then checks the running config again, you should expect that playbook to be very slow. + +.. _network_faq_limit_ProxyCommand: + +Use ``ProxyCommand`` only if you absolutely must +--------------------------------------------------------------------------------- + +Network modules support the use of a :ref:`proxy or jump host<network_delegate_to_vs_ProxyCommand>` with the ``ProxyCommand`` parameter. However, when you use a jump host, Ansible must open a new SSH connection for every task, even if you are using a persistent connection type (``network_cli`` or ``netconf``). To maximize the performance benefits of the persistent connection types introduced in version 2.5, avoid using jump hosts whenever possible. + +.. _network_faq_set_forks: + +Set ``--forks`` to match your needs +--------------------------------------------------------------------------------- + +Every time Ansible runs a task, it forks its own process. The ``--forks`` parameter defines the number of concurrent tasks - if you retain the default setting, which is ``--forks=5``, and you are running a playbook on 10 hosts, five of those hosts will have to wait until a fork is available. Of course, the more forks you allow, the more memory and processing power Ansible will use. Since most network tasks are run on the control host, this means your laptop can quickly become cpu- or memory-bound. + +.. _network_faq_redacted_output: + +Why is my output sometimes replaced with ``********``? +====================================================== + +Ansible replaces any string marked ``no_log``, including passwords, with ``********`` in Ansible output. This is done by design, to protect your sensitive data. Most users are happy to have their passwords redacted. However, Ansible replaces every string that matches your password with ``********``. If you use a common word for your password, this can be a problem. For example, if you choose ``Admin`` as your password, Ansible will replace every instance of the word ``Admin`` with ``********`` in your output. This may make your output harder to read. To avoid this problem, select a secure password that will not occur elsewhere in your Ansible output. + +.. _network_faq_no_abbreviations_with_config: + +Why do the ``*_config`` modules always return ``changed=true`` with abbreviated commands? +========================================================================================= + +When you issue commands directly on a network device, you can use abbreviated commands. For example, ``int g1/0/11`` and ``interface GigabitEthernet1/0/11`` do the same thing; ``shut`` and ``shutdown`` do the same thing. Ansible Network ``*_command`` modules work with abbreviations, because they run commands through the network OS. + +When committing configuration, however, the network OS converts abbreviations into long-form commands. Whether you use ``shut`` or ``shutdown`` on ``GigabitEthernet1/0/11``, the result in the configuration is the same: ``shutdown``. + +Ansible Network ``*_config`` modules compare the text of the commands you specify in ``lines`` to the text in the configuration. If you use ``shut`` in the ``lines`` section of your task, and the configuration reads ``shutdown``, the module returns ``changed=true`` even though the configuration is already correct. Your task will update the configuration every time it runs. + +To avoid this problem, use long-form commands with the ``*_config`` modules: + + +.. code-block:: yaml + + --- + - hosts: all + gather_facts: no + tasks: + - cisco.ios.ios_config: + lines: + - shutdown + parents: interface GigabitEthernet1/0/11 diff --git a/docs/docsite/rst/network/user_guide/index.rst b/docs/docsite/rst/network/user_guide/index.rst new file mode 100644 index 0000000..306a627 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/index.rst @@ -0,0 +1,26 @@ +.. _network_advanced: + +********************************** +Network Advanced Topics +********************************** + +Once you have mastered the basics of network automation with Ansible, as presented in :ref:`network_getting_started`, use this guide understand platform-specific details, optimization, and troubleshooting tips for Ansible for network automation. + +**Who should use this guide?** + +This guide is intended for network engineers using Ansible for automation. It covers advanced topics. If you understand networks and Ansible, this guide is for you. You may read through the entire guide if you choose, or use the links below to find the specific information you need. + +If you're new to Ansible, or new to using Ansible for network automation, start with the :ref:`network_getting_started`. + +.. toctree:: + :maxdepth: 2 + :caption: Advanced Topics + + network_resource_modules + network_best_practices_2.5 + cli_parsing + validate + network_debug_troubleshooting + network_working_with_command_output + faq + platform_index diff --git a/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst b/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst new file mode 100644 index 0000000..4b236ce --- /dev/null +++ b/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst @@ -0,0 +1,483 @@ +.. _network-best-practices: + +************************ +Ansible Network Examples +************************ + +This document describes some examples of using Ansible to manage your network infrastructure. + +.. contents:: + :local: + +Prerequisites +============= + +This example requires the following: + +* **Ansible 2.10** (or higher) installed. See :ref:`intro_installation_guide` for more information. +* One or more network devices that are compatible with Ansible. +* Basic understanding of YAML :ref:`yaml_syntax`. +* Basic understanding of Jinja2 templates. See :ref:`playbooks_templating` for more information. +* Basic Linux command line use. +* Basic knowledge of network switch & router configurations. + + +Groups and variables in an inventory file +========================================= + +An ``inventory`` file is a YAML or INI-like configuration file that defines the mapping of hosts into groups. + +In our example, the inventory file defines the groups ``eos``, ``ios``, ``vyos`` and a "group of groups" called ``switches``. Further details about subgroups and inventory files can be found in the :ref:`Ansible inventory Group documentation <subgroups>`. + +Because Ansible is a flexible tool, there are a number of ways to specify connection information and credentials. We recommend using the ``[my_group:vars]`` capability in your inventory file. + +.. code-block:: ini + + [all:vars] + # these defaults can be overridden for any group in the [group:vars] section + ansible_connection=ansible.netcommon.network_cli + ansible_user=ansible + + [switches:children] + eos + ios + vyos + + [eos] + veos01 ansible_host=veos-01.example.net + veos02 ansible_host=veos-02.example.net + veos03 ansible_host=veos-03.example.net + veos04 ansible_host=veos-04.example.net + + [eos:vars] + ansible_become=yes + ansible_become_method=enable + ansible_network_os=arista.eos.eos + ansible_user=my_eos_user + ansible_password=my_eos_password + + [ios] + ios01 ansible_host=ios-01.example.net + ios02 ansible_host=ios-02.example.net + ios03 ansible_host=ios-03.example.net + + [ios:vars] + ansible_become=yes + ansible_become_method=enable + ansible_network_os=cisco.ios.ios + ansible_user=my_ios_user + ansible_password=my_ios_password + + [vyos] + vyos01 ansible_host=vyos-01.example.net + vyos02 ansible_host=vyos-02.example.net + vyos03 ansible_host=vyos-03.example.net + + [vyos:vars] + ansible_network_os=vyos.vyos.vyos + ansible_user=my_vyos_user + ansible_password=my_vyos_password + +If you use ssh-agent, you do not need the ``ansible_password`` lines. If you use ssh keys, but not ssh-agent, and you have multiple keys, specify the key to use for each connection in the ``[group:vars]`` section with ``ansible_ssh_private_key_file=/path/to/correct/key``. For more information on ``ansible_ssh_`` options see :ref:`behavioral_parameters`. + +.. FIXME FUTURE Gundalow - Link to network auth & proxy page (to be written) + +.. warning:: Never store passwords in plain text. + +Ansible vault for password encryption +------------------------------------- + +The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :ref:`playbooks_vault` for more information. + +Here's what it would look like if you specified your SSH passwords (encrypted with Ansible Vault) among your variables: + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + ansible_ssh_pass: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 39336231636137663964343966653162353431333566633762393034646462353062633264303765 + 6331643066663534383564343537343334633031656538370a333737656236393835383863306466 + 62633364653238323333633337313163616566383836643030336631333431623631396364663533 + 3665626431626532630a353564323566316162613432373738333064366130303637616239396438 + 9853 + +Common inventory variables +-------------------------- + +The following variables are common for all platforms in the inventory, though they can be overwritten for a particular inventory group or host. + +:ansible_connection: + + Ansible uses the ansible-connection setting to determine how to connect to a remote device. When working with Ansible Networking, set this to an appropriate network connection option, such as``ansible.netcommon.network_cli``, so Ansible treats the remote node as a network device with a limited execution environment. Without this setting, Ansible would attempt to use ssh to connect to the remote and execute the Python script on the network device, which would fail because Python generally isn't available on network devices. +:ansible_network_os: + Informs Ansible which Network platform this hosts corresponds to. This is required when using the ``ansible.netcommon.*`` connection options. +:ansible_user: The user to connect to the remote device (switch) as. Without this the user that is running ``ansible-playbook`` would be used. + Specifies which user on the network device the connection +:ansible_password: + The corresponding password for ``ansible_user`` to log in as. If not specified SSH key will be used. +:ansible_become: + If enable mode (privilege mode) should be used, see the next section. +:ansible_become_method: + Which type of `become` should be used, for ``network_cli`` the only valid choice is ``enable``. + +Privilege escalation +-------------------- + +Certain network platforms, such as Arista EOS and Cisco IOS, have the concept of different privilege modes. Certain network modules, such as those that modify system state including users, will only work in high privilege states. Ansible supports ``become`` when using ``connection: ansible.netcommon.network_cli``. This allows privileges to be raised for the specific tasks that need them. Adding ``become: yes`` and ``become_method: enable`` informs Ansible to go into privilege mode before executing the task, as shown here: + +.. code-block:: ini + + [eos:vars] + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=arista.eos.eos + ansible_become=yes + ansible_become_method=enable + +For more information, see the :ref:`using become with network modules<become_network>` guide. + + +Jump hosts +---------- + +If the Ansible Controller does not have a direct route to the remote device and you need to use a Jump Host, please see the :ref:`Ansible Network Proxy Command <network_delegate_to_vs_ProxyCommand>` guide for details on how to achieve this. + +Example 1: collecting facts and creating backup files with a playbook +===================================================================== + +Ansible facts modules gather system information 'facts' that are available to the rest of your playbook. + +Ansible Networking ships with a number of network-specific facts modules. In this example, we use the ``_facts`` modules :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>`, :ref:`cisco.ios.ios_facts <ansible_collections.cisco.ios.ios_facts_module>` and :ref:`vyos.vyos.vyos_facts <ansible_collections.vyos.vyos.vyos_facts_module>` to connect to the remote networking device. As the credentials are not explicitly passed with module arguments, Ansible uses the username and password from the inventory file. + +Ansible's "Network Fact modules" gather information from the system and store the results in facts prefixed with ``ansible_net_``. The data collected by these modules is documented in the `Return Values` section of the module docs, in this case :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>` and :ref:`vyos.vyos.vyos_facts <ansible_collections.vyos.vyos.vyos_facts_module>`. We can use the facts, such as ``ansible_net_version`` late on in the "Display some facts" task. + +To ensure we call the correct mode (``*_facts``) the task is conditionally run based on the group defined in the inventory file, for more information on the use of conditionals in Ansible Playbooks see :ref:`the_when_statement`. + +In this example, we will create an inventory file containing some network switches, then run a playbook to connect to the network devices and return some information about them. + +Step 1: Creating the inventory +------------------------------ + +First, create a file called ``inventory``, containing: + +.. code-block:: ini + + [switches:children] + eos + ios + vyos + + [eos] + eos01.example.net + + [ios] + ios01.example.net + + [vyos] + vyos01.example.net + + +Step 2: Creating the playbook +----------------------------- + +Next, create a playbook file called ``facts-demo.yml`` containing the following: + +.. code-block:: yaml + + - name: "Demonstrate connecting to switches" + hosts: switches + gather_facts: no + + tasks: + ### + # Collect data + # + - name: Gather facts (eos) + arista.eos.eos_facts: + when: ansible_network_os == 'arista.eos.eos' + + - name: Gather facts (ios) + cisco.ios.ios_facts: + when: ansible_network_os == 'cisco.ios.ios' + + - name: Gather facts (vyos) + vyos.vyos.vyos_facts: + when: ansible_network_os == 'vyos.vyos.vyos' + + ### + # Demonstrate variables + # + - name: Display some facts + debug: + msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" + + - name: Facts from a specific host + debug: + var: hostvars['vyos01.example.net'] + + - name: Write facts to disk using a template + copy: + content: | + #jinja2: lstrip_blocks: True + EOS device info: + {% for host in groups['eos'] %} + Hostname: {{ hostvars[host].ansible_net_hostname }} + Version: {{ hostvars[host].ansible_net_version }} + Model: {{ hostvars[host].ansible_net_model }} + Serial: {{ hostvars[host].ansible_net_serialnum }} + {% endfor %} + + IOS device info: + {% for host in groups['ios'] %} + Hostname: {{ hostvars[host].ansible_net_hostname }} + Version: {{ hostvars[host].ansible_net_version }} + Model: {{ hostvars[host].ansible_net_model }} + Serial: {{ hostvars[host].ansible_net_serialnum }} + {% endfor %} + + VyOS device info: + {% for host in groups['vyos'] %} + Hostname: {{ hostvars[host].ansible_net_hostname }} + Version: {{ hostvars[host].ansible_net_version }} + Model: {{ hostvars[host].ansible_net_model }} + Serial: {{ hostvars[host].ansible_net_serialnum }} + {% endfor %} + dest: /tmp/switch-facts + run_once: yes + + ### + # Get running configuration + # + + - name: Backup switch (eos) + arista.eos.eos_config: + backup: yes + register: backup_eos_location + when: ansible_network_os == 'arista.eos.eos' + + - name: backup switch (vyos) + vyos.vyos.vyos_config: + backup: yes + register: backup_vyos_location + when: ansible_network_os == 'vyos.vyos.vyos' + + - name: Create backup dir + file: + path: "/tmp/backups/{{ inventory_hostname }}" + state: directory + recurse: yes + + - name: Copy backup files into /tmp/backups/ (eos) + copy: + src: "{{ backup_eos_location.backup_path }}" + dest: "/tmp/backups/{{ inventory_hostname }}/{{ inventory_hostname }}.bck" + when: ansible_network_os == 'arista.eos.eos' + + - name: Copy backup files into /tmp/backups/ (vyos) + copy: + src: "{{ backup_vyos_location.backup_path }}" + dest: "/tmp/backups/{{ inventory_hostname }}/{{ inventory_hostname }}.bck" + when: ansible_network_os == 'vyos.vyos.vyos' + +Step 3: Running the playbook +---------------------------- + +To run the playbook, run the following from a console prompt: + +.. code-block:: console + + ansible-playbook -i inventory facts-demo.yml + +This should return output similar to the following: + +.. code-block:: console + + PLAY RECAP + eos01.example.net : ok=7 changed=2 unreachable=0 failed=0 + ios01.example.net : ok=7 changed=2 unreachable=0 failed=0 + vyos01.example.net : ok=6 changed=2 unreachable=0 failed=0 + +Step 4: Examining the playbook results +-------------------------------------- + +Next, look at the contents of the file we created containing the switch facts: + +.. code-block:: console + + cat /tmp/switch-facts + +You can also look at the backup files: + +.. code-block:: console + + find /tmp/backups + + +If `ansible-playbook` fails, please follow the debug steps in :ref:`network_debug_troubleshooting`. + + +.. _network-independent-examples: + +Example 2: simplifying playbooks with platform-independent modules +================================================================== + +(This example originally appeared in the `Deep Dive on cli_command for Network Automation <https://www.ansible.com/blog/deep-dive-on-cli-command-for-network-automation>`_ blog post by Sean Cavanaugh -`@IPvSean <https://github.com/IPvSean>`_). + +If you have two or more network platforms in your environment, you can use the platform-independent modules to simplify your playbooks. You can use platform-independent modules such as ``ansible.netcommon.cli_command`` or ``ansible.netcommon.cli_config`` in place of the platform-specific modules such as ``arista.eos.eos_config``, ``cisco.ios.ios_config``, and ``junipernetworks.junos.junos_config``. This reduces the number of tasks and conditionals you need in your playbooks. + +.. note:: + Platform-independent modules require the :ref:`ansible.netcommon.network_cli <ansible_collections.ansible.netcommon.network_cli_connection>` connection plugin. + + +Sample playbook with platform-specific modules +---------------------------------------------- + +This example assumes three platforms, Arista EOS, Cisco NXOS, and Juniper JunOS. Without the platform-independent modules, a sample playbook might contain the following three tasks with platform-specific commands: + +.. code-block:: yaml + + --- + - name: Run Arista command + arista.eos.eos_command: + commands: show ip int br + when: ansible_network_os == 'arista.eos.eos' + + - name: Run Cisco NXOS command + cisco.nxos.nxos_command: + commands: show ip int br + when: ansible_network_os == 'cisco.nxos.nxos' + + - name: Run Vyos command + vyos.vyos.vyos_command: + commands: show interface + when: ansible_network_os == 'vyos.vyos.vyos' + +Simplified playbook with ``cli_command`` platform-independent module +-------------------------------------------------------------------- + +You can replace these platform-specific modules with the platform-independent ``ansible.netcommon.cli_command`` module as follows: + +.. code-block:: yaml + + --- + - hosts: network + gather_facts: false + connection: ansible.netcommon.network_cli + + tasks: + - name: Run cli_command on Arista and display results + block: + - name: Run cli_command on Arista + ansible.netcommon.cli_command: + command: show ip int br + register: result + + - name: Display result to terminal window + debug: + var: result.stdout_lines + when: ansible_network_os == 'arista.eos.eos' + + - name: Run cli_command on Cisco IOS and display results + block: + - name: Run cli_command on Cisco IOS + ansible.netcommon.cli_command: + command: show ip int br + register: result + + - name: Display result to terminal window + debug: + var: result.stdout_lines + when: ansible_network_os == 'cisco.ios.ios' + + - name: Run cli_command on Vyos and display results + block: + - name: Run cli_command on Vyos + ansible.netcommon.cli_command: + command: show interfaces + register: result + + - name: Display result to terminal window + debug: + var: result.stdout_lines + when: ansible_network_os == 'vyos.vyos.vyos' + + +If you use groups and group_vars by platform type, this playbook can be further simplified to : + +.. code-block:: yaml + + --- + - name: Run command and print to terminal window + hosts: routers + gather_facts: false + + tasks: + - name: Run show command + ansible.netcommon.cli_command: + command: "{{show_interfaces}}" + register: command_output + + +You can see a full example of this using group_vars and also a configuration backup example at `Platform-independent examples <https://github.com/network-automation/agnostic_example>`_. + +Using multiple prompts with the ``ansible.netcommon.cli_command`` +------------------------------------------------------------------- + +The ``ansible.netcommon.cli_command`` also supports multiple prompts. + +.. code-block:: yaml + + --- + - name: Change password to default + ansible.netcommon.cli_command: + command: "{{ item }}" + prompt: + - "New password" + - "Retype new password" + answer: + - "mypassword123" + - "mypassword123" + check_all: True + loop: + - "configure" + - "rollback" + - "set system root-authentication plain-text-password" + - "commit" + +See the :ref:`ansible.netcommon.cli_command <cli_command_module>` for full documentation on this command. + + +Implementation Notes +==================== + + +Demo variables +-------------- + +Although these tasks are not needed to write data to disk, they are used in this example to demonstrate some methods of accessing facts about the given devices or a named host. + +Ansible ``hostvars`` allows you to access variables from a named host. Without this we would return the details for the current host, rather than the named host. + +For more information, see :ref:`magic_variables_and_hostvars`. + +Get running configuration +------------------------- + +The :ref:`arista.eos.eos_config <ansible_collections.arista.eos.eos_config_module>` and :ref:`vyos.vyos.vyos_config <ansible_collections.vyos.vyos.vyos_config_module>` modules have a ``backup:`` option that when set will cause the module to create a full backup of the current ``running-config`` from the remote device before any changes are made. The backup file is written to the ``backup`` folder in the playbook root directory. If the directory does not exist, it is created. + +To demonstrate how we can move the backup file to a different location, we register the result and move the file to the path stored in ``backup_path``. + +Note that when using variables from tasks in this way we use double quotes (``"``) and double curly-brackets (``{{...}}`` to tell Ansible that this is a variable. + +Troubleshooting +=============== + +If you receive an connection error please double check the inventory and playbook for typos or missing lines. If the issue still occurs follow the debug steps in :ref:`network_debug_troubleshooting`. + +.. seealso:: + + * :ref:`network_guide` + * :ref:`intro_inventory` + * :ref:`Keeping vaulted variables visible <tip_for_variables_and_vaults>` diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst new file mode 100644 index 0000000..d0fbcd6 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -0,0 +1,840 @@ +.. _network_debug_troubleshooting: + +*************************************** +Network Debug and Troubleshooting Guide +*************************************** + +This section discusses how to debug and troubleshoot network modules in Ansible. + +.. contents:: + :local: + + +How to troubleshoot +=================== + +Ansible network automation errors generally fall into one of the following categories: + +:Authentication issues: + * Not correctly specifying credentials + * Remote device (network switch/router) not falling back to other other authentication methods + * SSH key issues +:Timeout issues: + * Can occur when trying to pull a large amount of data + * May actually be masking a authentication issue +:Playbook issues: + * Use of ``delegate_to``, instead of ``ProxyCommand``. See :ref:`network proxy guide <network_delegate_to_vs_ProxyCommand>` for more information. + +.. warning:: ``unable to open shell`` + + The ``unable to open shell`` message means that the ``ansible-connection`` daemon has not been able to successfully + talk to the remote network device. This generally means that there is an authentication issue. See the "Authentication and connection issues" section + in this document for more information. + +.. _enable_network_logging: + +Enabling Networking logging and how to read the logfile +------------------------------------------------------- + +**Platforms:** Any + +Ansible includes logging to help diagnose and troubleshoot issues regarding Ansible Networking modules. + +Because logging is very verbose, it is disabled by default. It can be enabled with the :envvar:`ANSIBLE_LOG_PATH` and :envvar:`ANSIBLE_DEBUG` options on the ansible-controller, that is the machine running ``ansible-playbook``. + +Before running ``ansible-playbook``, run the following commands to enable logging: + +.. code:: shell + + # Specify the location for the log file + export ANSIBLE_LOG_PATH=~/ansible.log + # Enable Debug + export ANSIBLE_DEBUG=True + + # Run with 4*v for connection level verbosity + ansible-playbook -vvvv ... + +After Ansible has finished running you can inspect the log file which has been created on the ansible-controller: + +.. code:: + + less $ANSIBLE_LOG_PATH + + 2017-03-30 13:19:52,740 p=28990 u=fred | creating new control socket for host veos01:22 as user admin + 2017-03-30 13:19:52,741 p=28990 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a + 2017-03-30 13:19:52,741 p=28990 u=fred | current working directory is /home/fred/ansible/test/integration + 2017-03-30 13:19:52,741 p=28990 u=fred | using connection plugin network_cli + ... + 2017-03-30 13:20:14,771 paramiko.transport userauth is OK + 2017-03-30 13:20:15,283 paramiko.transport Authentication (keyboard-interactive) successful! + 2017-03-30 13:20:15,302 p=28990 u=fred | ssh connection done, setting terminal + 2017-03-30 13:20:15,321 p=28990 u=fred | ssh connection has completed successfully + 2017-03-30 13:20:15,322 p=28990 u=fred | connection established to veos01 in 0:00:22.580626 + + +From the log notice: + +* ``p=28990`` Is the PID (Process ID) of the ``ansible-connection`` process +* ``u=fred`` Is the user `running` ansible, not the remote-user you are attempting to connect as +* ``creating new control socket for host veos01:22 as user admin`` host:port as user +* ``control socket path is`` location on disk where the persistent connection socket is created +* ``using connection plugin network_cli`` Informs you that persistent connection is being used +* ``connection established to veos01 in 0:00:22.580626`` Time taken to obtain a shell on the remote device + + +.. note:: Port None ``creating new control socket for host veos01:None`` + + If the log reports the port as ``None`` this means that the default port is being used. + A future Ansible release will improve this message so that the port is always logged. + +Because the log files are verbose, you can use grep to look for specific information. For example, once you have identified the ``pid`` from the ``creating new control socket for host`` line you can search for other connection log entries: + +.. code:: shell + + grep "p=28990" $ANSIBLE_LOG_PATH + + +Enabling Networking device interaction logging +---------------------------------------------- + +**Platforms:** Any + +Ansible includes logging of device interaction in the log file to help diagnose and troubleshoot +issues regarding Ansible Networking modules. The messages are logged in the file pointed to by the ``log_path`` configuration +option in the Ansible configuration file or by setting the :envvar:`ANSIBLE_LOG_PATH`. + +.. warning:: + The device interaction messages consist of command executed on the target device and the returned response. Since this + log data can contain sensitive information including passwords in plain text it is disabled by default. + Additionally, in order to prevent accidental leakage of data, a warning will be shown on every task with this + setting enabled, specifying which host has it enabled and where the data is being logged. + +Be sure to fully understand the security implications of enabling this option. The device interaction logging can be enabled either globally by setting in configuration file or by setting environment or enabled on per task basis by passing a special variable to the task. + +Before running ``ansible-playbook`` run the following commands to enable logging: + +.. code-block:: text + + # Specify the location for the log file + export ANSIBLE_LOG_PATH=~/ansible.log + + +Enable device interaction logging for a given task + +.. code-block:: yaml + + - name: get version information + cisco.ios.ios_command: + commands: + - show version + vars: + ansible_persistent_log_messages: True + + +To make this a global setting, add the following to your ``ansible.cfg`` file: + +.. code-block:: ini + + [persistent_connection] + log_messages = True + +or enable the environment variable `ANSIBLE_PERSISTENT_LOG_MESSAGES`: + +.. code-block:: text + + # Enable device interaction logging + export ANSIBLE_PERSISTENT_LOG_MESSAGES=True + +If the task is failing on connection initialization itself, you should enable this option +globally. If an individual task is failing intermittently this option can be enabled for that task itself to find the root cause. + +After Ansible has finished running you can inspect the log file which has been created on the ansible-controller + +.. note:: Be sure to fully understand the security implications of enabling this option as it can log sensitive + information in log file thus creating security vulnerability. + + +Isolating an error +------------------ + +**Platforms:** Any + +As with any effort to troubleshoot it's important to simplify the test case as much as possible. + +For Ansible this can be done by ensuring you are only running against one remote device: + +* Using ``ansible-playbook --limit switch1.example.net...`` +* Using an ad hoc ``ansible`` command + +`ad hoc` refers to running Ansible to perform some quick command using ``/usr/bin/ansible``, rather than the orchestration language, which is ``/usr/bin/ansible-playbook``. In this case we can ensure connectivity by attempting to execute a single command on the remote device: + +.. code-block:: text + + ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k + +In the above example, we: + +* connect to ``switch1.example.net`` specified in the inventory file ``inventory`` +* use the module ``arista.eos.eos_command`` +* run the command ``?`` +* connect using the username ``admin`` +* inform the ``ansible`` command to prompt for the SSH password by specifying ``-k`` + +If you have SSH keys configured correctly, you don't need to specify the ``-k`` parameter. + +If the connection still fails you can combine it with the enable_network_logging parameter. For example: + +.. code-block:: text + + # Specify the location for the log file + export ANSIBLE_LOG_PATH=~/ansible.log + # Enable Debug + export ANSIBLE_DEBUG=True + # Run with ``-vvvv`` for connection level verbosity + ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k + +Then review the log file and find the relevant error message in the rest of this document. + +.. For details on other ways to authenticate, see LINKTOAUTHHOWTODOCS. + +.. _socket_path_issue: + +Troubleshooting socket path issues +================================== + +**Platforms:** Any + +The ``Socket path does not exist or cannot be found`` and ``Unable to connect to socket`` messages indicate that the socket used to communicate with the remote network device is unavailable or does not exist. + +For example: + +.. code-block:: none + + fatal: [spine02]: FAILED! => { + "changed": false, + "failed": true, + "module_stderr": "Traceback (most recent call last):\n File \"/tmp/ansible_TSqk5J/ansible_modlib.zip/ansible/module_utils/connection.py\", line 115, in _exec_jsonrpc\nansible.module_utils.connection.ConnectionError: Socket path XX does not exist or cannot be found. See Troubleshooting socket path issues in the Network Debug and Troubleshooting Guide\n", + "module_stdout": "", + "msg": "MODULE FAILURE", + "rc": 1 + } + +or + +.. code-block:: none + + fatal: [spine02]: FAILED! => { + "changed": false, + "failed": true, + "module_stderr": "Traceback (most recent call last):\n File \"/tmp/ansible_TSqk5J/ansible_modlib.zip/ansible/module_utils/connection.py\", line 123, in _exec_jsonrpc\nansible.module_utils.connection.ConnectionError: Unable to connect to socket XX. See Troubleshooting socket path issues in Network Debug and Troubleshooting Guide\n", + "module_stdout": "", + "msg": "MODULE FAILURE", + "rc": 1 + } + +Suggestions to resolve: + +#. Verify that you have write access to the socket path described in the error message. + +#. Follow the steps detailed in :ref:`enable network logging <enable_network_logging>`. + +If the identified error message from the log file is: + +.. code-block:: yaml + + 2017-04-04 12:19:05,670 p=18591 u=fred | command timeout triggered, timeout value is 30 secs + +or + +.. code-block:: yaml + + 2017-04-04 12:19:05,670 p=18591 u=fred | persistent connection idle timeout triggered, timeout value is 30 secs + +Follow the steps detailed in :ref:`timeout issues <timeout_issues>` + + +.. _unable_to_open_shell: + +Category "Unable to open shell" +=============================== + + +**Platforms:** Any + +The ``unable to open shell`` message means that the ``ansible-connection`` daemon has not been able to successfully talk to the remote network device. This generally means that there is an authentication issue. It is a "catch all" message, meaning you need to enable :ref:`logging <a_note_about_logging>` to find the underlying issues. + + + +For example: + +.. code-block:: none + + TASK [prepare_eos_tests : enable cli on remote device] ************************************************** + fatal: [veos01]: FAILED! => {"changed": false, "failed": true, "msg": "unable to open shell"} + + +or: + + +.. code-block:: none + + TASK [ios_system : configure name_servers] ************************************************************* + task path: + fatal: [ios-csr1000v]: FAILED! => { + "changed": false, + "failed": true, + "msg": "unable to open shell", + } + +Suggestions to resolve: + +Follow the steps detailed in enable_network_logging_. + +Once you've identified the error message from the log file, the specific solution can be found in the rest of this document. + + + +Error: "[Errno -2] Name or service not known" +--------------------------------------------- + +**Platforms:** Any + +Indicates that the remote host you are trying to connect to can not be reached + +For example: + +.. code-block:: yaml + + 2017-04-04 11:39:48,147 p=15299 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a + 2017-04-04 11:39:48,147 p=15299 u=fred | current working directory is /home/fred/git/ansible-inc/stable-2.3/test/integration + 2017-04-04 11:39:48,147 p=15299 u=fred | using connection plugin network_cli + 2017-04-04 11:39:48,340 p=15299 u=fred | connecting to host veos01 returned an error + 2017-04-04 11:39:48,340 p=15299 u=fred | [Errno -2] Name or service not known + + +Suggestions to resolve: + +* If you are using the ``provider:`` options ensure that its suboption ``host:`` is set correctly. +* If you are not using ``provider:`` nor top-level arguments ensure your inventory file is correct. + + + + + +Error: "Authentication failed" +------------------------------ + +**Platforms:** Any + +Occurs if the credentials (username, passwords, or ssh keys) passed to ``ansible-connection`` (through ``ansible`` or ``ansible-playbook``) can not be used to connect to the remote device. + + + +For example: + +.. code-block:: yaml + + <ios01> ESTABLISH CONNECTION FOR USER: cisco on PORT 22 TO ios01 + <ios01> Authentication failed. + + +Suggestions to resolve: + +If you are specifying credentials through ``password:`` (either directly or through ``provider:``) or the environment variable `ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this: + +.. code-block:: yaml + + export ANSIBLE_PARAMIKO_LOOK_FOR_KEYS=False + +To make this a permanent change, add the following to your ``ansible.cfg`` file: + +.. code-block:: ini + + [paramiko_connection] + look_for_keys = False + + +Error: "connecting to host <hostname> returned an error" or "Bad address" +------------------------------------------------------------------------- + +This may occur if the SSH fingerprint hasn't been added to Paramiko's (the Python SSH library) know hosts file. + +When using persistent connections with Paramiko, the connection runs in a background process. If the host doesn't already have a valid SSH key, by default Ansible will prompt to add the host key. This will cause connections running in background processes to fail. + +For example: + +.. code-block:: yaml + + 2017-04-04 12:06:03,486 p=17981 u=fred | using connection plugin network_cli + 2017-04-04 12:06:04,680 p=17981 u=fred | connecting to host veos01 returned an error + 2017-04-04 12:06:04,682 p=17981 u=fred | (14, 'Bad address') + 2017-04-04 12:06:33,519 p=17981 u=fred | number of connection attempts exceeded, unable to connect to control socket + 2017-04-04 12:06:33,520 p=17981 u=fred | persistent_connect_interval=1, persistent_connect_retries=30 + + +Suggestions to resolve: + +Use ``ssh-keyscan`` to pre-populate the known_hosts. You need to ensure the keys are correct. + +.. code-block:: shell + + ssh-keyscan veos01 + + +or + +You can tell Ansible to automatically accept the keys + +Environment variable method: + +.. code-block:: shell + + export ANSIBLE_PARAMIKO_HOST_KEY_AUTO_ADD=True + ansible-playbook ... + +``ansible.cfg`` method: + +ansible.cfg + +.. code-block:: ini + + [paramiko_connection] + host_key_auto_add = True + + + +.. warning: Security warning + + Care should be taken before accepting keys. + +Error: "No authentication methods available" +-------------------------------------------- + +For example: + +.. code-block:: yaml + + 2017-04-04 12:19:05,670 p=18591 u=fred | creating new control socket for host veos01:None as user admin + 2017-04-04 12:19:05,670 p=18591 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a + 2017-04-04 12:19:05,670 p=18591 u=fred | current working directory is /home/fred/git/ansible-inc/ansible-workspace-2/test/integration + 2017-04-04 12:19:05,670 p=18591 u=fred | using connection plugin network_cli + 2017-04-04 12:19:06,606 p=18591 u=fred | connecting to host veos01 returned an error + 2017-04-04 12:19:06,606 p=18591 u=fred | No authentication methods available + 2017-04-04 12:19:35,708 p=18591 u=fred | connect retry timeout expired, unable to connect to control socket + 2017-04-04 12:19:35,709 p=18591 u=fred | persistent_connect_retry_timeout is 15 secs + + +Suggestions to resolve: + +No password or SSH key supplied + +Clearing Out Persistent Connections +----------------------------------- + +**Platforms:** Any + +In Ansible 2.3, persistent connection sockets are stored in ``~/.ansible/pc`` for all network devices. When an Ansible playbook runs, the persistent socket connection is displayed when verbose output is specified. + +``<switch> socket_path: /home/fred/.ansible/pc/f64ddfa760`` + +To clear out a persistent connection before it times out (the default timeout is 30 seconds +of inactivity), simple delete the socket file. + + +.. _timeout_issues: + +Timeout issues +============== + +Persistent connection idle timeout +---------------------------------- + +By default, ``ANSIBLE_PERSISTENT_CONNECT_TIMEOUT`` is set to 30 (seconds). You may see the following error if this value is too low: + +.. code-block:: yaml + + 2017-04-04 12:19:05,670 p=18591 u=fred | persistent connection idle timeout triggered, timeout value is 30 secs + +Suggestions to resolve: + +Increase value of persistent connection idle timeout: + +.. code-block:: sh + + export ANSIBLE_PERSISTENT_CONNECT_TIMEOUT=60 + +To make this a permanent change, add the following to your ``ansible.cfg`` file: + +.. code-block:: ini + + [persistent_connection] + connect_timeout = 60 + +Command timeout +--------------- + +By default, ``ANSIBLE_PERSISTENT_COMMAND_TIMEOUT`` is set to 30 (seconds). Prior versions of Ansible had this value set to 10 seconds by default. +You may see the following error if this value is too low: + + +.. code-block:: yaml + + 2017-04-04 12:19:05,670 p=18591 u=fred | command timeout triggered, timeout value is 30 secs + +Suggestions to resolve: + +* Option 1 (Global command timeout setting): + Increase value of command timeout in configuration file or by setting environment variable. + + .. code-block:: yaml + + export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=60 + + To make this a permanent change, add the following to your ``ansible.cfg`` file: + + .. code-block:: ini + + [persistent_connection] + command_timeout = 60 + +* Option 2 (Per task command timeout setting): + Increase command timeout per task basis. All network modules support a + timeout value that can be set on a per task basis. + The timeout value controls the amount of time in seconds before the + task will fail if the command has not returned. + + For local connection type: + + .. FIXME: Detail error here + + Suggestions to resolve: + + Some modules support a ``timeout`` option, which is different to the ``timeout`` keyword for tasks. + + .. code-block:: yaml + + - name: save running-config + cisco.ios.ios_command: + commands: copy running-config startup-config + provider: "{{ cli }}" + timeout: 30 + + + Suggestions to resolve: + + If the module does not support the ``timeout`` option directly, most networking connection plugins can enable similar functionality with the ``ansible_command_timeout`` variable. + + .. code-block:: yaml + + - name: save running-config + cisco.ios.ios_command: + commands: copy running-config startup-config + vars: + ansible_command_timeout: 60 + +Some operations take longer than the default 30 seconds to complete. One good +example is saving the current running config on IOS devices to startup config. +In this case, changing the timeout value from the default 30 seconds to 60 +seconds will prevent the task from failing before the command completes +successfully. + +Persistent connection retry timeout +----------------------------------- + +By default, ``ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT`` is set to 15 (seconds). You may see the following error if this value is too low: + +.. code-block:: yaml + + 2017-04-04 12:19:35,708 p=18591 u=fred | connect retry timeout expired, unable to connect to control socket + 2017-04-04 12:19:35,709 p=18591 u=fred | persistent_connect_retry_timeout is 15 secs + +Suggestions to resolve: + +Increase the value of the persistent connection idle timeout. +Note: This value should be greater than the SSH timeout value (the timeout value under the defaults +section in the configuration file) and less than the value of the persistent +connection idle timeout (connect_timeout). + +.. code-block:: yaml + + export ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT=30 + +To make this a permanent change, add the following to your ``ansible.cfg`` file: + +.. code-block:: ini + + [persistent_connection] + connect_retry_timeout = 30 + + +Timeout issue due to platform specific login menu with ``network_cli`` connection type +-------------------------------------------------------------------------------------- + +In Ansible 2.9 and later, the network_cli connection plugin configuration options are added +to handle the platform specific login menu. These options can be set as group/host or tasks +variables. + +Example: Handle single login menu prompts with host variables + +.. code-block:: console + + $cat host_vars/<hostname>.yaml + --- + ansible_terminal_initial_prompt: + - "Connect to a host" + ansible_terminal_initial_answer: + - "3" + +Example: Handle remote host multiple login menu prompts with host variables + +.. code-block:: console + + $cat host_vars/<inventory-hostname>.yaml + --- + ansible_terminal_initial_prompt: + - "Press any key to enter main menu" + - "Connect to a host" + ansible_terminal_initial_answer: + - "\\r" + - "3" + ansible_terminal_initial_prompt_checkall: True + +To handle multiple login menu prompts: + +* The values of ``ansible_terminal_initial_prompt`` and ``ansible_terminal_initial_answer`` should be a list. +* The prompt sequence should match the answer sequence. +* The value of ``ansible_terminal_initial_prompt_checkall`` should be set to ``True``. + +.. note:: If all the prompts in sequence are not received from remote host at the time connection initialization it will result in a timeout. + + +Playbook issues +=============== + +This section details issues are caused by issues with the Playbook itself. + +Error: "Unable to enter configuration mode" +------------------------------------------- + +**Platforms:** Arista EOS and Cisco IOS + +This occurs when you attempt to run a task that requires privileged mode in a user mode shell. + +For example: + +.. code-block:: console + + TASK [ios_system : configure name_servers] ***************************************************************************** + task path: + fatal: [ios-csr1000v]: FAILED! => { + "changed": false, + "failed": true, + "msg": "unable to enter configuration mode", + } + +Suggestions to resolve: + + Use ``connection: ansible.netcommon.network_cli`` and ``become: yes`` + + +Proxy Issues +============ + + .. _network_delegate_to_vs_ProxyCommand: + +delegate_to vs ProxyCommand +--------------------------- + +In order to use a bastion or intermediate jump host to connect to network devices over ``cli`` +transport, network modules support the use of ``ProxyCommand``. + +To use ``ProxyCommand``, configure the proxy settings in the Ansible inventory +file to specify the proxy host. + +.. code-block:: ini + + [nxos] + nxos01 + nxos02 + + [nxos:vars] + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +With the configuration above, simply build and run the playbook as normal with +no additional changes necessary. The network module will now connect to the +network device by first connecting to the host specified in +``ansible_ssh_common_args``, which is ``bastion01`` in the above example. + +You can also set the proxy target for all hosts by using environment variables. + +.. code-block:: sh + + export ANSIBLE_SSH_ARGS='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + +Using bastion/jump host with netconf connection +----------------------------------------------- + +Enabling jump host setting +-------------------------- + + +Bastion/jump host with netconf connection can be enabled by: + - Setting Ansible variable ``ansible_netconf_ssh_config`` either to ``True`` or custom ssh config file path + - Setting environment variable ``ANSIBLE_NETCONF_SSH_CONFIG`` to ``True`` or custom ssh config file path + - Setting ``ssh_config = 1`` or ``ssh_config = <ssh-file-path>`` under ``netconf_connection`` section + +If the configuration variable is set to 1 the proxycommand and other ssh variables are read from +default ssh config file (~/.ssh/config). + +If the configuration variable is set to file path the proxycommand and other ssh variables are read +from the given custom ssh file path + +Example ssh config file (~/.ssh/config) +--------------------------------------- + +.. code-block:: ini + + Host jumphost + HostName jumphost.domain.name.com + User jumphost-user + IdentityFile "/path/to/ssh-key.pem" + Port 22 + + # Note: Due to the way that Paramiko reads the SSH Config file, + # you need to specify the NETCONF port that the host uses. + # In other words, it does not automatically use ansible_port + # As a result you need either: + + Host junos01 + HostName junos01 + ProxyCommand ssh -W %h:22 jumphost + + # OR + + Host junos01 + HostName junos01 + ProxyCommand ssh -W %h:830 jumphost + + # Depending on the netconf port used. + +Example Ansible inventory file + +.. code-block:: ini + + [junos] + junos01 + + [junos:vars] + ansible_connection=ansible.netcommon.netconf + ansible_network_os=junipernetworks.junos.junos + ansible_user=myuser + ansible_password=!vault... + + +.. note:: Using ``ProxyCommand`` with passwords through variables + + By design, SSH doesn't support providing passwords through environment variables. + This is done to prevent secrets from leaking out, for example in ``ps`` output. + + We recommend using SSH Keys, and if needed an ssh-agent, rather than passwords, where ever possible. + +Miscellaneous Issues +==================== + + +Intermittent failure while using ``ansible.netcommon.network_cli`` connection type +------------------------------------------------------------------------------------ + +If the command prompt received in response is not matched correctly within +the ``ansible.netcommon.network_cli`` connection plugin the task might fail intermittently with truncated +response or with the error message ``operation requires privilege escalation``. +Starting in 2.7.1 a new buffer read timer is added to ensure prompts are matched properly +and a complete response is send in output. The timer default value is 0.2 seconds and +can be adjusted on a per task basis or can be set globally in seconds. + +Example Per task timer setting + +.. code-block:: yaml + + - name: gather ios facts + cisco.ios.ios_facts: + gather_subset: all + register: result + vars: + ansible_buffer_read_timeout: 2 + + +To make this a global setting, add the following to your ``ansible.cfg`` file: + +.. code-block:: ini + + [persistent_connection] + buffer_read_timeout = 2 + +This timer delay per command executed on remote host can be disabled by setting the value to zero. + + +Task failure due to mismatched error regex within command response using ``ansible.netcommon.network_cli`` connection type +---------------------------------------------------------------------------------------------------------------------------- + +In Ansible 2.9 and later, the ``ansible.netcommon.network_cli`` connection plugin configuration options are added +to handle the stdout and stderr regex to identify if the command execution response consist +of a normal response or an error response. These options can be set group/host variables or as +tasks variables. + +Example: For mismatched error response + +.. code-block:: yaml + + - name: fetch logs from remote host + cisco.ios.ios_command: + commands: + - show logging + + +Playbook run output: + +.. code-block:: console + + TASK [first fetch logs] ******************************************************** + fatal: [ios01]: FAILED! => { + "changed": false, + "msg": "RF Name:\r\n\r\n <--nsip--> + \"IPSEC-3-REPLAY_ERROR: Test log\"\r\n*Aug 1 08:36:18.483: %SYS-7-USERLOG_DEBUG: + Message from tty578(user id: ansible): test\r\nan-ios-02#"} + +Suggestions to resolve: + +Modify the error regex for individual task. + +.. code-block:: yaml + + - name: fetch logs from remote host + cisco.ios.ios_command: + commands: + - show logging + vars: + ansible_terminal_stderr_re: + - pattern: 'connection timed out' + flags: 're.I' + +The terminal plugin regex options ``ansible_terminal_stderr_re`` and ``ansible_terminal_stdout_re`` have +``pattern`` and ``flags`` as keys. The value of the ``flags`` key should be a value that is accepted by +the ``re.compile`` python method. + + +Intermittent failure while using ``ansible.netcommon.network_cli`` connection type due to slower network or remote target host +---------------------------------------------------------------------------------------------------------------------------------- + +In Ansible 2.9 and later, the ``ansible.netcommon.network_cli`` connection plugin configuration option is added to control +the number of attempts to connect to a remote host. The default number of attempts is three. +After every retry attempt the delay between retries is increased by power of 2 in seconds until either the +maximum attempts are exhausted or either the ``persistent_command_timeout`` or ``persistent_connect_timeout`` timers are triggered. + +To make this a global setting, add the following to your ``ansible.cfg`` file: + +.. code-block:: ini + + [persistent_connection] + network_cli_retries = 5 diff --git a/docs/docsite/rst/network/user_guide/network_resource_modules.rst b/docs/docsite/rst/network/user_guide/network_resource_modules.rst new file mode 100644 index 0000000..1d048f5 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/network_resource_modules.rst @@ -0,0 +1,196 @@ +.. _resource_modules: + +************************ +Network Resource Modules +************************ + +Ansible network resource modules simplify and standardize how you manage different network devices. Network devices separate configuration into sections (such as interfaces and VLANs) that apply to a network service. Ansible network resource modules take advantage of this to allow you to configure subsections or *resources* within the network device configuration. Network resource modules provide a consistent experience across different network devices. + + +.. contents:: + :local: + +Network resource module states +=============================== + +You use the network resource modules by assigning a state to what you want the module to do. The resource modules support the following states: + +merged + Ansible merges the on-device configuration with the provided configuration in the task. + +replaced + Ansible replaces the on-device configuration subsection with the provided configuration subsection in the task. + +overridden + Ansible overrides the on-device configuration for the resource with the provided configuration in the task. Use caution with this state as you could remove your access to the device (for example, by overriding the management interface configuration). + +deleted + Ansible deletes the on-device configuration subsection and restores any default settings. + +gathered + Ansible displays the resource details gathered from the network device and accessed with the ``gathered`` key in the result. + +rendered + Ansible renders the provided configuration in the task in the device-native format (for example, Cisco IOS CLI). Ansible returns this rendered configuration in the ``rendered`` key in the result. Note this state does not communicate with the network device and can be used offline. + +parsed + Ansible parses the configuration from the ``running_config`` option into Ansible structured data in the ``parsed`` key in the result. Note this does not gather the configuration from the network device so this state can be used offline. + +Using network resource modules +============================== + +This example configures the L3 interface resource on a Cisco IOS device, based on different state settings. + + .. code-block:: yaml + + - name: configure l3 interface + cisco.ios.ios_l3_interfaces: + config: "{{ config }}" + state: <state> + +The following table shows an example of how an initial resource configuration changes with this task for different states. + ++-----------------------------------------+------------------------------------+-----------------------------------------+ +| Resource starting configuration | task-provided configuration (YAML) | Final resource configuration on device | ++=========================================+====================================+=========================================+ +| .. code-block:: text | .. code-block:: yaml | *merged* | +| | | .. code-block:: text | +| interface loopback100 | config: | | +| ip address 10.10.1.100 255.255.255.0 | - ipv6: | interface loopback100 | +| ipv6 address FC00:100/64 | - address: fc00::100/64 | ip address 10.10.1.100 255.255.255.0| +| | - address: fc00::101/64 | ipv6 address FC00:100/64 | +| | name: loopback100 | ipv6 address FC00:101/64 | +| | +-----------------------------------------+ +| | | *replaced* | +| | | .. code-block:: text | +| | | | +| | | interface loopback100 | +| | | no ip address | +| | | ipv6 address FC00:100/64 | +| | | ipv6 address FC00:101/64 | +| | +-----------------------------------------+ +| | | *overridden* | +| | | Incorrect use case. This would remove | +| | | all interfaces from the device | +| | | (including the mgmt interface) except | +| | | the configured loopback100 | +| | +-----------------------------------------+ +| | | *deleted* | +| | | .. code-block:: text | +| | | | +| | | interface loopback100 | +| | | no ip address | ++-----------------------------------------+------------------------------------+-----------------------------------------+ + +Network resource modules return the following details: + +* The *before* state - the existing resource configuration before the task was executed. +* The *after* state - the new resource configuration that exists on the network device after the task was executed. +* Commands - any commands configured on the device. + +.. code-block:: yaml + + ok: [nxos101] => + result: + after: + contact: IT Support + location: Room E, Building 6, Seattle, WA 98134 + users: + - algorithm: md5 + group: network-admin + localized_key: true + password: '0x73fd9a2cc8c53ed3dd4ed8f4ff157e69' + privacy_password: '0x73fd9a2cc8c53ed3dd4ed8f4ff157e69' + username: admin + before: + contact: IT Support + location: Room E, Building 5, Seattle HQ + users: + - algorithm: md5 + group: network-admin + localized_key: true + password: '0x73fd9a2cc8c53ed3dd4ed8f4ff157e69' + privacy_password: '0x73fd9a2cc8c53ed3dd4ed8f4ff157e69' + username: admin + changed: true + commands: + - snmp-server location Room E, Building 6, Seattle, WA 98134 + failed: false + + +Example: Verifying the network device configuration has not changed +==================================================================== + +The following playbook uses the :ref:`arista.eos.eos_l3_interfaces <ansible_collections.arista.eos.eos_l3_interfaces_module>` module to gather a subset of the network device configuration (Layer 3 interfaces only) and verifies the information is accurate and has not changed. This playbook passes the results of :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>` directly to the ``arista.eos.eos_l3_interfaces`` module. + + +.. code-block:: yaml + + - name: Example of facts being pushed right back to device. + hosts: arista + gather_facts: false + tasks: + - name: grab arista eos facts + arista.eos.eos_facts: + gather_subset: min + gather_network_resources: l3_interfaces + + - name: Ensure that the IP address information is accurate. + arista.eos.eos_l3_interfaces: + config: "{{ ansible_network_resources['l3_interfaces'] }}" + register: result + + - name: Ensure config did not change. + assert: + that: not result.changed + +Example: Acquiring and updating VLANs on a network device +========================================================== + +This example shows how you can use resource modules to: + +#. Retrieve the current configuration on a network device. +#. Save that configuration locally. +#. Update that configuration and apply it to the network device. + +This example uses the ``cisco.ios.ios_vlans`` resource module to retrieve and update the VLANs on an IOS device. + +1. Retrieve the current IOS VLAN configuration: + +.. code-block:: yaml + + - name: Gather VLAN information as structured data + cisco.ios.ios_facts: + gather_subset: + - '!all' + - '!min' + gather_network_resources: + - 'vlans' + +2. Store the VLAN configuration locally: + +.. code-block:: yaml + + - name: Store VLAN facts to host_vars + copy: + content: "{{ ansible_network_resources | to_nice_yaml }}" + dest: "{{ playbook_dir }}/host_vars/{{ inventory_hostname }}" + +3. Modify the stored file to update the VLAN configuration locally. + +4. Merge the updated VLAN configuration with the existing configuration on the device: + +.. code-block:: yaml + + - name: Make VLAN config changes by updating stored facts on the controller. + cisco.ios.ios_vlans: + config: "{{ vlans }}" + state: merged + tags: update_config + +.. seealso:: + + `Network Features in Ansible 2.9 <https://www.ansible.com/blog/network-features-coming-soon-in-ansible-engine-2.9>`_ + A introductory blog post on network resource modules. + `Deep Dive into Network Resource Modules <https://www.ansible.com/deep-dive-into-ansible-network-resource-module>`_ + A deeper dive presentation into network resource modules. diff --git a/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst b/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst new file mode 100644 index 0000000..6215df9 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst @@ -0,0 +1,126 @@ +.. _networking_working_with_command_output: + +********************************************************** +Working with command output and prompts in network modules +********************************************************** + +.. contents:: + :local: + +Conditionals in networking modules +=================================== + +Ansible allows you to use conditionals to control the flow of your playbooks. Ansible networking command modules use the following unique conditional statements. + +* ``eq`` - Equal +* ``neq`` - Not equal +* ``gt`` - Greater than +* ``ge`` - Greater than or equal +* ``lt`` - Less than +* ``le`` - Less than or equal +* ``contains`` - Object contains specified item + + +Conditional statements evaluate the results from the commands that are +executed remotely on the device. Once the task executes the command +set, the ``wait_for`` argument can be used to evaluate the results before +returning control to the Ansible playbook. + +For example: + +.. code-block:: yaml + + --- + - name: wait for interface to be admin enabled + arista.eos.eos_command: + commands: + - show interface Ethernet4 | json + wait_for: + - "result[0].interfaces.Ethernet4.interfaceStatus eq connected" + +In the above example task, the command :code:`show interface Ethernet4 | json` +is executed on the remote device and the results are evaluated. If +the path +:code:`(result[0].interfaces.Ethernet4.interfaceStatus)` is not equal to +"connected", then the command is retried. This process continues +until either the condition is satisfied or the number of retries has +expired (by default, this is 10 retries at 1 second intervals). + +The commands module can also evaluate more than one set of command +results in an interface. For instance: + +.. code-block:: yaml + + --- + - name: wait for interfaces to be admin enabled + arista.eos.eos_command: + commands: + - show interface Ethernet4 | json + - show interface Ethernet5 | json + wait_for: + - "result[0].interfaces.Ethernet4.interfaceStatus eq connected" + - "result[1].interfaces.Ethernet5.interfaceStatus eq connected" + +In the above example, two commands are executed on the +remote device, and the results are evaluated. By specifying the result +index value (0 or 1), the correct result output is checked against the +conditional. + +The ``wait_for`` argument must always start with result and then the +command index in ``[]``, where ``0`` is the first command in the commands list, +``1`` is the second command, ``2`` is the third and so on. + + +Handling prompts in network modules +=================================== + +Network devices may require that you answer a prompt before performing a change on the device. Individual network modules such as :ref:`cisco.ios.ios_command <ansible_collections.cisco.ios.ios_command_module>` and :ref:`cisco.nxos.nxos_command <ansible_collections.cisco.nxos.nxos_command_module>` can handle this with a ``prompt`` parameter. + +.. note:: + + ``prompt`` is a Python regex. If you add special characters such as ``?`` in the ``prompt`` value, the prompt won't match and you will get a timeout. To avoid this, ensure that the ``prompt`` value is a Python regex that matches the actual device prompt. Any special characters must be handled correctly in the ``prompt`` regex. + +You can also use the :ref:`ansible.netcommon.cli_command <ansible_collections.ansible.netcommon.cli_command_module>` to handle multiple prompts. + +.. code-block:: yaml + + --- + - name: multiple prompt, multiple answer (mandatory check for all prompts) + ansible.netcommon.cli_command: + command: "copy sftp sftp://user@host//user/test.img" + check_all: True + prompt: + - "Confirm download operation" + - "Password" + - "Do you want to change that to the standby image" + answer: + - 'y' + - <password> + - 'y' + +You must list the prompt and the answers in the same order (that is, prompt[0] is answered by answer[0]). + +In the above example, ``check_all: True`` ensures that the task gives the matching answer to each prompt. Without that setting, a task with multiple prompts would give the first answer to every prompt. + +In the following example, the second answer would be ignored and ``y`` would be the answer given to both prompts. That is, this task only works because both answers are identical. Also notice again that ``prompt`` must be a Python regex, which is why the ``?`` is escaped in the first prompt. + +.. code-block:: yaml + + --- + - name: reboot ios device + ansible.netcommon.cli_command: + command: reload + prompt: + - Save\? + - confirm + answer: + - y + - y + +.. seealso:: + + `Rebooting network devices with Ansible <https://www.ansible.com/blog/rebooting-network-devices-with-ansible>`_ + Examples using ``wait_for``, ``wait_for_connection``, and ``prompt`` for network devices. + + `Deep dive on cli_command <https://www.ansible.com/blog/deep-dive-on-cli-command-for-network-automation>`_ + Detailed overview of how to use the ``cli_command``. diff --git a/docs/docsite/rst/network/user_guide/platform_ce.rst b/docs/docsite/rst/network/user_guide/platform_ce.rst new file mode 100644 index 0000000..1949174 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_ce.rst @@ -0,0 +1,213 @@ +.. _ce_platform_options: + +*************************************** +CloudEngine OS Platform Options +*************************************** + +CloudEngine CE OS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== ========================= + .. CLI NETCONF + + + ==================== ========================================== ========================= + Protocol SSH XML over SSH + + Credentials uses SSH keys / SSH-agent if present uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password accepts ``-u myuser -k`` if using password + + Indirect Access via a bastion (jump host) via a bastion (jump host) + + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.netconf`` + + |enable_mode| not supported by ce OS not supported by ce OS + + Returned Data Format Refer to individual module documentation Refer to individual module documentation + ==================== ========================================== ========================= + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.netconf`` or ``ansible_connection=ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +==================== + +Example CLI inventory ``[ce:vars]`` +-------------------------------------- + +.. code-block:: yaml + + [ce:vars] + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=community.network.ce + ansible_user=myuser + ansible_password=!vault... + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve CE OS version + community.network.ce_command: + commands: display version + when: ansible_network_os == 'community.network.ce' + + +Using NETCONF in Ansible +======================== + +Enabling NETCONF +---------------- + +Before you can use NETCONF to connect to a switch, you must: + +- install the ``ncclient`` python package on your control node(s) with ``pip install ncclient`` +- enable NETCONF on the CloudEngine OS device(s) + +To enable NETCONF on a new switch using Ansible, use the ``community.network.ce_config`` module with the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this: + +.. code-block:: yaml + + - name: Enable NETCONF + connection: ansible.netcommon.network_cli + community.network.ce_config: + lines: + - snetconf server enable + when: ansible_network_os == 'community.network.ce' + +Once NETCONF is enabled, change your variables to use the NETCONF connection. + +Example NETCONF inventory ``[ce:vars]`` +------------------------------------------ + +.. code-block:: yaml + + [ce:vars] + ansible_connection=ansible.netcommon.netconf + ansible_network_os=community.network.ce + ansible_user=myuser + ansible_password=!vault | + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +Example NETCONF task +-------------------- + +.. code-block:: yaml + + - name: Create a vlan, id is 50(ce) + community.network.ce_vlan: + vlan_id: 50 + name: WEB + when: ansible_network_os == 'community.network.ce' + + +Notes +======================== + +Modules that work with ``ansible.netcommon.network_cli`` +--------------------------------------------------------- + +.. code-block:: yaml + + community.network.ce_acl_interface + community.network.ce_command + community.network.ce_config + community.network.ce_evpn_bgp + community.network.ce_evpn_bgp_rr + community.network.ce_evpn_global + community.network.ce_facts + community.network.ce_mlag_interface + community.network.ce_mtu + community.network.ce_netstream_aging + community.network.ce_netstream_export + community.network.ce_netstream_global + community.network.ce_netstream_template + community.network.ce_ntp_auth + community.network.ce_rollback + community.network.ce_snmp_contact + community.network.ce_snmp_location + community.network.ce_snmp_traps + community.network.ce_startup + community.network.ce_stp + community.network.ce_vxlan_arp + community.network.ce_vxlan_gateway + community.network.ce_vxlan_global + + +Modules that work with ``ansible.netcommon.netconf`` +----------------------------------------------------- + +.. code-block:: yaml + + community.network.ce_aaa_server + community.network.ce_aaa_server_host + community.network.ce_acl + community.network.ce_acl_advance + community.network.ce_bfd_global + community.network.ce_bfd_session + community.network.ce_bfd_view + community.network.ce_bgp + community.network.ce_bgp_af + community.network.ce_bgp_neighbor + community.network.ce_bgp_neighbor_af + community.network.ce_dldp + community.network.ce_dldp_interface + community.network.ce_eth_trunk + community.network.ce_evpn_bd_vni + community.network.ce_file_copy + community.network.ce_info_center_debug + community.network.ce_info_center_global + community.network.ce_info_center_log + community.network.ce_info_center_trap + community.network.ce_interface + community.network.ce_interface_ospf + community.network.ce_ip_interface + community.network.ce_lacp + community.network.ce_link_status + community.network.ce_lldp + community.network.ce_lldp_interface + community.network.ce_mlag_config + community.network.ce_netconf + community.network.ce_ntp + community.network.ce_ospf + community.network.ce_ospf_vrf + community.network.ce_reboot + community.network.ce_sflow + community.network.ce_snmp_community + community.network.ce_snmp_target_host + community.network.ce_snmp_user + community.network.ce_static_route + community.network.ce_static_route_bfd + community.network.ce_switchport + community.network.ce_vlan + community.network.ce_vrf + community.network.ce_vrf_af + community.network.ce_vrf_interface + community.network.ce_vrrp + community.network.ce_vxlan_tunnel + community.network.ce_vxlan_vap + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_cnos.rst b/docs/docsite/rst/network/user_guide/platform_cnos.rst new file mode 100644 index 0000000..0044847 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_cnos.rst @@ -0,0 +1,78 @@ +.. _cnos_platform_options: + +*************************************** +CNOS Platform Options +*************************************** + +CNOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/cnos.yml`` +-------------------------------------------------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.cnos + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve CNOS OS version + community.network.cnos_command: + commands: show version + when: ansible_network_os == 'community.network.cnos' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_dellos10.rst b/docs/docsite/rst/network/user_guide/platform_dellos10.rst new file mode 100644 index 0000000..cdffdd5 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_dellos10.rst @@ -0,0 +1,80 @@ +.. _dellos10_platform_options: + +*************************************** +Dell OS10 Platform Options +*************************************** + +The `dellemc.os10 <https://galaxy.ansible.com/dellemc_networking/os10>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access through a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/dellos10.yml`` +--------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: dellemc.os10.os10 + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (dellos10) + dellemc.os10.os10_config: + backup: yes + register: backup_dellos10_location + when: ansible_network_os == 'dellemc.os10.os10' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_dellos6.rst b/docs/docsite/rst/network/user_guide/platform_dellos6.rst new file mode 100644 index 0000000..ae8083d --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_dellos6.rst @@ -0,0 +1,79 @@ +.. _dellos6_platform_options: + +*************************************** +Dell OS6 Platform Options +*************************************** + +The `dellemc.os6 <https://github.com/ansible-collections/dellemc.os6>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access through a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/dellos6.yml`` +-------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: dellemc.os6.os6 + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (dellos6) + dellemc.os6.os6_config: + backup: yes + register: backup_dellso6_location + when: ansible_network_os == 'dellemc.os6.os6' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_dellos9.rst b/docs/docsite/rst/network/user_guide/platform_dellos9.rst new file mode 100644 index 0000000..ac1f52f --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_dellos9.rst @@ -0,0 +1,79 @@ +.. _dellos9_platform_options: + +*************************************** +Dell OS9 Platform Options +*************************************** + +The `dellemc.os9 <https://github.com/ansible-collections/dellemc.os9>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access through a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/dellos9.yml`` +-------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: dellemc.os9.os9 + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (dellos9) + dellemc.os9.os9_config: + backup: yes + register: backup_dellos9_location + when: ansible_network_os == 'dellemc.os9.os9' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_enos.rst b/docs/docsite/rst/network/user_guide/platform_enos.rst new file mode 100644 index 0000000..3cf17c3 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_enos.rst @@ -0,0 +1,80 @@ +.. _enos_platform_options: + +*************************************** +ENOS Platform Options +*************************************** + +ENOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + ++---------------------------+-----------------------------------------------+ + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/enos.yml`` +-------------------------------------------------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.enos + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve ENOS OS version + community.network.enos_command: + commands: show version + when: ansible_network_os == 'community.network.enos' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_eos.rst b/docs/docsite/rst/network/user_guide/platform_eos.rst new file mode 100644 index 0000000..588118e --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_eos.rst @@ -0,0 +1,140 @@ +.. _eos_platform_options: + +*************************************** +EOS Platform Options +*************************************** + +The `Arista EOS <https://galaxy.ansible.com/arista/eos>`_ collection supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== =========================== + .. CLI eAPI + ==================== ========================================== =========================== + Protocol SSH HTTP(S) + + Credentials uses SSH keys / SSH-agent if present uses HTTPS certificates if + present + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) through a web proxy + + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi`` + + + |enable_mode| supported: |br| supported: |br| + + * use ``ansible_become: yes`` * ``httpapi`` + with ``ansible_become_method: enable`` uses ``ansible_become: yes`` + with ``ansible_become_method: enable`` + + Returned Data Format ``stdout[0].`` ``stdout[0].messages[0].`` + ==================== ========================================== =========================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi`` instead. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/eos.yml`` +---------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: arista.eos.eos + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (eos) + arista.eos.eos_config: + backup: yes + register: backup_eos_location + when: ansible_network_os == 'arista.eos.eos' + + + +Using eAPI in Ansible +===================== + +Enabling eAPI +------------- + +Before you can use eAPI to connect to a switch, you must enable eAPI. To enable eAPI on a new switch with Ansible, use the ``arista.eos.eos_eapi`` module through the CLI connection. Set up ``group_vars/eos.yml`` just like in the CLI example above, then run a playbook task like this: + +.. code-block:: yaml + + - name: Enable eAPI + arista.eos.eos_eapi: + enable_http: yes + enable_https: yes + become: true + become_method: enable + when: ansible_network_os == 'arista.eos.eos' + +You can find more options for enabling HTTP/HTTPS connections in the :ref:`arista.eos.eos_eapi <ansible_collections.arista.eos.eos_eapi_module>` module documentation. + +Once eAPI is enabled, change your ``group_vars/eos.yml`` to use the eAPI connection. + +Example eAPI ``group_vars/eos.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: arista.eos.eos + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + proxy_env: + http_proxy: http://proxy.example.com:8080 + +- If you are accessing your host directly (not through a web proxy) you can remove the ``proxy_env`` configuration. +- If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``. + + +Example eAPI task +----------------- + +.. code-block:: yaml + + - name: Backup current switch config (eos) + arista.eos.eos_config: + backup: yes + register: backup_eos_location + environment: "{{ proxy_env }}" + when: ansible_network_os == 'arista.eos.eos' + +In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module in the task. + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst b/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst new file mode 100644 index 0000000..8e8bef0 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst @@ -0,0 +1,73 @@ +.. _eic_eccli_platform_options: + +*************************************** +ERIC_ECCLI Platform Options +*************************************** + +Extreme ERIC_ECCLI is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. This page offers details on how to use ``ansible.netcommon.network_cli`` on ERIC_ECCLI in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| not supported by ERIC_ECCLI + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +ERIC_ECCLI does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/eric_eccli.yml`` +----------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.eric_eccli + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: run show version on remote devices (eric_eccli) + community.network.eric_eccli_command: + commands: show version + when: ansible_network_os == 'community.network.eric_eccli' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_exos.rst b/docs/docsite/rst/network/user_guide/platform_exos.rst new file mode 100644 index 0000000..2e74be5 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_exos.rst @@ -0,0 +1,108 @@ +.. _exos_platform_options: + +*************************************** +EXOS Platform Options +*************************************** + +Extreme EXOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ + + +.. table:: + :class: documentation-table + + ==================== ========================================== ========================= + .. CLI EXOS-API + ==================== ========================================== ========================= + Protocol SSH HTTP(S) + + Credentials uses SSH keys / SSH-agent if present uses HTTPS certificates if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) through a web proxy + + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi`` + + |enable_mode| not supported by EXOS not supported by EXOS + + Returned Data Format ``stdout[0].`` ``stdout[0].messages[0].`` + ==================== ========================================== ========================= + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +EXOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/exos.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.exos + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve EXOS OS version + community.network.exos_command: + commands: show version + when: ansible_network_os == 'community.network.exos' + + + +Using EXOS-API in Ansible +========================= + +Example EXOS-API ``group_vars/exos.yml`` +---------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: community.network.exos + ansible_user: myuser + ansible_password: !vault... + proxy_env: + http_proxy: http://proxy.example.com:8080 + +- If you are accessing your host directly (not through a web proxy) you can remove the ``proxy_env`` configuration. +- If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``. + + +Example EXOS-API task +--------------------- + +.. code-block:: yaml + + - name: Retrieve EXOS OS version + community.network.exos_command: + commands: show version + when: ansible_network_os == 'community.network.exos' + +In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module used in the task. + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_frr.rst b/docs/docsite/rst/network/user_guide/platform_frr.rst new file mode 100644 index 0000000..0261250 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_frr.rst @@ -0,0 +1,73 @@ +.. _frr_platform_options: + +*************************************** +FRR Platform Options +*************************************** + +The `FRR <https://galaxy.ansible.com/frr/frr>`_ collection supports the ``ansible.netcommon.network_cli`` connection. This section provides details on how to use this connection for Free Range Routing (FRR). + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| not supported + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/frr.yml`` +---------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: frr.frr.frr + ansible_user: frruser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + +- The ``ansible_user`` should be a part of the ``frrvty`` group and should have the default shell set to ``/bin/vtysh``. +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Gather FRR facts + frr.frr.frr_facts: + gather_subset: + - config + - hardware + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_icx.rst b/docs/docsite/rst/network/user_guide/platform_icx.rst new file mode 100644 index 0000000..ee87b76 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_icx.rst @@ -0,0 +1,77 @@ +.. _icx_platform_options: + +*************************************** +ICX Platform Options +*************************************** + +ICX is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` with + ``ansible_become_method: enable`` and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/icx.yml`` +---------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.icx + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (icx) + community.network.icx_config: + backup: yes + register: backup_icx_location + when: ansible_network_os == 'community.network.icx' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_index.rst b/docs/docsite/rst/network/user_guide/platform_index.rst new file mode 100644 index 0000000..f9a8bc5 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_index.rst @@ -0,0 +1,124 @@ +.. _platform_options: + +**************** +Platform Options +**************** + +Some Ansible Network platforms support multiple connection types, privilege escalation (``enable`` mode), or other options. The pages in this section offer standardized guides to understanding available options on each network platform. We welcome contributions from community-maintained platforms to this section. + +.. toctree:: + :maxdepth: 2 + :caption: Platform Options + + platform_ce + platform_cnos + platform_dellos6 + platform_dellos9 + platform_dellos10 + platform_enos + platform_eos + platform_eric_eccli + platform_exos + platform_frr + platform_icx + platform_ios + platform_iosxr + platform_ironware + platform_junos + platform_meraki + platform_netvisor + platform_nos + platform_nxos + platform_routeros + platform_slxos + platform_voss + platform_vyos + platform_weos4 + platform_netconf_enabled + +.. _settings_by_platform: + +Settings by Platform +================================ + +.. raw:: html + + <style> + /* Style for this single table. Add delimiters between header columns */ + table#network-platform-table thead tr th.head { + border-left-width: 1px; + border-left-color: rgb(225, 228, 229); + border-left-style: solid; + } + </style> + +.. table:: + :name: network-platform-table + + =============================== ================================ =========== ======= ======= =========== + .. ``ansible_connection:`` settings available + ----------------------------------------------------------------- ------------------------------------------ + Network OS ``ansible_network_os:`` network_cli netconf httpapi local + =============================== ================================ =========== ======= ======= =========== + `Arista EOS`_ `[†]`_ ``arista.eos.eos`` ✓ ✓ ✓ + `Ciena SAOS6`_ ``ciena.saos6.saos6`` ✓ ✓ + `Cisco ASA`_ `[†]`_ ``cisco.asa.asa`` ✓ ✓ + `Cisco IOS`_ `[†]`_ ``cisco.ios.ios`` ✓ ✓ + `Cisco IOS XR`_ `[†]`_ ``cisco.iosxr.iosxr`` ✓ ✓ + `Cisco NX-OS`_ `[†]`_ ``cisco.nxos.nxos`` ✓ ✓ ✓ + `Cloudengine OS`_ ``community.network.ce`` ✓ ✓ ✓ + `Dell OS6`_ ``dellemc.os6.os6`` ✓ ✓ + `Dell OS9`_ ``dellemc.os9.os9`` ✓ ✓ + `Dell OS10`_ ``dellemc.os10.os10`` ✓ ✓ + `Ericsson ECCLI`_ ``community.network.eric_eccli`` ✓ ✓ + `Extreme EXOS`_ ``community.network.exos`` ✓ ✓ + `Extreme IronWare`_ ``community.network.ironware`` ✓ ✓ + `Extreme NOS`_ ``community.network.nos`` ✓ + `Extreme SLX-OS`_ ``community.network.slxos`` ✓ + `Extreme VOSS`_ ``community.network.voss`` ✓ + `F5 BIG-IP`_ ✓ + `F5 BIG-IQ`_ ✓ + `Junos OS`_ `[†]`_ ``junipernetworks.junos.junos`` ✓ ✓ ✓ + `Lenovo CNOS`_ ``community.network.cnos`` ✓ ✓ + `Lenovo ENOS`_ ``community.network.enos`` ✓ ✓ + `Meraki`_ ✓ + `MikroTik RouterOS`_ ``community.network.routeros`` ✓ + `Nokia SR OS`_ ✓ + `Pluribus Netvisor`_ ``community.network.netvisor`` ✓ + `Ruckus ICX`_ ``community.network.icx`` ✓ + `VyOS`_ `[†]`_ ``vyos.vyos.vyos`` ✓ ✓ + `Westermo WeOS 4`_ ``community.network.weos4`` ✓ + OS that supports Netconf `[†]`_ ``<network-os>`` ✓ ✓ + =============================== ================================ =========== ======= ======= =========== + +.. _Arista EOS: https://galaxy.ansible.com/arista/eos +.. _Ciena SAOS6: https://galaxy.ansible.com/ciena/saos6 +.. _Cisco ASA: https://galaxy.ansible.com/cisco/asa +.. _Cisco IOS: https://galaxy.ansible.com/cisco/ios +.. _Cisco IOS XR: https://galaxy.ansible.com/cisco/iosxr +.. _Cisco NX-OS: https://galaxy.ansible.com/cisco/nxos +.. _Cloudengine OS: https://galaxy.ansible.com/community/network +.. _Dell OS6: https://github.com/ansible-collections/dellemc.os6 +.. _Dell OS9: https://github.com/ansible-collections/dellemc.os9 +.. _Dell OS10: https://galaxy.ansible.com/dellemc/os10 +.. _Ericsson ECCLI: https://galaxy.ansible.com/community/network +.. _Extreme EXOS: https://galaxy.ansible.com/community/network +.. _Extreme IronWare: https://galaxy.ansible.com/community/network +.. _Extreme NOS: https://galaxy.ansible.com/community/network +.. _Extreme SLX-OS: https://galaxy.ansible.com/community/network +.. _Extreme VOSS: https://galaxy.ansible.com/community/network +.. _F5 BIG-IP: https://galaxy.ansible.com/f5networks/f5_modules +.. _F5 BIG-IQ: https://galaxy.ansible.com/f5networks/f5_modules +.. _Junos OS: https://galaxy.ansible.com/junipernetworks/junos +.. _Lenovo CNOS: https://galaxy.ansible.com/community/network +.. _Lenovo ENOS: https://galaxy.ansible.com/community/network +.. _Meraki: https://galaxy.ansible.com/cisco/meraki +.. _MikroTik RouterOS: https://galaxy.ansible.com/community/network +.. _Nokia SR OS: https://galaxy.ansible.com/community/network +.. _Pluribus Netvisor: https://galaxy.ansible.com/community/network +.. _Ruckus ICX: https://galaxy.ansible.com/community/network +.. _VyOS: https://galaxy.ansible.com/vyos/vyos +.. _Westermo WeOS 4: https://galaxy.ansible.com/community/network +.. _`[†]`: + +**[†]** Maintained by Ansible Network Team diff --git a/docs/docsite/rst/network/user_guide/platform_ios.rst b/docs/docsite/rst/network/user_guide/platform_ios.rst new file mode 100644 index 0000000..c7bd9ab --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_ios.rst @@ -0,0 +1,79 @@ +.. _ios_platform_options: + +*************************************** +IOS Platform Options +*************************************** + +The `Cisco IOS <https://galaxy.ansible.com/cisco/ios>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IOS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` with + ``ansible_become_method: enable`` and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/ios.yml`` +---------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: cisco.ios.ios + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (ios) + cisco.ios.ios_config: + backup: yes + register: backup_ios_location + when: ansible_network_os == 'cisco.ios.ios' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_iosxr.rst b/docs/docsite/rst/network/user_guide/platform_iosxr.rst new file mode 100644 index 0000000..30e4995 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_iosxr.rst @@ -0,0 +1,130 @@ +.. _iosxr_platform_options: + +*************************************** +IOS-XR Platform Options +*************************************** + +The `Cisco IOS-XR collection <https://galaxy.ansible.com/cisco/iosxr>`_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== ========================= + .. CLI NETCONF + + only for modules ``iosxr_banner``, + ``iosxr_interface``, ``iosxr_logging``, + ``iosxr_system``, ``iosxr_user`` + ==================== ========================================== ========================= + Protocol SSH XML over SSH + + Credentials uses SSH keys / SSH-agent if present uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) by a bastion (jump host) + + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.netconf`` + + |enable_mode| not supported not supported + + Returned Data Format Refer to individual module documentation Refer to individual module documentation + ==================== ========================================== ========================= + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.netconf`` instead. + +Using CLI in Ansible +==================== + +Example CLI inventory ``[iosxr:vars]`` +-------------------------------------- + +.. code-block:: yaml + + [iosxr:vars] + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=cisco.iosxr.iosxr + ansible_user=myuser + ansible_password=!vault... + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve IOS-XR version + cisco.iosxr.iosxr_command: + commands: show version + when: ansible_network_os == 'cisco.iosxr.iosxr' + + +Using NETCONF in Ansible +======================== + +Enabling NETCONF +---------------- + +Before you can use NETCONF to connect to a switch, you must: + +- install the ``ncclient`` python package on your control node(s) with ``pip install ncclient`` +- enable NETCONF on the Cisco IOS-XR device(s) + +To enable NETCONF on a new switch via Ansible, use the ``cisco.iosxr.iosxr_netconf`` module through the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this: + +.. code-block:: yaml + + - name: Enable NETCONF + connection: ansible.netcommon.network_cli + cisco.iosxr.iosxr_netconf: + when: ansible_network_os == 'cisco.iosxr.iosxr' + +Once NETCONF is enabled, change your variables to use the NETCONF connection. + +Example NETCONF inventory ``[iosxr:vars]`` +------------------------------------------ + +.. code-block:: yaml + + [iosxr:vars] + ansible_connection=ansible.netcommon.netconf + ansible_network_os=cisco.iosxr.iosxr + ansible_user=myuser + ansible_password=!vault | + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +Example NETCONF task +-------------------- + +.. code-block:: yaml + + - name: Configure hostname and domain-name + cisco.iosxr.iosxr_system: + hostname: iosxr01 + domain_name: test.example.com + domain_search: + - ansible.com + - redhat.com + - cisco.com + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_ironware.rst b/docs/docsite/rst/network/user_guide/platform_ironware.rst new file mode 100644 index 0000000..dbb2c41 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_ironware.rst @@ -0,0 +1,80 @@ +.. _ironware_platform_options: + +*************************************** +IronWare Platform Options +*************************************** + +IronWare is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/mlx.yml`` +---------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.ironware + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (ironware) + community.network.ironware_config: + backup: yes + register: backup_ironware_location + when: ansible_network_os == 'community.network.ironware' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_junos.rst b/docs/docsite/rst/network/user_guide/platform_junos.rst new file mode 100644 index 0000000..08cf8fc --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_junos.rst @@ -0,0 +1,129 @@ +.. _junos_platform_options: + +*************************************** +Junos OS Platform Options +*************************************** + +The `Juniper Junos OS <https://galaxy.ansible.com/junipernetworks/junos>`_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== ========================= + .. CLI NETCONF + + ``junos_netconf`` & ``junos_command`` all modules except ``junos_netconf``, + modules only which enables NETCONF + ==================== ========================================== ========================= + Protocol SSH XML over SSH + + Credentials uses SSH keys / SSH-agent if present uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) by a bastion (jump host) + + Connection Settings ``ansible_connection: ``ansible_connection: + ``ansible.netcommon.network_cli`` ``ansible.netcommon.netconf`` + + |enable_mode| not supported by Junos OS not supported by Junos OS + + Returned Data Format ``stdout[0].`` * json: ``result[0]['software-information'][0]['host-name'][0]['data'] foo lo0`` + * text: ``result[1].interface-information[0].physical-interface[0].name[0].data foo lo0`` + * xml: ``result[1].rpc-reply.interface-information[0].physical-interface[0].name[0].data foo lo0`` + ==================== ========================================== ========================= + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.netconf`` instead. + +Using CLI in Ansible +==================== + +Example CLI inventory ``[junos:vars]`` +-------------------------------------- + +.. code-block:: yaml + + [junos:vars] + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=junipernetworks.junos.junos + ansible_user=myuser + ansible_password=!vault... + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve Junos OS version + junipernetworks.junos.junos_command: + commands: show version + when: ansible_network_os == 'junipernetworks.junos.junos' + + +Using NETCONF in Ansible +======================== + +Enabling NETCONF +---------------- + +Before you can use NETCONF to connect to a switch, you must: + +- install the ``ncclient`` python package on your control node(s) with ``pip install ncclient`` +- enable NETCONF on the Junos OS device(s) + +To enable NETCONF on a new switch through Ansible, use the ``junipernetworks.junos.junos_netconf`` module through the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this: + +.. code-block:: yaml + + - name: Enable NETCONF + connection: ansible.netcommon.network_cli + junipernetworks.junos.junos_netconf: + when: ansible_network_os == 'junipernetworks.junos.junos' + +Once NETCONF is enabled, change your variables to use the NETCONF connection. + +Example NETCONF inventory ``[junos:vars]`` +------------------------------------------ + +.. code-block:: yaml + + [junos:vars] + ansible_connection=ansible.netcommon.netconf + ansible_network_os=junipernetworks.junos.junos + ansible_user=myuser + ansible_password=!vault | + ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +Example NETCONF task +-------------------- + +.. code-block:: yaml + + - name: Backup current switch config (junos) + junipernetworks.junos.junos_config: + backup: yes + register: backup_junos_location + when: ansible_network_os == 'junipernetworks.junos.junos' + + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_meraki.rst b/docs/docsite/rst/network/user_guide/platform_meraki.rst new file mode 100644 index 0000000..e51ca5b --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_meraki.rst @@ -0,0 +1,44 @@ +.. _meraki_platform_options: + +*************************************** +Meraki Platform Options +*************************************** + +The `cisco.meraki <https://galaxy.ansible.com/cisco/meraki>`_ collection only supports the ``local`` connection type at this time. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. Dashboard API + ==================== ========================================== + Protocol HTTP(S) + + Credentials uses API key from Dashboard + + Connection Settings ``ansible_connection: localhost`` + + Returned Data Format ``data.`` + ==================== ========================================== + + +Example Meraki task +------------------- + +.. code-block:: yaml + + cisco.meraki.meraki_organization: + auth_key: abc12345 + org_name: YourOrg + state: present + delegate_to: localhost + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst b/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst new file mode 100644 index 0000000..e481ed6 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst @@ -0,0 +1,133 @@ +.. _netconf_enabled_platform_options: + +*************************************** +Netconf enabled Platform Options +*************************************** + +This page offers details on how the netconf connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ +.. table:: + :class: documentation-table + + ==================== ========================================== + .. NETCONF + + all modules except ``junos_netconf``, + which enables NETCONF + ==================== ========================================== + Protocol XML over SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access through a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.netconf`` + ==================== ========================================== + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.netconf`` instead. + +Using NETCONF in Ansible +======================== + +Enabling NETCONF +---------------- + +Before you can use NETCONF to connect to a switch, you must: + +- install the ``ncclient`` Python package on your control node(s) with ``pip install ncclient`` +- enable NETCONF on the Junos OS device(s) + +To enable NETCONF on a new switch through Ansible, use the platform specific module through the CLI connection or set it manually. +For example set up your platform-level variables just like in the CLI example above, then run a playbook task like this: + +.. code-block:: yaml + + - name: Enable NETCONF + connection: ansible.netcommon.network_cli + junipernetworks.junos.junos_netconf: + when: ansible_network_os == 'junipernetworks.junos.junos' + +Once NETCONF is enabled, change your variables to use the NETCONF connection. + +Example NETCONF inventory ``[junos:vars]`` +------------------------------------------ + +.. code-block:: yaml + + [junos:vars] + ansible_connection=ansible.netcommon.netconf + ansible_network_os=junipernetworks.junos.junos + ansible_user=myuser + ansible_password=!vault | + + +Example NETCONF task +-------------------- + +.. code-block:: yaml + + - name: Backup current switch config + junipernetworks.junos.netconf_config: + backup: yes + register: backup_junos_location + +Example NETCONF task with configurable variables +------------------------------------------------ + +.. code-block:: yaml + + - name: configure interface while providing different private key file path + junipernetworks.junos.netconf_config: + backup: yes + register: backup_junos_location + vars: + ansible_private_key_file: /home/admin/.ssh/newprivatekeyfile + +Note: For netconf connection plugin configurable variables see :ref:`ansible.netcommon.netconf <ansible_collections.ansible.netcommon.netconf_connection>`. + +Bastion/Jumphost configuration +------------------------------ +To use a jump host to connect to a NETCONF enabled device you must set the ``ANSIBLE_NETCONF_SSH_CONFIG`` environment variable. + +``ANSIBLE_NETCONF_SSH_CONFIG`` can be set to either: + - 1 or TRUE (to trigger the use of the default SSH config file ~/.ssh/config) + - The absolute path to a custom SSH config file. + +The SSH config file should look something like: + +.. code-block:: ini + + Host * + proxycommand ssh -o StrictHostKeyChecking=no -W %h:%p jumphost-username@jumphost.fqdn.com + StrictHostKeyChecking no + +Authentication for the jump host must use key based authentication. + +You can either specify the private key used in the SSH config file: + +.. code-block:: ini + + IdentityFile "/absolute/path/to/private-key.pem" + +Or you can use an ssh-agent. + +ansible_network_os auto-detection +--------------------------------- + +If ``ansible_network_os`` is not specified for a host, then Ansible will attempt to automatically detect what ``network_os`` plugin to use. + +``ansible_network_os`` auto-detection can also be triggered by using ``auto`` as the ``ansible_network_os``. (Note: Previously ``default`` was used instead of ``auto``). + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_netvisor.rst b/docs/docsite/rst/network/user_guide/platform_netvisor.rst new file mode 100644 index 0000000..648e9c1 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_netvisor.rst @@ -0,0 +1,78 @@ +.. _netvisor_platform_options: + +********************************** +Pluribus NETVISOR Platform Options +********************************** + +Pluribus NETVISOR Ansible is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on NETVISOR in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| not supported by NETVISOR + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +Pluribus NETVISOR does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/netvisor.yml`` +--------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.netcommon.netvisor + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Create access list + community.network.pn_access_list: + pn_name: "foo" + pn_scope: "local" + state: "present" + register: acc_list + when: ansible_network_os == 'community.network.netvisor' + + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_nos.rst b/docs/docsite/rst/network/user_guide/platform_nos.rst new file mode 100644 index 0000000..6bc244c --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_nos.rst @@ -0,0 +1,76 @@ +.. _nos_platform_options: + +*************************************** +NOS Platform Options +*************************************** + +Extreme NOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on NOS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: community.netcommon.network_cli`` + + |enable_mode| not supported by NOS + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +NOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/nos.yml`` +---------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.nos + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Get version information (nos) + community.network.nos_command: + commands: "show version" + register: show_ver + when: ansible_network_os == 'community.network.nos' + + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_nxos.rst b/docs/docsite/rst/network/user_guide/platform_nxos.rst new file mode 100644 index 0000000..3794cfc --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_nxos.rst @@ -0,0 +1,166 @@ +.. _nxos_platform_options: + +*************************************** +NXOS Platform Options +*************************************** + +The `Cisco NXOS <https://galaxy.ansible.com/cisco/nxos>`_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== ========================= + .. CLI NX-API + ==================== ========================================== ========================= + Protocol SSH HTTP(S) + + Credentials uses SSH keys / SSH-agent if present uses HTTPS certificates if + present + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) by a web proxy + + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi`` + + |enable_mode| supported: use ``ansible_become: yes`` not supported by NX-API + with ``ansible_become_method: enable`` + and ``ansible_become_password:`` + + Returned Data Format ``stdout[0].`` ``stdout[0].messages[0].`` + ==================== ========================================== ========================= + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) |br| supported as of 2.5.3 + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi`` instead. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/nxos.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: cisco.nxos.nxos + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (nxos) + cisco.nxos.nxos_config: + backup: yes + register: backup_nxos_location + when: ansible_network_os == 'cisco.nxos.nxos' + + + +Using NX-API in Ansible +======================= + +Enabling NX-API +--------------- + +Before you can use NX-API to connect to a switch, you must enable NX-API. To enable NX-API on a new switch through Ansible, use the ``nxos_nxapi`` module through the CLI connection. Set up group_vars/nxos.yml just like in the CLI example above, then run a playbook task like this: + +.. code-block:: yaml + + - name: Enable NX-API + cisco.nxos.nxos_nxapi: + enable_http: yes + enable_https: yes + when: ansible_network_os == 'cisco.nxos.nxos' + +To find out more about the options for enabling HTTP/HTTPS and local http see the :ref:`nxos_nxapi <nxos_nxapi_module>` module documentation. + +Once NX-API is enabled, change your ``group_vars/nxos.yml`` to use the NX-API connection. + +Example NX-API ``group_vars/nxos.yml`` +-------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: cisco.nxos.nxos + ansible_user: myuser + ansible_password: !vault... + proxy_env: + http_proxy: http://proxy.example.com:8080 + +- If you are accessing your host directly (not through a web proxy) you can remove the ``proxy_env`` configuration. +- If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``. + + +Example NX-API task +------------------- + +.. code-block:: yaml + + - name: Backup current switch config (nxos) + cisco.nxos.nxos_config: + backup: yes + register: backup_nxos_location + environment: "{{ proxy_env }}" + when: ansible_network_os == 'cisco.nxos.nxos' + +In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module used in the task. + +.. include:: shared_snippets/SSH_warning.txt + +Cisco Nexus platform support matrix +=================================== + +The following platforms and software versions have been certified by Cisco to work with this version of Ansible. + +.. table:: Platform / Software Minimum Requirements + :align: center + + =================== ===================== + Supported Platforms Minimum NX-OS Version + =================== ===================== + Cisco Nexus N3k 7.0(3)I2(5) and later + Cisco Nexus N9k 7.0(3)I2(5) and later + Cisco Nexus N5k 7.3(0)N1(1) and later + Cisco Nexus N6k 7.3(0)N1(1) and later + Cisco Nexus N7k 7.3(0)D1(1) and later + Cisco Nexus MDS 8.4(1) and later (Please see individual module documentation for compatibility) + =================== ===================== + +.. table:: Platform Models + :align: center + + ======== ============================================== + Platform Description + ======== ============================================== + N3k Support includes N30xx, N31xx and N35xx models + N5k Support includes all N5xxx models + N6k Support includes all N6xxx models + N7k Support includes all N7xxx models + N9k Support includes all N9xxx models + MDS Support includes all MDS 9xxx models + ======== ============================================== + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_routeros.rst b/docs/docsite/rst/network/user_guide/platform_routeros.rst new file mode 100644 index 0000000..ff404e6 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_routeros.rst @@ -0,0 +1,80 @@ +.. _routeros_platform_options: + +*************************************** +RouterOS Platform Options +*************************************** + +RouterOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on RouterOS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.network.network_cli`` + + |enable_mode| not supported by RouterOS + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/routeros.yml`` +--------------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.routeros + ansible_user: myuser + ansible_password: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. +- If you are getting timeout errors you may want to add ``+cet1024w`` suffix to your username which will disable console colors, enable "dumb" mode, tell RouterOS not to try detecting terminal capabilities and set terminal width to 1024 columns. See article `Console login process <https://wiki.mikrotik.com/wiki/Manual:Console_login_process>`_ in MikroTik wiki for more information. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Display resource statistics (routeros) + community.network.routeros_command: + commands: /system resource print + register: routeros_resources + when: ansible_network_os == 'community.network.routeros' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_slxos.rst b/docs/docsite/rst/network/user_guide/platform_slxos.rst new file mode 100644 index 0000000..4c41451 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_slxos.rst @@ -0,0 +1,77 @@ +.. _slxos_platform_options: + +*************************************** +SLX-OS Platform Options +*************************************** + +Extreme SLX-OS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on SLX-OS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| not supported by SLX-OS + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +SLX-OS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/slxos.yml`` +------------------------------------ + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.slxos + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Backup current switch config (slxos) + community.network.slxos_config: + backup: yes + register: backup_slxos_location + when: ansible_network_os == 'community.network.slxos' + + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_voss.rst b/docs/docsite/rst/network/user_guide/platform_voss.rst new file mode 100644 index 0000000..172a053 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_voss.rst @@ -0,0 +1,78 @@ +.. _voss_platform_options: + +*************************************** +VOSS Platform Options +*************************************** + +Extreme VOSS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. This page offers details on how to +use ``ansible.netcommon.network_cli`` on VOSS in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| supported: use ``ansible_become: yes`` + with ``ansible_become_method: enable`` + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +VOSS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/voss.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.voss + ansible_user: myuser + ansible_become: yes + ansible_become_method: enable + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve VOSS info + community.network.voss_command: + commands: show sys-info + when: ansible_network_os == 'community.network.voss' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_vyos.rst b/docs/docsite/rst/network/user_guide/platform_vyos.rst new file mode 100644 index 0000000..f101fe7 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_vyos.rst @@ -0,0 +1,74 @@ +.. _vyos_platform_options: + +*************************************** +VyOS Platform Options +*************************************** + +The `VyOS <https://galaxy.ansible.com/vyos/vyos>`_ collection supports the ``ansible.netcommon.network_cli`` connection type. This page offers details on connection options to manage VyOS using Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| not supported + + Returned Data Format Refer to individual module documentation + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/vyos.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve VyOS version info + vyos.vyos.vyos_command: + commands: show version + when: ansible_network_os == 'vyos.vyos.vyos' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/platform_weos4.rst b/docs/docsite/rst/network/user_guide/platform_weos4.rst new file mode 100644 index 0000000..dd5dc83 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_weos4.rst @@ -0,0 +1,88 @@ +.. _weos4_platform_options: + +*************************************** +WeOS 4 Platform Options +*************************************** + +Westermo WeOS 4 is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections. +This page offers details on how to use ``ansible.netcommon.network_cli`` on WeOS 4 in Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: community.netcommon.network_cli`` + + |enable_mode| not supported by WeOS 4 + + Returned Data Format ``stdout[0].`` + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + +WeOS 4 does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/weos4.yml`` +------------------------------------ + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.weos4 + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Get version information (WeOS 4) + ansible.netcommon.cli_command: + commands: "show version" + register: show_ver + when: ansible_network_os == 'community.network.weos4' + +Example Configuration task +-------------------------- + +.. code-block:: yaml + + - name: Replace configuration with file on ansible host (WeOS 4) + ansible.netcommon.cli_config: + config: "{{ lookup('file', 'westermo.conf') }}" + replace: "yes" + diff_match: exact + diff_replace: config + when: ansible_network_os == 'community.network.weos4' + +.. include:: shared_snippets/SSH_warning.txt + +.. seealso:: + + :ref:`timeout_options` diff --git a/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.txt b/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.txt new file mode 100644 index 0000000..27424f5 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.txt @@ -0,0 +1,2 @@ +.. warning:: + Never store passwords in plain text. We recommend using SSH keys to authenticate SSH connections. Ansible supports ssh-agent to manage your SSH keys. If you must use passwords to authenticate SSH connections, we recommend encrypting them with :ref:`Ansible Vault <playbooks_vault>`. diff --git a/docs/docsite/rst/network/user_guide/validate.rst b/docs/docsite/rst/network/user_guide/validate.rst new file mode 100644 index 0000000..aeda1b2 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/validate.rst @@ -0,0 +1,164 @@ +.. _validate_data: + +************************************************* +Validate data against set criteria with Ansible +************************************************* + +The :ref:`validate <ansible_collections.ansible.utils.validate_module>` module validates data against your predefined criteria using a validation engine. You can pull this data from a device or file, validate it against your defined criteria, and use the results to identify configuration or operational state drift and optionally take remedial action. + + +.. contents:: + :local: + +Understanding the validate plugin +================================== + +The `ansible.utils <https://galaxy.ansible.com/ansible/utils>`_ collection includes the :ref:`validate <ansible_collections.ansible.utils.validate_module>` module. + +To validate data: + +#. Pull in structured data or convert your data to structured format with the :ref:`cli_parse <ansible_collections.ansible.utils.cli_parse_module>` module. +#. Define the criteria to test that data against. +#. Select a validation engine and test the data to see if it is valid based on the selected criteria and validation engine. + +The structure of the data and the criteria depends on the validation engine you select. The examples here use the ``jsonschema`` validation engine provided in the `ansible.utils <https://galaxy.ansible.com/ansible/utils>`_ collection.Red Hat Ansible Automation Platform subscription supports limited use if jsonschema public APIs as documented. + +Structuring the data +===================== + +You can pull previously structured data from a file, or use the :ref:`cli_parse <ansible_collections.ansible.utils.cli_parse_module>` module to structure your data. + +The following example fetches the operational state of some network (Cisco NXOS) interfaces and translates that state to structured data using the ``ansible.netcommon.pyats`` parser. + +.. code-block:: yaml + + --- + - hosts: nxos + connection: ansible.netcommon.network_cli + gather_facts: false + vars: + ansible_network_os: cisco.nxos.nxos + ansible_user: "changeme" + ansible_password: "changeme" + + tasks: + - name: "Fetch interface state and parse with pyats" + ansible.utils.cli_parse: + command: show interface + parser: + name: ansible.netcommon.pyats + register: nxos_pyats_show_interface + + - name: print structured interface state data + ansible.builtin.debug: + msg: "{{ nxos_pyats_show_interface['parsed'] }}" + ---- + +This results in the following structured data. + +.. code-block:: text + + ok: [nxos] => { + "changed": false, + "parsed": { + "Ethernet2/1": { + "admin_state": "down", + "auto_mdix": "off", + "auto_negotiate": false, + "bandwidth": 1000000, + "beacon": "off" + <--output omitted--> + }, + "Ethernet2/10": { + "admin_state": "down", + "auto_mdix": "off", + "auto_negotiate": false, + "bandwidth": 1000000, + "beacon": "off", + <--output omitted--> + } + } + } + +See :ref:`cli_parsing` for details on how to parse semi-structured data into structured data. + +Defining the criteria to validate against +========================================= + +This example uses the `jsonschema <https://pypi.org/project/jsonschema/>`_ validation engine to parse the JSON structured data we created in the prior section. the criteria defines the state we want the data to conform to. In this instance, we can validate against a desired admin state of ``up`` for all the interfaces. + +The criteria for ``jsonschema`` in this example is as follows: + +.. code-block:: text + + $cat criteria/nxos_show_interface_admin_criteria.json + { + "type" : "object", + "patternProperties": { + "^.*": { + "type": "object", + "properties": { + "admin_state": { + "type": "string", + "pattern": "up" + } + } + } + } + } + +Validating the data +==================== + +Now that we have the structured data and the criteria, we can validate this data with the :ref:`validate <ansible_collections.ansible.utils.validate_module>` module. + +The following tasks check if the current state of the interfaces match the desired state defined in the criteria file. + +.. code-block:: yaml + + - name: Validate interface admin state + ansible.utils.validate: + data: "{{ nxos_pyats_show_interface['parsed'] }}" + criteria: + - "{{ lookup('file', './criteria/nxos_show_interface_admin_criteria.json') | from_json }}" + engine: ansible.utils.jsonschema + ignore_errors: true + register: result + + - name: Print the interface names that do not satisfy the desired state + ansible.builtin.debug: + msg: "{{ item['data_path'].split('.')[0] }}" + loop: "{{ result['errors'] }}" + when: "'errors' in result" + + +In these tasks, we have: + +#. Set ``data`` to the structured JSON data from the :ref:`cli_parse <ansible_collections.ansible.utils.cli_parse_module>` module. +#. Set ``criteria`` to the JSON criteria file we defined. +#. Set the validate engine to ``jsonschema``. + +.. note:: + + The value of the criteria option can be a list and should be in a format that is defined by the validation engine used. You need to install the `jsonschema <https://pypi.org/project/jsonschema/>`_ on the control node for this example. + +The tasks output a list of errors indicating interfaces that do not have admin value in ``up`` state. + +.. code-block:: text + + TASK [Validate interface for admin state] *********************************************************************************************************** + fatal: [nxos02]: FAILED! => {"changed": false, "errors": [{"data_path": "Ethernet2/1.admin_state", "expected": "up", "found": "down", "json_path": "$.Ethernet2/1.admin_state", "message": "'down' does not match 'up'", "relative_schema": {"pattern": "up", "type": "string"}, "schema_path": "patternProperties.^.*.properties.admin_state.pattern", "validator": "pattern"}, {"data_path": "Ethernet2/10.admin_state", "expected": "up", "found": "down", "json_path": "$.Ethernet2/10.admin_state", "message": "'down' does not match 'up'", "relative_schema": {"pattern": "up", "type": "string"}, "schema_path": "patternProperties.^.*.properties.admin_state.pattern", "validator": "pattern"}], "msg": "Validation errors were found.\nAt 'patternProperties.^.*.properties.admin_state.pattern' 'down' does not match 'up'. \nAt 'patternProperties.^.*.properties.admin_state.pattern' 'down' does not match 'up'. \nAt 'patternProperties.^.*.properties.admin_state.pattern' 'down' does not match 'up'. "} + ...ignoring + + + TASK [Print the interface names that do not satisfy the desired state] **************************************************************************** + Monday 14 December 2020 11:05:38 +0530 (0:00:01.661) 0:00:28.676 ******* + ok: [nxos] => { + "msg": "Ethernet2/1" + } + ok: [nxos] => { + "msg": "Ethernet2/10" + } + + +This shows Ethernet2/1 and Ethernet2/10 are not in the desired state based on the defined criteria. You can create a report or take further action to remediate this to bring the interfaces to the desired state based on the defined criteria. |