From fa05af8321394d09590eacad8179e54b5de294f5 Mon Sep 17 00:00:00 2001 From: Willams de Lima Date: Thu, 18 Feb 2021 19:48:22 -0300 Subject: [PATCH] Fixing ad-hoc commands #73636 (#73646) --- .../getting_started/network_differences.rst | 2 +- .../network_debug_troubleshooting.rst | 4 ++-- docs/docsite/rst/plugins/callback.rst | 2 +- docs/docsite/rst/reference_appendices/faq.rst | 4 ++-- .../general_precedence.rst | 2 +- .../rst/scenario_guides/guide_cloudstack.rst | 2 +- .../docsite/rst/scenario_guides/guide_rax.rst | 2 +- .../rst/shared_snippets/basic_concepts.txt | 2 +- docs/docsite/rst/user_guide/index.rst | 2 +- docs/docsite/rst/user_guide/intro.rst | 2 +- docs/docsite/rst/user_guide/intro_adhoc.rst | 22 +++++++++---------- .../rst/user_guide/intro_getting_started.rst | 6 ++--- .../docsite/rst/user_guide/intro_patterns.rst | 6 ++--- .../rst/user_guide/playbooks_async.rst | 4 ++-- docs/docsite/rst/user_guide/sample_setup.rst | 2 +- docs/docsite/rst/user_guide/vault.rst | 2 +- docs/docsite/rst/user_guide/windows_usage.rst | 2 +- 17 files changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/docsite/rst/network/getting_started/network_differences.rst b/docs/docsite/rst/network/getting_started/network_differences.rst index 76b18aa424f..0e3fd72873d 100644 --- a/docs/docsite/rst/network/getting_started/network_differences.rst +++ b/docs/docsite/rst/network/getting_started/network_differences.rst @@ -10,7 +10,7 @@ Network automation leverages the basic Ansible concepts, but there are important Execution on the control node ================================================================================ -Unlike most Ansible modules, network modules do not run on the managed nodes. From a user's point of view, network modules work like any other modules. They work with ad-hoc commands, playbooks, and roles. Behind the scenes, however, network modules use a different methodology than the other (Linux/Unix and Windows) modules use. Ansible is written and executed in Python. Because the majority of network devices can not run Python, the Ansible network modules are executed on the Ansible control node, where ``ansible`` or ``ansible-playbook`` runs. +Unlike most Ansible modules, network modules do not run on the managed nodes. From a user's point of view, network modules work like any other modules. They work with ad hoc commands, playbooks, and roles. Behind the scenes, however, network modules use a different methodology than the other (Linux/Unix and Windows) modules use. Ansible is written and executed in Python. Because the majority of network devices can not run Python, the Ansible network modules are executed on the Ansible control node, where ``ansible`` or ``ansible-playbook`` runs. Network modules also use the control node as a destination for backup files, for those modules that offer a ``backup`` option. With Linux/Unix modules, where a configuration file already exists on the managed node(s), the backup file gets written by default in the same directory as the new, changed file. Network modules do not update configuration files on the managed nodes, because network configuration is not written in files. Network modules write backup files on the control node, usually in the `backup` directory under the playbook root directory. diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst index 97f671bb2ae..2e9e605acce 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -160,9 +160,9 @@ As with any effort to troubleshoot it's important to simplify the test case as m 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 +* 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:: +`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:: ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 918da447dd0..17a3a25043d 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -53,7 +53,7 @@ or for my custom callback: This only affects :ref:`ansible-playbook` by default. -Setting a callback plugin for ad-hoc commands +Setting a callback plugin for ad hoc commands --------------------------------------------- The :ref:`ansible` ad hoc command specifically uses a different callback plugin for stdout, diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index fce890479f0..7c3ec2d3add 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -352,7 +352,7 @@ How do I see a list of all of the ansible\_ variables? Ansible by default gathers "facts" about the machines under management, and these facts can be accessed in playbooks and in templates. To see a list of all of the facts that are available about a machine, you can run the ``setup`` module -as an ad-hoc action: +as an ad hoc action: .. code-block:: shell-session @@ -519,7 +519,7 @@ and distribution and local configuration. How do I generate encrypted passwords for the user module? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Ansible ad-hoc command is the easiest option: +Ansible ad hoc command is the easiest option: .. code-block:: shell-session diff --git a/docs/docsite/rst/reference_appendices/general_precedence.rst b/docs/docsite/rst/reference_appendices/general_precedence.rst index 90494b69815..3fbc98b2b7b 100644 --- a/docs/docsite/rst/reference_appendices/general_precedence.rst +++ b/docs/docsite/rst/reference_appendices/general_precedence.rst @@ -47,7 +47,7 @@ When you type something directly at the command line, you may feel that your han You can override all other settings from all other sources in all other precedence categories at the command line by :ref:`general_precedence_extra_vars`, but that is not a command-line option, it is a way of passing a :ref:`variable`. -At the command line, if you pass multiple values for a parameter that accepts only a single value, the last defined value wins. For example, this :ref:`ad-hoc task` will connect as ``carol``, not as ``mike``:: +At the command line, if you pass multiple values for a parameter that accepts only a single value, the last defined value wins. For example, this :ref:`ad hoc task` will connect as ``carol``, not as ``mike``:: ansible -u mike -m ping myhost -u carol diff --git a/docs/docsite/rst/scenario_guides/guide_cloudstack.rst b/docs/docsite/rst/scenario_guides/guide_cloudstack.rst index fcfb8120a10..6d3f2b4d5ec 100644 --- a/docs/docsite/rst/scenario_guides/guide_cloudstack.rst +++ b/docs/docsite/rst/scenario_guides/guide_cloudstack.rst @@ -27,7 +27,7 @@ Or alternatively starting with Debian 9 and Ubuntu 16.04: $ sudo apt install python-cs -.. note:: cs also includes a command line interface for ad-hoc interaction with the CloudStack API, for example ``$ cs listVirtualMachines state=Running``. +.. note:: cs also includes a command line interface for ad hoc interaction with the CloudStack API, for example ``$ cs listVirtualMachines state=Running``. Limitations and Known Issues ```````````````````````````` diff --git a/docs/docsite/rst/scenario_guides/guide_rax.rst b/docs/docsite/rst/scenario_guides/guide_rax.rst index b6100b8b9ff..8dcf0d12293 100644 --- a/docs/docsite/rst/scenario_guides/guide_rax.rst +++ b/docs/docsite/rst/scenario_guides/guide_rax.rst @@ -100,7 +100,7 @@ The 'rax' module provides the ability to provision instances within Rackspace Cl them as module arguments, or by specifying the location of a credentials file. -Here is a basic example of provisioning an instance in ad-hoc mode: +Here is a basic example of provisioning an instance in ad hoc mode: .. code-block:: bash diff --git a/docs/docsite/rst/shared_snippets/basic_concepts.txt b/docs/docsite/rst/shared_snippets/basic_concepts.txt index e10e2d4f2cf..684340e5a43 100644 --- a/docs/docsite/rst/shared_snippets/basic_concepts.txt +++ b/docs/docsite/rst/shared_snippets/basic_concepts.txt @@ -26,7 +26,7 @@ The units of code Ansible executes. Each module has a particular use, from admin Tasks ===== -The units of action in Ansible. You can execute a single task once with an ad-hoc command. +The units of action in Ansible. You can execute a single task once with an ad hoc command. Playbooks ========= diff --git a/docs/docsite/rst/user_guide/index.rst b/docs/docsite/rst/user_guide/index.rst index 73f3ac6523f..726c09a9134 100644 --- a/docs/docsite/rst/user_guide/index.rst +++ b/docs/docsite/rst/user_guide/index.rst @@ -21,7 +21,7 @@ Getting started * a :ref:`text introduction ` * I'm ready to learn about Ansible. What :ref:`basic_concepts` do I need to learn? -* I want to use Ansible without writing a playbook. How do I use :ref:`ad-hoc commands `? +* I want to use Ansible without writing a playbook. How do I use :ref:`ad hoc commands `? Writing tasks, plays, and playbooks =================================== diff --git a/docs/docsite/rst/user_guide/intro.rst b/docs/docsite/rst/user_guide/intro.rst index d6ff243f8df..124bde65dea 100644 --- a/docs/docsite/rst/user_guide/intro.rst +++ b/docs/docsite/rst/user_guide/intro.rst @@ -3,7 +3,7 @@ Introduction ============ -Before we start exploring the main components of Ansible -- playbooks, configuration management, deployment, and orchestration -- we'll learn how to get Ansible installed and cover some basic concepts. We'll also go over how to execute ad-hoc commands in parallel across your nodes using /usr/bin/ansible, and see what modules are available in Ansible's core (you can also write your own, which is covered later). +Before we start exploring the main components of Ansible -- playbooks, configuration management, deployment, and orchestration -- we'll learn how to get Ansible installed and cover some basic concepts. We'll also go over how to execute ad hoc commands in parallel across your nodes using /usr/bin/ansible, and see what modules are available in Ansible's core (you can also write your own, which is covered later). .. toctree:: :maxdepth: 1 diff --git a/docs/docsite/rst/user_guide/intro_adhoc.rst b/docs/docsite/rst/user_guide/intro_adhoc.rst index a7aa8da3993..aa0eb586bf1 100644 --- a/docs/docsite/rst/user_guide/intro_adhoc.rst +++ b/docs/docsite/rst/user_guide/intro_adhoc.rst @@ -1,18 +1,18 @@ .. _intro_adhoc: ******************************* -Introduction to ad-hoc commands +Introduction to ad hoc commands ******************************* -An Ansible ad-hoc command uses the `/usr/bin/ansible` command-line tool to automate a single task on one or more managed nodes. Ad-hoc commands are quick and easy, but they are not reusable. So why learn about ad-hoc commands first? Ad-hoc commands demonstrate the simplicity and power of Ansible. The concepts you learn here will port over directly to the playbook language. Before reading and executing these examples, please read :ref:`intro_inventory`. +An Ansible ad hoc command uses the `/usr/bin/ansible` command-line tool to automate a single task on one or more managed nodes. ad hoc commands are quick and easy, but they are not reusable. So why learn about ad hoc commands first? ad hoc commands demonstrate the simplicity and power of Ansible. The concepts you learn here will port over directly to the playbook language. Before reading and executing these examples, please read :ref:`intro_inventory`. .. contents:: :local: -Why use ad-hoc commands? +Why use ad hoc commands? ======================== -Ad-hoc commands are great for tasks you repeat rarely. For example, if you want to power off all the machines in your lab for Christmas vacation, you could execute a quick one-liner in Ansible without writing a playbook. An ad-hoc command looks like this: +ad hoc commands are great for tasks you repeat rarely. For example, if you want to power off all the machines in your lab for Christmas vacation, you could execute a quick one-liner in Ansible without writing a playbook. An ad hoc command looks like this: .. code-block:: bash @@ -20,17 +20,17 @@ Ad-hoc commands are great for tasks you repeat rarely. For example, if you want You can learn more about :ref:`patterns` and :ref:`modules` on other pages. -Use cases for ad-hoc tasks +Use cases for ad hoc tasks ========================== -Ad-hoc tasks can be used to reboot servers, copy files, manage packages and users, and much more. You can use any Ansible module in an ad-hoc task. Ad-hoc tasks, like playbooks, use a declarative model, +ad hoc tasks can be used to reboot servers, copy files, manage packages and users, and much more. You can use any Ansible module in an ad hoc task. ad hoc tasks, like playbooks, use a declarative model, calculating and executing the actions required to reach a specified final state. They achieve a form of idempotence by checking the current state before they begin and doing nothing unless the current state is different from the specified final state. Rebooting servers ----------------- -The default module for the ``ansible`` command-line utility is the :ref:`ansible.builtin.command module`. You can use an ad-hoc task to call the command module and reboot all web servers in Atlanta, 10 at a time. Before Ansible can do this, you must have all servers in Atlanta listed in a group called [atlanta] in your inventory, and you must have working SSH credentials for each machine in that group. To reboot all the servers in the [atlanta] group: +The default module for the ``ansible`` command-line utility is the :ref:`ansible.builtin.command module`. You can use an ad hoc task to call the command module and reboot all web servers in Atlanta, 10 at a time. Before Ansible can do this, you must have all servers in Atlanta listed in a group called [atlanta] in your inventory, and you must have working SSH credentials for each machine in that group. To reboot all the servers in the [atlanta] group: .. code-block:: bash @@ -79,7 +79,7 @@ evaluate the variable on the box you were on. Managing files -------------- -An ad-hoc task can harness the power of Ansible and SCP to transfer many files to multiple machines in parallel. To transfer a file directly to all servers in the [atlanta] group: +An ad hoc task can harness the power of Ansible and SCP to transfer many files to multiple machines in parallel. To transfer a file directly to all servers in the [atlanta] group: .. code-block:: bash @@ -112,7 +112,7 @@ As well as delete directories (recursively) and delete files: Managing packages ----------------- -You might also use an ad-hoc task to install, update, or remove packages on managed nodes using a package management module like yum. To ensure a package is installed without updating it: +You might also use an ad hoc task to install, update, or remove packages on managed nodes using a package management module like yum. To ensure a package is installed without updating it: .. code-block:: bash @@ -143,7 +143,7 @@ Ansible has modules for managing packages under many platforms. If there is no m Managing users and groups ------------------------- -You can create, manage, and remove user accounts on your managed nodes with ad-hoc tasks: +You can create, manage, and remove user accounts on your managed nodes with ad hoc tasks: .. code-block:: bash @@ -182,7 +182,7 @@ Ensure a service is stopped: Gathering facts --------------- -Facts represent discovered variables about a system. You can use facts to implement conditional execution of tasks but also just to get ad-hoc information about your systems. To see all facts: +Facts represent discovered variables about a system. You can use facts to implement conditional execution of tasks but also just to get ad hoc information about your systems. To see all facts: .. code-block:: bash diff --git a/docs/docsite/rst/user_guide/intro_getting_started.rst b/docs/docsite/rst/user_guide/intro_getting_started.rst index b22d83df6bc..92586cdf222 100644 --- a/docs/docsite/rst/user_guide/intro_getting_started.rst +++ b/docs/docsite/rst/user_guide/intro_getting_started.rst @@ -10,7 +10,7 @@ Now that you have read the :ref:`installation guide` and ins * connects to those machines (or network devices, or other managed nodes), usually over SSH * copies one or more modules to the remote machines and starts execution there -Ansible can do much more, but you should understand the most common use case before exploring all the powerful configuration, deployment, and orchestration features of Ansible. This page illustrates the basic process with a simple inventory and an ad-hoc command. Once you understand how Ansible works, you can read more details about :ref:`ad-hoc commands`, organize your infrastructure with :ref:`inventory`, and harness the full power of Ansible with :ref:`playbooks`. +Ansible can do much more, but you should understand the most common use case before exploring all the powerful configuration, deployment, and orchestration features of Ansible. This page illustrates the basic process with a simple inventory and an ad hoc command. Once you understand how Ansible works, you can read more details about :ref:`ad hoc commands`, organize your infrastructure with :ref:`inventory`, and harness the full power of Ansible with :ref:`playbooks`. .. contents:: :local: @@ -18,7 +18,7 @@ Ansible can do much more, but you should understand the most common use case bef Selecting machines from inventory ================================= -Ansible reads information about which machines you want to manage from your inventory. Although you can pass an IP address to an ad-hoc command, you need inventory to take advantage of the full flexibility and repeatability of Ansible. +Ansible reads information about which machines you want to manage from your inventory. Although you can pass an IP address to an ad hoc command, you need inventory to take advantage of the full flexibility and repeatability of Ansible. Action: create a basic inventory -------------------------------- @@ -111,7 +111,7 @@ If you need privilege escalation (sudo and similar) to run a command, pass the ` You can read more about privilege escalation in :ref:`become`. -Congratulations! You have contacted your nodes using Ansible. You used a basic inventory file and an ad-hoc command to direct Ansible to connect to specific remote nodes, copy a module file there and execute it, and return output. You have a fully working infrastructure. +Congratulations! You have contacted your nodes using Ansible. You used a basic inventory file and an ad hoc command to direct Ansible to connect to specific remote nodes, copy a module file there and execute it, and return output. You have a fully working infrastructure. Resources ================================= diff --git a/docs/docsite/rst/user_guide/intro_patterns.rst b/docs/docsite/rst/user_guide/intro_patterns.rst index 79f199c844c..b3a7b13816c 100644 --- a/docs/docsite/rst/user_guide/intro_patterns.rst +++ b/docs/docsite/rst/user_guide/intro_patterns.rst @@ -3,7 +3,7 @@ Patterns: targeting hosts and groups ==================================== -When you execute Ansible through an ad-hoc command or by running a playbook, you must choose which managed nodes or groups you want to execute against. Patterns let you run commands and playbooks against specific hosts and/or groups in your inventory. An Ansible pattern can refer to a single host, an IP address, an inventory group, a set of groups, or all hosts in your inventory. Patterns are highly flexible - you can exclude or require subsets of hosts, use wildcards or regular expressions, and more. Ansible executes on all inventory hosts included in the pattern. +When you execute Ansible through an ad hoc command or by running a playbook, you must choose which managed nodes or groups you want to execute against. Patterns let you run commands and playbooks against specific hosts and/or groups in your inventory. An Ansible pattern can refer to a single host, an IP address, an inventory group, a set of groups, or all hosts in your inventory. Patterns are highly flexible - you can exclude or require subsets of hosts, use wildcards or regular expressions, and more. Ansible executes on all inventory hosts included in the pattern. .. contents:: :local: @@ -11,7 +11,7 @@ When you execute Ansible through an ad-hoc command or by running a playbook, you Using patterns -------------- -You use a pattern almost any time you execute an ad-hoc command or a playbook. The pattern is the only element of an :ref:`ad-hoc command` that has no flag. It is usually the second element:: +You use a pattern almost any time you execute an ad hoc command or a playbook. The pattern is the only element of an :ref:`ad hoc command` that has no flag. It is usually the second element:: ansible -m -a "" @@ -31,7 +31,7 @@ For example:: - name: restart webservers hosts: webservers -Since you often want to run a command or playbook against multiple hosts at once, patterns often refer to inventory groups. Both the ad-hoc command and the playbook above will execute against all machines in the ``webservers`` group. +Since you often want to run a command or playbook against multiple hosts at once, patterns often refer to inventory groups. Both the ad hoc command and the playbook above will execute against all machines in the ``webservers`` group. .. _common_patterns: diff --git a/docs/docsite/rst/user_guide/playbooks_async.rst b/docs/docsite/rst/user_guide/playbooks_async.rst index 09fe5d5dd32..50a2cd7be3f 100644 --- a/docs/docsite/rst/user_guide/playbooks_async.rst +++ b/docs/docsite/rst/user_guide/playbooks_async.rst @@ -8,10 +8,10 @@ By default Ansible runs tasks synchronously, holding the connection to the remot .. contents:: :local: -Asynchronous ad-hoc tasks +Asynchronous ad hoc tasks ------------------------- -You can execute long-running operations in the background with :ref:`ad-hoc tasks `. For example, to execute ``long_running_operation`` asynchronously in the background, with a timeout (``-B``) of 3600 seconds, and without polling (``-P``):: +You can execute long-running operations in the background with :ref:`ad hoc tasks `. For example, to execute ``long_running_operation`` asynchronously in the background, with a timeout (``-B``) of 3600 seconds, and without polling (``-P``):: $ ansible all -B 3600 -P 0 -a "/usr/bin/long_running_operation --do-stuff" diff --git a/docs/docsite/rst/user_guide/sample_setup.rst b/docs/docsite/rst/user_guide/sample_setup.rst index a0e12997aad..b3cddd7c586 100644 --- a/docs/docsite/rst/user_guide/sample_setup.rst +++ b/docs/docsite/rst/user_guide/sample_setup.rst @@ -234,7 +234,7 @@ To reconfigure only the first 10 webservers in Boston, and then the next 10:: ansible-playbook -i production webservers.yml --limit boston[0:9] ansible-playbook -i production webservers.yml --limit boston[10:19] -The sample setup also supports basic ad-hoc commands:: +The sample setup also supports basic ad hoc commands:: ansible boston -i production -m ping ansible boston -i production -m command -a '/sbin/reboot' diff --git a/docs/docsite/rst/user_guide/vault.rst b/docs/docsite/rst/user_guide/vault.rst index cd54f329f0a..a101aa3c4bf 100644 --- a/docs/docsite/rst/user_guide/vault.rst +++ b/docs/docsite/rst/user_guide/vault.rst @@ -9,7 +9,7 @@ Ansible Vault encrypts variables and files so you can protect sensitive content .. warning:: * Encryption with Ansible Vault ONLY protects 'data at rest'. Once the content is decrypted ('data in use'), play and plugin authors are responsible for avoiding any secret disclosure, see :ref:`no_log ` for details on hiding output and :ref:`vault_securing_editor` for security considerations on editors you use with Ansible Vault. -You can use encrypted variables and files in ad-hoc commands and playbooks by supplying the passwords you used to encrypt them. You can modify your ``ansible.cfg`` file to specify the location of a password file or to always prompt for the password. +You can use encrypted variables and files in ad hoc commands and playbooks by supplying the passwords you used to encrypt them. You can modify your ``ansible.cfg`` file to specify the location of a password file or to always prompt for the password. .. contents:: :local: diff --git a/docs/docsite/rst/user_guide/windows_usage.rst b/docs/docsite/rst/user_guide/windows_usage.rst index b39413cd030..c7bd3f60952 100644 --- a/docs/docsite/rst/user_guide/windows_usage.rst +++ b/docs/docsite/rst/user_guide/windows_usage.rst @@ -433,7 +433,7 @@ This example shows the use of single quotes when they are required:: Legacy key=value Style ---------------------- -The legacy ``key=value`` syntax is used on the command line for ad-hoc commands, +The legacy ``key=value`` syntax is used on the command line for ad hoc commands, or inside playbooks. The use of this style is discouraged within playbooks because backslash characters need to be escaped, making playbooks harder to read. The legacy syntax depends on the specific implementation in Ansible, and quoting