Lines Matching refs:msgid
6 msgid ""
20 msgid "Developing network plugins"
24 msgid "You can extend the existing network modules with custom plugins in your collection."
28 msgid "Network connection plugins"
32 msgid "Each network connection plugin has a set of its own plugins which provide a specification of…
36 msgid "Public methods of these plugins may be called from a module or module_utils with the connect…
40 msgid "Developing httpapi plugins"
44 msgid ":ref:`httpapi plugins <httpapi_plugins>` serve as adapters for various HTTP(S) APIs for use …
48 msgid "Specifically, there are a few methods that the ``httpapi`` connection plugin expects to exis…
52 msgid "Making requests"
56 msgid "The ``httpapi`` connection plugin has a ``send()`` method, but an httpapi plugin needs a ``s…
60 msgid "Authenticating"
64 msgid "By default, all requests will authenticate with HTTP Basic authentication. If a request can …
68 msgid "If instead an explicit login endpoint needs to be requested to receive an authentication tok…
72 msgid "Similarly, ``logout(self)`` can be implemented to call an endpoint to invalidate and/or rele…
76 msgid "Error handling"
80 msgid "The ``handle_httperror(self, exception)`` method can deal with status codes returned by the …
84 msgid "A value of ``true`` means that the request can be retried. This my be used to indicate a tra…
88 msgid "A value of ``false`` means that the plugin is unable to recover from this response. The stat…
92 msgid "Any other value will be taken as a nonfatal response from the request. This may be useful if…
96 msgid "For example httpapi plugins, see the `source code for the httpapi plugins <https://github.co…
100 msgid "Developing NETCONF plugins"
104 msgid "The :ref:`netconf <netconf_connection>` connection plugin provides a connection to remote de…
108 msgid "The ``netconf`` connection plugin uses the ``ncclient`` Python library under the hood to ini…
112 msgid "To use the ``netconf`` connection plugin for network devices that support standard NETCONF (…
116 msgid "As a contributor and user, you should be able to use all the methods under the ``NetconfBase…
120 msgid "For Junos for example:"
124 msgid "See the vendor-specific Junos RPC methods implemented in ``plugins/netconf/junos.py``."
128 msgid "Set the value of ``ansible_network_os`` to the name of the netconf plugin file, that is ``ju…
132 msgid "Developing network_cli plugins"
136 msgid "The :ref:`network_cli <network_cli_connection>` connection type uses ``paramiko_ssh`` under …
140 msgid "Terminal plugin (for example ``plugins/terminal/ios.py``) - Controls the parameters related …
144 msgid ":ref:`cliconf_plugins` (for example, :ref:`ios cliconf <ios_cliconf>`) - Provides an abstrac…
148 msgid "To contribute a new network operating system to work with the ``network_cli`` connection, im…
152 msgid "The plugins can reside in:"
156 msgid "Adjacent to playbook in folders"
160 msgid "Roles"
165 msgid "Collections"
169 msgid "The user can also set the :ref:`DEFAULT_CLICONF_PLUGIN_PATH` to configure the ``cliconf`` p…
173 msgid "After adding the ``cliconf`` and ``terminal`` plugins in the expected locations, users can:"
177 msgid "Use the :ref:`cli_command <cli_command_module>` to run an arbitrary command on the network d…
181 msgid "Use the :ref:`cli_config <cli_config_module>` to implement configuration changes on the rem…
185 msgid "Developing cli_parser plugins in a collection"
189 msgid "You can use ``cli_parse`` as an entry point for a cli_parser plugin in your own collection."
193 msgid "The following sample shows the start of a custom cli_parser plugin:"
197 msgid "The following task uses this custom cli_parser plugin:"
201 msgid "To develop a custom plugin: - Each cli_parser plugin requires a ``CliParser`` class. - Each …
205 msgid ":ref:`cli_parsing`"
209 msgid "Developing network resource modules"
213 msgid "Understanding network and security resource modules"
217 msgid "Network and security devices separate configuration into sections (such as interfaces, VLANs…
221 msgid "Fetches a piece of the configuration (fact gathering), for example, the interfaces configura…
225 msgid "Converts the returned configuration into key-value pairs."
229 msgid "Places those key-value pairs into an internal agnostic structured data format."
233 msgid "Now that the configuration data is normalized, the user can update and modify the data and t…
237 msgid "The resource module has two top-level keys - ``config`` and ``state``:"
241 msgid "``config`` defines the resource configuration data model as key-value pairs. The type of th…
245 msgid "``state`` defines the action the resource module takes on the end device."
249 msgid "The ``state`` for a new resource module should support the following values (as applicable f…
254 msgid "merged"
259 msgid "Ansible merges the on-device configuration with the provided configuration in the task."
264 msgid "replaced"
269 msgid "Ansible replaces the on-device configuration subsection with the provided configuration subs…
274 msgid "overridden"
279 msgid "Ansible overrides the on-device configuration for the resource with the provided configurati…
284 msgid "deleted"
289 msgid "Ansible deletes the on-device configuration subsection and restores any default settings."
294 msgid "gathered"
299 msgid "Ansible displays the resource details gathered from the network device and accessed with the…
304 msgid "rendered"
309 msgid "Ansible renders the provided configuration in the task in the device-native format (for exam…
314 msgid "parsed"
319 msgid "Ansible parses the configuration from the ``running_configuration`` option into Ansible stru…
323 msgid "Modules in Ansible-maintained collections must support these state values. If you develop a …
327 msgid "The states ``rendered``, ``gathered``, and ``parsed`` do not perform any change on the devic…
331 msgid "`Deep Dive on VLANs Resource Modules for Network Automation <https://www.ansible.com/blog/de…
335 msgid "Walkthrough of how state values are implemented for VLANs."
339 msgid "Developing network and security resource modules"
343 msgid "The Ansible Engineering team ensures the module design and code pattern within Ansible-main…
347 msgid "The highlevel process for developing a resource module is:"
351 msgid "Create and share a resource model design in the `resource module models repository <https://…
355 msgid "Download the latest version of the `resource module builder <https://github.com/ansible-netw…
359 msgid "Run the ``resource module builder`` to create a collection scaffold from your approved resou…
363 msgid "Write the code to implement your resource module."
367 msgid "Develop integration and unit tests to verify your resource module."
371 msgid "Create a PR to the appropriate collection that you want to add your new resource module to. …
375 msgid "Understanding the model and resource module builder"
379 msgid "The resource module builder is an Ansible Playbook that helps developers scaffold and mainta…
383 msgid "The resource module builder has the following capabilities:"
387 msgid "Uses a defined model to scaffold a resource module directory layout and initial class files."
391 msgid "Scaffolds either an Ansible role or a collection."
395 msgid "Subsequent uses of the resource module builder will only replace the module arspec and file …
399 msgid "Allows you to store complex examples along side the model in the same directory."
403 msgid "Maintains the model as the source of truth for the module and use resource module builder to…
407 msgid "Generates working sample modules for both ``<network_os>_<resource>`` and ``<network_os>_fac…
411 msgid "Accessing the resource module builder"
415 msgid "To access the resource module builder:"
419 msgid "clone the github repository:"
423 msgid "Install the requirements:"
427 msgid "Creating a model"
431 msgid "You must create a model for your new resource. The model is the single source of truth for b…
435 msgid "The scaffold for a new module"
439 msgid "The argspec for the new module"
443 msgid "The docstring for the new module"
447 msgid "For any subsequent changes to the functionality, update the model first and use the resource…
451 msgid "For example, the resource model builder includes the ``myos_interfaces.yml`` sample in the :…
455 msgid "Notice that you should include examples for each of the states that the resource supports. T…
459 msgid "Share this model as a PR for review at `resource module models repository <https://github.co…
463 msgid "Creating a collection scaffold from a resource model"
467 msgid "To use the resource module builder to create a collection scaffold from your approved resour…
471 msgid "Where the parameters are as follows:"
475 msgid "``rm_dest``: The directory where the resource module builder places the files and directorie…
479 msgid "``structure``: The directory layout type (role or collection)"
483 msgid "``role``: Generate a role directory layout."
487 msgid "``collection``: Generate a collection directory layout."
491 msgid "``collection_org``: The organization of the collection, required when `structure=collection`…
495 msgid "``collection_name``: The name of the collection, required when `structure=collection`."
499 msgid "``model``: The path to the model file."
503 msgid "To use the resource module builder to create a role scaffold:"
507 msgid "Examples"
511 msgid "Collection directory layout"
515 msgid "This example shows the directory layout for the following:"
520 msgid "``network_os``: myos"
525 msgid "``resource``: interfaces"
529 msgid "Role directory layout"
533 msgid "This example displays the role directory layout for the following:"
537 msgid "Using the collection"
541 msgid "This example shows how to use the generated collection in a playbook:"
545 msgid "Using the role"
549 msgid "This example shows how to use the generated role in a playbook:"
553 msgid "Resource module structure and workflow"
557 msgid "The resource module structure includes the following components:"
561 msgid "Module"
565 msgid "``library/<ansible_network_os>_<resource>.py``."
569 msgid "Imports the ``module_utils`` resource package and calls ``execute_module`` API:"
573 msgid "Module argspec"
577 msgid "``module_utils/<ansible_network_os>/argspec/<resource>/``."
581 msgid "Argspec for the resource."
585 msgid "Facts"
589 msgid "``module_utils/<ansible_network_os>/facts/<resource>/``."
593 msgid "Populate facts for the resource."
597 msgid "Entry in ``module_utils/<ansible_network_os>/facts/facts.py`` for ``get_facts`` API to keep …
601 msgid "Entry of Resource subset in FACTS_RESOURCE_SUBSETS list in ``module_utils/<ansible_network_o…
605 msgid "Module package in module_utils"
609 msgid "``module_utils/<ansible_network_os>/<config>/<resource>/``."
613 msgid "Implement ``execute_module`` API that loads the configuration to device and generates the re…
617 msgid "Call ``get_facts`` API that returns the ``<resource>`` configuration facts or return the dif…
621 msgid "Compare facts gathered and given key-values if diff is not supported."
625 msgid "Generate final configuration."
629 msgid "Utils"
633 msgid "``module_utils/<ansible_network_os>/utils``."
637 msgid "Utilities for the ``<ansible_network_os>`` platform."
641 msgid "Running ``ansible-test sanity`` and ``tox`` on resource modules"
645 msgid "You should run ``ansible-test sanity`` and ``tox -elinters`` from the collection root direct…
649 msgid "To install the necessary packages:"
653 msgid "Ensure you have a valid Ansible development environment configured. See :ref:`environment_se…
657 msgid "Run ``pip install -r requirements.txt`` from the collection root directory."
661 msgid "Running ``tox -elinters``:"
665 msgid "Reads :file:`tox.ini` from the collection root directory and installs required dependencies …
669 msgid "Runs these with preconfigured options (such as line-length and ignores.)"
673 msgid "Runs ``black`` in check mode to show which files will be formatted without actually format…
677 msgid "Testing resource modules"
681 msgid "The tests rely on a role generated by the resource module builder. After changes to the reso…
685 msgid "Resource module integration tests"
689 msgid "High-level integration test requirements for new resource modules are as follows:"
693 msgid "Write a test case for every state."
697 msgid "Write additional test cases to test the behavior of the module when an empty ``config.yaml``…
701 msgid "Add a round trip test case. This involves a ``merge`` operation, followed by ``gather_facts`…
705 msgid "Wherever applicable, assertions should check after and before ``dicts`` against a hard coded…
709 msgid "We use Zuul as the CI to run the integration test."
713 msgid "To view the report, click :guilabel:`Details` on the CI comment in the PR"
717 msgid "To view a failure report, click :guilabel:`ansible/check` and select the failed test."
721 msgid "To view logs while the test is running, check for your PR number in the `Zull status board <…
725 msgid "To fix static test failure locally, run the :command:`tox -e black` **inside the root folde…
729 msgid "To view The Ansible run logs and debug test failures:"
733 msgid "Click the failed job to get the summary, and click :guilabel:`Logs` for the log."
737 msgid "Click :guilabel:`console` and scroll down to find the failed test."
741 msgid "Click :guilabel:`>` next to the failed test for complete details."
745 msgid "Integration test structure"
749 msgid "Each test case should generally follow this pattern:"
753 msgid "setup —> test —> assert —> test again (for idempotency) —> assert —> tear down (if needed) -…
757 msgid "Include a name for each task that is not an assertion. You can add names to assertions as we…
761 msgid "Files containing test cases must end in ``.yaml``"
765 msgid "Implementation"
769 msgid "For platforms that support ``connection: local`` *and* ``connection: network_cli`` use the …
773 msgid "Name the :file:`targets/` directories after the module name."
777 msgid "The :file:`main.yaml` file should just reference the transport."
781 msgid "The following example walks through the integration tests for the ``vyos.vyos.vyos_l3_interf…
785 msgid "``test/integration/targets/vyos_l3_interfaces/tasks/main.yaml``"
789 msgid "``test/integration/targets/vyos_l3_interfaces/tasks/cli.yaml``"
793 msgid "``test/integration/targets/vyos_l3_interfaces/tests/cli/overridden.yaml``"
797 msgid "Detecting test resources at runtime"
801 msgid "Your tests should detect resources (such as interfaces) at runtime rather than hard-coding t…
812 msgid "For example:"
816 msgid "See the complete test example of this at https://github.com/ansible-collections/cisco.nxos/b…
820 msgid "Running network integration tests"
824 msgid "Ansible uses Zuul to run an integration test suite on every PR, including new tests introduc…
828 msgid "First, create an inventory file that points to your test machines. The inventory group shoul…
832 msgid "To run these network integration tests, use ``ansible-test network-integration --inventory <…
836 msgid "To run all network tests for a particular platform:"
840 msgid "This example will run against all ``vyos`` modules. Note that ``vyos_.*`` is a regex match, …
844 msgid "To run integration tests for a specific module:"
848 msgid "To run a single test case on a specific module:"
852 msgid "To run integration tests for a specific transport:"
856 msgid "See `test/integration/targets/nxos_bgp/tasks/main.yaml <https://github.com/ansible-collectio…
860 msgid "For more options:"
864 msgid "If you need additional help or feedback, reach out in the ``#ansible-network`` IRC channel o…
868 msgid "Unit test requirements"
872 msgid "High-level unit test requirements that new resource modules should follow:"
876 msgid "Write test cases for all the states with all possible combinations of config values."
880 msgid "Write test cases to test the error conditions ( negative scenarios)."
884 msgid "Check the value of ``changed`` and ``commands`` keys in every test case."
888 msgid "We run all unit test cases on our Zuul test suite, on the latest python version supported by…
892 msgid "Use the :ref:`same procedure <using_zuul_resource_modules>` as the integration tests to view…
896 msgid "See :ref:`unit module testing <testing_units_modules>` for general unit test details."
900 msgid "Example: Unit testing Ansible network resource modules"
904 msgid "This section walks through an example of how to develop unit tests for Ansible resource modu…
908 msgid "See :ref:`testing_units` and :ref:`testing_units_modules` for general documentation on Ansib…
912 msgid "Using mock objects to unit test Ansible network resource modules"
916 msgid "`Mock objects <https://docs.python.org/3/library/unittest.mock.html>`_ can be very useful in…
920 msgid "You can mock the device connection and output from the device as follows:"
924 msgid "The facts file of the module now includes a new method, ``get_device_data``. Call ``get_devi…
928 msgid "Mocking device data"
932 msgid "To mock fetching results from devices or provide other complex data structures that come fro…
936 msgid "Load data using the ``load_fixture`` method and set this data as the return value of the ``g…
940 msgid "See the unit test file `test_eos_l2_interfaces <https://github.com/ansible-collections/arist…
944 msgid ":ref:`testing_units`"
948 msgid "Deep dive into developing unit tests for Ansible modules"
952 msgid ":ref:`testing_running_locally`"
956 msgid "Running tests locally including gathering and reporting coverage data"
960 msgid ":ref:`developing_modules_general`"
964 msgid "Get started developing a module"
968 msgid "Documenting new network platforms"
972 msgid "When you create network modules for a new platform, or modify the connections provided by an…
976 msgid "You should already have documented each module as described in :ref:`developing_modules_docu…
980 msgid "Modifying the platform options table"
984 msgid "The :ref:`settings_by_platform` table is a convenient summary of the connections options pro…
988 msgid "Ensure that the table stays formatted correctly. That is:"
992 msgid "Each row is inserted in alphabetical order."
996 msgid "The cell division ``|`` markers line up with the ``+`` markers."
1000 msgid "The check marks appear only for the connection types provided by the network modules."
1004 msgid "Adding a platform-specific options section"
1008 msgid "The platform- specific sections are individual ``.rst`` files that provide more detailed inf…
1012 msgid "Your platform-specific section should include the following:"
1016 msgid "**Connections available table** - a deeper dive into each connection type, including details…
1020 msgid "**How to use each connection type** - with working examples of each connection type."
1024 msgid "If your network platform supports SSH connections, also include the following at the bottom …
1028 msgid "Adding your new file to the table of contents"
1032 msgid "As a final step, add your new file in alphabetical order in the ``platform_index.rst`` file.…
1036 msgid "Network Developer Guide"
1040 msgid "Welcome to the Developer Guide for Ansible Network Automation!"
1046 msgid "**Who should use this guide?**"
1050 msgid "If you want to extend Ansible for Network Automation by creating a module or plugin, this gu…
1054 msgid "How to :ref:`add a custom plugin or module locally <developing_locally>`."
1058 msgid "How to figure out if :ref:`developing a module is the right approach <module_dev_should_you>…
1062 msgid "How to :ref:`set up my Python development environment <environment_setup>`."
1066 msgid "How to :ref:`get started writing a module <developing_modules_general>`."
1070 msgid "Find the network developer task that best describes what you want to do:"
1074 msgid "I want to :ref:`develop a network resource module <developing_resource_modules>`."
1078 msgid "I want to :ref:`develop a network connection plugin <developing_plugins_network>`."
1082 msgid "I want to :ref:`document my set of modules for a network platform <documenting_modules_netwo…
1086 msgid "If you prefer to read the entire guide, here's a list of the pages in order."
1090 msgid "Basic Concepts"
1094 msgid "These concepts are common to all uses of Ansible, including network automation. You need to …
1098 msgid "Control node"
1102 msgid "Any machine with Ansible installed. You can run Ansible commands and playbooks by invoking t…
1106 msgid "Managed nodes"
1110 msgid "The network devices (and/or servers) you manage with Ansible. Managed nodes are also sometim…
1114 msgid "Inventory"
1118 msgid "A list of managed nodes. An inventory file is also sometimes called a \"hostfile\". Your inv…
1122 msgid "Collections are a distribution format for Ansible content that can include playbooks, roles,…
1126 msgid "Modules"
1130 msgid "The units of code Ansible executes. Each module has a particular use, from administering use…
1134 msgid "Tasks"
1138 msgid "The units of action in Ansible. You can execute a single task once with an ad hoc command."
1142 msgid "Playbooks"
1146 msgid "Ordered lists of tasks, saved so you can run those tasks in that order repeatedly. Playbooks…
1150 msgid "Build Your Inventory"
1154 msgid "Running a playbook without an inventory requires several command-line flags. Also, running a…
1158 msgid "Basic inventory"
1162 msgid "First, group your inventory logically. Best practice is to group servers and network devices…
1166 msgid "**What**: db, web, leaf, spine"
1170 msgid "**Where**: east, west, floor_19, building_A"
1174 msgid "**When**: dev, test, staging, prod"
1178 msgid "Avoid spaces, hyphens, and preceding numbers (use ``floor_19``, not ``19th_floor``) in your …
1182 msgid "This tiny example data center illustrates a basic group structure. You can group groups usin…
1186 msgid "You can also create this same inventory in INI format."
1190 msgid "Add variables to the inventory"
1194 msgid "Next, you can set values for many of the variables you needed in your first Ansible command …
1198 msgid "Group variables within inventory"
1202 msgid "When devices in a group share the same variable values, such as OS or SSH user, you can redu…
1206 msgid "Variable syntax"
1210 msgid "The syntax for variable values is different in inventory, in playbooks, and in the ``group_v…
1214 msgid "In an ini-style inventory file you **must** use the syntax ``key=value`` for variable values…
1218 msgid "In any file with the ``.yml`` or ``.yaml`` extension, including playbooks and ``group_vars``…
1222 msgid "In ``group_vars`` files, use the full ``key`` name: ``ansible_network_os: vyos.vyos.vyos``."
1226 msgid "In playbooks, use the short-form ``key`` name, which drops the ``ansible`` prefix: ``network…
1230 msgid "Group inventory by platform"
1234 msgid "As your inventory grows, you may want to group devices by platform. This allows you to speci…
1238 msgid "With this setup, you can run ``first_playbook.yml`` with only two flags:"
1242 msgid "With the ``-k`` flag, you provide the SSH password(s) at the prompt. Alternatively, you can …
1246 msgid "Verifying the inventory"
1250 msgid "You can use the :ref:`ansible-inventory` CLI command to display the inventory as Ansible see…
1254 msgid "Protecting sensitive variables with ``ansible-vault``"
1258 msgid "The ``ansible-vault`` command provides encryption for files and/or individual variables like…
1262 msgid "First you must create a password for ansible-vault itself. It is used as the encryption key,…
1266 msgid "Create a file and write your password for ansible-vault to it:"
1270 msgid "Create the encrypted ssh password for your VyOS network devices, pulling your ansible-vault …
1274 msgid "If you prefer to type your ansible-vault password rather than store it in a file, you can re…
1278 msgid "and type in the vault password for ``my_user``."
1282 msgid "The :option:`--vault-id <ansible-playbook --vault-id>` flag allows different vault passwords…
1286 msgid "This is an example using an extract from a YAML inventory, as the INI format does not suppo…
1290 msgid "To use an inline vaulted variables with an INI inventory you need to store it in a 'vars' fi…
1294 msgid "To run a playbook with this setup, drop the ``-k`` flag and add a flag for your ``vault-id``…
1298 msgid "Or with a prompt instead of the vault password file:"
1302 msgid "To see the original value, you can use the debug module. Please note if your YAML file defin…
1306 msgid "Vault content can only be decrypted with the password that was used to encrypt it. If you wa…
1310 msgid "For more details on building inventory files, see :ref:`the introduction to inventory<intro_…
1314 msgid "Now that you understand the basics of commands, playbooks, and inventory, it's time to explo…
1318 msgid "Run Your First Command and Playbook"
1322 msgid "Put the concepts you learned to work with this quick tutorial. Install Ansible, execute a ne…
1327 msgid "Prerequisites"
1331 msgid "Before you work through this tutorial you need:"
1335 msgid "Ansible 2.10 (or higher) installed"
1339 msgid "One or more network devices that are compatible with Ansible"
1343 msgid "Basic Linux command line knowledge"
1347 msgid "Basic knowledge of network switch & router configuration"
1351 msgid "Install Ansible"
1355 msgid "Install Ansible using your preferred method. See :ref:`installation_guide`. Then return to t…
1359 msgid "Confirm the version of Ansible (must be >= 2.10):"
1363 msgid "Establish a manual connection to a managed node"
1367 msgid "To confirm your credentials, connect to a network device manually and retrieve its configura…
1371 msgid "This manual connection also establishes the authenticity of the network device, adding its R…
1375 msgid "Run your first network Ansible command"
1379 msgid "Instead of manually connecting and running a command on the network device, you can retrieve…
1383 msgid "The flags in this command set seven values:"
1387 msgid "the host group(s) to which the command should apply (in this case, all)"
1391 msgid "the inventory (-i, the device or devices to target - without the trailing comma -i points to…
1395 msgid "the connection method (-c, the method for connecting and executing ansible)"
1399 msgid "the user (-u, the username for the SSH connection)"
1403 msgid "the SSH connection method (-k, please prompt for the password)"
1407 msgid "the module (-m, the Ansible module to run, using the fully qualified collection name (FQCN))"
1411 msgid "an extra variable ( -e, in this case, setting the network OS value)"
1415 msgid "NOTE: If you use ``ssh-agent`` with ssh keys, Ansible loads them automatically. You can omit…
1419 msgid "If you are running Ansible in a virtual environment, you will also need to add the variable …
1423 msgid "Create and run your first network Ansible Playbook"
1427 msgid "If you want to run this command every day, you can save it in a playbook and run it with ``a…
1431 msgid "Download :download:`first_playbook.yml <sample_files/first_playbook.yml>`, which looks like …
1435 msgid "The playbook sets three of the seven values from the command line above: the group (``hosts:…
1439 msgid "Run the playbook with the command:"
1443 msgid "The playbook contains one play with two tasks, and should generate output like this:"
1447 msgid "Now that you can retrieve the device config, try updating it with Ansible. Download :downloa…
1451 msgid "The extended first playbook has four tasks in a single play. Run it with the same command yo…
1455 msgid "Gathering facts from network devices"
1459 msgid "The ``gather_facts`` keyword now supports gathering network device facts in standardized key…
1463 msgid "You can also use the new ``gather_network_resources`` parameter with the network ``*_facts``…
1467 msgid "The playbook returns the following interface facts:"
1471 msgid "Note that this returns a subset of what is returned by just setting ``gather_subset: interfa…
1475 msgid "You can store these facts and use them directly in another task, such as with the :ref:`eos_…
1479 msgid "Getting Started Guide"
1483 msgid "Network Getting Started"
1487 msgid "Ansible collections support a wide range of vendors, device types, and actions, so you can m…
1491 msgid "Automate repetitive tasks to speed routine network changes and free up your time for more st…
1495 msgid "Leverage the same simple, powerful, and agentless automation tool for network tasks that ope…
1499 msgid "Separate the data model (in a playbook or role) from the execution layer (via Ansible module…
1503 msgid "Benefit from community and vendor-generated sample playbooks and roles to help accelerate ne…
1507 msgid "Communicate securely with network hardware over SSH or HTTPS"
1511 msgid "This guide is intended for network engineers using Ansible for the first time. If you unders…
1515 msgid "This guide is also useful for experienced Ansible users automating network tasks for the fir…
1519 msgid "This guide introduces basic Ansible concepts and guides you through your first Ansible comma…
1523 msgid "Beyond the basics"
1527 msgid "This page introduces some concepts that help you manage your Ansible workflow with directory…
1531 msgid "A typical Ansible filetree"
1535 msgid "Ansible expects to find certain files in certain places. As you expand your inventory and cr…
1539 msgid "The ``backup`` directory and the files in it get created when you run modules like ``vyos_co…
1543 msgid "Tracking changes to inventory and playbooks: source control with git"
1547 msgid "As you expand your inventory, roles and playbooks, you should place your Ansible projects un…
1551 msgid "Working with network connection options"
1555 msgid "Network modules can support multiple connection protocols, such as ``ansible.netcommon.netwo…
1559 msgid "Common options are:"
1563 msgid "``become`` and ``become_method`` as described in :ref:`privilege_escalation`."
1567 msgid "``network_os`` - set to match your network platform you are communicating with. See the :ref…
1571 msgid "``remote_user`` as described in :ref:`connection_set_user`."
1575 msgid "Timeout options - ``persistent_command_timeout``, ``persistent_connect_timeout``, and ``time…
1579 msgid "Setting timeout options"
1583 msgid "When communicating with a remote device, you have control over how long Ansible maintains th…
1587 msgid "For example, the three options for controlling the connection timeout are as follows."
1591 msgid "Using vars (per task):"
1595 msgid "Using the environment variable:"
1599 msgid "Using the global configuration (in :file:`ansible.cfg`)"
1603 msgid "See :ref:`ansible_variable_precedence` for details on the relative precedence of each of the…
1607 msgid "How Network Automation is Different"
1611 msgid "Network automation leverages the basic Ansible concepts, but there are important differences…
1615 msgid "Execution on the control node"
1619 msgid "Unlike most Ansible modules, network modules do not run on the managed nodes. From a user's …
1623 msgid "Network modules also use the control node as a destination for backup files, for those modul…
1627 msgid "Multiple communication protocols"
1631 msgid "Because network modules execute on the control node instead of on the managed nodes, they ca…
1635 msgid "Value of ansible_connection"
1664 msgid "Protocol"
1668 msgid "Requires"
1672 msgid "Persistent?"
1676 msgid "ansible.netcommon.network_cli"
1680 msgid "CLI over SSH"
1684 msgid "network_os setting"
1688 msgid "yes"
1692 msgid "ansible.netcommon.netconf"
1700 msgid "XML over SSH"
1704 msgid "ansible.netcommon.httpapi"
1708 msgid "API over HTTP/HTTPS"
1713 msgid "local"
1717 msgid "depends on provider"
1721 msgid "provider setting"
1725 msgid "no"
1729 msgid "``ansible.netcommon.httpapi`` deprecates ``eos_eapi`` and ``nxos_nxapi``. See :ref:`httpapi_…
1733 msgid "The ``ansible_connection: local`` has been deprecated. Please use one of the persistent conn…
1737 msgid "Collections organized by network platform"
1741 msgid "A network platform is a set of network devices with a common operating system that can be ma…
1745 msgid "Arista: `arista.eos <https://galaxy.ansible.com/arista/eos>`_"
1749 msgid "Cisco: `cisco.ios <https://galaxy.ansible.com/cisco/ios>`_, `cisco.iosxr <https://galaxy.ans…
1753 msgid "Juniper: `junipernetworks.junos <https://galaxy.ansible.com/junipernetworks/junos>`_"
1757 msgid "VyOS `vyos.vyos <https://galaxy.ansible.com/vyos/vyos>`_"
1761 msgid "All modules within a network platform share certain requirements. Some network platforms hav…
1765 msgid "Privilege Escalation: ``enable`` mode, ``become``, and ``authorize``"
1769 msgid "Several network platforms support privilege escalation, where certain tasks must be done by …
1773 msgid "Using ``become`` for privilege escalation"
1777 msgid "Use the top-level Ansible parameter ``become: yes`` with ``become_method: enable`` to run a …
1781 msgid "For more information, see :ref:`Become and Networks<become_network>`"
1785 msgid "Resources and next steps"
1789 msgid "Documents"
1793 msgid "Read more about Ansible for Network Automation:"
1797 msgid "Network Automation on the `Ansible website <https://www.ansible.com/overview/networking>`_"
1801 msgid "Ansible Network `Blog posts <https://www.ansible.com/blog/topic/networks>`_"
1805 msgid "Events (on video and in person)"
1809 msgid "All sessions at Ansible events are recorded and include many Network-related topics (use Fil…
1813 msgid "`Recorded AnsibleFests <https://www.ansible.com/resources/videos/ansiblefest>`_"
1817 msgid "`Recorded AnsibleAutomates <https://www.ansible.com/resources/webinars-training>`_"
1821 msgid "`Upcoming Ansible Events <https://www.ansible.com/community/events>`_ page."
1825 msgid "GitHub repos"
1829 msgid "Ansible hosts module code, examples, demonstrations, and other content on GitHub. Anyone wit…
1833 msgid "`Network-Automation <https://github.com/network-automation>`_ is an open community for all t…
1837 msgid "`Ansible collections <https://github.com/ansible-collections>`_ is the main repository for A…
1841 msgid "IRC and Slack"
1845 msgid "Join us on:"
1849 msgid "IRC Channel - ``#ansible-network`` on `irc.libera.chat <https://libera.chat/>`_"
1853 msgid "Slack - `<https://ansiblenetwork.slack.com>`_"
1857 msgid "Use Ansible network roles"
1861 msgid "Roles are sets of Ansible defaults, files, tasks, templates, variables, and other Ansible co…
1865 msgid "Understanding roles"
1869 msgid "So what exactly is a role, and why should you care? Ansible roles are basically playbooks br…
1873 msgid "To simplify your workflow even further, the Ansible Network team has written a series of rol…
1877 msgid "A sample DNS playbook"
1881 msgid "To demonstrate the concept of what a role is, the example ``playbook.yml`` below is a single…
1885 msgid "If you run this playbook using the ``ansible-playbook`` command, you'll see the output below…
1889 msgid "This playbook configured the hostname and DNS servers. You can verify that configuration on…
1893 msgid "Convert the playbook into a role"
1897 msgid "The next step is to convert this playbook into a reusable role. You can create the directory…
1901 msgid "This first demonstration uses only the **tasks** and **vars** directories. The directory st…
1905 msgid "Next, move the content of the ``vars`` and ``tasks`` sections from the original Ansible Play…
1909 msgid "Next, move the variables into the ``vars/main.yml`` file:"
1913 msgid "Finally, modify the original Ansible Playbook to remove the ``tasks`` and ``vars`` sections …
1917 msgid "To summarize, this demonstration now has a total of three directories and three YAML files. …
1921 msgid "Running the playbook results in identical behavior with slightly different output:"
1925 msgid "As seen above each task is now prepended with the role name, in this case ``system-demo``. …
1929 msgid "As before, the playbook will generate the following configuration on a Cisco IOS-XE router:"
1933 msgid "This is why Ansible roles can be simply thought of as deconstructed playbooks. They are simp…
1937 msgid "Variable precedence"
1941 msgid "What if you want to change the DNS servers? You aren't expected to change the ``vars/main.y…
1945 msgid "Lowest precedence"
1949 msgid "The lowest precedence is the ``defaults`` directory within a role. This means all the other…
1953 msgid "Add a new ``vars`` section to the playbook to override the default behavior (where the varia…
1957 msgid "Run this updated playbook on **rtr2**:"
1961 msgid "The configuration on the **rtr2** Cisco router will look as follows:"
1965 msgid "The variable configured in the playbook now has precedence over the ``defaults`` directory. …
1969 msgid "Highest precedence"
1973 msgid "Specifying variables in the ``defaults`` directory within a role will always take the lowest…
1977 msgid "The result on the Cisco IOS XE router will only contain the highest precedence setting of 19…
1981 msgid "How is this useful? Why should you care? Extra vars are commonly used by network operators…
1985 msgid "Update an installed role"
1989 msgid "The Ansible Galaxy page for a role lists all available versions. To update a locally install…
1993 msgid "`Ansible Galaxy documentation <https://galaxy.ansible.com/docs/>`_"
1997 msgid "Ansible Galaxy user guide"
2001 msgid "Ansible for Network Automation"
2005 msgid "Ansible Network modules extend the benefits of simple, powerful, agentless automation to net…
2009 msgid "If you're new to Ansible, or new to using Ansible for network management, start with :ref:`n…
2013 msgid "For documentation on using a particular network module, consult the :ref:`list of all networ…
2017 msgid "Parsing semi-structured text with Ansible"
2021 msgid "The :ref:`cli_parse <ansible_collections.ansible.netcommon.cli_parse_module>` module parses …
2025 msgid "Understanding the CLI parser"
2029 msgid "The `ansible.netcommon <https://galaxy.ansible.com/ansible/netcommon>`_ collection version 1…
2033 msgid "Why parse the text?"
2037 msgid "Parsing semi-structured data such as network configurations into structured data allows prog…
2041 msgid "The ``when`` clause to conditionally run other tasks or roles"
2045 msgid "The ``assert`` module to check configuration and operational state compliance"
2049 msgid "The ``template`` module to generate reports about configuration and operational state inform…
2053 msgid "Templates and ``command`` or ``config`` modules to generate host, device, or platform comman…
2057 msgid "The current platform ``facts`` modules to supplement native facts information"
2061 msgid "By parsing semi-structured text into Ansible native data structures, you can take full advan…
2065 msgid "When not to parse the text"
2069 msgid "You should not parse semi-structured text when:"
2073 msgid "The device, host, or platform has a RESTAPI and returns JSON."
2077 msgid "Existing Ansible facts modules already return the desired data."
2081 msgid "Ansible network resource modules exist for configuration management of the device and resour…
2085 msgid "Parsing the CLI"
2089 msgid "The ``cli_parse`` module includes the following cli_parsing plugins:"
2093 msgid "``native``"
2097 msgid "The native parsing engine built into Ansible and requires no addition python libraries"
2101 msgid "``xml``"
2105 msgid "Convert XML to an Ansible native data structure"
2109 msgid "``textfsm``"
2113 msgid "A python module which implements a template based state machine for parsing semi-formatted t…
2117 msgid "``ntc_templates``"
2121 msgid "Predefined ``textfsm`` templates packages supporting a variety of platforms and commands"
2125 msgid "``ttp``"
2129 msgid "A library for semi-structured text parsing using templates, with added capabilities to simpl…
2133 msgid "``pyats``"
2137 msgid "Uses the parsers included with the Cisco Test Automation & Validation Solution"
2141 msgid "``jc``"
2145 msgid "A python module that converts the output of dozens of popular Linux/UNIX/macOS/Windows comma…
2149 msgid "``json``"
2153 msgid "Converts JSON output at the CLI to an Ansible native data structure"
2158 msgid "Although Ansible contains a number of plugins that can convert XML to Ansible native data st…
2162 msgid "Because ``cli_parse`` uses a plugin based architecture, it can use additional parsing engine…
2166 msgid "The ``ansible.netcommon.native`` and ``ansible.netcommon.json`` parsing engines are fully s…
2170 msgid "Parsing with the native parsing engine"
2174 msgid "The native parsing engine is included with the ``cli_parse`` module. It uses data captured u…
2178 msgid "Networking example"
2182 msgid "This example uses the output of a network device command and applies a native template to pr…
2186 msgid "The ``show interface`` command output from the network device looks as follows:"
2190 msgid "Create the native template to match this output and store it as ``templates/nxos_show_interf…
2194 msgid "This native parser template is structured as a list of parsers, each containing the followin…
2198 msgid "``example`` - An example line of the text line to be parsed"
2202 msgid "``getval`` - A regular expression using named capture groups to store the extracted data"
2206 msgid "``result`` - A data tree, populated as a template, from the parsed data"
2210 msgid "``shared`` - (optional) The shared key makes the parsed values available to the rest of the …
2214 msgid "The following example task uses ``cli_parse`` with the native parser and the example templat…
2222 msgid "Taking a deeper dive into this task:"
2226 msgid "The ``command`` option provides the command you want to run on the device or host. Alternate…
2230 msgid "The ``parser`` option provides information specific to the parser engine."
2234 msgid "The ``name`` suboption provides the fully qualified collection name (FQCN) of the parsing en…
2238 msgid "The ``cli_parse`` module, by default, looks for the template in the templates directory as `…
2242 msgid "The ``short_os`` in the template filename is derived from either the host ``ansible_network_…
2246 msgid "Spaces in the network or host command are replace with ``_`` in the ``command`` portion of t…
2250 msgid "``ansible.netcommon.native`` parsing engine is fully supported with a Red Hat Ansible Automa…
2254 msgid "Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` fact for the …
2258 msgid "Linux example"
2262 msgid "You can also use the native parser to run commands and parse output from Linux hosts."
2266 msgid "The output of a sample Linux command (``ip addr show``) looks as follows:"
2270 msgid "Create the native template to match this output and store it as ``templates/fedora_ip_addr_s…
2274 msgid "The ``shared`` key in the parser template allows the interface name to be used in subsequent…
2278 msgid "The following example task uses ``cli_parse`` with the native parser and the example templat…
2282 msgid "This task assumes you previously gathered facts to determine the ``ansible_distribution`` ne…
2286 msgid "Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` fact for the …
2290 msgid "Parsing JSON"
2294 msgid "Although Ansible will natively convert serialized JSON to Ansible native data when recognize…
2300 msgid "Example task:"
2304 msgid "The ``show interface | json`` command is issued on the device."
2308 msgid "The output is set as the ``interfaces`` fact for the device."
2312 msgid "JSON support is provided primarily for playbook consistency."
2316 msgid "The use of ``ansible.netcommon.json`` is fully supported with a Red Hat Ansible Automation P…
2320 msgid "Parsing with ntc_templates"
2324 msgid "The ``ntc_templates`` python library includes pre-defined ``textfsm`` templates for parsing …
2328 msgid "The ``ansible_network_os`` of the device is converted to the ntc_template format ``cisco_nxo…
2332 msgid "The ``cisco_nxos_show_interface.textfsm`` template, included with the ``ntc_templates`` pack…
2336 msgid "See `the ntc_templates README <https://github.com/networktocode/ntc-templates/blob/master/RE…
2340 msgid "Red Hat Ansible Automation Platform subscription support is limited to the use of the ``ntc_…
2344 msgid "This task and and the predefined template sets the following fact as the ``interfaces`` fact…
2348 msgid "Parsing with pyATS"
2352 msgid "``pyATS`` is part of the Cisco Test Automation & Validation Solution. It includes many prede…
2356 msgid "The ``cli_parse`` modules converts the ``ansible_network_os`` automatically (in this example…
2361 msgid "Using a combination of the command and OS, the pyATS selects the following parser: https://p…
2365 msgid "The ``cli_parse`` module sets ``cisco.ios.ios`` to ``iosxe`` for pyATS. You can override thi…
2369 msgid "``cli_parse`` only uses the predefined parsers in pyATS. See the `pyATS documentation <https…
2373 msgid "Red Hat Ansible Automation Platform subscription support is limited to the use of the pyATS …
2378 msgid "This task sets the following fact as the ``interfaces`` fact for the host:"
2382 msgid "Parsing with textfsm"
2386 msgid "``textfsm`` is a Python module which implements a template-based state machine for parsing s…
2390 msgid "The following sample``textfsm`` template is stored as ``templates/nxos_show_interface.textfs…
2394 msgid "The following task uses the example template for ``textfsm`` with the ``cli_parse`` module."
2398 msgid "The ``ansible_network_os`` for the device (``cisco.nxos.nxos``) is converted to ``nxos``. Al…
2402 msgid "The textfsm template name defaulted to ``templates/nxos_show_interface.textfsm`` using a com…
2406 msgid "See the `textfsm README <https://github.com/google/textfsm>`_ for details."
2410 msgid "``textfsm`` was previously made available as a filter plugin. Ansible users should transitio…
2414 msgid "Red Hat Ansible Automation Platform subscription support is limited to the use of the ``text…
2418 msgid "Parsing with TTP"
2422 msgid "TTP is a Python library for semi-structured text parsing using templates. TTP uses a jinja-l…
2426 msgid "The following is an example TTP template stored as ``templates/nxos_show_interface.ttp``:"
2430 msgid "The following task uses this template to parse the ``show interface`` command output:"
2434 msgid "Taking a deeper dive in this task:"
2438 msgid "The default template path ``templates/nxos_show_interface.ttp`` was generated using the ``an…
2442 msgid "TTP supports several additional variables that will be passed to the parser. These include:"
2446 msgid "``parser/vars/ttp_init`` - Additional parameter passed when the parser is initialized."
2450 msgid "``parser/vars/ttp_results`` - Additional parameters used to influence the parser output."
2454 msgid "``parser/vars/ttp_vars`` - Additional variables made available in the template."
2458 msgid "See the `TTP documentation <https://ttp.readthedocs.io>`_ for details."
2462 msgid "The task sets the follow fact as the ``interfaces`` fact for the host:"
2466 msgid "Parsing with JC"
2470 msgid "JC is a python library that converts the output of dozens of common Linux/UNIX/macOS/Windows…
2474 msgid "The following is an example using JC to parse the output of the ``dig`` command:"
2478 msgid "The JC project and documentation can be found `here <https://github.com/kellyjonbrazil/jc/>`…
2482 msgid "See this `blog entry <https://blog.kellybrazil.com/2020/08/30/parsing-command-output-in-ansi…
2486 msgid "Converting XML"
2490 msgid "This example task runs the ``show interface`` command and parses the output as XML:"
2494 msgid "Red Hat Ansible Automation Platform subscription support is limited to the use of the ``xmlt…
2498 msgid "This task sets the ``interfaces`` fact for the host based on this returned output:"
2502 msgid "Advanced use cases"
2506 msgid "The ``cli_parse`` module supports several features to support more complex uses cases."
2510 msgid "Provide a full template path"
2514 msgid "Use the ``template_path`` option to override the default template path in the task:"
2518 msgid "Provide command to parser different than the command run"
2522 msgid "Use the ``command`` suboption for the ``parser`` to configure the command the parser expects…
2526 msgid "Provide a custom OS value"
2530 msgid "Use the ``os`` suboption to the parser to directly set the OS instead of using ``ansible_net…
2534 msgid "Parse existing text"
2538 msgid "Use the ``text`` option instead of ``command`` to parse text collected earlier in the playb…
2542 msgid ":ref:`develop_cli_parse_plugins`"
2546 msgid "Ansible Network FAQ"
2550 msgid "Topics"
2554 msgid "How can I improve performance for network playbooks?"
2558 msgid "Consider ``strategy: free`` if you are running on multiple hosts"
2562 msgid "The ``strategy`` plugin tells Ansible how to order multiple tasks on multiple hosts. :ref:`S…
2566 msgid "The default strategy is ``linear``. With strategy set to ``linear``, Ansible waits until the…
2570 msgid "Using the ``free`` strategy, Ansible uses available forks to execute tasks on each host as q…
2574 msgid "Execute ``show running`` only if you absolutely must"
2578 msgid "The ``show running`` command is the most resource-intensive command to execute on a network …
2582 msgid "Use ``ProxyCommand`` only if you absolutely must"
2586 msgid "Network modules support the use of a :ref:`proxy or jump host<network_delegate_to_vs_ProxyCo…
2590 msgid "Set ``--forks`` to match your needs"
2594 msgid "Every time Ansible runs a task, it forks its own process. The ``--forks`` parameter defines …
2598 msgid "Why is my output sometimes replaced with ``********``?"
2602 msgid "Ansible replaces any string marked ``no_log``, including passwords, with ``********`` in Ans…
2606 msgid "Why do the ``*_config`` modules always return ``changed=true`` with abbreviated commands?"
2610 msgid "When you issue commands directly on a network device, you can use abbreviated commands. For …
2614 msgid "When committing configuration, however, the network OS converts abbreviations into long-form…
2618 msgid "Ansible Network ``*_config`` modules compare the text of the commands you specify in ``lines…
2622 msgid "To avoid this problem, use long-form commands with the ``*_config`` modules:"
2626 msgid "Advanced Topics"
2630 msgid "Network Advanced Topics"
2634 msgid "Once you have mastered the basics of network automation with Ansible, as presented in :ref:`…
2638 msgid "This guide is intended for network engineers using Ansible for automation. It covers advance…
2642 msgid "If you're new to Ansible, or new to using Ansible for network automation, start with the :re…
2646 msgid "Ansible Network Examples"
2650 msgid "This document describes some examples of using Ansible to manage your network infrastructure…
2654 msgid "This example requires the following:"
2658 msgid "**Ansible 2.10** (or higher) installed. See :ref:`intro_installation_guide` for more informa…
2662 msgid "One or more network devices that are compatible with Ansible."
2666 msgid "Basic understanding of YAML :ref:`yaml_syntax`."
2670 msgid "Basic understanding of Jinja2 templates. See :ref:`playbooks_templating` for more informatio…
2674 msgid "Basic Linux command line use."
2678 msgid "Basic knowledge of network switch & router configurations."
2682 msgid "Groups and variables in an inventory file"
2686 msgid "An ``inventory`` file is a YAML or INI-like configuration file that defines the mapping of h…
2690 msgid "In our example, the inventory file defines the groups ``eos``, ``ios``, ``vyos`` and a \"gro…
2694 msgid "Because Ansible is a flexible tool, there are a number of ways to specify connection informa…
2698 msgid "If you use ssh-agent, you do not need the ``ansible_password`` lines. If you use ssh keys, b…
2702 msgid "Never store passwords in plain text."
2706 msgid "Ansible vault for password encryption"
2710 msgid "The \"Vault\" feature of Ansible allows you to keep sensitive data such as passwords or keys…
2714 msgid "Here's what it would look like if you specified your SSH passwords (encrypted with Ansible V…
2718 msgid "Common inventory variables"
2722 msgid "The following variables are common for all platforms in the inventory, though they can be ov…
2726 msgid "ansible_connection"
2730 msgid "Ansible uses the ansible-connection setting to determine how to connect to a remote device. …
2734 msgid "ansible_network_os"
2738 msgid "Informs Ansible which Network platform this hosts corresponds to. This is required when usin…
2742 msgid "ansible_user"
2746 msgid "The user to connect to the remote device (switch) as. Without this the user that is running …
2750 msgid "ansible_password"
2754 msgid "The corresponding password for ``ansible_user`` to log in as. If not specified SSH key will …
2758 msgid "ansible_become"
2762 msgid "If enable mode (privilege mode) should be used, see the next section."
2766 msgid "ansible_become_method"
2770 msgid "Which type of `become` should be used, for ``network_cli`` the only valid choice is ``enable…
2774 msgid "Privilege escalation"
2778 msgid "Certain network platforms, such as Arista EOS and Cisco IOS, have the concept of different p…
2782 msgid "For more information, see the :ref:`using become with network modules<become_network>` guide…
2786 msgid "Jump hosts"
2790 msgid "If the Ansible Controller does not have a direct route to the remote device and you need to …
2794 msgid "Example 1: collecting facts and creating backup files with a playbook"
2798 msgid "Ansible facts modules gather system information 'facts' that are available to the rest of yo…
2802 msgid "Ansible Networking ships with a number of network-specific facts modules. In this example, w…
2806 msgid "Ansible's \"Network Fact modules\" gather information from the system and store the results …
2810 msgid "To ensure we call the correct mode (``*_facts``) the task is conditionally run based on the …
2814 msgid "In this example, we will create an inventory file containing some network switches, then run…
2818 msgid "Step 1: Creating the inventory"
2822 msgid "First, create a file called ``inventory``, containing:"
2826 msgid "Step 2: Creating the playbook"
2830 msgid "Next, create a playbook file called ``facts-demo.yml`` containing the following:"
2834 msgid "Step 3: Running the playbook"
2838 msgid "To run the playbook, run the following from a console prompt:"
2842 msgid "This should return output similar to the following:"
2846 msgid "Step 4: Examining the playbook results"
2850 msgid "Next, look at the contents of the file we created containing the switch facts:"
2854 msgid "You can also look at the backup files:"
2858 msgid "If `ansible-playbook` fails, please follow the debug steps in :ref:`network_debug_troublesho…
2862 msgid "Example 2: simplifying playbooks with network agnostic modules"
2866 msgid "(This example originally appeared in the `Deep Dive on cli_command for Network Automation <h…
2870 msgid "If you have two or more network platforms in your environment, you can use the network agnos…
2874 msgid "Network agnostic modules require the :ref:`ansible.netcommon.network_cli <ansible_collection…
2878 msgid "Sample playbook with platform-specific modules"
2882 msgid "This example assumes three platforms, Arista EOS, Cisco NXOS, and Juniper JunOS. Without th…
2886 msgid "Simplified playbook with ``cli_command`` network agnostic module"
2890 msgid "You can replace these platform-specific modules with the network agnostic ``ansible.netcommo…
2894 msgid "If you use groups and group_vars by platform type, this playbook can be further simplified t…
2898 msgid "You can see a full example of this using group_vars and also a configuration backup example …
2902 msgid "Using multiple prompts with the ``ansible.netcommon.cli_command``"
2906 msgid "The ``ansible.netcommon.cli_command`` also supports multiple prompts."
2910 msgid "See the :ref:`ansible.netcommon.cli_command <cli_command_module>` for full documentation on …
2914 msgid "Implementation Notes"
2918 msgid "Demo variables"
2922 msgid "Although these tasks are not needed to write data to disk, they are used in this example to …
2926 msgid "Ansible ``hostvars`` allows you to access variables from a named host. Without this we would…
2930 msgid "For more information, see :ref:`magic_variables_and_hostvars`."
2934 msgid "Get running configuration"
2938 msgid "The :ref:`arista.eos.eos_config <ansible_collections.arista.eos.eos_config_module>` and :ref…
2942 msgid "To demonstrate how we can move the backup file to a different location, we register the resu…
2946 msgid "Note that when using variables from tasks in this way we use double quotes (``\"``) and doub…
2950 msgid "Troubleshooting"
2954 msgid "If you receive an connection error please double check the inventory and playbook for typos …
2958 msgid ":ref:`network_guide`"
2962 msgid ":ref:`intro_inventory`"
2966 msgid ":ref:`Keeping vaulted variables visible <tip_for_variables_and_vaults>`"
2970 msgid "Network Debug and Troubleshooting Guide"
2974 msgid "This section discusses how to debug and troubleshoot network modules in Ansible."
2978 msgid "How to troubleshoot"
2982 msgid "Ansible network automation errors generally fall into one of the following categories:"
2986 msgid "Authentication issues"
2990 msgid "Not correctly specifying credentials"
2994 msgid "Remote device (network switch/router) not falling back to other other authentication methods"
2998 msgid "SSH key issues"
3003 msgid "Timeout issues"
3007 msgid "Can occur when trying to pull a large amount of data"
3011 msgid "May actually be masking a authentication issue"
3016 msgid "Playbook issues"
3020 msgid "Use of ``delegate_to``, instead of ``ProxyCommand``. See :ref:`network proxy guide <network_…
3024 msgid "``unable to open shell``"
3028 msgid "The ``unable to open shell`` message means that the ``ansible-connection`` daemon has not be…
3032 msgid "Enabling Networking logging and how to read the logfile"
3043 msgid "**Platforms:** Any"
3047 msgid "Ansible includes logging to help diagnose and troubleshoot issues regarding Ansible Networki…
3051 msgid "Because logging is very verbose, it is disabled by default. It can be enabled with the :envv…
3055 msgid "Before running ``ansible-playbook``, run the following commands to enable logging::"
3059 msgid "After Ansible has finished running you can inspect the log file which has been created on th…
3063 msgid "From the log notice:"
3067 msgid "``p=28990`` Is the PID (Process ID) of the ``ansible-connection`` process"
3071 msgid "``u=fred`` Is the user `running` ansible, not the remote-user you are attempting to connect …
3075 msgid "``creating new control socket for host veos01:22 as user admin`` host:port as user"
3079 msgid "``control socket path is`` location on disk where the persistent connection socket is create…
3083 msgid "``using connection plugin network_cli`` Informs you that persistent connection is being used"
3087 msgid "``connection established to veos01 in 0:00:22.580626`` Time taken to obtain a shell on the r…
3091 msgid "Because the log files are verbose, you can use grep to look for specific information. For ex…
3095 msgid "Enabling Networking device interaction logging"
3099 msgid "Ansible includes logging of device interaction in the log file to help diagnose and troubles…
3103 msgid "The device interaction messages consist of command executed on the target device and the ret…
3107 msgid "Be sure to fully understand the security implications of enabling this option. The device in…
3111 msgid "Before running ``ansible-playbook`` run the following commands to enable logging:"
3115 msgid "Enable device interaction logging for a given task"
3121 msgid "To make this a global setting, add the following to your ``ansible.cfg`` file:"
3125 msgid "or enable the environment variable `ANSIBLE_PERSISTENT_LOG_MESSAGES`:"
3129 msgid "If the task is failing on connection initialization itself, you should enable this option gl…
3133 msgid "After Ansible has finished running you can inspect the log file which has been created on th…
3137 msgid "Be sure to fully understand the security implications of enabling this option as it can log …
3141 msgid "Isolating an error"
3145 msgid "As with any effort to troubleshoot it's important to simplify the test case as much as possi…
3149 msgid "For Ansible this can be done by ensuring you are only running against one remote device:"
3153 msgid "Using ``ansible-playbook --limit switch1.example.net...``"
3157 msgid "Using an ad hoc ``ansible`` command"
3161 msgid "`ad hoc` refers to running Ansible to perform some quick command using ``/usr/bin/ansible``,…
3165 msgid "In the above example, we:"
3169 msgid "connect to ``switch1.example.net`` specified in the inventory file ``inventory``"
3173 msgid "use the module ``arista.eos.eos_command``"
3177 msgid "run the command ``?``"
3181 msgid "connect using the username ``admin``"
3185 msgid "inform the ``ansible`` command to prompt for the SSH password by specifying ``-k``"
3189 msgid "If you have SSH keys configured correctly, you don't need to specify the ``-k`` parameter."
3193 msgid "If the connection still fails you can combine it with the enable_network_logging parameter. …
3197 msgid "Then review the log file and find the relevant error message in the rest of this document."
3201 msgid "Troubleshooting socket path issues"
3205 msgid "The ``Socket path does not exist or cannot be found`` and ``Unable to connect to socket`` m…
3211 msgid "or"
3227 msgid "Suggestions to resolve:"
3231 msgid "Verify that you have write access to the socket path described in the error message."
3235 msgid "Follow the steps detailed in :ref:`enable network logging <enable_network_logging>`."
3239 msgid "If the identified error message from the log file is:"
3243 msgid "Follow the steps detailed in :ref:`timeout issues <timeout_issues>`"
3247 msgid "Category \"Unable to open shell\""
3251 msgid "The ``unable to open shell`` message means that the ``ansible-connection`` daemon has not be…
3255 msgid "or:"
3259 msgid "Follow the steps detailed in enable_network_logging_."
3263 msgid "Once you've identified the error message from the log file, the specific solution can be fou…
3267 msgid "Error: \"[Errno -2] Name or service not known\""
3271 msgid "Indicates that the remote host you are trying to connect to can not be reached"
3275 msgid "If you are using the ``provider:`` options ensure that its suboption ``host:`` is set correc…
3279 msgid "If you are not using ``provider:`` nor top-level arguments ensure your inventory file is cor…
3283 msgid "Error: \"Authentication failed\""
3287 msgid "Occurs if the credentials (username, passwords, or ssh keys) passed to ``ansible-connection`…
3291 msgid "If you are specifying credentials via ``password:`` (either directly or via ``provider:``) o…
3298 msgid "To make this a permanent change, add the following to your ``ansible.cfg`` file:"
3302 msgid "Error: \"connecting to host <hostname> returned an error\" or \"Bad address\""
3306 msgid "This may occur if the SSH fingerprint hasn't been added to Paramiko's (the Python SSH librar…
3310 msgid "When using persistent connections with Paramiko, the connection runs in a background process…
3314 msgid "Use ``ssh-keyscan`` to pre-populate the known_hosts. You need to ensure the keys are correct…
3318 msgid "You can tell Ansible to automatically accept the keys"
3322 msgid "Environment variable method::"
3326 msgid "``ansible.cfg`` method:"
3330 msgid "ansible.cfg"
3334 msgid "Error: \"No authentication methods available\""
3338 msgid "No password or SSH key supplied"
3342 msgid "Clearing Out Persistent Connections"
3346 msgid "In Ansible 2.3, persistent connection sockets are stored in ``~/.ansible/pc`` for all networ…
3350 msgid "``<switch> socket_path: /home/fred/.ansible/pc/f64ddfa760``"
3354 msgid "To clear out a persistent connection before it times out (the default timeout is 30 seconds …
3358 msgid "Persistent connection idle timeout"
3362 msgid "By default, ``ANSIBLE_PERSISTENT_CONNECT_TIMEOUT`` is set to 30 (seconds). You may see the f…
3366 msgid "Increase value of persistent connection idle timeout:"
3370 msgid "Command timeout"
3374 msgid "By default, ``ANSIBLE_PERSISTENT_COMMAND_TIMEOUT`` is set to 30 (seconds). Prior versions of…
3378 msgid "Option 1 (Global command timeout setting): Increase value of command timeout in configuratio…
3382 msgid "Option 2 (Per task command timeout setting): Increase command timeout per task basis. All ne…
3386 msgid "For local connection type:"
3390 msgid "Some operations take longer than the default 30 seconds to complete. One good example is sa…
3394 msgid "Persistent connection retry timeout"
3398 msgid "By default, ``ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT`` is set to 15 (seconds). You may see…
3402 msgid "Increase the value of the persistent connection idle timeout. Note: This value should be gre…
3406 msgid "Timeout issue due to platform specific login menu with ``network_cli`` connection type"
3410 msgid "In Ansible 2.9 and later, the network_cli connection plugin configuration options are added …
3414 msgid "Example: Handle single login menu prompts with host variables"
3418 msgid "Example: Handle remote host multiple login menu prompts with host variables"
3422 msgid "To handle multiple login menu prompts:"
3426 msgid "The values of ``ansible_terminal_initial_prompt`` and ``ansible_terminal_initial_answer`` sh…
3430 msgid "The prompt sequence should match the answer sequence."
3434 msgid "The value of ``ansible_terminal_initial_prompt_checkall`` should be set to ``True``."
3438 msgid "If all the prompts in sequence are not received from remote host at the time connection init…
3442 msgid "This section details issues are caused by issues with the Playbook itself."
3446 msgid "Error: \"Unable to enter configuration mode\""
3450 msgid "**Platforms:** Arista EOS and Cisco IOS"
3454 msgid "This occurs when you attempt to run a task that requires privileged mode in a user mode shel…
3458 msgid "Use ``connection: ansible.netcommon.network_cli`` and ``become: yes``"
3462 msgid "Proxy Issues"
3466 msgid "delegate_to vs ProxyCommand"
3470 msgid "In order to use a bastion or intermediate jump host to connect to network devices over ``cli…
3474 msgid "To use ``ProxyCommand``, configure the proxy settings in the Ansible inventory file to speci…
3478 msgid "With the configuration above, simply build and run the playbook as normal with no additional…
3482 msgid "You can also set the proxy target for all hosts by using environment variables."
3486 msgid "Using bastion/jump host with netconf connection"
3490 msgid "Enabling jump host setting"
3494 msgid "Bastion/jump host with netconf connection can be enabled by:"
3498 msgid "Setting Ansible variable ``ansible_netconf_ssh_config`` either to ``True`` or custom ssh con…
3502 msgid "Setting environment variable ``ANSIBLE_NETCONF_SSH_CONFIG`` to ``True`` or custom ssh config…
3506 msgid "Setting ``ssh_config = 1`` or ``ssh_config = <ssh-file-path>`` under ``netconf_connection`` …
3510 msgid "If the configuration variable is set to 1 the proxycommand and other ssh variables are read …
3514 msgid "If the configuration variable is set to file path the proxycommand and other ssh variables a…
3518 msgid "Example ssh config file (~/.ssh/config)"
3522 msgid "Example Ansible inventory file"
3526 msgid "Using ``ProxyCommand`` with passwords via variables"
3530 msgid "By design, SSH doesn't support providing passwords via environment variables. This is done t…
3534 msgid "We recommend using SSH Keys, and if needed an ssh-agent, rather than passwords, where ever p…
3538 msgid "Miscellaneous Issues"
3542 msgid "Intermittent failure while using ``ansible.netcommon.network_cli`` connection type"
3546 msgid "If the command prompt received in response is not matched correctly within the ``ansible.net…
3550 msgid "Example Per task timer setting"
3554 msgid "This timer delay per command executed on remote host can be disabled by setting the value to…
3558 msgid "Task failure due to mismatched error regex within command response using ``ansible.netcommon…
3562 msgid "In Ansible 2.9 and later, the ``ansible.netcommon.network_cli`` connection plugin configurat…
3566 msgid "Example: For mismatched error response"
3570 msgid "Playbook run output:"
3574 msgid "Modify the error regex for individual task."
3578 msgid "The terminal plugin regex options ``ansible_terminal_stderr_re`` and ``ansible_terminal_stdo…
3582 msgid "Intermittent failure while using ``ansible.netcommon.network_cli`` connection type due to sl…
3586 msgid "In Ansible 2.9 and later, the ``ansible.netcommon.network_cli`` connection plugin configurat…
3590 msgid "Network Resource Modules"
3594 msgid "Ansible network resource modules simplify and standardize how you manage different network d…
3598 msgid "Network resource module states"
3602 msgid "You use the network resource modules by assigning a state to what you want the module to do.…
3606 msgid "Using network resource modules"
3610 msgid "This example configures the L3 interface resource on a Cisco IOS device, based on different …
3614 msgid "The following table shows an example of how an initial resource configuration changes with t…
3618 msgid "Resource starting configuration"
3622 msgid "task-provided configuration (YAML)"
3626 msgid "Final resource configuration on device"
3630 msgid "*merged*"
3634 msgid "*replaced*"
3638 msgid "*overridden*"
3642 msgid "Incorrect use case. This would remove all interfaces from the device"
3646 msgid "(including the mgmt interface) except"
3650 msgid "the configured loopback100"
3654 msgid "*deleted*"
3658 msgid "Network resource modules return the following details:"
3662 msgid "The *before* state - the existing resource configuration before the task was executed."
3666 msgid "The *after* state - the new resource configuration that exists on the network device after t…
3670 msgid "Commands - any commands configured on the device."
3674 msgid "Example: Verifying the network device configuration has not changed"
3678 msgid "The following playbook uses the :ref:`arista.eos.eos_l3_interfaces <ansible_collections.aris…
3682 msgid "Example: Acquiring and updating VLANs on a network device"
3686 msgid "This example shows how you can use resource modules to:"
3690 msgid "Retrieve the current configuration on a network device."
3694 msgid "Save that configuration locally."
3698 msgid "Update that configuration and apply it to the network device."
3702 msgid "This example uses the ``cisco.ios.ios_vlans`` resource module to retrieve and update the VLA…
3706 msgid "Retrieve the current IOS VLAN configuration:"
3710 msgid "Store the VLAN configuration locally:"
3714 msgid "Modify the stored file to update the VLAN configuration locally."
3718 msgid "Merge the updated VLAN configuration with the existing configuration on the device:"
3722 msgid "`Network Features in Ansible 2.9 <https://www.ansible.com/blog/network-features-coming-soon-…
3726 msgid "A introductory blog post on network resource modules."
3730 msgid "`Deep Dive into Network Resource Modules <https://www.ansible.com/deep-dive-into-ansible-net…
3734 msgid "A deeper dive presentation into network resource modules."
3738 msgid "Working with command output and prompts in network modules"
3742 msgid "Conditionals in networking modules"
3746 msgid "Ansible allows you to use conditionals to control the flow of your playbooks. Ansible networ…
3750 msgid "``eq`` - Equal"
3754 msgid "``neq`` - Not equal"
3758 msgid "``gt`` - Greater than"
3762 msgid "``ge`` - Greater than or equal"
3766 msgid "``lt`` - Less than"
3770 msgid "``le`` - Less than or equal"
3774 msgid "``contains`` - Object contains specified item"
3778 msgid "Conditional statements evaluate the results from the commands that are executed remotely on …
3782 msgid "For example::"
3786 msgid "In the above example task, the command :code:`show interface Ethernet4 | json` is executed o…
3790 msgid "The commands module can also evaluate more than one set of command results in an interface. …
3794 msgid "In the above example, two commands are executed on the remote device, and the results are ev…
3798 msgid "The ``wait_for`` argument must always start with result and then the command index in ``[]``…
3802 msgid "Handling prompts in network modules"
3806 msgid "Network devices may require that you answer a prompt before performing a change on the devic…
3810 msgid "``prompt`` is a Python regex. If you add special characters such as ``?`` in the ``prompt`` …
3814 msgid "You can also use the :ref:`ansible.netcommon.cli_command <ansible_collections.ansible.netcom…
3818 msgid "You must list the prompt and the answers in the same order (that is, prompt[0] is answered b…
3822 msgid "In the above example, ``check_all: True`` ensures that the task gives the matching answer to…
3826 msgid "In the following example, the second answer would be ignored and ``y`` would be the answer g…
3830 msgid "`Rebooting network devices with Ansible <https://www.ansible.com/blog/rebooting-network-devi…
3834 msgid "Examples using ``wait_for``, ``wait_for_connection``, and ``prompt`` for network devices."
3838 msgid "`Deep dive on cli_command <https://www.ansible.com/blog/deep-dive-on-cli-command-for-network…
3842 msgid "Detailed overview of how to use the ``cli_command``."
3846 msgid "CloudEngine OS Platform Options"
3850 msgid "CloudEngine CE OS is part of the `community.network <https://galaxy.ansible.com/community/ne…
3878 msgid "Connections available"
3904 msgid "CLI"
3911 msgid "NETCONF"
3937 msgid "SSH"
3965 msgid "Credentials"
3992 msgid "uses SSH keys / SSH-agent if present"
4019 msgid "accepts ``-u myuser -k`` if using password"
4046 msgid "Indirect Access"
4073 msgid "via a bastion (jump host)"
4101 msgid "Connection Settings"
4108 msgid "``ansible_connection:``"
4115 msgid "``ansible.netcommon.network_cli``"
4120 msgid "``ansible.netcommon.netconf``"
4146 msgid "|enable_mode|"
4150 msgid "not supported by ce OS"
4177 msgid "Returned Data Format"
4183 msgid "Refer to individual module documentation"
4187 msgid "The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ans…
4213 msgid "Using CLI in Ansible"
4217 msgid "Example CLI inventory ``[ce:vars]``"
4243 msgid "If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` c…
4269 msgid "If you are accessing your host directly (not through a bastion/jump host) you can remove the…
4295 msgid "If you are accessing your host through a bastion/jump host, you cannot include your SSH pass…
4321 msgid "Example CLI task"
4328 msgid "Using NETCONF in Ansible"
4335 msgid "Enabling NETCONF"
4342 msgid "Before you can use NETCONF to connect to a switch, you must:"
4348 msgid "install the ``ncclient`` python package on your control node(s) with ``pip install ncclient`…
4352 msgid "enable NETCONF on the CloudEngine OS device(s)"
4356 msgid "To enable NETCONF on a new switch using Ansible, use the ``community.network.ce_config`` mod…
4363 msgid "Once NETCONF is enabled, change your variables to use the NETCONF connection."
4367 msgid "Example NETCONF inventory ``[ce:vars]``"
4374 msgid "Example NETCONF task"
4378 msgid "Notes"
4382 msgid "Modules that work with ``ansible.netcommon.network_cli``"
4386 msgid "Modules that work with ``ansible.netcommon.netconf``"
4390 msgid "Never store passwords in plain text. We recommend using SSH keys to authenticate SSH connect…
4418 msgid ":ref:`timeout_options`"
4422 msgid "CNOS Platform Options"
4426 msgid "CNOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ coll…
4443 msgid "``ansible_connection: ansible.netcommon.network_cli``"
4455 msgid "supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` and ``ansible_…
4478 msgid "``stdout[0].``"
4489 msgid "The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansi…
4493 msgid "Example CLI ``group_vars/cnos.yml``"
4497 msgid "Dell OS10 Platform Options"
4501 msgid "The `dellemc.os10 <https://galaxy.ansible.com/dellemc_networking/os10>`_ collection supports…
4505 msgid "Example CLI ``group_vars/dellos10.yml``"
4509 msgid "Dell OS6 Platform Options"
4513 msgid "The `dellemc.os6 <https://github.com/ansible-collections/dellemc.os6>`_ collection supports …
4517 msgid "Example CLI ``group_vars/dellos6.yml``"
4521 msgid "Dell OS9 Platform Options"
4525 msgid "The `dellemc.os9 <https://github.com/ansible-collections/dellemc.os9>`_ collection supports…
4529 msgid "Example CLI ``group_vars/dellos9.yml``"
4533 msgid "ENOS Platform Options"
4537 msgid "ENOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ coll…
4541 msgid "Example CLI ``group_vars/enos.yml``"
4545 msgid "EOS Platform Options"
4549 msgid "The `Arista EOS <https://galaxy.ansible.com/arista/eos>`_ collection supports multiple conne…
4553 msgid "eAPI"
4560 msgid "HTTP(S)"
4566 msgid "uses HTTPS certificates if present"
4572 msgid "via a web proxy"
4576 msgid "``ansible_connection:`` ``ansible.netcommon.network_cli``"
4580 msgid "``ansible_connection:`` ``ansible.netcommon.httpapi``"
4584 msgid "supported: |br|"
4588 msgid "use ``ansible_become: yes`` with ``ansible_become_method: enable``"
4592 msgid "``httpapi`` uses ``ansible_become: yes`` with ``ansible_become_method: enable``"
4598 msgid "``stdout[0].messages[0].``"
4603 msgid "The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansi…
4607 msgid "Example CLI ``group_vars/eos.yml``"
4611 msgid "Using eAPI in Ansible"
4615 msgid "Enabling eAPI"
4619 msgid "Before you can use eAPI to connect to a switch, you must enable eAPI. To enable eAPI on a ne…
4623 msgid "You can find more options for enabling HTTP/HTTPS connections in the :ref:`arista.eos.eos_ea…
4627 msgid "Once eAPI is enabled, change your ``group_vars/eos.yml`` to use the eAPI connection."
4631 msgid "Example eAPI ``group_vars/eos.yml``"
4637 msgid "If you are accessing your host directly (not through a web proxy) you can remove the ``proxy…
4643 msgid "If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to…
4647 msgid "Example eAPI task"
4651 msgid "In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``en…
4655 msgid "ERIC_ECCLI Platform Options"
4659 msgid "Extreme ERIC_ECCLI is part of the `community.network <https://galaxy.ansible.com/community/n…
4663 msgid "not supported by ERIC_ECCLI"
4667 msgid "ERIC_ECCLI does not support ``ansible_connection: local``. You must use ``ansible_connection…
4671 msgid "Example CLI ``group_vars/eric_eccli.yml``"
4675 msgid "EXOS Platform Options"
4679 msgid "Extreme EXOS is part of the `community.network <https://galaxy.ansible.com/community/network…
4683 msgid "EXOS-API"
4688 msgid "``ansible.netcommon.httpapi``"
4692 msgid "not supported by EXOS"
4696 msgid "EXOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansi…
4700 msgid "Example CLI ``group_vars/exos.yml``"
4704 msgid "Using EXOS-API in Ansible"
4708 msgid "Example EXOS-API ``group_vars/exos.yml``"
4712 msgid "Example EXOS-API task"
4717 msgid "In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``en…
4721 msgid "FRR Platform Options"
4725 msgid "The `FRR <https://galaxy.ansible.com/frr/frr>`_ collection supports the ``ansible.netcommon.…
4731 msgid "not supported"
4735 msgid "Example CLI ``group_vars/frr.yml``"
4739 msgid "The ``ansible_user`` should be a part of the ``frrvty`` group and should have the default sh…
4743 msgid "ICX Platform Options"
4747 msgid "ICX is part of the `community.network <https://galaxy.ansible.com/community/network>`_ colle…
4751 msgid "Example CLI ``group_vars/icx.yml``"
4756 msgid "Platform Options"
4760 msgid "Some Ansible Network platforms support multiple connection types, privilege escalation (``en…
4764 msgid "Settings by Platform"
4768 msgid "``ansible_connection:`` settings available"
4772 msgid "Network OS"
4776 msgid "``ansible_network_os:``"
4780 msgid "network_cli"
4784 msgid "netconf"
4788 msgid "httpapi"
4792 msgid "`Arista EOS`_ `[†]`_"
4796 msgid "``arista.eos.eos``"
4828 msgid "✓"
4832 msgid "`Ciena SAOS6`_"
4836 msgid "``ciena.saos6.saos6``"
4840 msgid "`Cisco ASA`_ `[†]`_"
4844 msgid "``cisco.asa.asa``"
4848 msgid "`Cisco IOS`_ `[†]`_"
4852 msgid "``cisco.ios.ios``"
4856 msgid "`Cisco IOS XR`_ `[†]`_"
4860 msgid "``cisco.iosxr.iosxr``"
4864 msgid "`Cisco NX-OS`_ `[†]`_"
4868 msgid "``cisco.nxos.nxos``"
4872 msgid "`Cloudengine OS`_"
4876 msgid "``community.network.ce``"
4880 msgid "`Dell OS6`_"
4884 msgid "``dellemc.os6.os6``"
4888 msgid "`Dell OS9`_"
4892 msgid "``dellemc.os9.os9``"
4896 msgid "`Dell OS10`_"
4900 msgid "``dellemc.os10.os10``"
4904 msgid "`Ericsson ECCLI`_"
4908 msgid "``community.network.eric_eccli``"
4912 msgid "`Extreme EXOS`_"
4916 msgid "``community.network.exos``"
4920 msgid "`Extreme IronWare`_"
4924 msgid "``community.network.ironware``"
4928 msgid "`Extreme NOS`_"
4932 msgid "``community.network.nos``"
4936 msgid "`Extreme SLX-OS`_"
4940 msgid "``community.network.slxos``"
4944 msgid "`Extreme VOSS`_"
4948 msgid "``community.network.voss``"
4952 msgid "`F5 BIG-IP`_"
4956 msgid "`F5 BIG-IQ`_"
4960 msgid "`Junos OS`_ `[†]`_"
4964 msgid "``junipernetworks.junos.junos``"
4968 msgid "`Lenovo CNOS`_"
4972 msgid "``community.network.cnos``"
4976 msgid "`Lenovo ENOS`_"
4980 msgid "``community.network.enos``"
4984 msgid "`Meraki`_"
4988 msgid "`MikroTik RouterOS`_"
4992 msgid "``community.network.routeros``"
4996 msgid "`Nokia SR OS`_"
5000 msgid "`Pluribus Netvisor`_"
5004 msgid "``community.network.netvisor``"
5008 msgid "`Ruckus ICX`_"
5012 msgid "``community.network.icx``"
5016 msgid "`VyOS`_ `[†]`_"
5020 msgid "``vyos.vyos.vyos``"
5024 msgid "`Westermo WeOS 4`_"
5028 msgid "``community.network.weos4``"
5032 msgid "OS that supports Netconf `[†]`_"
5036 msgid "``<network-os>``"
5040 msgid "**[†]** Maintained by Ansible Network Team"
5044 msgid "IOS Platform Options"
5048 msgid "The `Cisco IOS <https://galaxy.ansible.com/cisco/ios>`_ collection supports Enable Mode (Pri…
5052 msgid "Example CLI ``group_vars/ios.yml``"
5056 msgid "IOS-XR Platform Options"
5060 msgid "The `Cisco IOS-XR collection <https://galaxy.ansible.com/cisco/iosxr>`_ supports multiple co…
5064 msgid "only for modules ``iosxr_banner``, ``iosxr_interface``, ``iosxr_logging``, ``iosxr_system``,…
5069 msgid "The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansi…
5073 msgid "Example CLI inventory ``[iosxr:vars]``"
5077 msgid "enable NETCONF on the Cisco IOS-XR device(s)"
5081 msgid "To enable NETCONF on a new switch via Ansible, use the ``cisco.iosxr.iosxr_netconf`` module …
5085 msgid "Example NETCONF inventory ``[iosxr:vars]``"
5089 msgid "IronWare Platform Options"
5093 msgid "IronWare is part of the `community.network <https://galaxy.ansible.com/community/network>`_ …
5097 msgid "Example CLI ``group_vars/mlx.yml``"
5101 msgid "Junos OS Platform Options"
5105 msgid "The `Juniper Junos OS <https://galaxy.ansible.com/junipernetworks/junos>`_ supports multiple…
5109 msgid "``junos_netconf`` & ``junos_command`` modules only"
5114 msgid "all modules except ``junos_netconf``, which enables NETCONF"
5118 msgid "``ansible_connection: ``ansible.netcommon.network_cli``"
5122 msgid "``ansible_connection: ``ansible.netcommon.netconf``"
5126 msgid "not supported by Junos OS"
5130 msgid "json: ``result[0]['software-information'][0]['host-name'][0]['data'] foo lo0``"
5134 msgid "text: ``result[1].interface-information[0].physical-interface[0].name[0].data foo lo0``"
5138 msgid "xml: ``result[1].rpc-reply.interface-information[0].physical-interface[0].name[0].data foo l…
5142 msgid "Example CLI inventory ``[junos:vars]``"
5147 msgid "enable NETCONF on the Junos OS device(s)"
5151 msgid "To enable NETCONF on a new switch via Ansible, use the ``junipernetworks.junos.junos_netconf…
5156 msgid "Example NETCONF inventory ``[junos:vars]``"
5160 msgid "Meraki Platform Options"
5164 msgid "The `cisco.meraki <https://galaxy.ansible.com/cisco/meraki>`_ collection only supports the `…
5168 msgid "Dashboard API"
5172 msgid "uses API key from Dashboard"
5176 msgid "``ansible_connection: localhost``"
5180 msgid "``data.``"
5184 msgid "Example Meraki task"
5188 msgid "Netconf enabled Platform Options"
5192 msgid "This page offers details on how the netconf connection works in Ansible and how to use it."
5196 msgid "``ansible_connection: ansible.netcommon.netconf``"
5200 msgid "The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansi…
5204 msgid "install the ``ncclient`` Python package on your control node(s) with ``pip install ncclient`…
5208 msgid "To enable NETCONF on a new switch via Ansible, use the platform specific module via the CLI …
5212 msgid "Example NETCONF task with configurable variables"
5216 msgid "Note: For netconf connection plugin configurable variables see :ref:`ansible.netcommon.netco…
5220 msgid "Bastion/Jumphost configuration"
5224 msgid "To use a jump host to connect to a NETCONF enabled device you must set the ``ANSIBLE_NETCONF…
5228 msgid "``ANSIBLE_NETCONF_SSH_CONFIG`` can be set to either:"
5232 msgid "1 or TRUE (to trigger the use of the default SSH config file ~/.ssh/config)"
5236 msgid "The absolute path to a custom SSH config file."
5240 msgid "The SSH config file should look something like:"
5244 msgid "Authentication for the jump host must use key based authentication."
5248 msgid "You can either specify the private key used in the SSH config file:"
5252 msgid "Or you can use an ssh-agent."
5256 msgid "ansible_network_os auto-detection"
5260 msgid "If ``ansible_network_os`` is not specified for a host, then Ansible will attempt to automati…
5264 msgid "``ansible_network_os`` auto-detection can also be triggered by using ``auto`` as the ``ansib…
5268 msgid "Pluribus NETVISOR Platform Options"
5272 msgid "Pluribus NETVISOR Ansible is part of the `community.network <https://galaxy.ansible.com/comm…
5276 msgid "not supported by NETVISOR"
5280 msgid "Pluribus NETVISOR does not support ``ansible_connection: local``. You must use ``ansible_con…
5284 msgid "Example CLI ``group_vars/netvisor.yml``"
5288 msgid "NOS Platform Options"
5292 msgid "Extreme NOS is part of the `community.network <https://galaxy.ansible.com/community/network>…
5297 msgid "``ansible_connection: community.netcommon.network_cli``"
5301 msgid "not supported by NOS"
5305 msgid "NOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansib…
5309 msgid "Example CLI ``group_vars/nos.yml``"
5313 msgid "NXOS Platform Options"
5317 msgid "The `Cisco NXOS <https://galaxy.ansible.com/cisco/nxos>`_ supports multiple connections. Thi…
5321 msgid "NX-API"
5325 msgid "not supported by NX-API"
5329 msgid "Example CLI ``group_vars/nxos.yml``"
5333 msgid "Using NX-API in Ansible"
5337 msgid "Enabling NX-API"
5341 msgid "Before you can use NX-API to connect to a switch, you must enable NX-API. To enable NX-API o…
5345 msgid "To find out more about the options for enabling HTTP/HTTPS and local http see the :ref:`nxos…
5349 msgid "Once NX-API is enabled, change your ``group_vars/nxos.yml`` to use the NX-API connection."
5353 msgid "Example NX-API ``group_vars/nxos.yml``"
5357 msgid "Example NX-API task"
5361 msgid "Cisco Nexus platform support matrix"
5365 msgid "The following platforms and software versions have been certified by Cisco to work with this…
5369 msgid "Platform / Software Minimum Requirements"
5373 msgid "Supported Platforms"
5377 msgid "Minimum NX-OS Version"
5381 msgid "Cisco Nexus N3k"
5386 msgid "7.0(3)I2(5) and later"
5390 msgid "Cisco Nexus N9k"
5394 msgid "Cisco Nexus N5k"
5399 msgid "7.3(0)N1(1) and later"
5403 msgid "Cisco Nexus N6k"
5407 msgid "Cisco Nexus N7k"
5411 msgid "7.3(0)D1(1) and later"
5415 msgid "Cisco Nexus MDS"
5419 msgid "8.4(1) and later"
5423 msgid "Platform Models"
5427 msgid "Platform"
5431 msgid "Description"
5435 msgid "N3k"
5439 msgid "Support includes N30xx, N31xx and N35xx models"
5443 msgid "N5k"
5447 msgid "Support includes all N5xxx models"
5451 msgid "N6k"
5455 msgid "Support includes all N6xxx models"
5459 msgid "N7k"
5463 msgid "Support includes all N7xxx models"
5467 msgid "N9k"
5471 msgid "Support includes all N9xxx models"
5475 msgid "MDS"
5479 msgid "Support includes all MDS 9xxx models"
5483 msgid "RouterOS Platform Options"
5487 msgid "RouterOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ …
5491 msgid "``ansible_connection: ansible.network.network_cli``"
5495 msgid "not supported by RouterOS"
5499 msgid "RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: …
5503 msgid "Example CLI ``group_vars/routeros.yml``"
5507 msgid "If you are getting timeout errors you may want to add ``+cet1024w`` suffix to your username …
5511 msgid "SLX-OS Platform Options"
5515 msgid "Extreme SLX-OS is part of the `community.network <https://galaxy.ansible.com/community/netwo…
5519 msgid "not supported by SLX-OS"
5523 msgid "SLX-OS does not support ``ansible_connection: local``. You must use ``ansible_connection: an…
5527 msgid "Example CLI ``group_vars/slxos.yml``"
5531 msgid "VOSS Platform Options"
5535 msgid "Extreme VOSS is part of the `community.network <https://galaxy.ansible.com/community/network…
5539 msgid "supported: use ``ansible_become: yes`` with ``ansible_become_method: enable``"
5543 msgid "VOSS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansi…
5547 msgid "Example CLI ``group_vars/voss.yml``"
5551 msgid "VyOS Platform Options"
5555 msgid "The `VyOS <https://galaxy.ansible.com/vyos/vyos>`_ collection supports the ``ansible.netcomm…
5559 msgid "Example CLI ``group_vars/vyos.yml``"
5563 msgid "WeOS 4 Platform Options"
5567 msgid "Westermo WeOS 4 is part of the `community.network <https://galaxy.ansible.com/community/netw…
5571 msgid "not supported by WeOS 4"
5575 msgid "WeOS 4 does not support ``ansible_connection: local``. You must use ``ansible_connection: an…
5579 msgid "Example CLI ``group_vars/weos4.yml``"
5583 msgid "Example Configuration task"
5586 #~ msgid "The units of action in Ansible. You can execute a single task once with an ad-hoc command…
5589 #~ msgid "Unlike most Ansible modules, network modules do not run on the managed nodes. From a user…
5592 #~ msgid "Although Ansible contains a number of plugins that can convert XML to Ansible native data…
5595 #~ msgid "The following is an example TTP template stored as ``templates/nxos_show_interfaces.ttp``…
5598 #~ msgid "Using an ad-hoc ``ansible`` command"
5601 #~ msgid "`ad-hoc` refers to running Ansible to perform some quick command using ``/usr/bin/ansible…
5604 #~ msgid "Freenode IRC - ``#ansible-network`` Freenode channel"