Docs: Issue 78082 Create command line guide (#78567)

pull/78581/head
Don Naro 2 years ago committed by GitHub
parent 9e287d9002
commit e0eb45e753
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -43,6 +43,7 @@ Ansible releases a new major release approximately twice a year. The core applic
user_guide/index
inventory_guide/index
command_guide/index
playbook_guide/index
os_guide/index
tips_tricks/index

@ -0,0 +1,33 @@
.. _cheatsheet:
**********************
Ansible CLI cheatsheet
**********************
This page shows one or more examples of each Ansible command line utility with some common flags added and a link to the full documentation for the command.
This page offers a quick reminder of some common use cases only - it may be out of date or incomplete or both.
For canonical documentation, follow the links to the CLI pages.
.. contents::
:local:
ansible-playbook
================
.. code-block:: bash
ansible-playbook -i /path/to/my_inventory_file -u my_connection_user -k -f 3 -T 30 -t my_tag -m /path/to/my_modules -b -K my_playbook.yml
Loads ``my_playbook.yml`` from the current working directory and:
- ``-i`` - uses ``my_inventory_file`` in the path provided for :ref:`inventory <intro_inventory>` to match the :ref:`pattern <intro_patterns>`.
- ``-u`` - connects :ref:`over SSH <connections>` as ``my_connection_user``.
- ``-k`` - asks for password which is then provided to SSH authentication.
- ``-f`` - allocates 3 :ref:`forks <playbooks_strategies>`.
- ``-T`` - sets a 30-second timeout.
- ``-t`` - runs only tasks marked with the :ref:`tag <tags>` ``my_tag``.
- ``-m`` - loads :ref:`local modules <developing_locally>` from ``/path/to/my/modules``.
- ``-b`` - executes with elevated privileges (uses :ref:`become <become>`).
- ``-K`` - prompts the user for the become password.
See :ref:`ansible-playbook` for detailed documentation.

@ -0,0 +1,20 @@
.. _command_line_tools:
Working with command line tools
===============================
Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides.
Below is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters.
.. toctree::
:maxdepth: 1
../cli/ansible.rst
../cli/ansible-config.rst
../cli/ansible-console.rst
../cli/ansible-doc.rst
../cli/ansible-galaxy.rst
../cli/ansible-inventory.rst
../cli/ansible-playbook.rst
../cli/ansible-pull.rst
../cli/ansible-vault.rst

@ -0,0 +1,21 @@
.. _command_guide_index:
################################
Using Ansible command line tools
################################
.. note::
**Making Open Source More Inclusive**
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. We ask that you open an issue or pull request if you come upon a term that we have missed. For more details, see `our CTO Chris Wright's message <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_.
Welcome to the guide for using Ansible command line tools.
Ansible provides ad hoc commands and several utilities for performing various operations and automation tasks.
.. toctree::
:maxdepth: 2
intro_adhoc
command_line_tools
cheatsheet

@ -0,0 +1,220 @@
.. _intro_adhoc:
*******************************
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?
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?
========================
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
$ ansible [pattern] -m [module] -a "[module options]"
The ``-a`` option accepts options either through the ``key=value`` syntax or a JSON string starting with ``{`` and ending with ``}`` for more complex option structure.
You can learn more about :ref:`patterns<intro_patterns>` and :ref:`modules<working_with_modules>` on other pages.
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,
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<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
$ ansible atlanta -a "/sbin/reboot"
By default Ansible uses only 5 simultaneous processes. If you have more hosts than the value set for the fork count, Ansible will talk to them, but it will take a little longer. To reboot the [atlanta] servers with 10 parallel forks:
.. code-block:: bash
$ ansible atlanta -a "/sbin/reboot" -f 10
/usr/bin/ansible will default to running from your user account. To connect as a different user:
.. code-block:: bash
$ ansible atlanta -a "/sbin/reboot" -f 10 -u username
Rebooting probably requires privilege escalation. You can connect to the server as ``username`` and run the command as the ``root`` user by using the :ref:`become <become>` keyword:
.. code-block:: bash
$ ansible atlanta -a "/sbin/reboot" -f 10 -u username --become [--ask-become-pass]
If you add ``--ask-become-pass`` or ``-K``, Ansible prompts you for the password to use for privilege escalation (sudo/su/pfexec/doas/etc).
.. note::
The :ref:`command module <command_module>` does not support extended shell syntax like piping and
redirects (although shell variables will always work). If your command requires shell-specific
syntax, use the `shell` module instead. Read more about the differences on the
:ref:`working_with_modules` page.
So far all our examples have used the default 'command' module. To use a different module, pass ``-m`` for module name. For example, to use the :ref:`ansible.builtin.shell module <shell_module>`:
.. code-block:: bash
$ ansible raleigh -m ansible.builtin.shell -a 'echo $TERM'
When running any command with the Ansible *ad hoc* CLI (as opposed to
:ref:`Playbooks <working_with_playbooks>`), pay particular attention to shell quoting rules, so
the local shell retains the variable and passes it to Ansible.
For example, using double rather than single quotes in the above example would
evaluate the variable on the box you were on.
.. _file_transfer:
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:
.. code-block:: bash
$ ansible atlanta -m ansible.builtin.copy -a "src=/etc/hosts dest=/tmp/hosts"
If you plan to repeat a task like this, use the :ref:`ansible.builtin.template<template_module>` module in a playbook.
The :ref:`ansible.builtin.file<file_module>` module allows changing ownership and permissions on files. These
same options can be passed directly to the ``copy`` module as well:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.file -a "dest=/srv/foo/a.txt mode=600"
$ ansible webservers -m ansible.builtin.file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
The ``file`` module can also create directories, similar to ``mkdir -p``:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.file -a "dest=/path/to/c mode=755 owner=mdehaan group=mdehaan state=directory"
As well as delete directories (recursively) and delete files:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.file -a "dest=/path/to/c state=absent"
.. _managing_packages:
Managing packages
-----------------
You might also use an ad hoc task to install, update, or remove packages on managed nodes using a package management module such as ``yum``. Package management modules support common functions to install, remove, and generally manage packages. Some specific functions for a package manager might not be present in the Ansible module since they are not part of general package management.
To ensure a package is installed without updating it:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=present"
To ensure a specific version of a package is installed:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme-1.5 state=present"
To ensure a package is at the latest version:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=latest"
To ensure a package is not installed:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=absent"
Ansible has modules for managing packages under many platforms. If there is no module for your package manager, you can install packages using the command module or create a module for your package manager.
.. _users_and_groups:
Managing users and groups
-------------------------
You can create, manage, and remove user accounts on your managed nodes with ad hoc tasks:
.. code-block:: bash
$ ansible all -m ansible.builtin.user -a "name=foo password=<crypted password here>"
$ ansible all -m ansible.builtin.user -a "name=foo state=absent"
See the :ref:`ansible.builtin.user <user_module>` module documentation for details on all of the available options, including
how to manipulate groups and group membership.
.. _managing_services:
Managing services
-----------------
Ensure a service is started on all webservers:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=started"
Alternatively, restart a service on all webservers:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=restarted"
Ensure a service is stopped:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=stopped"
.. _gathering_facts:
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:
.. code-block:: bash
$ ansible all -m ansible.builtin.setup
You can also filter this output to display only certain facts, see the :ref:`ansible.builtin.setup <setup_module>` module documentation for details.
Patterns and ad-hoc commands
----------------------------
See the :ref:`patterns <intro_patterns>` documentation for details on all of the available options, including
how to limit using patterns in ad-hoc commands.
Now that you understand the basic elements of Ansible execution, you are ready to learn to automate repetitive tasks using :ref:`Ansible Playbooks <playbooks_intro>`.
.. seealso::
:ref:`intro_configuration`
All about the Ansible config file
:ref:`list_of_collections`
Browse existing collections, modules, and plugins
:ref:`working_with_playbooks`
Using Ansible for configuration management & deployment
`Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
:ref:`communication_irc`
How to join Ansible chat channels

@ -50,6 +50,7 @@ This documentation covers the version of ``ansible-core`` noted in the upper lef
user_guide/index
inventory_guide/index
command_guide/index
playbook_guide/index
os_guide/index
tips_tricks/index

@ -10,7 +10,7 @@ Building Ansible inventories
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. We ask that you open an issue or pull request if you come upon a term that we have missed. For more details, see `our CTO Chris Wright's message <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_.
Welcome to the guide to building Ansible inventory.
Welcome to the guide to building Ansible inventories.
An inventory is a list of managed nodes, or hosts, that Ansible deploys and configures.
This guide introduces you to inventories and covers the following topics:

@ -1,31 +1,7 @@
.. _cheatsheet:
:orphan:
**********************
Ansible CLI cheatsheet
**********************
This page shows one or more examples of each Ansible command line utility with some common flags added and a link to the full documentation for the command. This page offers a quick reminder of some common use cases only - it may be out of date or incomplete or both. For canonical documentation, follow the links to the CLI pages.
.. contents::
:local:
ansible-playbook
================
.. code-block:: bash
ansible-playbook -i /path/to/my_inventory_file -u my_connection_user -k -f 3 -T 30 -t my_tag -m /path/to/my_modules -b -K my_playbook.yml
Loads ``my_playbook.yml`` from the current working directory and:
- ``-i`` - uses ``my_inventory_file`` in the path provided for :ref:`inventory <intro_inventory>` to match the :ref:`pattern <intro_patterns>`.
- ``-u`` - connects :ref:`over SSH <connections>` as ``my_connection_user``.
- ``-k`` - asks for password which is then provided to SSH authentication.
- ``-f`` - allocates 3 :ref:`forks <playbooks_strategies>`.
- ``-T`` - sets a 30-second timeout.
- ``-t`` - runs only tasks marked with the :ref:`tag <tags>` ``my_tag``.
- ``-m`` - loads :ref:`local modules <developing_locally>` from ``/path/to/my/modules``.
- ``-b`` - executes with elevated privileges (uses :ref:`become <become>`).
- ``-K`` - prompts the user for the become password.
See :ref:`ansible-playbook` for detailed documentation.
This page has moved to :ref:`cheatsheet`.

@ -1,20 +1,6 @@
.. _command_line_tools:
:orphan:
Working with command line tools
===============================
Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides.
Below is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters.
.. toctree::
:maxdepth: 1
../cli/ansible.rst
../cli/ansible-config.rst
../cli/ansible-console.rst
../cli/ansible-doc.rst
../cli/ansible-galaxy.rst
../cli/ansible-inventory.rst
../cli/ansible-playbook.rst
../cli/ansible-pull.rst
../cli/ansible-vault.rst
This page has moved to :ref:`command_line_tools`.

@ -24,7 +24,6 @@ Advanced features and reference
* Manipulating :ref:`complex data <complex_data_manipulation>`
* Using :ref:`plugins <plugins_lookup>`
* Using :ref:`command-line tools <command_line_tools>`
* Rejecting :ref:`specific modules <plugin_filtering_config>`
* Module :ref:`maintenance <modules_support>`
@ -36,9 +35,6 @@ Here is the complete list of resources in the Ansible User Guide:
.. toctree::
:maxdepth: 2
intro_adhoc
cheatsheet
command_line_tools
vault
complex_data_manipulation
plugin_filtering_config

@ -1,215 +1,7 @@
.. _intro_adhoc:
:orphan:
*******************************
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`.
.. contents::
:local:
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:
.. code-block:: bash
$ ansible [pattern] -m [module] -a "[module options]"
The ``-a`` option accepts options either through the ``key=value`` syntax or a JSON string starting with ``{`` and ending with ``}`` for more complex option structure.
You can learn more about :ref:`patterns<intro_patterns>` and :ref:`modules<working_with_modules>` on other pages.
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,
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<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
$ ansible atlanta -a "/sbin/reboot"
By default Ansible uses only 5 simultaneous processes. If you have more hosts than the value set for the fork count, Ansible will talk to them, but it will take a little longer. To reboot the [atlanta] servers with 10 parallel forks:
.. code-block:: bash
$ ansible atlanta -a "/sbin/reboot" -f 10
/usr/bin/ansible will default to running from your user account. To connect as a different user:
.. code-block:: bash
$ ansible atlanta -a "/sbin/reboot" -f 10 -u username
Rebooting probably requires privilege escalation. You can connect to the server as ``username`` and run the command as the ``root`` user by using the :ref:`become <become>` keyword:
.. code-block:: bash
$ ansible atlanta -a "/sbin/reboot" -f 10 -u username --become [--ask-become-pass]
If you add ``--ask-become-pass`` or ``-K``, Ansible prompts you for the password to use for privilege escalation (sudo/su/pfexec/doas/etc).
.. note::
The :ref:`command module <command_module>` does not support extended shell syntax like piping and
redirects (although shell variables will always work). If your command requires shell-specific
syntax, use the `shell` module instead. Read more about the differences on the
:ref:`working_with_modules` page.
So far all our examples have used the default 'command' module. To use a different module, pass ``-m`` for module name. For example, to use the :ref:`ansible.builtin.shell module <shell_module>`:
.. code-block:: bash
$ ansible raleigh -m ansible.builtin.shell -a 'echo $TERM'
When running any command with the Ansible *ad hoc* CLI (as opposed to
:ref:`Playbooks <working_with_playbooks>`), pay particular attention to shell quoting rules, so
the local shell retains the variable and passes it to Ansible.
For example, using double rather than single quotes in the above example would
evaluate the variable on the box you were on.
.. _file_transfer:
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:
.. code-block:: bash
$ ansible atlanta -m ansible.builtin.copy -a "src=/etc/hosts dest=/tmp/hosts"
If you plan to repeat a task like this, use the :ref:`ansible.builtin.template<template_module>` module in a playbook.
The :ref:`ansible.builtin.file<file_module>` module allows changing ownership and permissions on files. These
same options can be passed directly to the ``copy`` module as well:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.file -a "dest=/srv/foo/a.txt mode=600"
$ ansible webservers -m ansible.builtin.file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
The ``file`` module can also create directories, similar to ``mkdir -p``:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.file -a "dest=/path/to/c mode=755 owner=mdehaan group=mdehaan state=directory"
As well as delete directories (recursively) and delete files:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.file -a "dest=/path/to/c state=absent"
.. _managing_packages:
Managing packages
-----------------
You might also use an ad hoc task to install, update, or remove packages on managed nodes using a package management module such as ``yum``. Package management modules support common functions to install, remove, and generally manage packages. Some specific functions for a package manager might not be present in the Ansible module since they are not part of general package management.
To ensure a package is installed without updating it:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=present"
To ensure a specific version of a package is installed:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme-1.5 state=present"
To ensure a package is at the latest version:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=latest"
To ensure a package is not installed:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=absent"
Ansible has modules for managing packages under many platforms. If there is no module for your package manager, you can install packages using the command module or create a module for your package manager.
.. _users_and_groups:
Managing users and groups
-------------------------
You can create, manage, and remove user accounts on your managed nodes with ad hoc tasks:
.. code-block:: bash
$ ansible all -m ansible.builtin.user -a "name=foo password=<crypted password here>"
$ ansible all -m ansible.builtin.user -a "name=foo state=absent"
See the :ref:`ansible.builtin.user <user_module>` module documentation for details on all of the available options, including
how to manipulate groups and group membership.
.. _managing_services:
Managing services
-----------------
Ensure a service is started on all webservers:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=started"
Alternatively, restart a service on all webservers:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=restarted"
Ensure a service is stopped:
.. code-block:: bash
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=stopped"
.. _gathering_facts:
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:
.. code-block:: bash
$ ansible all -m ansible.builtin.setup
You can also filter this output to display only certain facts, see the :ref:`ansible.builtin.setup <setup_module>` module documentation for details.
Patterns and ad-hoc commands
----------------------------
See the :ref:`patterns <intro_patterns>` documentation for details on all of the available options, including
how to limit using patterns in ad-hoc commands.
Now that you understand the basic elements of Ansible execution, you are ready to learn to automate repetitive tasks using :ref:`Ansible Playbooks <playbooks_intro>`.
.. seealso::
:ref:`intro_configuration`
All about the Ansible config file
:ref:`list_of_collections`
Browse existing collections, modules, and plugins
:ref:`working_with_playbooks`
Using Ansible for configuration management & deployment
`Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
:ref:`communication_irc`
How to join Ansible chat channels
This page has moved to :ref:`intro_adhoc`.
Loading…
Cancel
Save